upgrade

package
v2026.0.153 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: MPL-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package upgrade stages one authenticated Release artifact into the fixed unselected installation slot, exposes its exact command path for product-owned trials, and atomically selects it only after a typed passing report. Successful promotion removes the former slot.

Upgrade streams downloads and verification through Objectstore, Filestore, Hostfacts, and Go. It owns no command arguments, test semantics, live-data sandbox, user-consent UI, ticket submission, retry, scheduler, background worker, transport, release authority, or general persistence framework.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DiscardTrial 

func DiscardTrial(
	ctx context.Context,
	request DiscardTrialRequest,
) error

DiscardTrial removes only the exact candidate while the primary still matches the authority from which that candidate was staged.

Types

type AttemptError 

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

AttemptError is the typed failure record returned for one candidate attempt. Products own durable recording, customer copy, and ticket submission.

func (AttemptError) Candidate 

func (e AttemptError) Candidate() core.BuildIdentity

Candidate returns the exact candidate named by the failed attempt.

func (AttemptError) Error 

func (e AttemptError) Error() string

Error returns a bounded diagnostic without rendering download authority.

func (AttemptError) Phase 

func (e AttemptError) Phase() FailurePhase

Phase returns the operation boundary that failed.

func (AttemptError) Unwrap 

func (e AttemptError) Unwrap() error

Unwrap preserves the stable Core identity and native cause.

func (AttemptError) Validate 

func (e AttemptError) Validate() error

Validate proves the record carries a phase, candidate, and Upgrade identity.

type BootstrapRequest 

type BootstrapRequest struct {
	Source    io.Reader
	Root      *os.Root
	Build     core.BuildIdentity
	Directory core.AbsolutePath
	Manifest  release.VerifiedManifest
}

BootstrapRequest establishes the first selector from an authenticated installed manifest and the exact currently working executable stream.

func (BootstrapRequest) Validate 

func (r BootstrapRequest) Validate() error

type DiscardTrialRequest 

type DiscardTrialRequest struct {
	Root      *os.Root
	Directory core.AbsolutePath
	Target    TrialTarget
}

DiscardTrialRequest names one exact unselected candidate to remove after a rejected or abandoned product trial.

func (DiscardTrialRequest) Validate 

func (r DiscardTrialRequest) Validate() error

type DownloadSource 

type DownloadSource struct {
	Client     objectstore.Client
	Observer   objectstore.ProgressObserver
	Capability objectstore.DownloadCapability
	Commitment objectstore.DownloadCapabilityCommitment
	Policy     objectstore.Policy
}

DownloadSource is one already-issued Objectstore download capability.

func (DownloadSource) Validate 

func (s DownloadSource) Validate() error

type FailurePhase 

type FailurePhase uint8

FailurePhase identifies the exact Upgrade boundary that failed. 

const (
	FailurePhaseUnknown FailurePhase = iota
	FailurePhaseBootstrap
	FailurePhaseCapacity
	FailurePhaseDownload
	FailurePhaseVerification
	FailurePhaseTrial
	FailurePhasePromotion
	FailurePhasePersistence
	FailurePhaseCleanup
)

func (FailurePhase) IsValid 

func (p FailurePhase) IsValid() bool

func (FailurePhase) OffWireEnum 

func (FailurePhase) OffWireEnum()

func (FailurePhase) String 

func (p FailurePhase) String() string

func (FailurePhase) Validate 

func (p FailurePhase) Validate() error

type Primary 

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

Primary is the exact artifact selected for normal product execution.

func Bootstrap 

func Bootstrap(
	ctx context.Context,
	request BootstrapRequest,
) (Primary, error)

Bootstrap writes and verifies slot A before exclusively creating the first selection. Any failure leaves no primary selector.

func Promote 

func Promote(
	ctx context.Context,
	request PromoteRequest,
) (Primary, error)

Promote re-verifies the candidate, atomically selects it, proves the new primary, then removes only the former fixed slot.

func ResolvePrimary 

func ResolvePrimary(
	ctx context.Context,
	request ResolveRequest,
) (Primary, error)

ResolvePrimary reads and verifies the selected executable without opening any update or licensing state.

func (Primary) Artifact 

func (p Primary) Artifact() release.Artifact

func (Primary) Command 

func (p Primary) Command() core.AbsolutePath

Command returns the exact absolute path products pass to Process.

func (Primary) Directory 

func (p Primary) Directory() core.AbsolutePath

func (Primary) Path 

