install

package
v0.8.3 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Overview

Package install owns the durable authority and orchestration contracts for the guided single-host installer. It deliberately does not import terminal presentation or deployment-manifest packages.

Index

Constants

View Source 
const (
	ExecutionBundleEstimateBytes      = int64(11 << 30)
	MinimumWorkspaceBytes             = standardresources.DurableCodingWorkspaceBytes
	MinimumBackingReserveBytes        = int64(16 << 30)
	MinimumControlBackingBytes        = MinimumBackingReserveBytes
	MinimumDeploymentBytes            = ExecutionBundleEstimateBytes
	RunnerStorageReserveBytes         = int64(4 << 30)
	MinimumRunnerStorageBytes         = ExecutionBundleEstimateBytes + MinimumWorkspaceBytes + RunnerStorageReserveBytes
	MinimumFilesystemImageBytes       = MinimumRunnerStorageBytes
	MinimumHostMemoryBytes            = int64(12 << 30)
	HostMemoryReserveBytes            = int64(4 << 30)
	MinimumHostCPUCount               = 6
	HostVCPUReserveCount              = int64(2)
	DurableCodingVCPUCount            = standardresources.DurableCodingVCPUCount
	DurableCodingMemoryBytes          = standardresources.DurableCodingMemoryBytes
	DurableCodingConcurrentOperations = standardresources.DurableCodingConcurrentOperations
	SingleHostFirecrackerCPUTemplate  = "None"
)
View Source 
const (
	HostFactsSchema = "secondbox.install.host-facts/v1"
	PlanSchemaV1    = "secondbox.install.plan/v1"
	PlanSchema      = "secondbox.install.plan/v2"
	ReceiptSchemaV1 = "secondbox.install.receipt/v1"
	ReceiptSchema   = "secondbox.install.receipt/v2"
)

Variables

View Source 
var StageSequence = []Stage{StagePreflight, StagePlanAccepted, StageHostApply, StageReleaseVerified, StageAssetsMaterialized, StageDeploymentMaterialized, StageRunnerEnrolled, StageComposeStarted, StageCLILogin, StageReadiness, StageSmokeExecution}
View Source 
var UpdateStageSequence = []UpdateStage{UpdateStagePreflight, UpdateStageReleaseVerified, UpdateStageAssetsStaged, UpdateStageActivationStarted, UpdateStageDeploymentPublished, UpdateStageComposeStarted, UpdateStageResourcesApplied, UpdateStageReadiness, UpdateStageSmokeExecution}

Functions

func Canonical 

func Canonical(value any) ([]byte, error)

func CleanupUpdateStaging added in v0.6.0 

func CleanupUpdateStaging(plan InstallPlan, update UpdateRecord, source, target releasecontract.ArtifactManifest) error

CleanupUpdateStaging removes only the verified, update-owned source backup and staging paths after the target deployment has passed its smoke test.

func Digest 

func Digest(content []byte) string

func HasBlockingFindings 

func HasBlockingFindings(facts HostFacts) bool

func HostFactsDigest 

func HostFactsDigest(facts HostFacts) (string, error)

func InspectOperationReleaseVersionReadOnly added in v0.7.0 

func InspectOperationReleaseVersionReadOnly(directory string, ownerUID int) (string, error)

InspectOperationReleaseVersionReadOnly securely reads only the release version needed to route an operation to a clean-install boundary diagnostic. It does not decode or accept the historical plan as a current plan.

func MaterializeRelease 

func MaterializeRelease(ctx context.Context, plan InstallPlan, receipt InstallReceipt, verified releaseverify.VerifiedRelease, dependencies ReleaseMaterializeDependencies) (InstallReceipt, VerifiedArtifact, error)

MaterializeRelease installs only bytes named by an independently verified release. The artifact directory is published with one rename after all allowlist, hash, signature, component, platform, and rootfs checks succeed.

func MountUnit 

func MountUnit(imagePath, storagePath string) string

func NewOperationID 

func NewOperationID() (string, error)

func NewUpdateID added in v0.6.0 

func NewUpdateID() (string, error)

func PlanDigest 

func PlanDigest(plan InstallPlan) (string, error)

func ReadAccepted 

func ReadAccepted(directory, expectedPlanDigest string, ownerUID int) (InstallPlan, InstallReceipt, error)

func ReadHostApply added in v0.4.4 

func ReadHostApply(directory, expectedPlanDigest string, ownerUID int) (InstallPlan, InstallReceipt, error)

ReadHostApply securely loads either the immutable pre-apply boundary or a receipt whose host apply has completed. The latter authorizes only the privileged read-only replay implemented by ApplyHost.

func ReadOperation 

func ReadOperation(directory string, ownerUID int) (InstallPlan, InstallReceipt, error)

ReadOperation securely reloads a durable installer operation without mutating pending commit state.

func ReadOperationReadOnly added in v0.6.0 

func ReadOperationReadOnly(directory string, ownerUID int) (InstallPlan, InstallReceipt, error)

ReadOperationReadOnly securely reloads an installer operation without completing a pending plan/receipt commit. Callers that promise not to mutate deployment state must direct the operator to resume recovery instead.

func RecoverOperation added in v0.6.0 

