upgradelifecycle

package
v0.39.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 24, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ExecutorStateSnapshotAPIVersion = "stackkit.executor-state-snapshot/v1"
)
View Source 
const (
	InspectionSchemaVersion = "stackkit.upgrade-inspection/v1"
)

Variables

This section is empty.

Functions

func RecoveryExecutableFromVerifiedRelease 

func RecoveryExecutableFromVerifiedRelease(
	proof releaseindex.VerifiedInstallation,
) ([]byte, error)

RecoveryExecutableFromVerifiedRelease returns the exact canonical stackkit executable from an already offline-verified installed release proof.

func SnapshotInventoryBlobPath 

func SnapshotInventoryBlobPath(snapshot ExecutorStateSnapshot) (string, error)

SnapshotInventoryBlobPath returns the content-addressed Inventory captured by a verified executor-state snapshot. Callers must load or verify the snapshot before handing this path to a release CLI.

func SnapshotRuntimeComposeBlobPath 

func SnapshotRuntimeComposeBlobPath(snapshot ExecutorStateSnapshot) (string, error)

SnapshotRuntimeComposeBlobPath returns the original, signed runtime Compose definition. During an upgrade, target Generate may replace the active file before Apply checks whether the old runtime owns its published ports.

Types

type ArtifactDiff 

type ArtifactDiff struct {
	ID              string `json:"id"`
	Path            string `json:"path"`
	Status          string `json:"status"`
	MetadataChanged bool   `json:"metadataChanged"`
	CurrentSHA256   string `json:"currentSha256,omitempty"`
	TargetSHA256    string `json:"targetSha256,omitempty"`
	CurrentKind     string `json:"currentKind,omitempty"`
	TargetKind      string `json:"targetKind,omitempty"`
	CurrentFormat   string `json:"currentFormat,omitempty"`
	TargetFormat    string `json:"targetFormat,omitempty"`
	CurrentMode     string `json:"currentMode,omitempty"`
	TargetMode      string `json:"targetMode,omitempty"`
}

type CurrentApplyResultVerifier 

type CurrentApplyResultVerifier struct {
	// contains filtered or unexported fields
}

CurrentApplyResultVerifier is an opaque adapter around the Architecture-v2 Apply verifier. Callers cannot substitute a verifier function.

func NewCurrentApplyResultVerifier 

func NewCurrentApplyResultVerifier(ctx context.Context, service *architecturev2.Service, journal *architecturev2.ProductApplyFileJournal) (CurrentApplyResultVerifier, error)

type CurrentSourceVerifier 

type CurrentSourceVerifier struct {
	// contains filtered or unexported fields
}

CurrentSourceVerifier re-resolves the exact recovery StackSpec and Inventory through a fresh Architecture-v2 CurrentResolution.

func NewCurrentSourceVerifier 

func NewCurrentSourceVerifier(service *architecturev2.Service) (CurrentSourceVerifier, error)

type CurrentStateAuthorityInput 

type CurrentStateAuthorityInput struct {
	WorkspaceRoot     string
	Plan              generationartifact.VerifiedPlan
	Manifest          generationartifact.ArtifactManifest
	GenerationReceipt generationartifact.GenerationReceipt
	Versions          generationartifact.ComponentVersions
	ApplyResult       []byte
	ApplyReceipt      []byte
	SourceVerifier    CurrentSourceVerifier
	ApplyVerifier     CurrentApplyResultVerifier
	Capture           ExecutorStateCaptureInput
	Legacy            *LegacyCurrentStateAuthorityInput
}

CurrentStateAuthorityInput contains the complete already-resolved current state. NewVerifiedExecutorStateCapture re-verifies every authority edge and returns the only handle accepted by ExecutorStateStore.

type CurrentStateCoreProfile 

type CurrentStateCoreProfile struct {
	ModuleRef         string
	ComposeArtifactID string
	ComposeOutputRef  string
	PolicyArtifactID  string
	PolicyOutputRef   string
}

CurrentStateCoreProfile is the exact Core profile and artifact pair used by the current Plan-owned recovery closure. The IDs come from ApplyRequirements; the stable profile identity and Compose output come from the existing local runtime profile registry.

