applicationlifecycle

package
v0.40.0 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: 17 Imported by: 0

Documentation

Overview

Package applicationlifecycle persists the resumable state of every selected Application Kit. The state is bound to the exact ResolvedPlan and lifecycle contract; StackSpec and caller-supplied package identities are never read.

Index

Constants

View Source 
const (
	AxisVerified    = "verified"
	AxisUnverified  = "unverified"
	AxisRequired    = "required"
	AxisBlocked     = "blocked"
	AxisAbsent      = "absent"
	AxisNotRequired = "not-required"

	FreshnessLive       = "live"
	FreshnessHistorical = "historical"
	FreshnessNone       = "none"
)
View Source 
const (
	SetupResultAPIVersion = "stackkit.application-setup-result/v1"

	// VaultOwnerInviteActionRef is the sole action allowed to persist the
	// preparation facts below. They describe server-side invitation metadata;
	// neither fact proves personal login or client-side decryption.
	VaultOwnerInviteActionRef       = "vault-owner-invite"
	VaultOwnerPreparationInvited    = "owner-invited"
	VaultOwnerPreparationRegistered = "owner-registered"
)
View Source 
const (
	APIVersion = "stackkit.application-lifecycle-state/v1"

	StatusRunning          = "running"
	StatusSucceeded        = "succeeded"
	StatusFailed           = "failed"
	StatusRecoveryRequired = "recovery-required"
	StatusRecovered        = "recovered"
)
View Source 
const ExperienceSchemaVersion = "stackkit.application-experience/v1"

ExperienceSchemaVersion identifies the derived, read-only application experience projection. It is deliberately separate from the durable lifecycle state: the projection may be recomputed from the current Plan and the owner-custodied evidence at any time.

Variables

This section is empty.

Functions

func NewOperationID 

func NewOperationID(operationRef string) (string, error)

NewOperationID returns a collision-resistant local operation identity. The operationRef prefix keeps persisted state readable without making wall-clock time or a caller-provided identifier authoritative.

Types

type ApplicationExperience 

type ApplicationExperience struct {
	SchemaVersion string `json:"schemaVersion"`
	WorkloadRef   string `json:"workloadRef"`
	PackageRef    string `json:"packageRef"`
	// LifecycleVersion identifies the version of the lifecycle contract used
	// for this projection. It is deliberately named so consumers do not read
	// it as the version of the deployed application artifact.
	LifecycleVersion string `json:"lifecycleVersion"`
	ServiceRef       string `json:"serviceRef,omitempty"`
	URL              string `json:"url,omitempty"`

	Installed   ExperienceAxis `json:"installed"`
	Reachable   ExperienceAxis `json:"reachable"`
	Setup       ExperienceAxis `json:"setup"`
	Usable      ExperienceAxis `json:"usable"`
	Recoverable ExperienceAxis `json:"recoverable"`

	NextActions []string                `json:"nextActions,omitempty"`
	SetupAction *ApplicationSetupAction `json:"setupAction,omitempty"`
}

ApplicationExperience is a derived user-facing view of one selected Application workload. It is not a second lifecycle state machine.

func ProjectExperience 

func ProjectExperience(input ExperienceInput) (ApplicationExperience, error)

ProjectExperience deterministically derives the five independent experience axes for one workload. It is intentionally conservative: healthy health evidence can establish the health of the bound probe target, but it cannot establish client-view route reachability, installation, runtime, setup completion, or usability. A staged restore result likewise never establishes application recovery until a typed activation receipt is validated by a caller.

type ApplicationSetupAction 

type ApplicationSetupAction struct {
	OperationRef                 string   `json:"operationRef"`
	WorkloadRef                  string   `json:"workloadRef"`
	Title                        string   `json:"title"`
	CredentialFields             []string `json:"credentialFields"`
	CredentialsFile              string   `json:"credentialsFile"`
	GuideURL                     string   `json:"guideUrl"`
	SupportsOnboardingCompletion bool     `json:"supportsOnboardingCompletion"`
}

ApplicationSetupAction points to the shared operation catalog. The CLI still re-admits the current Plan and exact runtime before any mutation.

type Authority 