func RecoverOperation(directory string, ownerUID int, lock *OperationLock) (InstallPlan, InstallReceipt, error)

RecoverOperation completes or discards a pending plan/receipt commit before reloading the operation. The caller must hold the operation lock.

func RenderPlanReview 

func RenderPlanReview(plan InstallPlan) string

func RenderPreflight 

func RenderPreflight(facts HostFacts) string

func SaveOperation added in v0.6.0 

func SaveOperation(directory string, plan InstallPlan, receipt InstallReceipt, ownerUID int) error

SaveOperation atomically advances the plan and receipt as one recoverable logical commit. A protected marker lets lock-owning recovery finish either rename after process or host failure; readers never accept a mixed pair.

func SaveReceipt 

func SaveReceipt(directory string, plan InstallPlan, receipt InstallReceipt, ownerUID int) error

SaveReceipt atomically persists a validated receipt inside its operation.

func StageUpdateRelease added in v0.6.0 

func StageUpdateRelease(ctx context.Context, plan InstallPlan, update UpdateRecord, verified releaseverify.VerifiedRelease, executor ReleaseMaterializeExecutor) (StagedUpdate, VerifiedArtifact, error)

func ValidateAcceptedHostPurge added in v0.4.4 

func ValidateAcceptedHostPurge(directory, expectedDigest string, ownerUID int) (resultErr error)

ValidateAcceptedHostPurge proves that the privileged purge boundary is still exactly the one accepted by the plan and receipt without mutating it. The public purge command runs this before removing Compose volumes or artifacts; PurgeAcceptedHost repeats it immediately before privileged deletion.

func ValidateCLIConfig 

func ValidateCLIConfig(plan InstallPlan) error

ValidateCLIConfig checks the protected stored authority without contacting the control plane or exposing the token through arguments or diagnostics.

func ValidateComposeProjectEvidence 

func ValidateComposeProjectEvidence(receipt InstallReceipt, actual string) error

func ValidatePlannedPath 

func ValidatePlannedPath(expected PlannedPath) error

ValidatePlannedPath proves one live filesystem object still has the exact kind, mode, and ownership accepted in the immutable install plan.

func ValidatePurgeUserResources added in v0.4.4 

func ValidatePurgeUserResources(plan InstallPlan, receipt InstallReceipt) error

ValidatePurgeUserResources checks every remaining user-owned target without deleting it. It catches changed files and closed directory allowlists before the public purge crosses any destructive boundary.

func ValidatePurgeVerifiedArtifacts added in v0.4.4 

func ValidatePurgeVerifiedArtifacts(plan InstallPlan, receipt InstallReceipt) error

ValidatePurgeVerifiedArtifacts proves the complete release-owned artifact directory against the still-present signed release manifest without removing either one.

func ValidateRecordedResources 

func ValidateRecordedResources(plan InstallPlan, receipt InstallReceipt) error

ValidateRecordedResources treats the accepted plan and receipt as evidence, not deletion or replay authority. The privileged host-apply helper validates root-only resources before this unprivileged validation runs; every other still-present resource must retain its exact path, kind, owner, mode, and recorded content digest.

func ValidateUpdateAssetCompatibility added in v0.6.0 

func ValidateUpdateAssetCompatibility(source, target releasecontract.ArtifactManifest) error

ValidateUpdateAssetCompatibility keeps existing Sandboxes runnable after an update. Sandboxes remain pinned to their immutable Profile revision, while a v1 Runner serves one verified runtime/toolchain bundle at a time.

func ValidateUpdateStagingCapacity added in v0.6.0 

func ValidateUpdateStagingCapacity(plan InstallPlan, target ReleasePlan) error

ValidateUpdateStagingCapacity preserves the operational storage margin while a second verified execution bundle exists beside the active bundle. It runs before an update is journaled so lack of local capacity remains a read-only admission failure.

func VerifyAcceptedHostTeardown added in v0.4.7 

func VerifyAcceptedHostTeardown(ctx context.Context, directory, expectedDigest string, callerUID int, verifier HostResourceVerifier) (resultErr error)

VerifyAcceptedHostTeardown proves that a completed host-apply boundary still identifies the same host and exact recorded privileged resources. Unlike a host-apply replay, it deliberately does not require compute devices, free UID ranges, or allocation capacity that Compose teardown does not consume.

func VerifyAcceptedHostUpdate added in v0.6.0 

func VerifyAcceptedHostUpdate(ctx context.Context, directory, expectedDigest string, callerUID int, verifier HostResourceVerifier) (resultErr error)

VerifyAcceptedHostUpdate proves that the completed guided deployment still owns the exact privileged Runner storage accepted during host preparation.

func VerifyHostTeardown added in v0.4.7 

func VerifyHostTeardown(ctx context.Context, plan InstallPlan, receipt InstallReceipt, verifier HostResourceVerifier) error

func VerifyHostUpdate added in v0.6.0 

func VerifyHostUpdate(ctx context.Context, plan InstallPlan, receipt InstallReceipt, verifier HostResourceVerifier) error

func WriteAccepted 

func WriteAccepted(directory string, plan InstallPlan, receipt InstallReceipt) (string, string, error)

func WriteSupportBundle 

func WriteSupportBundle(output string, plan InstallPlan, receipt InstallReceipt, evidence map[string][]byte) error

