update

package
v0.10.1 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package update implements verified binary staging and managed rollout messages.

Index

Constants

View Source
const GatewaySender = "@gateway"
View Source
const MaxBinarySize int64 = 128 << 20
View Source
const MaxReleaseManifestSize = 64 << 10
View Source
const MaxReleaseSignatureSize = 4 << 10
View Source
const ReleaseSignatureName = "control-manifest.sig"

Variables

This section is empty.

Functions

func AssetName

func AssetName(os, arch string) string

func CheckReleaseKeys added in v0.10.0

func CheckReleaseKeys(repository, keyID string, data []byte) error

CheckReleaseKeys checks public CI configuration against reviewed source pins. Configuration never replaces the keys trusted by a running executable.

func Download

func Download(ctx context.Context, client *http.Client, url, token, path string, asset Asset) error

func DownloadPreferred added in v0.5.1

func DownloadPreferred(ctx context.Context, route gatewayroute.Route, repository, version, gateway, token, path string, asset Asset) error

DownloadPreferred uses GitHub only for the exact authenticated gateway asset. Gateway storage remains a complete fallback, including for development builds. A proxied node streams from the gateway only, through its route: it has no direct internet path, and its proxy is not a general egress.

func InspectExecutable

func InspectExecutable(ctx context.Context, path string) (buildinfo.Info, error)

func IsCurrent

func IsCurrent(info buildinfo.Info, version string, asset Asset) bool

IsCurrent also requires retirement of a reported legacy supervisor. Runtime migration must not be used to gate software/protocol compatibility.

func IsSoftwareCurrent added in v0.8.4

func IsSoftwareCurrent(info buildinfo.Info, version string, asset Asset) bool

IsSoftwareCurrent checks the selected release independently of process topology. A running version still matches after a rebuild changes its checksum; Matches remains strict for binary validation.

func Matches

func Matches(info buildinfo.Info, asset Asset) bool

func PrepareWindowsRuntime added in v0.8.4

func PrepareWindowsRuntime(dir string, current RuntimeBinary, gui bool) (string, error)

PrepareWindowsRuntime must be called under runtime.lock, after the old process exits. It never overwrites a running executable.

func ReleaseSignatureMessage added in v0.10.0

func ReleaseSignatureMessage(repository, tag, keyID string, manifest []byte) ([]byte, error)

ReleaseSignatureMessage defines the v1 signing protocol for build-time tooling. NUL-delimited context fields exclude NUL themselves. Manifest bytes are last and are never reserialized, so even whitespace changes invalidate a signature.

func SaveBinary

func SaveBinary(reader io.Reader, path string, asset Asset) error

SaveBinary never publishes incomplete or unverified data.

func SaveRuntimeSwitch added in v0.8.4

func SaveRuntimeSwitch(dir string, current, next RuntimeBinary) error

SaveRuntimeSwitch retains recovery state before changing the selected binary.

func ShortError

func ShortError(err error) string

func ValidDigest

func ValidDigest(value string) bool

func ValidateExecutable

func ValidateExecutable(ctx context.Context, path, version string, asset Asset) error

func ValidatedExecutable added in v0.5.7

func ValidatedExecutable(ctx context.Context, path, version string, asset Asset) (buildinfo.Info, error)

ValidatedExecutable reads compatibility only after authenticating the bytes.

func Verify

func Verify(path string, asset Asset) error

Verify checks the actual bytes on every call. File metadata is not evidence of integrity: contents can change without changing size or modification time.

func VerifyReleaseManifest added in v0.4.0

func VerifyReleaseManifest(ctx context.Context, repository, tag string, manifest, proof []byte) error

VerifyReleaseManifest authenticates the exact manifest bytes with a pinned key.

func WindowsRuntimePath added in v0.8.4

func WindowsRuntimePath(dir string) string

WindowsRuntimePath is stable across releases and covered by firewall rules.

