cache

Documentation

Overview

Package cache is the device-side content-addressed store for weave guest artifacts (decision 0008): one OCI image layout shared by every image on a device, so a chunk present in two images is stored once; in-use pins that garbage collection never removes; least-recently-used eviction down to a quota; a disk-space check before the first byte of a pull; and OCI-layout export and import for air-gapped sites, with referrers carried along.

A Store serialises its own operations; separate processes sharing one cache directory must coordinate externally (open question in docs/research/12-open-questions.md).

Index

• Constants
• Variables
• type Entry
• type Guard
• type Options
• type Store
  • func Open(ctx context.Context, root string, o Options) (*Store, error)
  • func (s *Store) Dir() string
  • func (s *Store) Entries() []Entry
  • func (s *Store) ExportLayout(ctx context.Context, ref, dir string) (ocispec.Descriptor, error)
  • func (s *Store) GC(ctx context.Context, keep int64) (int64, error)
  • func (s *Store) ImportLayout(ctx context.Context, dir string) ([]ocispec.Descriptor, error)
  • func (s *Store) Pin(root digest.Digest, owner string) error
  • func (s *Store) Pull(ctx context.Context, c *client.Client, ref client.Reference) (ocispec.Descriptor, error)
  • func (s *Store) Remove(ctx context.Context, root digest.Digest) error
  • func (s *Store) Resolve(ctx context.Context, ref string) (ocispec.Descriptor, error)
  • func (s *Store) Target() *oci.Store
  • func (s *Store) Unpin(owner string) error
  • func (s *Store) Usage() (int64, error)

Constants

const DefaultQuota int64 = 100 << 30

DefaultQuota is 100 GiB.

Variables

var (
	// ErrNoSpace reports that a pull cannot fit even after evicting
	// everything unpinned.
	ErrNoSpace = errors.New("not enough disk space")
	// ErrNotCached reports a reference the cache does not hold.
	ErrNotCached = errors.New("not in cache")
	// ErrPinned reports an image an owner still holds.
	ErrPinned = errors.New("image is pinned")
)

Types

type Entry

type Entry struct {
	Root       digest.Digest
	Refs       []string
	LastAccess time.Time
	// PinnedBy lists the owners holding the image, sorted; empty when it
	// may be evicted.
	PinnedBy []string
}

Entry describes one cached image for listings and prune decisions.

type Guard

type Guard interface {
	Available(path string) (int64, error)
}

Guard reports free bytes for the volume holding path. guestweave-cli-macos supplies an implementation that counts purgeable APFS space.

type Options

type Options struct {
	// Quota caps the bytes the cache keeps after a GC; default 100 GiB.
	Quota int64
	// Guard checks free space before a pull; nil uses the platform's
	// file-system statistics.
	Guard Guard
	// Now is the clock; nil uses time.Now.
	Now func() time.Time
}

Options configure a Store.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is a cache directory.

func Open

func Open(ctx context.Context, root string, o Options) (*Store, error)

Open opens or creates a cache at root.

func (*Store) Dir

func (s *Store) Dir() string

Dir is the cache root directory.

func (*Store) Entries

func (s *Store) Entries() []Entry

Entries lists the cached images, least recently used first.

func (*Store) ExportLayout

func (s *Store) ExportLayout(ctx context.Context, ref, dir string) (ocispec.Descriptor, error)

ExportLayout writes root and its referrers to a new OCI layout at dir, tagged ref, for transfer to an air-gapped site.

func (*Store) GC

func (s *Store) GC(ctx context.Context, keep int64) (int64, error)

GC evicts unpinned images, least recently used first, until usage is at or below keep (the quota when keep <= 0), then removes unreferenced blobs. It returns the bytes freed.

func (*Store) ImportLayout

func (s *Store) ImportLayout(ctx context.Context, dir string) ([]ocispec.Descriptor, error)

ImportLayout copies every tagged root in the layout at dir, with referrers, into the cache. Digests are unchanged, so channel and signature verification still apply after the transfer.

func (*Store) Pin

func (s *Store) Pin(root digest.Digest, owner string) error

Pin keeps root alive for owner (a running VM, a clone, a hostweave attempt). A Windows parent disk must stay pinned while any differencing child exists.

func (*Store) Pull

func (s *Store) Pull(
	ctx context.Context,
	c *client.Client,
	ref client.Reference,
) (ocispec.Descriptor, error)

Pull fetches ref into the cache (with referrers) unless its root is already present, checking free space first and evicting least-recently-used unpinned images when needed. It returns the root descriptor.

func (*Store) Remove

func (s *Store) Remove(ctx context.Context, root digest.Digest) error

Remove evicts one image and its signatures, then collects unreferenced blobs. It refuses a pinned image: a consumer's VM may be built on it.

func (*Store) Resolve

func (s *Store) Resolve(ctx context.Context, ref string) (ocispec.Descriptor, error)

Resolve looks up a cached reference (as written by Pull or ImportLayout) or digest and marks it used.

func (*Store) Target

func (s *Store) Target() *oci.Store

Target is the underlying OCI layout store, for pack.Unpack and chunk.Assemble.

func (*Store) Unpin

func (s *Store) Unpin(owner string) error

Unpin releases owner's pin; unknown owners are ignored.

func (*Store) Usage

func (s *Store) Usage() (int64, error)

Usage returns the bytes held in the layout's blob store.