WriteSupportBundle writes bounded, redacted installer evidence. Callers may add only already-sanitized operational projections; secret files and Workspace contents are never opened for collection.

Types

type CLIPlan 

type CLIPlan struct {
	ConfigPath string `json:"configPath"`
}

type CandidateReleaseMaterializer 

type CandidateReleaseMaterializer struct {
	Directory  string
	Output     io.Writer
	Diagnostic io.Writer
}

CandidateReleaseMaterializer uses only exact images already loaded by the qualification controller and exact staged release objects. It never contacts a registry or release server before publication.

func (CandidateReleaseMaterializer) ExtractMicroVMImage 

func (executor CandidateReleaseMaterializer) ExtractMicroVMImage(ctx context.Context, reference, target string) error

func (CandidateReleaseMaterializer) Fetch 

func (executor CandidateReleaseMaterializer) Fetch(ctx context.Context, location string) ([]byte, error)

func (CandidateReleaseMaterializer) PullImage 

func (executor CandidateReleaseMaterializer) PullImage(ctx context.Context, reference string) error

type CapacityPlan 

type CapacityPlan struct {
	MaxSandboxes           int64            `json:"maxSandboxes"`
	MaxVCPUCount           int64            `json:"maxVcpuCount,omitempty"`
	LegacyMaxCPUMillis     int64            `json:"maxCpuMillis,omitempty"`
	MaxMemoryBytes         int64            `json:"maxMemoryBytes"`
	MaxWorkspaceBytes      int64            `json:"maxWorkspaceBytes"`
	ConcurrentStarts       int64            `json:"concurrentStarts"`
	ConcurrentOperations   int64            `json:"concurrentOperations"`
	StoragePressurePercent int64            `json:"storagePressurePercent"`
	SubjectQuotas          map[string]int64 `json:"subjectQuotas"`
}

CapacityPlan states the host's compute ceiling. Plan identity is the digest of the exact recorded document, so a plan accepted by a release that stated CPU in milli-units keeps that spelling on disk forever: LegacyMaxCPUMillis round-trips it untouched and VCPUCount is the single read path that normalizes either spelling to whole vCPUs. Exactly one spelling may be set.

func (CapacityPlan) SubjectQuotaVCPUCount added in v0.7.0 

func (capacity CapacityPlan) SubjectQuotaVCPUCount() int64

SubjectQuotaVCPUCount reports the planned per-subject CPU quota in whole vCPUs from either recorded spelling.

func (CapacityPlan) VCPUCount added in v0.7.0 

func (capacity CapacityPlan) VCPUCount() int64

VCPUCount reports the planned compute ceiling in whole vCPUs regardless of which spelling the recorded plan used, rounding legacy milli-units up to the whole vCPU that already covered the stated allowance.

type ClockProbe 

type ClockProbe interface{ Now() time.Time }

type CommandResult 

type CommandResult struct {
	Stdout string
	Stderr string
}

type ComputePlan added in v0.4.4 

type ComputePlan struct {
	FirecrackerCPUTemplate string `json:"firecrackerCpuTemplate"`
}

type CreatedResource 

type CreatedResource struct {
	ID       string       `json:"id"`
	Kind     ResourceKind `json:"kind"`
	Path     string       `json:"path,omitempty"`
	Class    PathClass    `json:"class,omitempty"`
	Stage    Stage        `json:"stage"`
	Mode     uint32       `json:"mode,omitempty"`
	OwnerUID int64        `json:"ownerUid,omitempty"`
	OwnerGID int64        `json:"ownerGid,omitempty"`
	Digest   string       `json:"digest,omitempty"`
	Identity string       `json:"identity,omitempty"`
}

func LoginCLI 

func LoginCLI(ctx context.Context, plan InstallPlan, httpClient *http.Client) ([]CreatedResource, error)

LoginCLI verifies the generated platform authority, then writes the invoking user's ordinary CLI configuration without ever putting the token in process arguments, the receipt, or diagnostic output.

type DeviceFact 

type DeviceFact struct {
	Path             string `json:"path"`
	Identity         string `json:"identity"`
	Filesystem       string `json:"filesystem,omitempty"`
	SizeBytes        int64  `json:"sizeBytes"`
	AvailableBytes   int64  `json:"availableBytes"`
	Mountpoint       string `json:"mountpoint,omitempty"`
	JailerCompatible bool   `json:"jailerCompatible"`
}

type FailureClass 

type FailureClass string
const (
	FailureBlocked     FailureClass = "blocked"
	FailureNeedsAction FailureClass = "needs_action"
	FailureRetryable   FailureClass = "retryable"
	FailureInternal    FailureClass = "internal"
)

type FilesystemProbe 

type FilesystemProbe interface {
	ReadFile(string) ([]byte, error)
	Lstat(string) (fs.FileInfo, error)
	StatFS(string) (available, total int64, err error)
	OpenReadWrite(string) error
}

type Finding 

type Finding struct {
	ID      string       `json:"id"`
	Class   FindingClass `json:"class"`
	Summary string       `json:"summary"`
	Detail  string       `json:"detail,omitempty"`
	Remedy  string       `json:"remedy,omitempty"`
}

type FindingClass 