type Authority struct {
	PlanHash              string `json:"planHash"`
	LifecycleContractHash string `json:"lifecycleContractHash"`
	LifecycleVersion      string `json:"lifecycleVersion"`
	PackageRef            string `json:"packageRef"`
}

type BeginRequest 

type BeginRequest struct {
	ID           string
	Stage        string
	OperationRef string
	Now          time.Time
}

type Contract 

type Contract struct {
	WorkloadRef  string
	PackageRef   string
	Version      string
	ContractHash string
	PlanHash     string
	Delivery     DeliveryContract
	Stages       map[string]StageContract
}

func ContractFromResolvedPlan 

func ContractFromResolvedPlan(plan resolvedplan.ResolvedPlan, workloadRef string) (Contract, error)

ContractFromResolvedPlan returns the only lifecycle contract runtimes may consume. The selected application and package are read from the compiled, authority-bound projection.

func ContractsFromResolvedPlan 

func ContractsFromResolvedPlan(plan resolvedplan.ResolvedPlan) ([]Contract, error)

ContractsFromResolvedPlan returns the complete, deterministically ordered application lifecycle projection from one verified canonical ResolvedPlan.

type DeliveryCapabilities 

type DeliveryCapabilities struct {
	Deployment     bool
	RouteTLS       bool
	StatusEvidence bool
	BackupRestore  bool
}

DeliveryCapabilities is the compiler-bound support row for the exact runtime adapter selected by one Application workload. It is catalog authority, not live evidence. Backup/restore remains false until that adapter owns a complete executable lifecycle.

type DeliveryContract 

type DeliveryContract struct {
	Kind         string
	AdapterRef   string
	Capabilities *DeliveryCapabilities
}

type Evidence 

type Evidence struct {
	Kind   string `json:"kind"`
	Ref    string `json:"ref"`
	Digest string `json:"digest"`
}

Evidence is an immutable content-addressed proof produced by the operation named in the ResolvedPlan lifecycle contract. Ref is a local owner-custody path or another stable identifier; Digest always identifies its exact bytes.

type ExperienceAxis 

type ExperienceAxis struct {
	ActivationStatus string               `json:"activationStatus,omitempty"`
	Status           string               `json:"status"`
	Reason           string               `json:"reason,omitempty"`
	Freshness        string               `json:"freshness"`
	ObservedAt       time.Time            `json:"observedAt,omitempty"`
	Evidence         []ExperienceEvidence `json:"evidence,omitempty"`
}

ExperienceAxis is one independently evaluated application state axis. Status is intentionally explicit: missing or stale evidence is unverified, never silently promoted to ready.

type ExperienceEvidence 

type ExperienceEvidence struct {
	Kind   string `json:"kind"`
	Ref    string `json:"ref"`
	Digest string `json:"digest,omitempty"`
}

ExperienceEvidence is a secret-free pointer to the proof used for one axis. A reference without a digest remains explanatory evidence only and cannot turn an axis into a verified state by itself.

type ExperienceInput 

type ExperienceInput struct {
	RestoreActivation *RestoreActivationInput
	Contract          Contract
	State             State
	ServiceRef        string
	RouteRef          string
	URL               string
	HealthRef         string
	RuntimeTargets    []RuntimeTarget
	Setup             SetupInput
	Observations      []runtimeobservation.Observation
}

ExperienceInput contains only current-plan bindings and read-only evidence already accepted by the CLI. No function here performs runtime, network, or backup operations.

type Operation 

type Operation struct {
	ID             string     `json:"id"`
	Stage          string     `json:"stage"`
	OperationRef   string     `json:"operationRef"`
	Status         string     `json:"status"`
	Attempt        uint64     `json:"attempt"`
	StartedAt      time.Time  `json:"startedAt"`
	UpdatedAt      time.Time  `json:"updatedAt"`
	CompletedAt    time.Time  `json:"completedAt,omitempty"`
	Authority      Authority  `json:"authority"`
	Evidence       []Evidence `json:"evidence"`
	LastError      string     `json:"lastError,omitempty"`
	RecoveryRef    string     `json:"recoveryRef,omitempty"`
	PreviousDigest string     `json:"previousDigest,omitempty"`
	Digest         string     `json:"digest"`
}

type RestoreActivationInput 

type RestoreActivationInput struct {
	OperationID string
	PlanHash    string
	Status      string
	Evidence    Evidence
	VerifiedAt  time.Time
}

