fleetlifecycle

package
v0.41.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: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	APIVersion = "stackkit.fleet-lifecycle/v1"
	Kind       = "FleetLifecycle"
)
View Source 
const (
	StateAPIVersion         = "stackkit.fleet-mutation-state/v1"
	PhaseEvidenceAPIVersion = "stackkit.fleet-mutation-evidence/v1"

	StatusRunning          = "running"
	StatusRecoveryRequired = "recovery-required"
	StatusSucceeded        = "succeeded"
	StatusRecovered        = "recovered"
)

Variables

This section is empty.

Functions

func NewOperationID 

func NewOperationID(operation Operation) (string, error)

NewOperationID returns a collision-resistant, readable local identity.

Types

type Approval 

type Approval struct {
	Required bool   `json:"required"`
	Class    string `json:"class"`
}

type ArtifactEvidence 

type ArtifactEvidence struct {
	Ref    string `json:"ref"`
	Digest string `json:"digest"`
}

type Authority 

type Authority struct {
	Source                        string      `json:"source"`
	PlanBinding                   PlanBinding `json:"planBinding"`
	OwnerApprovalRequired         bool        `json:"ownerApprovalRequired"`
	LocalCustodyRequired          bool        `json:"localCustodyRequired"`
	ProviderLifecycleOwned        bool        `json:"providerLifecycleOwned"`
	MultiServerOrchestrationOwned bool        `json:"multiServerOrchestrationOwned"`
	CredentialCustodyOwned        bool        `json:"credentialCustodyOwned"`
}

type CheckpointAuthority 

type CheckpointAuthority struct {
	Required bool   `json:"required"`
	Ref      string `json:"ref,omitempty"`
	Digest   string `json:"digest,omitempty"`
}

type Contract 

type Contract struct {
	APIVersion    string                          `json:"apiVersion"`
	Kind          string                          `json:"kind"`
	StackID       string                          `json:"stackId"`
	FleetRef      string                          `json:"fleetRef,omitempty"`
	SpecHash      string                          `json:"specHash"`
	InventoryHash string                          `json:"inventoryHash"`
	Scope         string                          `json:"scope"`
	Membership    Membership                      `json:"membership"`
	Authority     Authority                       `json:"authority"`
	Operations    map[Operation]OperationContract `json:"operations"`
}

func Project 

func Project(plan resolvedplan.ResolvedPlan) (Contract, error)

Project returns the exact compiler-owned fleet lifecycle contract carried by one integrity-valid ResolvedPlan. Callers do not reconstruct membership, operation semantics, or authority exclusions themselves.

type ControlAuthority 

type ControlAuthority struct {
	Mode             string   `json:"mode"`
	AuthoritySiteRef string   `json:"authoritySiteRef"`
	MemberRefs       []string `json:"memberRefs"`
}

type Evidence 

type Evidence struct {
	Schema         string   `json:"schema"`
	Immutable      bool     `json:"immutable"`
	LocalCustody   bool     `json:"localCustody"`
	RequiredPhases []string `json:"requiredPhases"`
}

type ExecuteInput 

type ExecuteInput struct {
	OperationID     string
	Operation       Operation
	CurrentPlan     resolvedplan.ResolvedPlan
	TargetPlan      resolvedplan.ResolvedPlan
	SourceMemberRef string
	TargetMemberRef string
	OwnerApproved   bool
}

type Executor 

type Executor interface {
	Prepare(context.Context, Mutation) (Preparation, error)
	ExecutePhase(context.Context, PhaseRequest) (ArtifactEvidence, error)
	Recover(context.Context, RecoveryRequest) (ArtifactEvidence, error)
}

Executor owns the finite local phase implementations. It receives no provider allocation, multi-server orchestration, or credential-custody authority from the lifecycle service.

type Member 

type Member struct {
	NodeRef            string   `json:"nodeRef"`
	SiteRef            string   `json:"siteRef"`
	Roles              []string `json:"roles"`
	Enabled            bool     `json:"enabled"`
	FailureDomain      string   `json:"failureDomain"`
	ControlPlaneMember bool     `json:"controlPlaneMember"`
}

type Membership 

type Membership struct {
	Members          []Member         `json:"members"`
	ControlAuthority ControlAuthority `json:"controlAuthority"`
}

type Mutation 

type Mutation struct {
	Authority MutationAuthority
	Contract  OperationContract
}

Mutation is the exact compiler-owned operation bound to current and target ResolvedPlans. The operation contract is kept beside the persisted authority so runners never reconstruct phases or approval semantics.