type FindingClass string
const (
	FindingPass        FindingClass = "pass"
	FindingWarning     FindingClass = "warning"
	FindingRemediable  FindingClass = "remediable"
	FindingNeedsAction FindingClass = "needs_action"
	FindingBlocked     FindingClass = "blocked"
)

type HostApplyDependencies 

type HostApplyDependencies struct {
	Executor       HostApplyExecutor
	PersistReceipt func(InstallReceipt) error
	Now            func() time.Time
}

type HostApplyExecutor 

type HostApplyExecutor interface {
	EffectiveUID() int
	Revalidate(context.Context, InstallPlan, InstallReceipt) error
	CreateDirectory(PlannedPath) error
	AllocateFilesystemImage(PlannedPath, int64) error
	FormatBtrfs(context.Context, string, string) error
	WriteMountUnit(PlannedPath, string) error
	EnableMountUnit(context.Context, string) error
	SecureDirectory(PlannedPath) error
	ProveReflinkTopology(string, string, string) (string, error)
	RemoveEmpty(CreatedResource) (bool, error)
}

type HostFacts 

type HostFacts struct {
	SchemaVersion        string            `json:"schemaVersion"`
	ObservedAt           time.Time         `json:"observedAt"`
	HostIdentity         string            `json:"hostIdentity"`
	OS                   string            `json:"os"`
	Architecture         string            `json:"architecture"`
	InvokingUID          int64             `json:"invokingUid"`
	InvokingGID          int64             `json:"invokingGid"`
	KernelVersion        string            `json:"kernelVersion"`
	SystemdVersion       string            `json:"systemdVersion,omitempty"`
	DockerVersion        string            `json:"dockerVersion,omitempty"`
	ComposeVersion       string            `json:"composeVersion,omitempty"`
	CgroupVersion        int               `json:"cgroupVersion"`
	CgroupControllers    []string          `json:"cgroupControllers"`
	CPUCount             int               `json:"cpuCount"`
	MemoryBytes          int64             `json:"memoryBytes"`
	Virtualization       string            `json:"virtualization,omitempty"`
	BtrfsSupported       bool              `json:"btrfsSupported"`
	KVMAccessible        bool              `json:"kvmAccessible"`
	TUNAccessible        bool              `json:"tunAccessible"`
	Devices              []DeviceFact      `json:"devices"`
	ListeningPorts       []PortFact        `json:"listeningPorts"`
	Routes               []RouteFact       `json:"routes"`
	DockerNetworkSubnets []string          `json:"dockerNetworkSubnets,omitempty"`
	DNSUpstreams         []string          `json:"dnsUpstreams"`
	AssignedUIDs         []int64           `json:"assignedUIDs"`
	ReservedIDRanges     []UIDRange        `json:"reservedIdRanges"`
	CandidateUIDRanges   []UIDRange        `json:"candidateUIDRanges"`
	Utilities            map[string]string `json:"utilities"`
	Findings             []Finding         `json:"findings"`
}

func DecodeHostFacts 

func DecodeHostFacts(content []byte) (HostFacts, error)

func Preflight 

func Preflight(ctx context.Context, probes PreflightProbes) (HostFacts, error)

func (HostFacts) Validate 

func (facts HostFacts) Validate() error

type HostResourceVerifier added in v0.6.0 

type HostResourceVerifier interface {
	EffectiveUID() int
	RevalidateHostResources(context.Context, InstallPlan, InstallReceipt) error
}

type InstallPlan 

type InstallPlan struct {
	SchemaVersion                string              `json:"schemaVersion"`
	OperationID                  string              `json:"operationId"`
	CreatedAt                    time.Time           `json:"createdAt"`
	HostFacts                    HostFacts           `json:"hostFacts"`
	HostFactsDigest              string              `json:"hostFactsDigest"`
	Release                      ReleasePlan         `json:"release"`
	Storage                      StoragePlan         `json:"storage"`
	Capacity                     CapacityPlan        `json:"capacity"`
	Compute                      ComputePlan         `json:"compute"`
	Network                      NetworkPlan         `json:"network"`
	CLI                          CLIPlan             `json:"cli"`
	Paths                        []PlannedPath       `json:"paths"`
	SecretTargets                []SecretTarget      `json:"secretTargets"`
	GeneratedAuthorityCategories []string            `json:"generatedAuthorityCategories"`
	StandardBundles              []string            `json:"standardBundles"`
	RetentionSeconds             int64               `json:"retentionSeconds"`
	PrivilegedActions            []string            `json:"privilegedActions"`
	ReleaseHistory               []ReleaseActivation `json:"releaseHistory,omitempty"`
}

func DecodePlan 

func DecodePlan(content []byte) (InstallPlan, error)

func ProposePlan 

func ProposePlan(facts HostFacts, input ProposalInput) (InstallPlan, error)

func ReadPlan 

func ReadPlan(path string) (InstallPlan, []byte, error)

func (InstallPlan) Validate 

func (plan InstallPlan) Validate() error

type InstallReceipt 