func CurrentStateCoreProfileForPlan 

func CurrentStateCoreProfileForPlan(
	plan generationartifact.VerifiedPlan,
	siteRef string,
	nodeRef string,
) (CurrentStateCoreProfile, error)

CurrentStateCoreProfileForPlan selects the one Full or Lite Core runtime and its Compose/source-policy artifacts from the verified Apply requirements. It never derives a profile from an artifact filename or generated bytes.

type ExecRunner 

type ExecRunner struct{}

func (ExecRunner) Run 

func (ExecRunner) Run(ctx context.Context, binary string, args []string, dir string) ([]byte, error)

type ExecutorStateBlob 

type ExecutorStateBlob struct {
	ID     string `json:"id"`
	Path   string `json:"path"`
	Mode   string `json:"mode"`
	SHA256 string `json:"sha256"`
}

type ExecutorStateBlobInput 

type ExecutorStateBlobInput struct {
	ID   string
	Path string
	Mode string
	Data []byte
}

type ExecutorStateCaptureInput 

type ExecutorStateCaptureInput struct {
	OperationID           string
	GenerationTarget      string
	CoreModuleRef         string
	CoreComposeArtifactID string
	CorePolicyArtifactID  string
	Release               releaseindex.VerifiedInstallation
	Executable            ExecutorStateExecutableInput
	Lineage               backuplifecycle.AuthorityLineage
	StackSpec             ExecutorStateBlobInput
	Inventory             *ExecutorStateBlobInput
	Artifacts             []ExecutorStateBlobInput
	RuntimeCompose        ExecutorStateBlobInput
	KopiaSnapshotAnchor   backuplifecycle.SnapshotAnchor
}

type ExecutorStateExecutable 

type ExecutorStateExecutable struct {
	Version string            `json:"version"`
	Blob    ExecutorStateBlob `json:"blob"`
}

type ExecutorStateExecutableInput 

type ExecutorStateExecutableInput struct {
	Blob ExecutorStateBlobInput
}

type ExecutorStateRecoveryResult 

type ExecutorStateRecoveryResult struct {
	SnapshotID          string                         `json:"snapshotId"`
	OperationID         string                         `json:"operationId"`
	Release             ExecutorStateRelease           `json:"release"`
	KopiaSnapshotAnchor backuplifecycle.SnapshotAnchor `json:"kopiaSnapshotAnchor"`
	RestoredPaths       []string                       `json:"restoredPaths"`
}

ExecutorStateRecoveryResult is the secret-free projection of one verified executor-state recovery handoff. Kopia data remains an owner-signed anchor; Recover never promotes staged backup data into live volumes.

type ExecutorStateRelease 

type ExecutorStateRelease struct {
	Kit                    string                `json:"kit"`
	Version                string                `json:"version"`
	Channel                releaseindex.Channel  `json:"channel"`
	Platform               releaseindex.Platform `json:"platform"`
	ArchiveSHA256          string                `json:"archiveSha256"`
	SBOMSHA256             string                `json:"sbomSha256"`
	AttestationSHA256      string                `json:"attestationSha256"`
	TrustedRootSHA256      string                `json:"trustedRootSha256"`
	IndexSHA256            string                `json:"indexSha256"`
	IndexAttestationSHA256 string                `json:"indexAttestationSha256"`
	AttestationIssuer      string                `json:"attestationIssuer"`
	CertificateIdentity    string                `json:"certificateIdentity"`
	AttestationSubject     string                `json:"attestationSubject"`
	PredicateType          string                `json:"predicateType"`
}

type ExecutorStateSnapshot 

