snapshot

Documentation

Overview

Package snapshot pushes and pulls cocoon VM snapshots as OCI artifacts. Push reads a `cocoon snapshot export` stream; Stream assembles a `cocoon snapshot import` tar into a caller-supplied writer.

Index

• Variables
• func FetchSnapshotConfig(ctx context.Context, dl Downloader, name string, desc manifest.Descriptor) (*manifest.SnapshotConfig, error)
• func MarshalEnvelope(cfg *manifest.SnapshotConfig, localName string) ([]byte, error)
• func Stream(ctx context.Context, raw []byte, dl Downloader, opts StreamOptions) error
• func StreamParsed(ctx context.Context, m *manifest.OCIManifest, dl Downloader, ...) error
• type CocoonRunner
• type Downloader
• type PushOptions
• type PushResult
• type Pusher
  • func (p *Pusher) Push(ctx context.Context, opts PushOptions) (*PushResult, error)
• type StreamOptions
• type Uploader

Variables

var (
	ErrManifestNotFound = errors.New("manifest not found")
)

Functions

func FetchSnapshotConfig

func FetchSnapshotConfig(ctx context.Context, dl Downloader, name string, desc manifest.Descriptor) (*manifest.SnapshotConfig, error)

FetchSnapshotConfig downloads and parses the snapshot config blob.

func MarshalEnvelope

func MarshalEnvelope(cfg *manifest.SnapshotConfig, localName string) ([]byte, error)

func Stream

func Stream(ctx context.Context, raw []byte, dl Downloader, opts StreamOptions) error

Stream reassembles a snapshot manifest into a cocoon-import tar stream. If raw is an OCI image-index (multi-platform), a child manifest is resolved via dl.GetManifest(..., childDigest) and streamed instead — preferring linux/amd64, falling back to the first non-attestation entry.

func StreamParsed

func StreamParsed(ctx context.Context, m *manifest.OCIManifest, dl Downloader, opts StreamOptions) error

StreamParsed accepts an already-parsed manifest.

Types

type CocoonRunner

type CocoonRunner interface {
	Export(ctx context.Context, name string) (io.ReadCloser, func() error, error)
}

CocoonRunner abstracts the `cocoon snapshot export` source Pusher reads from.

type Downloader

type Downloader interface {
	GetManifest(ctx context.Context, name, tag string) ([]byte, string, error)
	GetBlob(ctx context.Context, name, digest string) (io.ReadCloser, error)
}

Downloader abstracts OCI manifests and digest-verified blob streams.

type PushOptions

type PushOptions struct {
	Name        string
	Tag         string
	BaseImage   string // optional cocoonstack.snapshot.baseimage annotation
	Source      string
	Revision    string
	Annotations map[string]string
	Progress    func(string)

	// v2 wire-format knobs; all-zero reproduces the v1 writer exactly.
	ZstdLevel       int // >0: zstd-compress layers ≥ 1 MiB at this level
	ChunkSizeMiB    int // >0: split files into chunks of this many uncompressed MiB, one blob each
	Concurrency     int // parallel chunk uploads / encoder threads (default 8)
	MemoryBudgetMiB int // pipeline buffer cap (default 9216); workers clamp to budget/(2×chunk)−1
}

PushOptions configures a snapshot push operation.

type PushResult

type PushResult struct {
	Name           string
	Tag            string
	ManifestDigest string // sha256:<hex>
	ManifestBytes  []byte
	TotalSize      int64
	LayerCount     int
}

PushResult contains the outcome of a successful push.

type Pusher

type Pusher struct {
	Uploader Uploader
	Cocoon   CocoonRunner
}

Pusher exports and uploads cocoon snapshots as OCI artifacts.

func (*Pusher) Push

func (p *Pusher) Push(ctx context.Context, opts PushOptions) (*PushResult, error)

Push exports a snapshot via cocoon and uploads it as an OCI artifact.

type StreamOptions

type StreamOptions struct {
	Name            string
	LocalName       string // empty = use Name
	Writer          io.Writer
	Progress        func(string)
	Concurrency     int // parallel chunk prefetch for encoded layers (default 8)
	MemoryBudgetMiB int // prefetch-buffer cap for this Stream call (default 4096)
}

StreamOptions configures snapshot tar stream assembly.

type Uploader

type Uploader interface {
	HasBlob(ctx context.Context, name, digest string) (bool, error)
	PutBlob(ctx context.Context, name, digest string, body io.Reader, size int64) error
	PutManifest(ctx context.Context, name, tag string, data []byte, contentType string) error
}

Uploader abstracts OCI blob and manifest uploads.