type InstallReceipt struct {
	SchemaVersion       string            `json:"schemaVersion"`
	OperationID         string            `json:"operationId"`
	PlanDigest          string            `json:"planDigest"`
	HostIdentity        string            `json:"hostIdentity"`
	Status              OperationStatus   `json:"status"`
	FailureClass        FailureClass      `json:"failureClass,omitempty"`
	FailureStage        Stage             `json:"failureStage,omitempty"`
	CompletedStages     []StageRecord     `json:"completedStages"`
	CreatedResources    []CreatedResource `json:"createdResources"`
	PendingResourceIDs  []string          `json:"pendingResourceIds"`
	RemovedResourceIDs  []string          `json:"removedResourceIds"`
	CompletedPurgeSteps []string          `json:"completedPurgeSteps"`
	Updates             []UpdateRecord    `json:"updates,omitempty"`
	UpdatedAt           time.Time         `json:"updatedAt"`
}

func ApplyAcceptedHost 

func ApplyAcceptedHost(ctx context.Context, directory, expectedDigest string, callerUID int, executor HostApplyExecutor, now func() time.Time) (result InstallReceipt, resultErr error)

func ApplyHost 

func ApplyHost(ctx context.Context, plan InstallPlan, receipt InstallReceipt, dependencies HostApplyDependencies) (InstallReceipt, error)

func DecodeReceipt 

func DecodeReceipt(content []byte, plan InstallPlan) (InstallReceipt, error)

func NewReceipt 

func NewReceipt(plan InstallPlan, now time.Time) (InstallReceipt, error)

func PurgeAcceptedHost 

func PurgeAcceptedHost(ctx context.Context, directory, expectedDigest string, ownerUID int, now func() time.Time) (result InstallReceipt, resultErr error)

PurgeAcceptedHost removes only receipt-backed privileged resources. Missing targets are accepted as the postcondition of an interrupted purge, while a replacement, symlinked component, mount crossing, or changed regular file is refused.

func PurgeUserResources 

func PurgeUserResources(plan InstallPlan, receipt InstallReceipt, now func() time.Time, persist func(InstallReceipt) error) (InstallReceipt, error)

PurgeUserResources removes remaining create-only user-owned resources deepest-first and persists the removal ledger after every target.

func PurgeVerifiedArtifacts added in v0.4.4 

func PurgeVerifiedArtifacts(plan InstallPlan, receipt InstallReceipt, now func() time.Time, persist func(InstallReceipt) error) (InstallReceipt, error)

PurgeVerifiedArtifacts removes the independently verified execution assets before the privileged Runner storage root may be removed. The release manifest remains outside that root as the verification authority.

func (*InstallReceipt) ActivateUpdate added in v0.6.0 

func (receipt *InstallReceipt) ActivateUpdate(plan *InstallPlan, now time.Time) error

func (*InstallReceipt) ActiveUpdate added in v0.6.0 

func (receipt *InstallReceipt) ActiveUpdate() (UpdateRecord, bool)

func (*InstallReceipt) AppendResource 

func (receipt *InstallReceipt) AppendResource(resource CreatedResource) error

func (*InstallReceipt) BeginResource 

func (receipt *InstallReceipt) BeginResource(id string, now time.Time) error

func (*InstallReceipt) BeginUpdate added in v0.6.0 

func (receipt *InstallReceipt) BeginUpdate(id string, source, target ReleasePlan, now time.Time) error

func (*InstallReceipt) CompletePurgeStep 

func (receipt *InstallReceipt) CompletePurgeStep(step string, now time.Time) error

func (*InstallReceipt) CompleteResource 

func (receipt *InstallReceipt) CompleteResource(resource CreatedResource, now time.Time) error

func (*InstallReceipt) CompleteStage 

func (receipt *InstallReceipt) CompleteStage(stage Stage, now time.Time, evidence map[string]string) error

func (*InstallReceipt) CompleteUpdateStage added in v0.6.0 

func (receipt *InstallReceipt) CompleteUpdateStage(stage UpdateStage, now time.Time, evidence map[string]string) error

func (*InstallReceipt) Fail 

func (receipt *InstallReceipt) Fail(stage Stage, class FailureClass, now time.Time) error

Fail records a resumable stage failure without inventing a completed stage.

func (*InstallReceipt) FailUpdate added in v0.6.0 

func (receipt *InstallReceipt) FailUpdate(stage UpdateStage, class FailureClass, now time.Time) error

func (*InstallReceipt) MarkPurged 

func (receipt *InstallReceipt) MarkPurged(now time.Time) error

func (*InstallReceipt) MarkPurging 

func (receipt *InstallReceipt) MarkPurging(now time.Time) error

func (*InstallReceipt) MarkResourceRemoved 

func (receipt *InstallReceipt) MarkResourceRemoved(id string, now time.Time) error

func (*InstallReceipt) MarkUninstalled 

func (receipt *InstallReceipt) MarkUninstalled(now time.Time) error

func (*InstallReceipt) MarkUninstalling 

func (receipt *InstallReceipt) MarkUninstalling(now time.Time) error

func (*InstallReceipt) PrepareComposeRetry added in v0.4.7 

func (receipt *InstallReceipt) PrepareComposeRetry(now time.Time) error

PrepareComposeRetry journals a failed post-Compose operation back to the last durable pre-Compose stage. Generated Compose resources and the CLI configuration are replay-owned and must be recorded again after restart; pre-existing or installer-created CLI parent directories stay ledgered so a later purge does not lose ownership of directories the installer created.