func (p Primary) Path() core.RelativePath

func (Primary) Slot 

func (p Primary) Slot() Slot

func (Primary) Validate 

func (p Primary) Validate() error

type PromoteRequest 

type PromoteRequest struct {
	Root      *os.Root
	Directory core.AbsolutePath
	Promotion Promotion
}

PromoteRequest binds a passing trial to the exact rooted installation.

func (PromoteRequest) Validate 

func (r PromoteRequest) Validate() error

type Promotion 

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

Promotion is authority to select one candidate that passed its product-owned trial. It does not claim Primitive executed the product test.

func CompleteTrial 

func CompleteTrial(report TrialReport) (Promotion, error)

CompleteTrial admits only a passing report bound to the exact candidate.

func (Promotion) Validate 

func (p Promotion) Validate() error

type ResolveRequest 

type ResolveRequest struct {
	Root      *os.Root
	Directory core.AbsolutePath
}

ResolveRequest supplies the real rooted installation directory.

func (ResolveRequest) Validate 

func (r ResolveRequest) Validate() error

type Slot 

type Slot uint8

Slot is one of the two fixed installation namespaces. 

const (
	SlotUnknown Slot = iota
	SlotA
	SlotB
)

func (Slot) IsValid 

func (s Slot) IsValid() bool

func (Slot) MarshalJSON 

func (s Slot) MarshalJSON() ([]byte, error)

func (Slot) String 

func (s Slot) String() string

func (*Slot) UnmarshalJSON 

func (s *Slot) UnmarshalJSON(data []byte) error

func (Slot) Validate 

func (s Slot) Validate() error

type StagePolicy 

type StagePolicy struct {
	FreeSpaceReserve core.ByteLength
}

StagePolicy is the caller-owned free-space reserve left after the complete candidate extent is admitted.

func (StagePolicy) Validate 

func (p StagePolicy) Validate() error

type StageRequest 

type StageRequest struct {
	Root      *os.Root
	Directory core.AbsolutePath
	Source    DownloadSource
	Prepared  release.PreparedRelease
	Policy    StagePolicy
}

StageRequest binds one authenticated Release handoff to one exact download.

func (StageRequest) Validate 

func (r StageRequest) Validate() error

type TrialOutcome 

type TrialOutcome uint8

TrialOutcome is the product-owned result of running the exact candidate. 

const (
	TrialOutcomeUnknown TrialOutcome = iota
	TrialPassed
	TrialFailed
)

func (TrialOutcome) IsValid 

func (o TrialOutcome) IsValid() bool

func (TrialOutcome) OffWireEnum 

func (TrialOutcome) OffWireEnum()

func (TrialOutcome) String 

func (o TrialOutcome) String() string

func (TrialOutcome) Validate 

func (o TrialOutcome) Validate() error

type TrialReport 

type TrialReport struct {
	Observed    core.BuildIdentity
	Target      TrialTarget
	Observation temporal.Instant
	Outcome     TrialOutcome
}

TrialReport is a product-owned observation of the exact TrialTarget.

func (TrialReport) Validate 

func (r TrialReport) Validate() error

type TrialTarget 

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

TrialTarget is the exact unselected executable a product may exercise.

func Stage 

func Stage(ctx context.Context, request StageRequest) (TrialTarget, error)

Stage downloads directly into the fixed unselected slot, verifies the exact artifact, and returns the only path a product may trial. It never changes the primary selection.

Staging is idempotent for one exact candidate. A durable trial receipt binds the fixed slot to the prior selector and candidate before bytes arrive. An interrupted attempt is resumed, while a different live candidate conflicts without losing the earlier trial.

One installation directory admits one writer. Upgrade owns no lock: two concurrent Stage, Promote, or DiscardTrial calls against the same directory are a caller error that the typed authority conflict reports but cannot prevent.

func (TrialTarget) Candidate 

func (t TrialTarget) Candidate() release.Artifact

Candidate returns the exact candidate artifact.

func (TrialTarget) Command 

func (t TrialTarget) Command() core.AbsolutePath

Command returns the exact absolute path products pass to Process.

func (TrialTarget) Directory 

func (t TrialTarget) Directory() core.AbsolutePath

Directory returns the absolute directory named by the required os.Root.

func (TrialTarget) Path 

func (t TrialTarget) Path() core.RelativePath

Path returns the exact root-relative executable path products must run.

func (TrialTarget) Validate 

func (t TrialTarget) Validate() error

Validate proves every cached projection from the authenticated artifacts.

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.