images

Documentation

Index

• Variables
• func BuildGCModule[I any](cfg GCModuleConfig[I]) gc.Module[ImageGCSnapshot]
• func GCCollectBlobs(ctx context.Context, tempDir string, dirOnly bool, ids []string, ...) error
• func GCStaleTemp(ctx context.Context, dir string, dirOnly bool) []error
• func LookupRefs[E Entry](images map[string]*E, id string, normalizers ...func(string) (string, bool)) []string
• func NewStore[T any](filePath, lockPath string) (storage.Store[T], lock.Locker)
• func ReferencedDigests[E Entry](images map[string]*E) map[string]struct{}
• type BaseConfig
  • func (c *BaseConfig) BackendDir() string
  • func (c *BaseConfig) BlobPath(hex string) string
  • func (c *BaseConfig) BlobsDir() string
  • func (c *BaseConfig) DBDir() string
  • func (c *BaseConfig) EnsureBaseDirs() error
  • func (c *BaseConfig) IndexFile() string
  • func (c *BaseConfig) IndexLock() string
  • func (c *BaseConfig) TempDir() string
• type Digest
  • func NewDigest(hex string) Digest
  • func (d Digest) Hex() string
  • func (d Digest) String() string
• type Entry
• type GCModuleConfig
• type ImageGCSnapshot
• type Images
• type Index
  • func (idx *Index[E]) Init()
• type Ops
  • func (ops Ops[I, E]) Delete(ctx context.Context, ids []string) (deleted []string, err error)
  • func (ops Ops[I, E]) Inspect(ctx context.Context, id string) (result *types.Image, err error)
  • func (ops Ops[I, E]) List(ctx context.Context) (result []*types.Image, err error)

Variables

var ErrAmbiguous = errors.New("image ref resolves to multiple backends")

ErrAmbiguous reports an image ref that matches more than one backend.

Functions

func BuildGCModule

func BuildGCModule[I any](cfg GCModuleConfig[I]) gc.Module[ImageGCSnapshot]

BuildGCModule constructs a gc.Module from the config. This eliminates the near-identical GCModule() methods in oci/ and cloudimg/.

func GCCollectBlobs

func GCCollectBlobs(ctx context.Context, tempDir string, dirOnly bool, ids []string, removers ...func(string) error) error

GCCollectBlobs removes temp files and blob artifacts by hex ID. removers are called for each hex; fs.ErrNotExist errors are ignored.

func GCStaleTemp

func GCStaleTemp(ctx context.Context, dir string, dirOnly bool) []error

GCStaleTemp removes temp entries older than StaleTempAge. Set dirOnly=true to only remove directories (OCI uses dirs, cloudimg uses files).

Regular files whose name ends in ".lock" are preserved regardless of age — they are flock rendezvous files, and removing one while another process is holding the lock would break cross-process mutual exclusion (flock synchronizes on inode, not pathname: a subsequent flock.New on the same path would create a new inode and race with the lock holder). They are 0-byte files so the leak is negligible.

func LookupRefs

func LookupRefs[E Entry](images map[string]*E, id string, normalizers ...func(string) (string, bool)) []string

LookupRefs returns all ref keys matching id by exact key, optional normalization, or digest prefix. normalizers are tried in order for backend-specific key transforms (e.g., OCI image reference normalization).

func NewStore

func NewStore[T any](filePath, lockPath string) (storage.Store[T], lock.Locker)

NewStore creates a JSON-backed Store and returns it alongside the locker. Both use the same underlying flock so the locker can be passed independently (e.g. to gc.Module) while sharing the same cross-process lock file.

func ReferencedDigests

func ReferencedDigests[E Entry](images map[string]*E) map[string]struct{}

ReferencedDigests collects all blob digest hex strings referenced by any (*entry).

Types

type BaseConfig

type BaseConfig struct {
	Root    *config.Config
	Subdir  string // backend subdirectory under RootDir, e.g. "oci" or "cloudimg"
	BlobExt string // blob file extension, e.g. ".erofs" or ".qcow2"
}

BaseConfig holds the common directory layout shared by all image backends. Each backend embeds BaseConfig and adds type-specific paths.

func (*BaseConfig) BackendDir

func (c *BaseConfig) BackendDir() string

BackendDir returns the root directory for this image backend.

func (*BaseConfig) BlobPath

func (c *BaseConfig) BlobPath(hex string) string

BlobPath returns the full path for a blob with the given digest hex.

