Help us shape the future of Go! Take the 2026 Go Developer Survey

restoreactivation

package
v0.53.16 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Overview

Package restoreactivation derives and executes the fail-closed authority for promoting an owner-verified staged restore into the live kit core runtime (Basement Full-Core or CoreLite, or the Cloud standalone core).

Index

Constants

View Source 
const (
	// The workload's selected adapter row does not declare backupRestore: its
	// data is outside the node's signed Kopia source. Shared with the backup gate.
	ReasonApplicationRestoreAdapterUnsupported = actionableerror.ReasonSelectedAdapterBackupRestoreUnavailable
	// The workload restores with the node (standalone Compose); only a
	// platform-managed workload (Coolify, Komodo) activates on its own.
	ReasonApplicationRestoreScopeUnsupported = "application_restore_scope_unsupported"
	// The Plan selects no such application workload.
	ReasonApplicationRestoreWorkloadUnselected = "application_restore_workload_unselected"
	// The restore staged none of the workload's volumes under its coverage.
	ReasonApplicationRestoreWorkloadNotStaged = "application_restore_workload_not_staged"
)

Closed reasons for a workload-scoped restore the selected delivery cannot serve. Each refuses before staging verification, safety snapshot, journal or manager control, so no live volume is touched.

View Source 
const (
	StageStagedResult          = "staged-result"
	StageAuthorityRevalidation = "authority-revalidation"
	StagePrepareMutation       = "prepare-mutation"
	StageRuntimeInspect        = "runtime-inspect"
	StageStagingValidate       = "staging-validate"
	StageSafetySnapshot        = "safety-snapshot"
	StageJournalBegin          = "journal-begin"
	StageResultSign            = "result-sign"

	// Steps the command takes before it hands over to Activate.
	StageCommandAuthority = "command-authority"
	StagePlanManifest     = "plan-manifest"
	StageRestoreResult    = "restore-result"
	StageRuntimeBind      = "runtime-bind"
)

Closed pre-journal activation steps. After the journal begins, a failure is tagged with the journal phase it reached instead.

View Source 
const (
	// RuntimeRecoveryGraphAPIVersion identifies the canonical derived runtime
	// graph that can later be placed in an owner-signed recovery snapshot.
	RuntimeRecoveryGraphAPIVersion = "stackkit.restoreactivation-runtime-recovery-graph/v1"
	RuntimeRecoveryGraphKind       = "RuntimeRecoveryGraph"
)
View Source 
const (
	ResultAPIVersion = "stackkit.restore-activation-result/v1"
)

Variables

View Source 
var ErrCoreBackupSourceAbsent = errors.New("restoreactivation: the kit core declares no local Kopia backup source")

ErrCoreBackupSourceAbsent reports a verified plan whose kit core declares no local Kopia backup source this package can restore. It fails closed: such a kit (for example the Coolify Cloud core, whose recovery is the offsite backup owner) has no staged restore, drill or activation here.

Functions

func BindApplicationControls added in v0.53.13 

func BindApplicationControls(base Runtime, observe func(context.Context, string) (backupexec.QuiesceContainer, error), driver func(string, string, string) (backuplifecycle.RuntimeControlDriver, error)) error

func NotStarted added in v0.53.10 

func NotStarted(stage string, err error) error

NotStarted tags a failure that happened before the activation service ran, so no live volume was touched, with the closed step it happened at.

func ResultEvidence 

func ResultEvidence(workspace string, result Result) (string, string, error)

ResultEvidence returns the immutable owner-custody location and digest of the exact signed activation result bytes persisted by the service.

func StandaloneComposeWorkloadHoldsNoBackupData added in v0.53.15 

func StandaloneComposeWorkloadHoldsNoBackupData(canonicalPlan []byte, workloadRef string) (bool, error)

