Images - microsandbox

Inspect and prune the local OCI image cache: the images that sandbox creation has already pulled. Everything is reached through the package-level Image value, or through an ImageHandle once you hold one.

import m "github.com/superradcompany/microsandbox/sdk/go"

Typical flow

import m "github.com/superradcompany/microsandbox/sdk/go"

images, err := m.Image.List(ctx)        // 1. enumerate the cache
if err != nil {
    return err
}
for _, img := range images {
    fmt.Println(img.Reference(), img.LayerCount())
}

report, err := m.Image.Prune(ctx)       // 2. reclaim unused data
if err != nil {
    return err
}
fmt.Println(report.LayersRemoved, "layers removed")

Functions

Image.Get()

func (imageFactory) Get(ctx context.Context, reference string) (*ImageHandle, error)

Example

img, err := m.Image.Get(ctx, "python:3.12")
if err != nil {
    return err
}
fmt.Println(img.ManifestDigest())

Fetch one cached image by reference. Returns ErrImageNotFound when no image with that reference is present in the local cache.

Parameters

ctxcontext.Context

Cancels the lookup.

referencestring

Image reference, e.g. “python:3.12”.

Returns

*ImageHandle

Metadata handle for the cached image.

error

ErrImageNotFound when the reference is not cached.

Image.List()

func (imageFactory) List(ctx context.Context) ([]*ImageHandle, error)

Example

images, err := m.Image.List(ctx)
if err != nil {
    return err
}
for _, img := range images {
    fmt.Println(img.Reference(), img.LayerCount())
}

Return every cached image, ordered by creation time (newest first).

Parameters

ctxcontext.Context

Cancels the listing.

Returns

[]*ImageHandle

All cached image handles, newest first.

error

Non-nil on failure.

Image.Inspect()

func (imageFactory) Inspect(ctx context.Context, reference string) (*ImageDetail, error)

Example

detail, err := m.Image.Inspect(ctx, "python:3.12")
if err != nil {
    return err
}
fmt.Println(detail.Config.Entrypoint, len(detail.Layers), "layers")

Return the full detail for a cached image: the ImageHandle plus the parsed OCI config and the layer list.

Parameters

ctxcontext.Context

Cancels the inspection.

referencestring

Image reference, e.g. “python:3.12”.

Returns

*ImageDetail

Handle, OCI config, and layers.

error

ErrImageNotFound when the reference is not cached.

Image.Remove()

func (imageFactory) Remove(ctx context.Context, reference string, force bool) error

Example

if err := m.Image.Remove(ctx, "old:tag", false); err != nil {
    return err
}

Delete a cached image. When force is false, sandboxes that still reference the image cause the call to fail with ErrImageInUse.

Parameters

ctxcontext.Context

Cancels the removal.

referencestring

Image reference to delete.

forcebool

When true, remove even if sandboxes still reference it.

Returns

error

ErrImageInUse when in use and force is false.

Image.Prune()

func (imageFactory) Prune(ctx context.Context) (*ImagePruneReport, error)

Example

report, err := m.Image.Prune(ctx)
if err != nil {
    return err
}
fmt.Println(report.LayersRemoved, "layers removed")

Remove cached image data that is not used by any sandbox. Returns a report tallying the image refs, manifests, layers, fsmeta files, and VMDK files removed, plus bytes reclaimed.

Parameters

ctxcontext.Context

Cancels the prune.

Returns

*ImagePruneReport

Summary of what was reclaimed.

error

Non-nil on failure.

Methods

Instance methods on *ImageHandle, the metadata reference returned by Image.Get and Image.List. The accessors are pure reads of cached metadata; only Remove and Inspect take a context and reach the runtime.

h.Reference()

func (h *ImageHandle) Reference() string

The image reference, e.g. "docker.io/library/python:3.12".

Returns

string

Image reference.

h.ManifestDigest()

func (h *ImageHandle) ManifestDigest() string

The content-addressable manifest digest, or empty when unknown.

Returns

string

Manifest digest, or empty.

h.Architecture()

func (h *ImageHandle) Architecture() string

The architecture resolved during the pull, or empty.

Returns

string

Architecture, or empty.

h.OS()

func (h *ImageHandle) OS() string

The operating system resolved during the pull, or empty.

Returns

string

Operating system, or empty.

h.LayerCount()

func (h *ImageHandle) LayerCount() uint

The number of layers in the image.

Returns

uint

Layer count.

h.SizeBytes()

func (h *ImageHandle) SizeBytes() *int64

The total image size in bytes, or nil when unknown.

Returns

*int64

Total size in bytes, or nil.

h.CreatedAt()

func (h *ImageHandle) CreatedAt() time.Time

When this image was first pulled. Returns the zero time.Time when unknown.

Returns

time.Time

First-pulled time, or the zero value.

h.LastUsedAt()

func (h *ImageHandle) LastUsedAt() time.Time

When this image was last referenced. Returns the zero time.Time when unknown.