func (*BaseConfig) BlobsDir

func (c *BaseConfig) BlobsDir() string

BlobsDir returns the blob storage directory path.

func (*BaseConfig) DBDir

func (c *BaseConfig) DBDir() string

DBDir returns the database directory path.

func (*BaseConfig) EnsureBaseDirs

func (c *BaseConfig) EnsureBaseDirs() error

EnsureBaseDirs creates the common directories (db, temp, blobs).

func (*BaseConfig) IndexFile

func (c *BaseConfig) IndexFile() string

IndexFile returns the path to the image index JSON file.

func (*BaseConfig) IndexLock

func (c *BaseConfig) IndexLock() string

IndexLock returns the path to the image index lock file.

func (*BaseConfig) TempDir

func (c *BaseConfig) TempDir() string

TempDir returns the temporary working directory path.

type Digest

type Digest string

Digest represents a content-addressable digest in "algorithm:hex" format (e.g., "sha256:abcdef..."). Backed by opencontainers/go-digest.

func NewDigest

func NewDigest(hex string) Digest

NewDigest creates a Digest from a raw hex string, prefixing "sha256:".

func (Digest) Hex

func (d Digest) Hex() string

Hex returns the hex portion of the digest, stripping the algorithm prefix.

func (Digest) String

func (d Digest) String() string

String returns the full digest string including the algorithm prefix.

type Entry

type Entry interface {
	EntryID() string
	EntryRef() string
	EntryCreatedAt() time.Time
	DigestHexes() []string
}

Entry defines the common behavior of an image index (*entry). Both OCI and cloudimg imageEntry types implement this with value receivers.

type GCModuleConfig

type GCModuleConfig[I any] struct {
	Name   string
	Locker lock.Locker
	Store  storage.Store[I]
	// ReadRefs extracts referenced digest hexes from the index.
	ReadRefs func(*I) map[string]struct{}
	// ScanDisk returns digest hexes found on disk (blobs).
	ScanDisk func() ([]string, error)
	// ExtraDisk returns additional hex IDs on disk (e.g., OCI boot dirs). Optional.
	ExtraDisk func() ([]string, error)
	// Removers are called per hex ID during collect.
	Removers []func(string) error
	// TempDir for stale temp cleanup.
	TempDir string
	// DirOnly: true for OCI (temp dirs), false for cloudimg (temp files).
	DirOnly bool
}

GCModuleConfig configures a generic image GC module.

type ImageGCSnapshot

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

ImageGCSnapshot is the unified GC snapshot for image backends.

type Images

type Images interface {
	Type() string

	Pull(ctx context.Context, ref string, force bool, tracker progress.Tracker) error
	Import(ctx context.Context, name string, tracker progress.Tracker, file ...string) error
	Inspect(context.Context, string) (*types.Image, error)
	List(context.Context) ([]*types.Image, error)
	Delete(context.Context, []string) ([]string, error)
	RegisterGC(*gc.Orchestrator)

	Config(context.Context, []*types.VMConfig) ([][]*types.StorageConfig, []*types.BootConfig, error)
}

Images defines the interface for an image backend (OCI, cloudimg).

type Index

type Index[E any] struct {
	Images map[string]*E `json:"images"`
}

Index is the shared generic base for image indices. Both backends embed Index[imageEntry] to inherit Init() and the Images map.

func (*Index[E]) Init

func (idx *Index[E]) Init()

Init implements storage.Initer. Called automatically by storejson.Store after loading.

type Ops

type Ops[I any, E Entry] struct {
	Store      storage.Store[I]
	Type       string
	LookupRefs func(*I, string) []string
	Entries    func(*I) map[string]*E
	Sizer      func(*E) int64
}

Ops bundles the store and callbacks shared by Inspect/List/Delete. Each backend creates one Ops instance during initialization.

func (Ops[I, E]) Delete

func (ops Ops[I, E]) Delete(ctx context.Context, ids []string) (deleted []string, err error)

Delete deletes entries from an index by ids and returns removed refs.

func (Ops[I, E]) Inspect

func (ops Ops[I, E]) Inspect(ctx context.Context, id string) (result *types.Image, err error)

Inspect reads one entry by id and converts it to types.Image. Returns (nil, nil) when no entry matches.

func (Ops[I, E]) List

func (ops Ops[I, E]) List(ctx context.Context) (result []*types.Image, err error)

List reads all entries and converts them to []types.Image.