type ExecutorStateSnapshot struct {
	APIVersion            string                                    `json:"apiVersion"`
	ID                    string                                    `json:"id"`
	RequestHash           string                                    `json:"requestHash"`
	OwnerRef              string                                    `json:"ownerRef"`
	OperationID           string                                    `json:"operationId"`
	GenerationTarget      string                                    `json:"generationTarget"`
	CoreModuleRef         string                                    `json:"coreModuleRef,omitempty"`
	CoreComposeArtifactID string                                    `json:"coreComposeArtifactId,omitempty"`
	CorePolicyArtifactID  string                                    `json:"corePolicyArtifactId,omitempty"`
	Release               ExecutorStateRelease                      `json:"release"`
	Executable            ExecutorStateExecutable                   `json:"executable"`
	Lineage               backuplifecycle.AuthorityLineage          `json:"lineage"`
	StackSpec             ExecutorStateBlob                         `json:"stackSpec"`
	Inventory             *ExecutorStateBlob                        `json:"inventory,omitempty"`
	Artifacts             []ExecutorStateBlob                       `json:"artifacts"`
	RuntimeCompose        ExecutorStateBlob                         `json:"runtimeCompose"`
	KopiaSnapshotAnchor   backuplifecycle.SnapshotAnchor            `json:"kopiaSnapshotAnchor"`
	CapturedAt            time.Time                                 `json:"capturedAt"`
	Signature             localevidence.OwnerExecutorStateSignature `json:"signature"`
}

type ExecutorStateStore 

type ExecutorStateStore struct {
	Now func() time.Time
}

func (ExecutorStateStore) Capture 

func (store ExecutorStateStore) Capture(
	workspaceRoot string,
	verified VerifiedExecutorStateCapture,
) (ExecutorStateSnapshot, error)

func (ExecutorStateStore) Load 

func (store ExecutorStateStore) Load(workspaceRoot, snapshotID string) (ExecutorStateSnapshot, error)

func (ExecutorStateStore) Recover 

func (store ExecutorStateStore) Recover(
	ctx context.Context,
	workspaceRoot string,
	snapshotID string,
	invoke RecoveryCommand,
) (ExecutorStateRecoveryResult, error)

Recover verifies a committed executor-state snapshot and every retained blob before restoring only its StackSpec and optional Inventory. It invokes the caller with the exact captured executable and removes that temporary executable when the callback returns.

func (ExecutorStateStore) Verify 

func (store ExecutorStateStore) Verify(workspaceRoot string, snapshot ExecutorStateSnapshot) error

func (ExecutorStateStore) WithRuntimeCustody 

func (store ExecutorStateStore) WithRuntimeCustody(
	ctx context.Context,
	workspaceRoot, snapshotID string,
	use func(context.Context, MaterializedRuntimeCustody) error,
) (returnErr error)

WithRuntimeCustody verifies a committed owner-signed checkpoint and all its blobs, then copies the recorded runtime closure without generating artifacts or overwriting workspace files. The callback sees only a complete private view. That view is removed on success, failure, or context cancellation.

type Inspection 

type Inspection struct {
	SchemaVersion string              `json:"schemaVersion"`
	Target        Target              `json:"target"`
	Plan          PlanDiff            `json:"plan"`
	Artifacts     []ArtifactDiff      `json:"artifacts"`
	Execution     InspectionExecution `json:"execution"`
}

func (Inspection) MarshalCanonical 

func (inspection Inspection) MarshalCanonical() ([]byte, error)

type InspectionExecution 

type InspectionExecution struct {
	Mode            string `json:"mode"`
	TargetBinary    string `json:"targetBinary"`
	GenerateInvoked bool   `json:"generateInvoked"`
	ApplyInvoked    bool   `json:"applyInvoked"`
	SnapshotCreated bool   `json:"snapshotCreated"`
}

type Inspector 

type Inspector struct {
	Source            releaseindex.Source
	Attestations      releaseindex.AttestationVerifier
	Runner            Runner
	InventoryPath     string
	MaxBlobBytes      int64
	MaxExtractBytes   int64
	MaxWorkspaceBytes int64
	MaxFiles          int
	Timeout           time.Duration
}

func (Inspector) Inspect 

func (inspector Inspector) Inspect(ctx context.Context, resolution releaseindex.Resolution, workspace, specFile string, current generationartifact.PlanInspection) (Inspection, error)

type LegacyCurrentStateAuthorityInput 

type LegacyCurrentStateAuthorityInput struct {
	WorkspaceRoot     string
	Inspection        generationartifact.PlanInspection
	Manifest          generationartifact.ArtifactManifest
	GenerationReceipt generationartifact.GenerationReceipt
	ApplyResult       []byte
	ApplyReceipt      []byte
	Capture           ExecutorStateCaptureInput
}