func (*InstallReceipt) RecoverSucceeded 

func (receipt *InstallReceipt) RecoverSucceeded(now time.Time) error

RecoverSucceeded clears a transient post-install health failure after the complete installation has passed readiness again. It does not invent or repeat any completed stage.

func (*InstallReceipt) RefreshUpdatedResource added in v0.6.0 

func (receipt *InstallReceipt) RefreshUpdatedResource(id, digest string) error

func (*InstallReceipt) RestoreSucceeded 

func (receipt *InstallReceipt) RestoreSucceeded(now time.Time) error

func (InstallReceipt) Validate 

func (receipt InstallReceipt) Validate(planDigest, hostIdentity, operationID string) error

type NetworkOverrides 

type NetworkOverrides struct {
	APIPort       int
	RunnerPort    int
	DataPlanePort int
	DatabasePort  int
	GuestCIDR     string
	ComposeCIDR   string
	TAPPrefix     string
	CgroupParent  string
	DNSUpstream   string
	JailerUID     UIDRange
}

type NetworkPlan 

type NetworkPlan struct {
	APIAddress         string            `json:"apiAddress"`
	RunnerAddress      string            `json:"runnerAddress"`
	DataPlaneAddress   string            `json:"dataPlaneAddress"`
	DatabaseAddress    string            `json:"databaseAddress"`
	GuestBridgeCIDR    string            `json:"guestBridgeCidr"`
	ComposeBackendCIDR string            `json:"composeBackendCidr,omitempty"`
	TAPPrefix          string            `json:"tapPrefix"`
	CgroupParent       string            `json:"cgroupParent"`
	JailerUIDRange     UIDRange          `json:"jailerUidRange"`
	DNSUpstream        string            `json:"dnsUpstream"`
	Gateways           map[string]string `json:"gateways"`
}

type NetworkProbe 

type NetworkProbe interface {
	LookupHost(context.Context, string) ([]string, error)
	Head(context.Context, string) (int, error)
}

type OperationLock 

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

func AcquireLock 

func AcquireLock(directory string) (*OperationLock, error)

func (*OperationLock) Close 

func (lock *OperationLock) Close() error

type OperationStatus 

type OperationStatus string
const (
	OperationPlanned      OperationStatus = "planned"
	OperationRunning      OperationStatus = "running"
	OperationFailed       OperationStatus = "failed"
	OperationSucceeded    OperationStatus = "succeeded"
	OperationUninstalling OperationStatus = "uninstalling"
	OperationUninstalled  OperationStatus = "uninstalled"
	OperationPurging      OperationStatus = "purging"
	OperationPurged       OperationStatus = "purged"
)

type PathClass 

type PathClass string
const (
	PathUserDeployment    PathClass = "user_deployment"
	PathInstallerHost     PathClass = "installer_host"
	PathExistingWorkspace PathClass = "existing_workspace"
	PathFilesystemImage   PathClass = "filesystem_image"
)

type PlannedPath 

type PlannedPath struct {
	Name         string       `json:"name"`
	Path         string       `json:"path"`
	Class        PathClass    `json:"class"`
	Kind         ResourceKind `json:"kind"`
	Mode         uint32       `json:"mode"`
	OwnerUID     int64        `json:"ownerUid"`
	OwnerGID     int64        `json:"ownerGid"`
	RequiresSudo bool         `json:"requiresSudo"`
	Create       bool         `json:"create"`
}

type PortFact 

type PortFact struct {
	Address  string `json:"address"`
	Port     int    `json:"port"`
	Protocol string `json:"protocol"`
	Process  string `json:"process,omitempty"`
}

type PreflightProbes 

type PreflightProbes struct {
	Filesystem   FilesystemProbe
	Process      ProcessProbe
	Network      NetworkProbe
	Clock        ClockProbe
	Users        UserProbe
	LookupEnv    func(string) (string, bool)
	OS           string
	Architecture string
	CPUCount     int
	InvokingUID  int64
	InvokingGID  int64
	// Backend selects the compute-backend host requirements: "firecracker"
	// (the default when empty) requires KVM, TUN, and hardware
	// virtualization; "gvisor" requires none of those and instead requires
	// loop devices, nftables, and iproute2 for its host attachment and
	// routed-veth policy path.
	Backend string
}

func SystemPreflightProbes 

func SystemPreflightProbes() PreflightProbes

type ProcessProbe 

type ProcessProbe interface {
	Run(context.Context, string, ...string) (CommandResult, error)
	LookPath(string) (string, error)
}

type ProposalInput 

type ProposalInput struct {
	OperationID              string
	CreatedAt                time.Time
	DeploymentDirectory      string
	BinaryDirectory          string
	CLIConfigPath            string
	BackingAvailableBytes    int64
	DeploymentAvailableBytes int64
	Release                  ReleasePlan
	StorageChoice            StorageChoice
	ExistingMountpoint       string
	FilesystemImageBytes     int64
	NetworkOverrides         NetworkOverrides
	StandardBundles          []string
	RetentionSeconds         int64
}

type ReleaseActivation added in v0.6.0 

type ReleaseActivation struct {
	Release     ReleasePlan `json:"release"`
	ActivatedAt time.Time   `json:"activatedAt"`
	UpdateID    string      `json:"updateId,omitempty"`
}

