acquire

Documentation

Overview

Package acquire obtains a pinned binary artifact and places it on disk, verified. It is the content-agnostic core shared by anything that has to fetch and install an external binary: a local inference runtime, an external command-line dependency. It downloads a pinned archive over the hardened fetch path, verifies its digest, extracts it with a path-traversal guard and a total-size ceiling, installs it atomically into a target directory, and locates the wanted executable inside it.

It knows nothing about what the binary is or whether it is safe to run: the caller applies its own version gate before calling, and the caller runs the binary inside the sandbox afterward. This package only guarantees that the bytes installed at the target are the pinned, digest-verified release and that a hostile or corrupt archive can neither write outside the target nor exhaust the disk.

Index

• func FindBinary(root, binName string) (string, bool)
• func InstallTo(ctx context.Context, dl *fetch.Downloader, rel Release, targetDir string) (binPath string, reused bool, err error)
• func SafeJoin(base, name string) (string, bool)
• func TraversalError(name string) error
• type ArchiveKind
• type Release

Functions

func FindBinary

func FindBinary(root, binName string) (string, bool)

FindBinary searches the extracted tree under root for a file named binName and returns its path. A release archive may place the binary at the root or under a build directory depending on the platform, so it is located by name rather than a fixed path.

func InstallTo

func InstallTo(ctx context.Context, dl *fetch.Downloader, rel Release, targetDir string) (binPath string, reused bool, err error)

InstallTo ensures rel's binary is present at targetDir and returns the absolute path to it. It is idempotent: if the binary is already present at targetDir it is reused without a download and reused is true. targetDir should be a version-specific path so a new version installs alongside an old one rather than over it.

The archive is downloaded to a temporary file next to targetDir, verified against the pinned digest by the download path, then extracted into a sibling staging directory and moved into place only on success, so an interrupted or corrupt install never leaves a half-populated directory at targetDir.

func SafeJoin

func SafeJoin(base, name string) (string, bool)

SafeJoin resolves an archive or manifest entry name under base and confirms the result stays within base. An entry that is absolute or walks out of the tree with ".." is rejected outright rather than re-rooted, so a hostile archive or manifest cannot place a file outside the install directory and cannot disguise its intent by relying on path collapsing. The containment is then re-checked against the resolved path as defense in depth. It is exported so a caller writing files from an untrusted manifest (not only the archive extractor) can apply the same guard.

func TraversalError

func TraversalError(name string) error

TraversalError is the error SafeJoin's callers return when an entry escapes the install directory, so the refusal reads the same whether it came from the archive extractor or a manifest writer.

Types

type ArchiveKind

type ArchiveKind int

ArchiveKind is the container format a release ships in. Both are handled with the standard library, so acquiring a binary adds no decompression dependency.

const (
	// ArchiveZip is a .zip archive (the common Windows release form).
	ArchiveZip ArchiveKind = iota
	// ArchiveTarGz is a gzip-compressed tar (the common Linux and macOS release form).
	ArchiveTarGz
)

type Release

type Release struct {
	// URL is the https source of the release archive.
	URL string
	// SHA256 is the pinned digest the downloaded archive must match.
	SHA256 string
	// SizeBytes is the archive's known size, used as the download cap.
	SizeBytes int64
	// Archive is the archive's container format.
	Archive ArchiveKind
	// BinName is the executable to locate inside the extracted archive (for example
	// "flynn" or "flyctl.exe"). Its sibling files are extracted alongside it.
	BinName string
}

Release is a single pinned artifact for one platform: where to get it, the digest it must match, its container format, and which executable inside it the caller wants. A release is data, fixed at build time, so the set of artifacts that can be installed is auditable and cannot be redirected at runtime.