Documentation
¶
Overview ¶
Package toolchain provides a governed execution substrate for external tools.
StageFreight owns its toolchains. Every tool used is resolved, downloaded, verified, cached, and reported. No silent host fallback. No DinD. No containers-for-tools. No environment luck.
Contract properties:
- Immutable installs — once cached, a version directory is never mutated
- Checksum verification required — every download verified against official checksums
- Explicit provenance — .metadata.json records source URL, checksum, install time
- Deterministic resolution — same version = same binary, always
- No silent host fallback — system binaries in PATH are not used
- Hard failure on verification miss — checksum mismatch = error, not warning
Index ¶
- func AcquireInstallLock(dir string, timeout time.Duration) (*os.File, error)
- func CacheBinPathIn(root, tool, version, binary string) string
- func CacheDirIn(root, tool, version string) string
- func CleanEnv() []string
- func GoCacheDirs() (gomod, gocache string)
- func GoCacheStatus() (gomod, gocache string, warm bool)
- func InstallRoot(rootDir string) string
- func ManagedToolNames() []string
- func MetadataPathIn(root, tool, version string) string
- func PersistentCacheRoot() string
- func ReadRoots(rootDir string) []string
- func ReleaseInstallLock(f *os.File)
- func RenderPanel(w io.Writer, results []Result, cacheRoot string, elapsed fmt.Stringer)
- func Report(w io.Writer, r Result)
- func ResolveGoVersion(dir, repoRoot string) string
- func ResolveVersion(tool, requestedVersion string, desired map[string]config.ToolPinConfig) (version string, isPinned bool)
- func SeedDesired() map[string]config.ToolPinConfig
- func StampMetadata(m *Metadata)
- type Metadata
- type Result
- type ToolDef
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AcquireInstallLock ¶
AcquireInstallLock acquires an exclusive file lock for a tool install directory. Blocks up to timeout. Returns the lock file handle (caller must call ReleaseInstallLock). If lock cannot be acquired within timeout, returns an error — no deadlock.
func CacheBinPathIn ¶
CacheBinPathIn returns the binary path for a tool within a specific cache root.
func CacheDirIn ¶
CacheDirIn returns the versioned install directory within a specific cache root.
func CleanEnv ¶
func CleanEnv() []string
CleanEnv returns a minimal execution environment for toolchain-resolved binaries. No implicit PATH. No host leakage. All tools are invoked by absolute path.
Tools that need specific env vars (e.g. GRYPE_DB_CACHE_DIR, COSIGN_YES) append them to the returned slice at the call site.
func GoCacheDirs ¶ added in v0.6.1
func GoCacheDirs() (gomod, gocache string)
GoCacheDirs returns absolute GOMODCACHE and GOCACHE paths on the persistent runner mount, creating them, so a binary build reuses downloaded modules and compiled packages across CI jobs instead of paying the full cold-cache cost (module download + cross-compile, 170s+) every run. The Dockerfile reserves /stagefreight/cache for exactly this ("mount a volume here for cross-run reuse"); the container filesystem and the git workspace are both ephemeral.
Returns ("", "") when the mount is absent or unwritable (local dev), which signals the caller to leave Go's default $HOME-based caches untouched — those already persist across local runs.
func GoCacheStatus ¶ added in v0.6.1
GoCacheStatus returns the resolved GOMODCACHE/GOCACHE plus whether the build cache is already warm (a prior run populated it). gomod=="" means no persistent mount is available, so the build will fall back to Go's ephemeral $HOME caches — surfaced as an explicit "cache off" row. warm=true means the persistent GOCACHE already holds compiled packages, so this build reuses them (the fast path); cold means the build is populating the cache for next time.
func InstallRoot ¶
InstallRoot returns the directory where new toolchain installs are written. Prefers persistent mount if writable, otherwise workspace-local.
The persistent mount (/stagefreight) is supplied to every CI job container empty, so its toolchains/ subdir does not pre-exist — we create it on first use. Without that, the resolver fell back to the workspace-local cache, which the git checkout wipes every job, forcing a fresh Go SDK download each run.
func ManagedToolNames ¶
func ManagedToolNames() []string
ManagedToolNames returns a sorted list of all managed tool names.
func MetadataPathIn ¶
MetadataPathIn returns the metadata file path within a specific cache root.
func PersistentCacheRoot ¶
func PersistentCacheRoot() string
PersistentCacheRoot returns the persistent cache root path constant.
func ReadRoots ¶
ReadRoots returns cache roots to search for existing toolchain installs, in priority order. Persistent mount is checked first (operator-preseeded or previously written), then workspace-local.
func ReleaseInstallLock ¶
ReleaseInstallLock releases the file lock and closes the handle.
func RenderPanel ¶
RenderPanel writes the toolchain resolution panel to w. Called once during audition after all tools are resolved.
func Report ¶
Report writes a human-readable toolchain resolution summary to w. This is the ONLY human-output surface in the toolchain package. All other functions return structured data — no stderr, no prints.
func ResolveGoVersion ¶
ResolveGoVersion extracts the full Go version from go.work or go.mod. Returns the complete version string (e.g. "1.26.1"), not stripped to major.minor. Falls back to "1.24" if no version directive found.
func ResolveVersion ¶
func ResolveVersion(tool, requestedVersion string, desired map[string]config.ToolPinConfig) (version string, isPinned bool)
ResolveVersion determines the version to use for a tool.
Precedence (strict):
- requestedVersion — explicit caller override (non-empty = use it)
- desired[tool].Version — config pin (authoritative, not a hint)
- ToolDef.DefaultVer — hardcoded fallback
Returns the version string and whether it came from a config pin. The isPinned flag is critical: pinned versions that fail to resolve must hard-fail with no fallback to default.
func SeedDesired ¶
func SeedDesired() map[string]config.ToolPinConfig
SeedDesired returns a complete map of all managed tools with their current default versions. Used to populate toolchains.desired for new repos so that all managed tools are explicitly materialized in config from the start. Go is excluded — its version comes from go.mod, not the toolchain registry.
func StampMetadata ¶
func StampMetadata(m *Metadata)
StampMetadata sets the install timestamp and author.
Types ¶
type Metadata ¶
type Metadata struct {
Tool string `json:"tool"`
Version string `json:"version"`
Platform string `json:"platform"`
SourceURL string `json:"source_url"`
// SHA256 is the checksum of the downloaded archive (provenance).
// Verified against official release checksums at download time.
SHA256 string `json:"sha256"`
// BinSHA256 is the checksum of the extracted binary (cache validation).
// Used on cache hit to verify the binary hasn't been tampered with.
BinSHA256 string `json:"bin_sha256"`
InstalledAt string `json:"installed_at"`
InstalledBy string `json:"installed_by"`
}
Metadata is the provenance record for a cached toolchain install. Immutable after write. If missing or checksum mismatch, the install is treated as corrupt and skipped (or re-downloaded to a writable root).
type Result ¶
type Result struct {
Tool string // "go", "trivy", etc.
Version string // "1.26.1", "0.69.3", etc.
Path string // absolute path to binary
CacheHit bool // true if served from cache, false if downloaded
SourceURL string // where it was (or would be) fetched from
SHA256 string // verified archive/binary checksum (provenance)
BinSHA256 string // extracted binary checksum (cache validation)
}
Result is the outcome of a toolchain resolution. Every field is populated. Callers use Path for execution and can report provenance from the rest.
func Resolve ¶
Resolve ensures a tool at the requested version is available and verified. Returns the binary path and provenance. Downloads if not cached. Hard-fails on checksum mismatch, download error, or metadata write failure. Empty version uses ToolDef.DefaultVer. No fallback. No stderr output — callers own presentation.
type ToolDef ¶
type ToolDef struct {
Name string
BinaryName string // name of the binary file
DefaultVer string // default version if none specified
DownloadURL func(version, goos, goarch string) string // archive or binary URL
ChecksumURL func(version, goos, goarch string) string // checksum file URL
Format string // "tar.gz" or "binary"
ArchiveStrip string // prefix to strip from tar entries (e.g. "go/")
GitHubOwner string // GitHub owner for release checking (e.g. "aquasecurity")
GitHubRepo string // GitHub repo for release checking (e.g. "trivy")
}
ToolDef describes how to download and verify a tool.
func AllTools ¶
func AllTools() []ToolDef
AllTools returns a copy of all registered tool definitions. Callers can inspect metadata without mutating the registry.
func LookupTool ¶
LookupTool returns the ToolDef for a named tool.
Source Files