func BindMutation 

func BindMutation(
	currentPlan, targetPlan resolvedplan.ResolvedPlan,
	operation Operation,
	sourceMemberRef, targetMemberRef string,
) (Mutation, error)

BindMutation verifies both plans and admits only the membership delta owned by the selected compiler contract.

type MutationAuthority 

type MutationAuthority struct {
	StackID              string    `json:"stackId"`
	FleetRef             string    `json:"fleetRef,omitempty"`
	Operation            Operation `json:"operation"`
	CurrentPlanHash      string    `json:"currentPlanHash"`
	TargetPlanHash       string    `json:"targetPlanHash"`
	CurrentSpecHash      string    `json:"currentSpecHash"`
	TargetSpecHash       string    `json:"targetSpecHash"`
	CurrentInventoryHash string    `json:"currentInventoryHash"`
	TargetInventoryHash  string    `json:"targetInventoryHash"`
	SourceMemberRef      string    `json:"sourceMemberRef,omitempty"`
	TargetMemberRef      string    `json:"targetMemberRef,omitempty"`
	ContractDigest       string    `json:"contractDigest"`
}

MutationAuthority is the immutable authority carried by every durable fleet mutation record and phase-evidence document.

type MutationRecord 

type MutationRecord struct {
	ID               string              `json:"id"`
	Authority        MutationAuthority   `json:"authority"`
	OwnerRef         string              `json:"ownerRef"`
	Status           string              `json:"status"`
	CurrentPhase     string              `json:"currentPhase"`
	Attempt          uint64              `json:"attempt"`
	Checkpoint       CheckpointAuthority `json:"checkpoint"`
	Recovery         RecoveryAuthority   `json:"recovery"`
	Phases           []PhaseRecord       `json:"phases"`
	RecoveryEvidence *PhaseRecord        `json:"recoveryEvidence,omitempty"`
	LastError        string              `json:"lastError,omitempty"`
	StartedAt        time.Time           `json:"startedAt"`
	UpdatedAt        time.Time           `json:"updatedAt"`
	CompletedAt      time.Time           `json:"completedAt,omitempty"`
	PreviousDigest   string              `json:"previousDigest,omitempty"`
	Digest           string              `json:"digest"`
}

type Operation 

type Operation string
const (
	OperationAdd     Operation = "add"
	OperationReplace Operation = "replace"
	OperationDrain   Operation = "drain"
	OperationRecover Operation = "recover"
	OperationRemove  Operation = "remove"
)

type OperationContract 

type OperationContract struct {
	Name                 Operation `json:"name"`
	SourceMember         string    `json:"sourceMember"`
	TargetMember         string    `json:"targetMember"`
	TargetPlanRequired   bool      `json:"targetPlanRequired"`
	TargetPlanMustDiffer bool      `json:"targetPlanMustDiffer"`
	Mutation             bool      `json:"mutation"`
	Destructive          bool      `json:"destructive"`
	OwnerApproval        Approval  `json:"ownerApproval"`
	CheckpointRequired   bool      `json:"checkpointRequired"`
	RecoveryRequired     bool      `json:"recoveryRequired"`
	Phases               []string  `json:"phases"`
	Evidence             Evidence  `json:"evidence"`
}

type PhaseEvidence 

type PhaseEvidence struct {
	APIVersion             string                                        `json:"apiVersion"`
	OperationID            string                                        `json:"operationId"`
	Sequence               uint64                                        `json:"sequence"`
	Phase                  string                                        `json:"phase"`
	Status                 string                                        `json:"status"`
	Authority              MutationAuthority                             `json:"authority"`
	Checkpoint             CheckpointAuthority                           `json:"checkpoint"`
	Recovery               RecoveryAuthority                             `json:"recovery"`
	Artifact               ArtifactEvidence                              `json:"artifact"`
	PreviousEvidenceDigest string                                        `json:"previousEvidenceDigest,omitempty"`
	RecordedAt             time.Time                                     `json:"recordedAt"`
	Signature              localevidence.OwnerLifecycleMutationSignature `json:"signature"`
}

PhaseEvidence is an immutable, Owner-signed result for one compiler-owned fleet phase. The full document is stored under its content digest.

type PhaseRecord 

type PhaseRecord struct {
	Sequence uint64 `json:"sequence"`
	Phase    string `json:"phase"`
	Status   string `json:"status"`
	Ref      string `json:"ref"`
	Digest   string `json:"digest"`
}

type PhaseRequest 