Returns

time.Time

Last-referenced time, or the zero value.

h.Remove()

func (h *ImageHandle) Remove(ctx context.Context, force bool) error

Example

img, err := m.Image.Get(ctx, "old:tag")
if err != nil {
    return err
}
if err := img.Remove(ctx, false); err != nil {
    return err
}

Delete this image. Equivalent to Image.Remove(ctx, h.Reference(), force). When force is false, sandboxes that still reference the image cause the call to fail with ErrImageInUse.

Parameters

ctxcontext.Context

Cancels the removal.

forcebool

When true, remove even if sandboxes still reference it.

Returns

error

ErrImageInUse when in use and force is false.

h.Inspect()

func (h *ImageHandle) Inspect(ctx context.Context) (*ImageDetail, error)

Example

img, err := m.Image.Get(ctx, "python:3.12")
if err != nil {
    return err
}
detail, err := img.Inspect(ctx)
if err != nil {
    return err
}
fmt.Println(detail.Config.WorkingDir)

Return the full detail for this image. Equivalent to Image.Inspect(ctx, h.Reference()).

Parameters

ctxcontext.Context

Cancels the inspection.

Returns

*ImageDetail

Handle, OCI config, and layers.

error

Non-nil on failure.

Types

ImageHandle

Returned by Image.Get() · Image.List()

A lightweight metadata reference to a cached OCI image. Fields are unexported; read them through the accessor methods below. Embedded in ImageDetail.

Method	Returns	Description
Reference()	`string`	Image reference
ManifestDigest()	`string`	Content-addressable manifest digest, or empty
Architecture()	`string`	Resolved architecture, or empty
OS()	`string`	Resolved operating system, or empty
LayerCount()	`uint`	Number of layers
SizeBytes()	`*int64`	Total size in bytes, or `nil` when unknown
CreatedAt()	`time.Time`	First-pulled time, or the zero value
LastUsedAt()	`time.Time`	Last-referenced time, or the zero value
Remove(ctx, force)	`error`	Delete this image
Inspect(ctx)	`(*ImageDetail, error)`	Fetch full detail for this image

ImageDetail

Returned by Image.Inspect() · Inspect()

Bundles an ImageHandle (embedded, so all its accessors are promoted) with the parsed OCI config and layer list.

type ImageDetail struct {
    *ImageHandle
    Config *ImageConfig
    Layers []ImageLayer
}

Field	Type	Description
`*ImageHandle`	`*ImageHandle`	Embedded metadata handle (accessors promoted)
Config	`*ImageConfig`	Parsed OCI config block
Layers	`[]ImageLayer`	Layers in manifest order

ImageConfig

Used by ImageDetail.Config

The parsed OCI config block.

Field	Type	Description
Digest	`string`	Config blob digest
Env	`[]string`	Environment variables (`KEY=VALUE`)
Cmd	`[]string`	Default command
Entrypoint	`[]string`	Entrypoint
WorkingDir	`string`	Working directory
User	`string`	Default user
Labels	`map[string]string`	OCI labels
StopSignal	`string`	Stop signal

ImageLayer

Used by ImageDetail.Layers

One layer of an image manifest.

Field	Type	Description
DiffID	`string`	Uncompressed layer diff ID
BlobDigest	`string`	Compressed blob digest
MediaType	`string`	Layer media type
CompressedSizeBytes	`*int64`	Compressed size in bytes, or `nil`
ErofsSizeBytes	`*int64`	EROFS size in bytes, or `nil`
Position	`int32`	Index in the layer stack

ImagePruneReport

Returned by Image.Prune()

Summarizes the artifacts removed by Image.Prune.

Field	Type	Description
ImageRefsRemoved	`uint32`	Image references removed
ManifestsRemoved	`uint32`	Manifests removed
LayersRemoved	`uint32`	Layers removed
FsmetaRemoved	`uint32`	Fsmeta files removed
VMDKRemoved	`uint32`	VMDK files removed
BytesReclaimed	`*uint64`	Bytes reclaimed, or `nil` when unknown

​Functions

​Image.Get()

​Image.List()

​Image.Inspect()

​Image.Remove()

​Image.Prune()

​Methods

​h.Reference()

​h.ManifestDigest()

​h.Architecture()

​h.OS()

​h.LayerCount()

​h.SizeBytes()

​h.CreatedAt()

​h.LastUsedAt()

​h.Remove()

​h.Inspect()

​Types

​ImageHandle

​ImageDetail

​ImageConfig

​ImageLayer

​ImagePruneReport

Functions

Image.Get()

Image.List()

Image.Inspect()

Image.Remove()

Image.Prune()

Methods

h.Reference()

h.ManifestDigest()

h.Architecture()

h.OS()

h.LayerCount()

h.SizeBytes()

h.CreatedAt()

h.LastUsedAt()

h.Remove()

h.Inspect()

Types

ImageHandle

ImageDetail

ImageConfig

ImageLayer

ImagePruneReport