image

Documentation

Overview

Package image handles cloud image download, verification, and conversion.

The catalog is an embedded JSON file (catalog.json) keyed by alias; each alias pins a dated upstream snapshot and, per GOARCH, a download URL plus the SHA256 fetch verifies before use. The snapshot is stamped into the cache filename (for both the source and the converted raw) so an upstream bump is a cache miss, not a stale hit — images are pinned the way the VMM binary and firmware are (ADR-0011, ADR-0019).

Index

• func CopyDisk(src, dst string, sizeBytes int64) error
• func Ensure(cacheDir, urlOrAlias string) (string, error)
• type ArchImage
• type ImageInfo

Functions

func CopyDisk

func CopyDisk(src, dst string, sizeBytes int64) error

CopyDisk copies the source disk image to the destination with the given size. If size is larger than the source, the file is extended (sparse).

func Ensure

func Ensure(cacheDir, urlOrAlias string) (string, error)

Ensure downloads and prepares an image, returning the path to the raw disk. If the image is already cached it returns immediately. If urlOrAlias is a known catalog alias (e.g. "debian-12") the per-GOARCH entry is used: the source is fetched under a snapshot-stamped name, SHA256-verified, and converted (when it is a qcow2/.img) to the snapshot-stamped raw name. A non-alias is treated as a literal URL — unverified, with a basename-derived cache name (the BYO escape hatch, unchanged).

Types

type ArchImage

type ArchImage struct {
	URL    string `json:"url"`
	SHA256 string `json:"sha256"`
}

ArchImage is the per-architecture pinned download: the snapshot-stamped URL and the SHA256 fetch verifies the downloaded source against before it is cached.

type ImageInfo

type ImageInfo struct {
	Distro   string               `json:"distro"`
	Version  string               `json:"version"`
	Codename string               `json:"codename,omitempty"`
	Snapshot string               `json:"snapshot"`
	BumpedAt string               `json:"bumped_at,omitempty"`
	Arch     map[string]ArchImage `json:"arch"`
}

ImageInfo describes a pinned cloud image: a dated upstream snapshot and, per GOARCH, the snapshot-stamped download URL plus the SHA256 fetch verifies before use. The arch keys (amd64/arm64) match Go's GOARCH, so one alias resolves to the right image on macOS Apple Silicon and on Linux amd64/arm64.

Distro/Version/Codename/BumpedAt are inputs for the contrib/catalog refresher (the only writer of Snapshot/Arch values) and are ignored at runtime: the library reads only Snapshot (for the cache filename) and Arch (URL + SHA256).