hydrate

Documentation

Overview

Package hydrate makes the Pitot binary a repository property: a committed pin (.pitot/version) names the exact version, and hydration materializes it into a write-once user cache from the distribution front door. Fresh clones, CI, and cloud agents need no install step — the first invocation hydrates.

The package is governed by these control laws; each has a tagged conformance test (// control-law: <slug>):

• pin-is-the-only-version-authority — nothing resolves "latest" at exec time; Ensure takes the pinned version as its only version input. Only `pitot upgrade` may consult Latest.
• nothing-executes-unverified — the sha256 from checksums.txt must match before a byte lands in the slot; a failed verify leaves no slot.
• slots-are-write-once — a populated slot is never rewritten; rollback is reverting the pin (a cache hit).
• upgrade-is-a-reviewed-data-diff — the only repository mutation an upgrade makes is rewriting .pitot/version; binaries change only as a consequence of the committed pin.
• upgrade-preserves-the-tenancy-contract — an upgrade re-validates every tenant fragment (merge + requires_protocol) before rewriting the pin.
• absence-fails-closed-and-named — no cache hit plus no network (or PITOT_NO_HYDRATE=1) is a specific error naming the pin, the missing slot, and the kill switch; there is no fallback to a PATH binary.
• the-shim-carries-no-policy — the repo shim reads the pin, fetches, verifies, and execs; it never reads fragments or makes decisions.
• bindings-move-in-lockstep-with-the-CLI — one release tag ships binary, npm, and python bindings at one version; installs pin exactly.
• packages-come-from-our-registry-or-nowhere — consumers resolve bindings only through the front door host; registry internals never appear in client config.

Index

• Constants
• func BaseURL() string
• func CacheRoot() (string, error)
• func Ensure(ctx context.Context, version string) (string, error)
• func Host() string
• func Latest(ctx context.Context) (string, error)
• func Pin(root string) (string, error)
• func Slot(version string) (string, error)
• func WritePin(root, version string) error

Constants

const (
	// PinPath is the repository-relative pin file: one trimmed semver line.
	PinPath = ".pitot/version"
	// DefaultHost is the distribution front door. Overridable via EnvHost for
	// tests and air-gapped mirrors; the registry behind it never appears here.
	DefaultHost = "get.operatorstack.systems"
	// EnvHost overrides the front-door host (scheme-carrying values allowed,
	// e.g. http://127.0.0.1:PORT for hermetic tests).
	EnvHost = "PITOT_GET_HOST"
	// EnvNoHydrate is the kill switch: when set to a non-empty value other
	// than "0", hydration is cache-only and misses fail closed.
	EnvNoHydrate = "PITOT_NO_HYDRATE"
	// EnvCacheDir overrides the cache root (hermetic tests).
	EnvCacheDir = "PITOT_CACHE_DIR"
)

Functions

func BaseURL

func BaseURL() string

BaseURL normalizes the front-door host into a scheme-carrying base URL.

func CacheRoot

func CacheRoot() (string, error)

CacheRoot is the platform cache directory holding version slots. The rule must stay byte-identical with the shim scripts: POSIX (including darwin) uses ${XDG_CACHE_HOME:-$HOME/.cache}/pitot; Windows uses %LOCALAPPDATA%\pitot.

func Ensure

func Ensure(ctx context.Context, version string) (string, error)

Ensure materializes the pinned version's binary in its cache slot and returns the slot path. A populated slot is returned as-is (write-once); a miss downloads the release archive and checksums from the front door, verifies, extracts, and renames into place under a clone-wide lock.

func Host

func Host() string

Host returns the front-door host, honoring the EnvHost override.

func Latest

func Latest(ctx context.Context) (string, error)

Latest resolves the newest published version from the front door. Only `pitot upgrade` may call this — exec-time paths take the pin and nothing else (pin-is-the-only-version-authority).

func Pin

func Pin(root string) (string, error)

Pin reads the repository's committed version pin.

func Slot

func Slot(version string) (string, error)

Slot returns the write-once binary path for a version on this platform.

func WritePin

func WritePin(root, version string) error

WritePin records a version pin. The pin is the only version authority; a pin rewrite is the whole repository footprint of an upgrade.