type PhaseRequest struct {
	OperationID string
	Attempt     uint64
	Phase       string
	Authority   MutationAuthority
	Checkpoint  CheckpointAuthority
	Recovery    RecoveryAuthority
	Completed   []PhaseRecord
}

type PlanBinding 

type PlanBinding struct {
	CurrentHashField   string `json:"currentHashField"`
	TargetHashField    string `json:"targetHashField"`
	StackIdentityField string `json:"stackIdentityField"`
	FleetIdentityField string `json:"fleetIdentityField"`
	SpecIdentityField  string `json:"specIdentityField"`
	InventoryField     string `json:"inventoryField"`
}

type Preparation 

type Preparation struct {
	Checkpoint  ArtifactEvidence
	RecoveryRef string
}

type RecoveryAuthority 

type RecoveryAuthority struct {
	Required bool   `json:"required"`
	Ref      string `json:"ref"`
}

type RecoveryRequest 

type RecoveryRequest struct {
	OperationID string
	Attempt     uint64
	FailedPhase string
	LastError   string
	Authority   MutationAuthority
	Checkpoint  CheckpointAuthority
	Recovery    RecoveryAuthority
	Completed   []PhaseRecord
}

type Service 

type Service struct {
	Store    Store
	Executor Executor
	Now      func() time.Time
}

func (Service) Execute 

func (service Service) Execute(
	ctx context.Context,
	input ExecuteInput,
) (State, error)

Execute starts and completes one mutation through the exact compiler phase sequence. On any post-Begin failure the durable state is moved to recovery-required before the error is returned.

func (Service) Recover 

func (service Service) Recover(
	ctx context.Context,
	input ExecuteInput,
) (State, error)

Recover invokes the bounded recovery adapter and closes the exact operation without pretending that unfinished forward phases succeeded.

func (Service) Resume 

func (service Service) Resume(
	ctx context.Context,
	input ExecuteInput,
) (State, error)

Resume re-enters only the exact recovery-required operation and continues at its first phase without immutable evidence.

type State 

type State struct {
	APIVersion       string                                        `json:"apiVersion"`
	Kind             string                                        `json:"kind"`
	WorkspaceHash    string                                        `json:"workspaceHash"`
	StackID          string                                        `json:"stackId"`
	FleetRef         string                                        `json:"fleetRef,omitempty"`
	OwnerRef         string                                        `json:"ownerRef,omitempty"`
	CurrentPlanHash  string                                        `json:"currentPlanHash,omitempty"`
	CurrentOperation string                                        `json:"currentOperation,omitempty"`
	Operations       []MutationRecord                              `json:"operations"`
	UpdatedAt        time.Time                                     `json:"updatedAt,omitempty"`
	StateDigest      string                                        `json:"stateDigest,omitempty"`
	Signature        localevidence.OwnerLifecycleMutationSignature `json:"signature,omitempty"`
}

State is the one local fleet lifecycle projection consumed unchanged by the CLI, MCP status tool, and State Console.

type Store 

type Store struct {
	Workspace string
}

func (Store) BeginPrepared 

func (store Store) BeginPrepared(
	mutation Mutation,
	operationID string,
	ownerApproved bool,
	now time.Time,
	prepare func() (Preparation, error),
) (State, error)

BeginPrepared holds the fleet state lock while the caller establishes the exact checkpoint and recovery authority, then persists the first signed record before any mutation phase can run.

func (Store) Load 

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

Load verifies the complete signed state and every referenced immutable phase document. A missing state is represented as an empty projection.

func (Store) LoadForPlan 

func (store Store) LoadForPlan(plan resolvedplan.ResolvedPlan) (Contract, State, error)

LoadForPlan projects and verifies fleet state from the same canonical plan used by the runtime status surface.

func (Store) MarkRecovered 

func (store Store) MarkRecovered(
	mutation Mutation,
	operationID string,
	ownerApproved bool,
	artifact ArtifactEvidence,
	now time.Time,
) (State, error)

func (Store) RecordPhase 

func (store Store) RecordPhase(
	mutation Mutation,
	operationID string,
	artifact ArtifactEvidence,
	now time.Time,
) (State, error)

RecordPhase commits one successful phase as immutable Owner evidence. The next phase is always selected from the compiler contract, never by a caller.

func (Store) RequireRecovery 

func (store Store) RequireRecovery(
	mutation Mutation,
	operationID, diagnostic string,
	now time.Time,
) (State, error)

func (Store) Resume 

func (store Store) Resume(
	mutation Mutation,
	operationID string,
	ownerApproved bool,
	now time.Time,
) (State, error)

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.