ReleaseActivation is the append-only audit history for the release that an installation operation made active. The initial entry is derived from the original immutable install plan when a v1 operation is first read.

type ReleaseMaterializeDependencies 

type ReleaseMaterializeDependencies struct {
	Executor                  ReleaseMaterializeExecutor
	PersistReceipt            func(InstallReceipt) error
	Now                       func() time.Time
	ValidateBinaryReplacement func(PlannedPath, string) error
}

type ReleaseMaterializeExecutor 

type ReleaseMaterializeExecutor interface {
	PullImage(context.Context, string) error
	ExtractMicroVMImage(context.Context, string, string) error
	Fetch(context.Context, string) ([]byte, error)
}

type ReleasePlan 

type ReleasePlan struct {
	Version                string            `json:"version"`
	ArtifactManifestURL    string            `json:"artifactManifestUrl"`
	ArtifactManifestDigest string            `json:"artifactManifestDigest"`
	SigningKeyFingerprint  string            `json:"signingKeyFingerprint"`
	Images                 map[string]string `json:"images"`
	BinaryDigests          map[string]string `json:"binaryDigests"`
	ExpectedDownloadBytes  int64             `json:"expectedDownloadBytes"`
}

type ResourceKind 

type ResourceKind string
const (
	ResourceDirectory       ResourceKind = "directory"
	ResourceFile            ResourceKind = "file"
	ResourceFilesystemImage ResourceKind = "filesystem_image"
	ResourceMountUnit       ResourceKind = "mount_unit"
	ResourceBinary          ResourceKind = "binary"
	ResourceComposeProject  ResourceKind = "compose_project"
)

type RouteFact 

type RouteFact struct {
	Destination string `json:"destination"`
	Interface   string `json:"interface"`
	Gateway     string `json:"gateway,omitempty"`
}

type SecretTarget 

type SecretTarget struct {
	Category string `json:"category"`
	Path     string `json:"path"`
}

type Stage 

type Stage string
const (
	StagePreflight              Stage = "preflight"
	StagePlanAccepted           Stage = "plan_accepted"
	StageHostApply              Stage = "host_apply"
	StageReleaseVerified        Stage = "release_verified"
	StageAssetsMaterialized     Stage = "assets_materialized"
	StageDeploymentMaterialized Stage = "deployment_materialized"
	StageRunnerEnrolled         Stage = "runner_enrolled"
	StageComposeStarted         Stage = "compose_started"
	StageCLILogin               Stage = "cli_login"
	StageReadiness              Stage = "readiness"
	StageSmokeExecution         Stage = "smoke_execution"
)

type StageRecord 

type StageRecord struct {
	Stage       Stage             `json:"stage"`
	CompletedAt time.Time         `json:"completedAt"`
	Evidence    map[string]string `json:"evidence"`
}

type StagedUpdate added in v0.6.0 

type StagedUpdate struct {
	Root                    string
	Artifacts               string
	ArtifactPartial         string
	PreviousArtifacts       string
	SecondBoxBinary         string
	SecondBoxDeployBinary   string
	ReleaseArtifactManifest string
}

func UpdateStaging added in v0.6.0 

func UpdateStaging(plan InstallPlan, update UpdateRecord) (StagedUpdate, error)

type StorageChoice 

type StorageChoice string
const (
	StorageExistingMount StorageChoice = "existing_mount"
	StorageBtrfsImage    StorageChoice = "btrfs_image"
)

type StorageOption 

type StorageOption struct {
	Choice         StorageChoice
	Label          string
	Mountpoint     string
	DeviceIdentity string
	Filesystem     string
	AvailableBytes int64
}

func StorageOptions 

func StorageOptions(facts HostFacts, backingAvailableBytes, releaseDownloadBytes int64) []StorageOption

type StoragePlan 

type StoragePlan struct {
	Choice                 StorageChoice `json:"choice"`
	WorkspacePath          string        `json:"workspacePath"`
	ExistingDeviceIdentity string        `json:"existingDeviceIdentity,omitempty"`
	FilesystemImagePath    string        `json:"filesystemImagePath,omitempty"`
	ImageSizeBytes         int64         `json:"imageSizeBytes,omitempty"`
	MountUnitPath          string        `json:"mountUnitPath,omitempty"`
}

type SystemHostApplyExecutor 

type SystemHostApplyExecutor struct{ CallerUID int }

func (SystemHostApplyExecutor) AllocateFilesystemImage 

func (SystemHostApplyExecutor) AllocateFilesystemImage(path PlannedPath, size int64) error

func (SystemHostApplyExecutor) CreateDirectory 

func (SystemHostApplyExecutor) CreateDirectory(path PlannedPath) error

func (SystemHostApplyExecutor) EffectiveUID 

func (executor SystemHostApplyExecutor) EffectiveUID() int

func (SystemHostApplyExecutor) EnableMountUnit 

func (SystemHostApplyExecutor) EnableMountUnit(ctx context.Context, unitPath string) error

func (SystemHostApplyExecutor) FormatBtrfs 

func (SystemHostApplyExecutor) FormatBtrfs(ctx context.Context, imagePath, installerTools string) error

func (SystemHostApplyExecutor) ProveReflinkTopology added in v0.4.4 