RestoreActivationInput is a signed result already authenticated by the caller. It records runtime activation only; it cannot prove application-data readback.

type RuntimeTarget 

type RuntimeTarget struct {
	RequirementID string
	InstanceRef   string
}

RuntimeTarget binds a runtime observation requirement to the selected workload. Requirement and instance identities come from the verified Plan.

type SetupInput 

type SetupInput struct {
	PlanHash    string
	WorkloadRef string
	Policy      string
	ActionRefs  []string
	Runs        []SetupRun
}

SetupInput carries plan-declared setup actions and the currently observed setup records. The caller is responsible for selecting records by the exact workload identity from the current Plan.

type SetupResult 

type SetupResult struct {
	APIVersion         string    `json:"apiVersion"`
	Authority          Authority `json:"authority"`
	WorkloadRef        string    `json:"workloadRef"`
	OperationID        string    `json:"operationId"`
	ActionRef          string    `json:"actionRef"`
	ApplyResultHash    string    `json:"applyResultHash"`
	ArtifactDigest     string    `json:"artifactDigest"`
	InstanceRef        string    `json:"instanceRef"`
	ApplicationVersion string    `json:"applicationVersion"`
	AccountRef         string    `json:"accountRef"`
	Initialized        bool      `json:"initialized"`
	AdminLoginVerified bool      `json:"adminLoginVerified"`
	OnboardingComplete bool      `json:"onboardingComplete"`
	Preparation        string    `json:"preparation,omitempty"`
	VerifiedAt         time.Time `json:"verifiedAt"`
}

SetupResult is a secret-free observation of the application API. It is evidence for the existing application lifecycle, not a second setup state.

type SetupRun 

type SetupRun struct {
	// Set by SetupRuns for current-authority operations, even before a terminal
	// setup receipt exists. Completion still requires authenticated evidence.
	PlanHash string

	WorkloadRef   string
	AppName       string
	DropName      string
	RunID         string
	Policy        string
	Status        string
	Phase         string
	Message       string
	Error         string
	Evidence      []ExperienceEvidence
	LastRequested time.Time
	LastStarted   time.Time
	LastFinished  time.Time
	// contains filtered or unexported fields
}

SetupRun is the secret-free setup state consumed by the derived projection. PlanHash is populated only for an operation whose lifecycle Authority exactly matches the current Plan. Legacy and prior-Plan records leave it empty and cannot affect the current setup axis.

type StageContract 

type StageContract struct {
	Name          string
	Operations    []string
	Phases        []string
	Evidence      []string
	Mutation      bool
	Destructive   bool
	OwnerApproval bool
}

type State 

type State struct {
	APIVersion       string      `json:"apiVersion"`
	WorkloadRef      string      `json:"workloadRef"`
	Authority        Authority   `json:"authority"`
	CurrentOperation string      `json:"currentOperation,omitempty"`
	Operations       []Operation `json:"operations"`
	UpdatedAt        time.Time   `json:"updatedAt"`
	StateDigest      string      `json:"stateDigest"`
}

type Store 

type Store struct {
	Workspace string
}

func (Store) Begin 

func (store Store) Begin(contract Contract, request BeginRequest) (State, error)

func (Store) Load 

func (store Store) Load(contract Contract) (State, error)

func (Store) SaveSetupResult 

func (store Store) SaveSetupResult(contract Contract, result SetupResult) (Evidence, error)

SaveSetupResult seals one result before the existing lifecycle operation becomes terminal. A crash may leave an unreferenced immutable receipt; a retry re-observes the app and can safely finalize the same operation.

func (Store) SetupRuns 

func (store Store) SetupRuns(contract Contract, applyResultHash, actionRef string) ([]SetupRun, error)

SetupRuns projects the existing journal. Only operations with the exact current lifecycle Authority enter the current setup axis. An operation may be current and failed/running without a terminal receipt; only a matching signed Apply-bound receipt gains a verified setup result.

func (Store) Transition 

func (store Store) Transition(contract Contract, request TransitionRequest) (State, error)

type TransitionRequest 

type TransitionRequest struct {
	ID          string
	Status      string
	Evidence    []Evidence
	LastError   string
	RecoveryRef string
	Now         time.Time
}

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.