Types

type Asset

type Asset struct {
	OS     string `json:"os"`
	Arch   string `json:"arch"`
	File   string `json:"file"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

func WindowsRuntimeImage added in v0.8.4

func WindowsRuntimeImage(current RuntimeBinary, gui bool) ([]byte, Asset, error)

WindowsRuntimeImage verifies the source before deriving a console-free image. The source checksum remains the software identity; the derived checksum is used only to publish and verify the local launch copy.

type Command

type Command struct {
	ID          string    `json:"id"`
	Version     string    `json:"version,omitempty"`
	Asset       Asset     `json:"asset,omitempty"`
	LeaseUntil  time.Time `json:"leaseUntil,omitempty"`
	ReleaseRepo string    `json:"releaseRepo,omitempty"`
	// ProxyFor binds a child's maintenance reservation to its configured proxy.
	ProxyFor  string    `json:"proxyFor,omitempty"`
	ProxyURL  string    `json:"proxyUrl,omitempty"`
	ParkUntil time.Time `json:"parkUntil,omitzero"`
}

type Deployment

type Deployment struct {
	ID           string    `json:"id"`
	Manifest     Manifest  `json:"manifest"`
	Source       string    `json:"source"`
	Phase        string    `json:"phase"`
	Error        string    `json:"error,omitempty"`
	UpdatedAt    time.Time `json:"updatedAt"`
	Participants []string  `json:"participants,omitempty"`
	Deferred     []string  `json:"deferred,omitempty"`
	Contract     int       `json:"contract,omitempty"`
	InFlight     []string  `json:"inFlight,omitempty"`
	GatewayState string    `json:"gatewayState,omitempty"`
}

type Manifest

type Manifest struct {
	Version   string    `json:"version"`
	CreatedAt time.Time `json:"createdAt"`
	Assets    []Asset   `json:"assets"`
}

func (Manifest) Asset

func (m Manifest) Asset(os, arch string) (Asset, bool)

func (Manifest) ID

func (m Manifest) ID() string

func (Manifest) Validate

func (m Manifest) Validate() error

type PruneResult

type PruneResult struct {
	Blobs  int
	Staged int
}

type ReleaseKeyring added in v0.10.0

type ReleaseKeyring map[string]map[string]string

ReleaseKeyring maps exact repositories and key IDs to base64 Ed25519 public keys. Production uses only the reviewed pins in release_keys.go, never downloaded keys.

func (ReleaseKeyring) Verify added in v0.10.0

func (keys ReleaseKeyring) Verify(ctx context.Context, repository, tag string, manifest, proof []byte) error

Verify permits isolated keyrings for build tooling and tests without changing the process-wide production pins.

type ReleaseSignature added in v0.10.0

type ReleaseSignature struct {
	Version   int    `json:"version"`
	KeyID     string `json:"keyId"`
	Signature []byte `json:"signature"`
}

ReleaseSignature is a versioned detached Ed25519 signature, not a key source.

type Repository

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

func OpenRepository

func OpenRepository(dir string) (*Repository, error)

func (*Repository) BeginInstall

func (r *Repository) BeginInstall(id string, participants []string) error

func (*Repository) Blob

func (r *Repository) Blob(hash string) string

func (*Repository) Current

func (r *Repository) Current() *Deployment

func (*Repository) NodeInstall added in v0.5.7

func (r *Repository) NodeInstall(id, node string, pending bool) error

NodeInstall durably records commit intent, or clears it only after a fresh applied/resumed, exact-software/startup-blocked/resumed, or explicit failed/ resumed acknowledgement. Disconnection is not an acknowledgement and must not unlock publication; settling software does not claim startup migration passed.

func (*Repository) Pin

func (r *Repository) Pin(assets []Asset) func()

Pin keeps assets available while a release is downloaded and published.

func (*Repository) Prune

func (r *Repository) Prune(ctx context.Context, id string, retained []string) (PruneResult, error)

Prune removes obsolete gateway binaries only after durable rollout completion. Callers must serialize invitation creation and deployment selection with it.

func (*Repository) Publish

func (r *Repository) Publish(manifest Manifest, source string) (*Deployment, error)

func (*Repository) SetDeferred added in v0.5.1

func (r *Repository) SetDeferred(id string, deferred []string) error

SetDeferred records unavailable participants without claiming their updates succeeded. The selected manifest remains available when they reconnect.

func (*Repository) SetGatewayState added in v0.5.7

func (r *Repository) SetGatewayState(id, state string) error

func (*Repository) SetPhase

func (r *Repository) SetPhase(id, phase string, cause error) error

func (*Repository) Upload

func (r *Repository) Upload(reader io.Reader, asset Asset) error

func (*Repository) VerifyPinned added in v0.2.0

func (r *Repository) VerifyPinned(assets []Asset) (func(), error)

VerifyPinned hashes binaries without holding the repository mutex. The returned release function keeps cleanup from deleting them until their durable reference is published. Pins do not authorize unverified bytes.

type RuntimeBinary added in v0.8.4

type RuntimeBinary struct {
	Path    string `json:"path"`
	Version string `json:"version"`
	Asset   Asset  `json:"asset"`
}

RuntimeBinary is the durable selection, always referring to original verified bytes.

func InspectRuntime added in v0.8.4

func InspectRuntime(ctx context.Context, path string) (RuntimeBinary, error)

InspectRuntime validates the platform and complete executable bytes.

type Selection added in v0.5.1

type Selection struct {
	ID          string   `json:"id"`
	Manifest    Manifest `json:"manifest"`
	ReleaseRepo string   `json:"releaseRepo,omitempty"`
}

Selection exposes software metadata without cross-fleet rollout identities.

type Status

type Status struct {
	Software       buildinfo.Info `json:"software"`
	StagedSoftware buildinfo.Info `json:"stagedSoftware,omitzero"`
	ID             string         `json:"id,omitempty"`
	State          string         `json:"state"`
	Busy           bool           `json:"busy"`
	Paused         bool           `json:"paused"`
	LeaseUntil     time.Time      `json:"leaseUntil,omitempty"`
	Error          string         `json:"error,omitempty"`
	SeenAt         time.Time      `json:"seenAt"`
	ProxyDrain     bool           `json:"proxyDrain,omitempty"`
	ProxyFor       string         `json:"proxyFor,omitempty"`
	ParkUntil      time.Time      `json:"parkUntil,omitzero"`
}

type Updater

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

Updater stages gateway-published binaries and applies them under an idle reservation. It is part of the node service, not an AI agent or a separate execution role.

func NewUpdater

func NewUpdater(options UpdaterOptions) (*Updater, error)

func (*Updater) Receive

func (a *Updater) Receive(kind string, data []byte)

Receive is called only for messages authenticated as originating at the gateway.

func (*Updater) Run

func (a *Updater) Run(ctx context.Context)

func (*Updater) Snapshot

func (a *Updater) Snapshot() Status

type UpdaterOptions

type UpdaterOptions struct {
	Gateway, Token, Dir string
	CacheDir            string // Empty selects the OS machine-wide download cache.
	Software            buildinfo.Info
	// Route carries gateway selection reads and binary downloads.
	Route  gatewayroute.Route
	Busy   func() bool
	Pause  func() bool
	Resume func()
	Report func(context.Context, Status) error
	Apply  func(string) error
	// Only proxied nodes with a known worker can reserve and park for that
	// worker. Parking must refuse live gateway traffic, never cancel it.
	ProxyWorker   string
	ProxyURL      string
	ParkGateway   func(time.Time) bool
	ResumeGateway func()
}

UpdaterOptions supplies node-owned work admission and restart callbacks.

Jump to

Keyboard shortcuts

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