func (SystemHostApplyExecutor) ProveReflinkTopology(artifactParent, runDirectory, workspace string) (identity string, resultErr error)

func (SystemHostApplyExecutor) RemoveEmpty 

func (SystemHostApplyExecutor) RemoveEmpty(resource CreatedResource) (bool, error)

func (SystemHostApplyExecutor) Revalidate 

func (executor SystemHostApplyExecutor) Revalidate(ctx context.Context, plan InstallPlan, receipt InstallReceipt) error

func (SystemHostApplyExecutor) RevalidateHostResources added in v0.6.0 

func (executor SystemHostApplyExecutor) RevalidateHostResources(ctx context.Context, plan InstallPlan, receipt InstallReceipt) error

func (SystemHostApplyExecutor) SecureDirectory added in v0.4.4 

func (SystemHostApplyExecutor) SecureDirectory(path PlannedPath) error

func (SystemHostApplyExecutor) WriteMountUnit 

func (SystemHostApplyExecutor) WriteMountUnit(path PlannedPath, content string) (resultErr error)

type SystemReleaseMaterializer 

type SystemReleaseMaterializer struct {
	Output     io.Writer
	Diagnostic io.Writer
	HTTPClient *http.Client
}

SystemReleaseMaterializer executes the narrow Docker and HTTPS operations required by MaterializeRelease while forwarding bounded command output.

func (SystemReleaseMaterializer) ExtractMicroVMImage 

func (executor SystemReleaseMaterializer) ExtractMicroVMImage(ctx context.Context, reference, target string) (resultErr error)

func (SystemReleaseMaterializer) Fetch 

func (executor SystemReleaseMaterializer) Fetch(ctx context.Context, location string) ([]byte, error)

func (SystemReleaseMaterializer) PullImage 

func (executor SystemReleaseMaterializer) PullImage(ctx context.Context, reference string) error

type UIDRange 

type UIDRange struct {
	Start int64 `json:"start"`
	Count int64 `json:"count"`
}

type UpdateRecord added in v0.6.0 

type UpdateRecord struct {
	ID              string              `json:"id"`
	SourceRelease   ReleasePlan         `json:"sourceRelease"`
	TargetRelease   ReleasePlan         `json:"targetRelease"`
	Status          UpdateStatus        `json:"status"`
	FailureClass    FailureClass        `json:"failureClass,omitempty"`
	FailureStage    UpdateStage         `json:"failureStage,omitempty"`
	CompletedStages []UpdateStageRecord `json:"completedStages"`
	StartedAt       time.Time           `json:"startedAt"`
	UpdatedAt       time.Time           `json:"updatedAt"`
}

UpdateRecord journals one forward-only release transition inside the installation receipt. TargetRelease remains durable while an interrupted activation is resumed by a later target-release bootstrap.

type UpdateStage added in v0.6.0 

type UpdateStage string
const (
	UpdateStagePreflight           UpdateStage = "preflight"
	UpdateStageReleaseVerified     UpdateStage = "release_verified"
	UpdateStageAssetsStaged        UpdateStage = "assets_staged"
	UpdateStageActivationStarted   UpdateStage = "activation_started"
	UpdateStageDeploymentPublished UpdateStage = "deployment_published"
	UpdateStageComposeStarted      UpdateStage = "compose_started"
	UpdateStageResourcesApplied    UpdateStage = "resources_applied"
	UpdateStageReadiness           UpdateStage = "readiness"
	UpdateStageSmokeExecution      UpdateStage = "smoke_execution"
)

type UpdateStageRecord added in v0.6.0 

type UpdateStageRecord struct {
	Stage       UpdateStage       `json:"stage"`
	CompletedAt time.Time         `json:"completedAt"`
	Evidence    map[string]string `json:"evidence"`
}

type UpdateStatus added in v0.6.0 

type UpdateStatus string
const (
	UpdateRunning   UpdateStatus = "running"
	UpdateFailed    UpdateStatus = "failed"
	UpdateSucceeded UpdateStatus = "succeeded"
)

type UserProbe 

type UserProbe interface {
	AssignedUIDs() (map[int64]bool, error)
}

type UserRangeProbe 

type UserRangeProbe interface {
	ReservedIDRanges() ([]UIDRange, error)
}

type VerifiedArtifact 

type VerifiedArtifact struct {
	SigningPublicKeyPEM []byte
	SigningKeyID        string
	ManifestDigest      string
}

func ActivateUpdateArtifactsAndBinaries added in v0.6.0 

func ActivateUpdateArtifactsAndBinaries(plan InstallPlan, update UpdateRecord, source releasecontract.ArtifactManifest, target releaseverify.VerifiedRelease) (VerifiedArtifact, error)

func ValidateActivatedUpdateArtifactsAndBinaries added in v0.6.0 

func ValidateActivatedUpdateArtifactsAndBinaries(plan InstallPlan, update UpdateRecord, target releaseverify.VerifiedRelease) (VerifiedArtifact, error)

ValidateActivatedUpdateArtifactsAndBinaries verifies active target bytes without relying on staging paths that cleanup may already have removed.

func VerifyArtifactDirectory 

func VerifyArtifactDirectory(directory string, release releasecontract.ArtifactManifest) (VerifiedArtifact, 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.