LegacyCurrentStateAuthorityInput is intentionally limited to the exact published beta.4 through v0.12.0 authority discontinuities. The caller must still supply the immutable installed-release proof, owner-signed Apply evidence, complete generated artifact closure, and the candidate-created Kopia snapshot.

type MaterializedRuntimeCustody 

type MaterializedRuntimeCustody struct {
	// contains filtered or unexported fields
}

MaterializedRuntimeCustody identifies exact checkpoint files within a private workspace directory. It is valid only during WithRuntimeCustody's callback. It neither starts services nor authorizes a live data cutover.

func (MaterializedRuntimeCustody) BindRestore 

func (custody MaterializedRuntimeCustody) BindRestore(result backuplifecycle.RestoreResult) (restoreactivation.Authority, error)

BindRestore verifies the real owner-signed staging result against this exact checkpoint, then projects the historical runtime into the private file view. The upgrade controller still owns target admission and the mutation journal.

func (MaterializedRuntimeCustody) Graph 

func (custody MaterializedRuntimeCustody) Graph() restoreactivation.RuntimeRecoveryGraph

Graph returns historical, defensively copied data, never a fresh CUE plan.

func (MaterializedRuntimeCustody) OperationID 

func (custody MaterializedRuntimeCustody) OperationID() string

func (MaterializedRuntimeCustody) Path 

func (custody MaterializedRuntimeCustody) Path(original string) (string, error)

Path maps one recorded workspace-relative path to its private materialized copy. Callers retain the original workspace as the owner-custody root.

func (MaterializedRuntimeCustody) ReadArtifact 

func (custody MaterializedRuntimeCustody) ReadArtifact(id string) ([]byte, error)

ReadArtifact reads exact retained bytes by their checkpoint artifact identity. It rechecks the CAS digest and is valid only inside WithRuntimeCustody.

func (MaterializedRuntimeCustody) SnapshotID 

func (custody MaterializedRuntimeCustody) SnapshotID() string

type PlanDiff 

type PlanDiff struct {
	Changed             bool   `json:"changed"`
	CurrentPlanHash     string `json:"currentPlanHash"`
	TargetPlanHash      string `json:"targetPlanHash"`
	CurrentManifestHash string `json:"currentManifestHash"`
	TargetManifestHash  string `json:"targetManifestHash"`
}

type RecoveryCommand 

type RecoveryCommand func(
	context.Context,
	string,
	ExecutorStateSnapshot,
) error

RecoveryCommand receives the exact captured executable in a private, process-owned temporary directory after the captured StackSpec and optional Inventory have been restored atomically.

type Runner 

type Runner interface {
	Run(context.Context, string, []string, string) ([]byte, error)
}

type Target 

type Target struct {
	Kit           string                `json:"kit"`
	Version       string                `json:"version"`
	Channel       releaseindex.Channel  `json:"channel"`
	Platform      releaseindex.Platform `json:"platform"`
	Asset         string                `json:"asset"`
	ArchiveSHA256 string                `json:"archiveSha256"`
}

type VerifiedExecutorStateCapture 

type VerifiedExecutorStateCapture struct {
	// contains filtered or unexported fields
}

VerifiedExecutorStateCapture is an immutable authority handle created only after re-verifying the exact current Plan/Generation/Apply/Owner/Backup closure. No package outside upgradelifecycle can invoke state persistence from caller-assembled inputs.

func NewVerifiedExecutorStateCapture 

func NewVerifiedExecutorStateCapture(input CurrentStateAuthorityInput) (VerifiedExecutorStateCapture, error)

NewVerifiedExecutorStateCapture is the production authority constructor for one immutable current-state recovery closure. It performs no persistence.

func NewVerifiedLegacyExecutorStateCapture 

func NewVerifiedLegacyExecutorStateCapture(
	input LegacyCurrentStateAuthorityInput,
) (VerifiedExecutorStateCapture, error)

NewVerifiedLegacyExecutorStateCapture is the only cross-release constructor. It does not run the current CUE contract: the attested historical binary already supplied the exact PlanInspection and offline Verify proof. Everything that survives into rollback remains independently content-, release-, Owner-, and snapshot-bound here.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.