upgradegate

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package upgradegate composes release verification, durable migration state, public backup evidence and bounded candidate health before runtime admission. It never imports the runtime datastore or application wiring.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrRestoreRequired = errors.New("upgrade requires an explicit verified restore")
	ErrNextBinary      = errors.New("upgrade route requires its next exact binary; maintenance retained")
)

Functions

func InspectCustodyDirectory

func InspectCustodyDirectory(path string) (os.FileInfo, error)

InspectCustodyDirectory captures identity without creating a directory, lock or journal. A later selection must refer to this same persistent object.

func InstallLegacyOperator

func InstallLegacyOperator(ctx context.Context, directory, instance string, public []byte, epoch int64) (backupreceipt.PinnedOperator, error)

InstallLegacyOperator establishes the initial public pin only after local tooling authenticates a pre-ledger source against the signed genesis catalog. It cannot replace existing custody or authorize a key transition.

func InstalledOperator

func InstalledOperator(ctx context.Context, directory, instance string, configured []byte) (backupreceipt.PinnedOperator, error)

InstalledOperator reads public installation custody for local export/drill. It never bootstraps a missing pin from an archive or from supplied evidence.

func RotateOperator

func RotateOperator(ctx context.Context, request OperatorRotationRequest) (upgrade.State, error)

func WithInstalledOperator

func WithInstalledOperator(ctx context.Context, directory string, configured []byte, fn func(OperatorCustody) error) error

WithInstalledOperator holds public installation custody before the caller acquires datastore exclusion. Backup and reconciliation need no root escrow, but cannot bypass a pending journal, configured pin or external epoch floor.

Types

type ConfigurationCheck

type ConfigurationCheck func(context.Context, *upgrade.CandidateConfiguration, map[string]string) error

ConfigurationCheck receives a fixed owner projection and its opened values, never datastore authority. Nil projection means bootstrap configuration. It must start no listeners, workers, or provider requests.

type ConfigurationPreflight

type ConfigurationPreflight struct {
	Request          Request
	InstalledCustody os.FileInfo
	TargetManifest   string
	CiphertextPath   string
}

type ConfigurationProof

type ConfigurationProof struct {
	MaterialDigest string
	StateDigest    string
}

ConfigurationProof contains advisory digests, never admission or evidence consumption authority. StateDigest is rechecked before signing submit; MaterialDigest follows the selected artifacts across replacement/restart.

func CheckStartupConfiguration

func CheckStartupConfiguration(ctx context.Context, input ConfigurationPreflight) (ConfigurationProof, error)

CheckStartupConfiguration authenticates the already selected artifacts before Run. Historical evidence is checked at its signed issuance time here: Run alone decides if new evidence is needed and enforces real-time expiry under migration exclusion. This check cannot revive or consume historical evidence.

func PreflightConfiguration

func PreflightConfiguration(ctx context.Context, input ConfigurationPreflight) (ConfigurationProof, error)

PreflightConfiguration checks a proposed source without opening runtime stores, locks, pin copies or migrations. The serving process must already be healthy on this exact binary. Execution repeats authority checks in Run.

type Mode

type Mode string
const (
	Boot    Mode = "boot"
	Migrate Mode = "migrate"
	// PrepareBackup authenticates a route and freezes its source before export.
	PrepareBackup Mode = "prepare-backup"
	// PrepareRoute attaches verified recovery evidence without running SQL.
	// The final target coordinator can then launch an older first-hop binary.
	PrepareRoute Mode = "prepare-route"
	// MaintenanceConfiguration opens only the authenticated managed transport
	// projection during a resumed maintenance operation. It never migrates.
	MaintenanceConfiguration Mode = "maintenance-configuration"
)

type OperatorCustody

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

OperatorCustody is valid only inside WithInstalledOperator. It contains only public authority; callers must authenticate the actual source independently.

func (OperatorCustody) Check

func (c OperatorCustody) Check(state upgrade.State) error

func (OperatorCustody) CheckSource

func (c OperatorCustody) CheckSource(instance string, epoch int64) error

type OperatorRotationRequest

type OperatorRotationRequest struct {
	Store                              upgrade.Config
	StateDirectory                     string
	NewPublicKey, Statement, Signature []byte
	// Only an explicit local CLI loads this escrow material. HTTP must never
	// construct an operator rotation request or read root-key custody files.
	LocalRecoveryRoot []byte
	// contains filtered or unexported fields
}

type Request

type Request struct {

	// CheckConfiguration performs only bounded local configuration validation.
	// It must start no listeners, workers or provider requests and receives no
	// datastore capability. Application wiring supplies its candidate checks.
	CheckConfiguration ConfigurationCheck
	AllowMigrations    bool
	Store              upgrade.Config
	BundleDirectory    string
	Pinned             releasetrust.PinnedTrust
	Migrations         embed.FS
	MigrationDirectory string
	Mode               Mode
	// Target optionally names the final route target. This process may execute
	// only the hop whose authenticated target matches its embedded build.
	Target                   releaseidentity.Identity
	Operator                 backupreceipt.PinnedOperator
	Ciphertext               *backupreceipt.Ciphertext
	Evidence                 backupreceipt.EvidenceMaterial
	LegacyWritersStopped     bool
	RootKey                  []byte
	StateDirectory           string
	InitialOperatorPublicKey []byte
	// contains filtered or unexported fields
}

type Result

type Result struct {
	Admission  upgrade.Admission
	State      upgrade.State
	SchemaOnly bool
}

Result is operational evidence, not permission to open a datastore. F3's opaque admission is minted under the same Session after successful health.

func Run

func Run(ctx context.Context, request Request) (Result, error)

Run binds production execution to source-owned immutable build claims.

func RunDevelopment

func RunDevelopment(ctx context.Context, request Request) (Result, error)

RunDevelopment uses the same gate with a distinct durable trust domain. A development root or signed bundle cannot adopt a production datastore.

Directories

Path Synopsis
Package testfixture invokes the actual signed development gate for owned databases.
Package testfixture invokes the actual signed development gate for owned databases.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL