image

Documentation

Index

• func ConvertQCOW2(ctx context.Context, url, device string) error
• func Decompressor(r io.Reader, f Format) (io.Reader, io.Closer, error)
• func FetchOCILayer(ctx context.Context, reference string) (io.ReadCloser, error)
• func IsOCIReference(url string) bool
• func SelectBestSource(ctx context.Context, urls []string) (string, error)
• func Stream(ctx context.Context, url, device string, opts ...StreamOpts) error
• func StreamPartitions(ctx context.Context, url, device string) error
• func TrimOCIScheme(url string) string
• func VerifyGPGSignature(ctx context.Context, imageURL, sigURL, pubKeyPath string) error
• type Format
  • func DetectFormat(r io.Reader) (Format, io.Reader, error)
• type StreamOpts
• type WriteCounter
  • func (wc *WriteCounter) Write(p []byte) (int, error)

Functions

func ConvertQCOW2

func ConvertQCOW2(ctx context.Context, url, device string) error

ConvertQCOW2 downloads a qcow2 image to a tmpfs ramdisk, converts it to raw using qemu-img, and streams the result to the target device.

The flow is: download → tmpfs → qemu-img convert -f qcow2 -O raw → dd to device. The ramdisk is cleaned up after conversion.

func Decompressor

func Decompressor(r io.Reader, f Format) (io.Reader, io.Closer, error)

Decompressor wraps a reader with the appropriate decompression based on format. The returned io.Reader streams decompressed data. The closer (if non-nil) must be closed when done.

func FetchOCILayer

func FetchOCILayer(ctx context.Context, reference string) (io.ReadCloser, error)

FetchOCILayer pulls a single-layer OCI image and returns its content as a streaming io.ReadCloser. The reference should be a standard image ref (e.g. "ghcr.io/org/image:tag"). Auth uses the default Docker keychain (~/.docker/config.json).

func IsOCIReference

func IsOCIReference(url string) bool

IsOCIReference returns true if the URL uses the oci:// scheme.

func SelectBestSource

func SelectBestSource(ctx context.Context, urls []string) (string, error)

SelectBestSource probes multiple image URLs with HEAD requests and returns the one with the lowest response time. If only one URL is provided, it is returned directly. OCI references (oci://) are returned as-is without probing.

func Stream

func Stream(ctx context.Context, url, device string, opts ...StreamOpts) error

Stream downloads an image from a URL (http/https or oci://) and writes it to a block device. Compression is auto-detected via magic bytes (gzip, zstd, lz4, xz, bzip2). qcow2 images are detected and converted via ramdisk. Optional checksum validation is performed after write.

func StreamPartitions

func StreamPartitions(ctx context.Context, url, device string) error

StreamPartitions downloads an image to a tmpfs ramdisk, optionally converts qcow2 to raw, then copies each partition individually from the source image to the corresponding partition on the target disk.

This preserves the partition table on the target disk and allows the source image partitions to differ in size from the target.

func TrimOCIScheme

func TrimOCIScheme(url string) string

TrimOCIScheme removes the oci:// prefix from a URL.

func VerifyGPGSignature

func VerifyGPGSignature(ctx context.Context, imageURL, sigURL, pubKeyPath string) error

VerifyGPGSignature downloads a detached GPG signature from sigURL and verifies it against the image at imageURL using the public key at pubKeyPath. It uses gpgv (preferred) or gpg --verify as fallback. The image body is streamed directly into GPG's stdin to avoid storing multi-GB images in memory.

Types

type Format

type Format string

Format represents a detected compression format.

const (
	FormatRaw   Format = "raw"
	FormatGzip  Format = "gzip"
	FormatZstd  Format = "zstd"
	FormatLZ4   Format = "lz4"
	FormatXZ    Format = "xz"
	FormatBzip2 Format = "bzip2"
	FormatQCOW2 Format = "qcow2"
)

Supported compression and image formats.

func DetectFormat

func DetectFormat(r io.Reader) (Format, io.Reader, error)

DetectFormat peeks at the first bytes of the reader to determine compression format via magic bytes. Returns the detected format and a new reader that replays the peeked bytes.

type StreamOpts

type StreamOpts struct {
	// Checksum is the expected hex-encoded checksum of the decompressed data.
	Checksum string
	// ChecksumType is the hash algorithm: "sha256" or "sha512".
	ChecksumType string
}

StreamOpts are optional parameters for Stream.

type WriteCounter

type WriteCounter struct {
	Total atomic.Uint64
}

WriteCounter counts the number of bytes written to it. It implements to the io.Writer interface and we can pass this into io.TeeReader() which will report progress on each write cycle.

func (*WriteCounter) Write

func (wc *WriteCounter) Write(p []byte) (int, error)