StandaloneComposeWorkloadHoldsNoBackupData reports whether the verified plan delivers the application workload through standalone Compose without any backup-enabled storage. Such a workload (Remote's Guacamole, the ntfy live relay) contributes nothing to the node's signed backup source, so the backup gate admits it exactly as restore skips it. Any other or unreadable shape returns false and stays denied.

func VerifyResult 

func VerifyResult(workspace string, result Result) error

Types

type ActivateInput 

type ActivateInput struct {
	MarketplaceService string
	WorkloadRef        string
	WorkspaceRoot      string
	OperationID        string
	ExpectedPlanHash   string
	OwnerApproved      bool
	Plan               generationartifact.VerifiedPlan
	Manifest           generationartifact.ArtifactManifest
	RestoreResult      backuplifecycle.RestoreResult
	CurrentLineage     backuplifecycle.AuthorityLineage
	// RevalidateCurrentAuthority reads the existing current authority while
	// the shared lifecycle lock is held; cached preflight is not admission.
	RevalidateCurrentAuthority func(context.Context) (generationartifact.VerifiedPlan, backuplifecycle.AuthorityLineage, error)
	// PrepareMutation acquires existing application-specific quiescence only
	// after admission. Its release runs before the lifecycle lock is closed.
	PrepareMutation      func(context.Context) (func() error, error)
	CreateSafetySnapshot func(context.Context, string) (backuplifecycle.SnapshotAnchor, error)
	VerifyLive           func(context.Context) (LiveVerification, error)
	FinalizeResult       func(context.Context, Result, error) error
}

type ActivationNotStartedError added in v0.42.1 

type ActivationNotStartedError struct {
	Cause error
}

ActivationNotStartedError reports that activation failed before its recovery journal existed, so no live volume was touched and there is nothing to recover. Callers record the requested restore as failed.

func (*ActivationNotStartedError) Error added in v0.42.1 

func (err *ActivationNotStartedError) Error() string

func (*ActivationNotStartedError) Unwrap added in v0.42.1 

func (err *ActivationNotStartedError) Unwrap() error

type ActivationRecoveredError 

type ActivationRecoveredError struct {
	Cause  error
	Result Result
}

ActivationRecoveredError reports that activation failed but the prior live state was restored and its signed result was persisted. Callers must record the requested restore as recovered rather than asking for an impossible second recovery of the terminal journal.

func (*ActivationRecoveredError) Error 

func (err *ActivationRecoveredError) Error() string

func (*ActivationRecoveredError) Unwrap 

func (err *ActivationRecoveredError) Unwrap() error

type ApplicationRestoreUnsupportedError added in v0.53.12 

type ApplicationRestoreUnsupportedError struct {
	WorkloadRef string
	AdapterRef  string
	Reason      string
}

ApplicationRestoreUnsupportedError names why `backup restore activate --workload` refused. It carries identifiers only, never data or credentials.

func (*ApplicationRestoreUnsupportedError) ActionableError added in v0.53.12 

func (e *ApplicationRestoreUnsupportedError) ActionableError() actionableerror.Contract

func (*ApplicationRestoreUnsupportedError) ActionableStatus added in v0.53.12 

func (e *ApplicationRestoreUnsupportedError) ActionableStatus() string

An adapter without backup/restore is a denial, like the backup gate; a node-scoped or unknown selection is a failed request.

func (*ApplicationRestoreUnsupportedError) Error added in v0.53.12 

func (e *ApplicationRestoreUnsupportedError) Error() string

type Authority 

type Authority struct {
	OperationID          string           `json:"operationId"`
	RenderTarget         string           `json:"renderTarget,omitempty"`
	OwnerRef             string           `json:"ownerRef"`
	RestoreResultID      string           `json:"restoreResultId"`
	PlanHash             string           `json:"planHash"`
	ManifestHash         string           `json:"manifestHash"`
	ApplyResultHash      string           `json:"applyResultHash"`
	ManagedVolumeSetHash string           `json:"managedVolumeSetHash"`
	StackID              string           `json:"stackId"`
	ComposeProject       string           `json:"composeProject"`
	ComposePath          string           `json:"composePath"`
	ComposeDigest        string           `json:"composeDigest"`
	ComposeRuntimes      []ComposeRuntime `json:"composeRuntimes"`
	KopiaHelperImage     string           `json:"kopiaHelperImage"`
	StagingVolume        string           `json:"stagingVolume"`
	StagingPath          string           `json:"stagingPath"`
	Volumes              []string         `json:"volumes"`
	VolumeDetails        []Volume         `json:"volumeDetails"`
}

Authority is the immutable, plan-derived boundary for one restore activation. Volumes is the canonical sorted LiveName set used by the shared lifecycle journal; VolumeDetails carries the corresponding cutover paths.

func ApplicationAuthorityForVolumes added in v0.53.8 

func ApplicationAuthorityForVolumes(workspace string, plan generationartifact.VerifiedPlan, manifest generationartifact.ArtifactManifest, result backuplifecycle.RestoreResult, operation string, volumes []string) (Authority, string, bool, error)

ApplicationAuthorityForVolumes re-resolves a narrowed recovery from the original journal's exact canonical set; no caller-selected recovery scope.

func BindRuntimeRecoveryGraph 

func BindRuntimeRecoveryGraph(graph RuntimeRecoveryGraph, restoreResult backuplifecycle.RestoreResult) (Authority, error)

BindRuntimeRecoveryGraph binds historical graph data to the exact staged restore result. The lifecycle owner must verify custody of both inputs before using the returned projection; this function grants no mutation permission.

func DeriveApplicationAuthority added in v0.53.8 

func DeriveApplicationAuthority(workspace string, plan generationartifact.VerifiedPlan, manifest generationartifact.ArtifactManifest, result backuplifecycle.RestoreResult, operation, workload string) (Authority, error)

DeriveApplicationAuthority narrows a verified node restore to one selected managed workload. Names remain canonical; the existing manager custody adapter translates them at the Docker copy boundary, never in the journal.

func DeriveAuthority 

func DeriveAuthority(
	workspaceRoot string,
	plan generationartifact.VerifiedPlan,
	manifest generationartifact.ArtifactManifest,
	restoreResult backuplifecycle.RestoreResult,
	operationID string,
) (Authority, error)

DeriveAuthority binds a staged, owner-verified restore to the exact kit core plan and generation manifest without consulting mutable policy defaults.

func DeriveMarketplaceServiceAuthority added in v0.53.13 

func DeriveMarketplaceServiceAuthority(workspace string, plan generationartifact.VerifiedPlan, manifest generationartifact.ArtifactManifest, result backuplifecycle.RestoreResult, operation, service string) (Authority, error)

type CloudSessionStorage added in v0.53.9 

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

CloudSessionStorage reuses the restore runtime's isolated copy/digest primitives. Its authority is an existing signed component transaction, never a fabricated current Plan or Apply result.

func NewCloudSessionStorage added in v0.53.9 

func NewCloudSessionStorage(workspace string) (*CloudSessionStorage, error)

func (*CloudSessionStorage) DigestLive added in v0.53.9 

func (s *CloudSessionStorage) DigestLive(ctx context.Context, state localevidence.CloudSessionRouting) (string, error)

func (*CloudSessionStorage) RestoreOriginal added in v0.53.9 

func (s *CloudSessionStorage) RestoreOriginal(ctx context.Context, state localevidence.CloudSessionRouting) error

func (*CloudSessionStorage) Snapshot added in v0.53.9 

func (s *CloudSessionStorage) Snapshot(ctx context.Context, state localevidence.CloudSessionRouting, target bool) error

Snapshot copies only a quiesced TinyAuth volume to the journal-derived private original or target-retention volume and verifies every file's hash.

type ComposeRuntime 

type ComposeRuntime struct {
	Project           string                    `json:"project"`
	Path              string                    `json:"path"`
	Digest            string                    `json:"digest"`
	EnvironmentPath   string                    `json:"environmentPath,omitempty"`
	EnvironmentDigest string                    `json:"environmentDigest,omitempty"`
	Readiness         []ComposeRuntimeReadiness `json:"readiness,omitempty"`
	// StatePath and StateDigest bind the OpenTofu state of the root that
	// applies this Compose project under the opentofu and terramate targets,
	// so the state is restored and verified alongside the project's data.
	StatePath   string `json:"statePath,omitempty"`
	StateDigest string `json:"stateDigest,omitempty"`
	// Execution and RootConfigDigest retain the execution owning that bound
	// state. Empty execution is the Compose wrapper; native-docker must restart
	// existing containers rather than replace OpenTofu's resources with Compose.
	Execution        string `json:"execution,omitempty"`
	RootConfigDigest string `json:"rootConfigDigest,omitempty"`
}

ComposeRuntime binds one local Compose project to the exact owner-custody bytes that were verified before restore mutation. The kit core runtime and every selected standalone-compose Application and native Marketplace installation are represented independently. PaaS-deployed applications and remote runtimes are outside this authority.

type ComposeRuntimeReadiness 

type ComposeRuntimeReadiness struct {
	ComponentRef  string `json:"componentRef"`
	Lifecycle     string `json:"lifecycle"`
	HealthFailure string `json:"healthFailure"`
}

ComposeRuntimeReadiness carries the CUE-owned component health impact into restore activation. It lets activation wait for every blocking component while retaining a degraded component's healthcheck and diagnostics.

type LiveVerification 

type LiveVerification = backuplifecycle.RestoreVerification

type MarketplaceRuntimeCustody added in v0.53.1 

type MarketplaceRuntimeCustody struct {
	Document architecturev2renderer.MarketplaceCoolifyDocument
	Runtime  ComposeRuntime
	Volumes  []Volume
	Files    []StandaloneComposeRuntimeFile
}

MarketplaceRuntimeCustody retains the native installation selected by the verified plan. It grants no authority over applications deployed by a PaaS.

func DeriveHistoricalMarketplaceRuntimeCustody added in v0.53.4 

func DeriveHistoricalMarketplaceRuntimeCustody(workspace string, plan generationartifact.HistoricalPlan, manifest generationartifact.ArtifactManifest, operation string) (*MarketplaceRuntimeCustody, error)

func DeriveMarketplaceRuntimeCustody added in v0.53.1 

func DeriveMarketplaceRuntimeCustody(workspace string, plan generationartifact.VerifiedPlan, manifest generationartifact.ArtifactManifest, operationID string) (*MarketplaceRuntimeCustody, error)

type RecoverInput 

type RecoverInput struct {
	WorkspaceRoot    string
	OperationID      string
	ExpectedPlanHash string
	OwnerApproved    bool
	VerifyLive       func(context.Context) (LiveVerification, error)
	FinalizeResult   func(context.Context, Result, error) error
}

type RecoveryAuthorityResolver 

type RecoveryAuthorityResolver func(
	context.Context,
	lifecyclemutation.RestoreActivationAuthority,
) (Authority, error)

type Result 

type Result struct {
	APIVersion           string                                        `json:"apiVersion"`
	OperationID          string                                        `json:"operationId"`
	RestoreResultID      string                                        `json:"restoreResultId"`
	SafetySnapshotID     string                                        `json:"safetySnapshotId"`
	PlanHash             string                                        `json:"planHash"`
	ManagedVolumeSetHash string                                        `json:"managedVolumeSetHash"`
	Status               string                                        `json:"status"`
	Verification         LiveVerification                              `json:"verification"`
	Signature            localevidence.OwnerRestoreActivationSignature `json:"signature"`
}

func ReadResult 

func ReadResult(workspace, operationID string) (Result, error)

ReadResult reads the canonical persisted result and verifies its local Owner signature. Callers must additionally bind it to their current Plan and operation evidence.

type Runtime 

type Runtime interface {
	Inspect(context.Context, Authority) error
	ValidateStaging(context.Context, Authority) error
	Stop(context.Context, Authority) error
	PrepareRollback(context.Context, Authority, Volume) error
	ActivateVolume(context.Context, Authority, Volume) error
	RestoreVolume(context.Context, Authority, Volume) error
	Start(context.Context, Authority) error
	CleanupRollback(context.Context, Authority, Volume) error
	// DigestVolume reads one volume back, read-only, as a deterministic file
	// tree digest: the staged restore content or the live volume.
	DigestVolume(context.Context, Authority, Volume, bool) (backuplifecycle.VolumeReadback, error)
}

func NewDockerRuntime 

func NewDockerRuntime(workspace string) (Runtime, error)

func WithApplicationBinding added in v0.53.8 

func WithApplicationBinding(base Runtime, authority Authority, binding backupexec.ApplicationRuntimeBinding, current func(context.Context) (backupexec.ApplicationRuntimeBinding, error)) (Runtime, error)

WithApplicationBinding delegates service control to the retained manager while reusing the native activation copy, rollback and readback machinery. The callback must re-read signed current custody, including observed mounts.

func WithMarketplaceService added in v0.53.13 

func WithMarketplaceService(base Runtime, a Authority, s localbackuppolicy.MarketplaceService, observe func(context.Context) (backupexec.QuiesceContainer, error), driver backuplifecycle.RuntimeControlDriver) (Runtime, error)

Store data remains upstream-owned. This adapter supplies observation and native manager control to the existing activation/copy/rollback lifecycle.

type RuntimeRecoveryGraph 

type RuntimeRecoveryGraph struct {
	APIVersion           string                         `json:"apiVersion"`
	Kind                 string                         `json:"kind"`
	OperationID          string                         `json:"operationId"`
	RenderTarget         string                         `json:"renderTarget,omitempty"`
	PlanBinding          generationartifact.PlanBinding `json:"planBinding"`
	PlanHash             string                         `json:"planHash"`
	ManifestHash         string                         `json:"manifestHash"`
	ManagedVolumeSetHash string                         `json:"managedVolumeSetHash"`
	StackID              string                         `json:"stackId"`
	ComposeProject       string                         `json:"composeProject"`
	ComposePath          string                         `json:"composePath"`
	ComposeDigest        string                         `json:"composeDigest"`
	ComposeRuntimes      []ComposeRuntime               `json:"composeRuntimes"`
	CorePolicyArtifactID string                         `json:"corePolicyArtifactId"`
	CorePolicyPath       string                         `json:"corePolicyPath"`
	CorePolicyDigest     string                         `json:"corePolicyDigest"`
	KopiaHelperImage     string                         `json:"kopiaHelperImage"`
	StagingVolume        string                         `json:"stagingVolume"`
	StagingRoot          string                         `json:"stagingRoot"`
	Volumes              []string                       `json:"volumes"`
	VolumeDetails        []Volume                       `json:"volumeDetails"`
}

RuntimeRecoveryGraph is canonical derived runtime custody data from a verified plan, its generation manifest, and one operation identity. Its future signed snapshot or opaque materialization handle supplies immutable authority; this caller-mutable value is never a VerifiedPlan or mutation authorization by itself. Staging paths are deliberately absent from VolumeDetails until a real, verified RestoreResult is bound.

RenderTarget is empty for the compose generation target, which keeps the Compose graph byte-identical to graphs signed before OpenTofu targets. For the opentofu and terramate targets it names the target, every Compose runtime is the runtime Compose file its OpenTofu root writes, and every runtime carries the state of that root.

func DeriveHistoricalRuntimeRecoveryGraph added in v0.53.4 

func DeriveHistoricalRuntimeRecoveryGraph(workspace string, plan generationartifact.HistoricalPlan, manifest generationartifact.ArtifactManifest, operation string) (RuntimeRecoveryGraph, error)

func DeriveRuntimeRecoveryGraph 

func DeriveRuntimeRecoveryGraph(
	workspaceRoot string,
	plan generationartifact.VerifiedPlan,
	manifest generationartifact.ArtifactManifest,
	operationID string,
) (RuntimeRecoveryGraph, error)

DeriveRuntimeRecoveryGraph derives the current CUE-owned runtime graph without manufacturing a restore result. The returned graph is suitable for later owner-signed custody, while parsed graph data remains non-authorizing.

func ParseRuntimeRecoveryGraph 

func ParseRuntimeRecoveryGraph(data []byte) (RuntimeRecoveryGraph, error)

ParseRuntimeRecoveryGraph accepts only the exact canonical JSON emitted by MarshalCanonical and never turns the result into a verified plan.

func ReconcileRuntimeExecution added in v0.52.5 

func ReconcileRuntimeExecution(graph RuntimeRecoveryGraph, configurations map[string][]byte) (RuntimeRecoveryGraph, error)

ReconcileRuntimeExecution derives execution only from configuration bytes the lifecycle caller has authenticated in the same retained checkpoint as the graph's state. It does not read live files or rewrite signed history.

func (RuntimeRecoveryGraph) MarshalCanonical 

func (graph RuntimeRecoveryGraph) MarshalCanonical() ([]byte, error)

MarshalCanonical emits the one stable JSON representation used by signed recovery custody. It does not add CUE or runtime authorization semantics.

func (RuntimeRecoveryGraph) Validate 

func (graph RuntimeRecoveryGraph) Validate() error

Validate checks the closed, portable shape and internal bindings of a graph. It validates graph data only; it does not re-resolve CUE or authorize a mutation.

type Service 

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

func NewService 

func NewService(runtime Runtime, resolver RecoveryAuthorityResolver) (*Service, error)

func (*Service) Activate 

func (service *Service) Activate(ctx context.Context, input ActivateInput) (result Result, returnErr error)

func (*Service) Recover 

func (service *Service) Recover(ctx context.Context, input RecoverInput) (Result, error)

type StageError added in v0.53.10 

type StageError struct {
	Stage string
	Cause error
}

StageError names the closed activation step at which activation failed, so a caller can report it without exposing the cause text. Error returns the cause unchanged.

func (*StageError) Error added in v0.53.10 

func (err *StageError) Error() string

func (*StageError) Unwrap added in v0.53.10 

func (err *StageError) Unwrap() error

type StagedRestoreRemover added in v0.46.5 

type StagedRestoreRemover interface {
	RemoveStagedRestore(ctx context.Context, graph RuntimeRecoveryGraph, stagingPath string) error
}

StagedRestoreRemover removes one operation's staged restore tree from the governed staging volume. It is implemented by the Docker runtime and is used by the Advanced restore drill, which must leave no staged data behind and must never mount or modify a live application volume, and after a committed restore activation, whose staged data is then the live state.

type StandaloneComposeRuntimeCustody 

type StandaloneComposeRuntimeCustody struct {
	Project     string
	Runtime     ComposeRuntime
	Bundle      StandaloneComposeRuntimeFile
	Compose     StandaloneComposeRuntimeFile
	Environment StandaloneComposeRuntimeFile
	ConfigFiles []StandaloneComposeRuntimeFile
}

StandaloneComposeRuntimeCustody contains the generated runtime files that must travel with one standalone Compose application. Its contents are derived from the same CUE-owned runtime graph used by restore activation.

func DeriveHistoricalStandaloneComposeRuntimeCustody added in v0.53.4 

func DeriveHistoricalStandaloneComposeRuntimeCustody(workspace string, plan generationartifact.HistoricalPlan, manifest generationartifact.ArtifactManifest, operation string) ([]StandaloneComposeRuntimeCustody, error)

func DeriveStandaloneComposeRuntimeCustody 

func DeriveStandaloneComposeRuntimeCustody(
	workspaceRoot string,
	plan generationartifact.VerifiedPlan,
	manifest generationartifact.ArtifactManifest,
	operationID string,
) ([]StandaloneComposeRuntimeCustody, error)

DeriveStandaloneComposeRuntimeCustody reads and verifies the exact owner-local standalone Compose runtime files selected by a verified plan. It shares restore activation's CUE/runtime binding and is intended for inclusion in another owner-signed recovery closure.

type StandaloneComposeRuntimeFile 

type StandaloneComposeRuntimeFile struct {
	Path string
	Mode string
	Data []byte
}

StandaloneComposeRuntimeFile is one owner-local runtime file that belongs to a selected standalone Compose application. The bytes are returned only to the caller that is building an owner-signed recovery closure.

type Volume 

type Volume struct {
	MarketplaceService   string `json:"marketplaceService,omitempty"`
	MarketplaceComponent string `json:"marketplaceComponent,omitempty"`
	ComponentRef         string `json:"componentRef"`
	LogicalName          string `json:"logicalName"`
	ComposeProject       string `json:"composeProject"`
	LiveName             string `json:"liveName"`
	StagingPath          string `json:"stagingPath"`
	RollbackName         string `json:"rollbackName"`
}

Volume is one exact persistent backup volume selected by the kit core runtime. LogicalName comes from the component graph; LiveName is the Compose-qualified Docker volume name. RollbackName is deterministic for the activation operation and never caller supplied.

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.