image

package
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 12, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxLayerBlobSize = 16 << 30 // 16 GiB

MaxLayerBlobSize bounds a single layer-tar blob loaded from a spooled image archive. Distinct from MaxSaveSize because layer blobs aggregate many files (apt caches, ML model directories, full base-image userlands) and legitimately exceed the per-file cap. 16 GiB is permissive enough for production ML images while still rejecting a malformed manifest that claims a single blob is petabytes.

View Source 
const MaxSaveSize = 2 << 30 // 2 GiB

MaxSaveSize bounds save-to-disk extraction. The viewer caps reads at MaxViewSize, but the save path historically called io.ReadAll with no limit — a 10 GB file inside a layer (or a maliciously crafted tar entry with an inflated header.Size) would OOM the process. 2 GiB is generous enough for legitimate single-file extracts and well below typical RAM.

View Source 
const MaxViewSize = 1 << 20 // 1 MB
View Source 
const SchemaVersion = 2

SchemaVersion is the on-disk schema version for cached analysis files. Bump when the cacheEnvelope, cachedLayer, or cachedNode shape changes (or when the parse output produced by docker.go/parseLayers changes in a way that affects what we persist). Do NOT bump for stack.go or size.go changes — those run on every load and are not persisted.

Variables

This section is empty.

Functions

func CacheDir added in v1.2.0 

func CacheDir() (string, error)

CacheDir returns the directory where layerx persists analysis caches. Resolution order:

  1. LAYERX_CACHE_DIR (if set and usable as a directory)
  2. os.UserCacheDir() joined with "layerx"

CacheDir does not create the directory; saveCache creates digest subdirectories on demand with mode 0700.

func FormatBytes 

func FormatBytes(b int64) string

func FormatMode 

func FormatMode(m fs.FileMode) string

func FormatSignedBytes 

func FormatSignedBytes(b int64) string

FormatSignedBytes formats b like FormatBytes but with an explicit sign for non-zero values: "+12 MB", "-3.0 MB", "0 B". Used for net deltas.

func IsBinary 

func IsBinary(data []byte) bool

IsBinary reports whether data appears to be binary content. Trusts net/http content detection for text/* (covering UTF-8/16/32 with BOMs) and only falls back to null-byte scanning when detection is inconclusive.

func IsWhiteoutName added in v1.3.0 

func IsWhiteoutName(name string) bool

IsWhiteoutName reports whether name is an overlay whiteout marker: either an opaque-directory marker (`.wh..wh..opq`) or a per-file tombstone (`.wh.<name>`). Exported so consumers outside image/ — such as ci/path-rules — can identify these markers in raw per-layer trees, where tar entries land as regular FileNodes (DiffType=Unchanged) until stack.go interprets them.

func TreeLiveFileBytes 

func TreeLiveFileBytes(tree *FileTree) int64

TreeLiveFileBytes returns the sum of file sizes in tree, excluding directories and any nodes marked Removed (their subtrees are not descended). Returns 0 for nil tree or nil root.

Types

type Analysis 

type Analysis struct {
	ImageRef     string
	Layers       []Layer
	StackedTrees []*FileTree
	TotalSize    int64
}

Analysis holds the complete result of inspecting an image.

func Analyze 

func Analyze(ctx context.Context, resolver Resolver, imageRef string) (*Analysis, error)

Analyze resolves an image and computes stacked file trees. Backwards-compatible shim around AnalyzeWithOptions; caching is enabled, no progress channel.

func AnalyzeWithOptions added in v1.2.0 

func AnalyzeWithOptions(ctx context.Context, resolver Resolver, imageRef string, opts AnalyzeOptions) (*Analysis, error)

AnalyzeWithOptions is the cache-aware entry point.

Flow:

  1. Try to obtain image content digest via Resolver.ImageID. On error (e.g. image not local yet, daemon hiccup) we skip the cache lookup and proceed to a cold resolve; ResolveWithProgress will pull as needed.
  2. If !opts.NoCache and the digest is known, try loadCache. On hit we skip ResolveWithProgress entirely; emit PhaseCacheLoad.
  3. Otherwise call ResolveWithProgress (existing pull/export/parse path).
  4. After a successful resolve, re-read ImageID and require the result to match the pre-resolve digest before persisting the cache. A mismatch means the tag flipped during the run (concurrent docker pull) — caching either set of layers under either digest would lie.
  5. Stack + assignNetDeltas + TotalSize, build Analysis, return.

Hit and miss paths converge at step 5: the same Analysis assembly runs either way. ImageRef is taken from imageRef (the current arg), never from the envelope.

func AnalyzeWithProgress 

func AnalyzeWithProgress(ctx context.Context, resolver Resolver, imageRef string, progress chan<- ProgressEvent) (*Analysis, error)

AnalyzeWithProgress is preserved for callers that already pass a progress channel. Equivalent to AnalyzeWithOptions{Progress: progress}.

type AnalyzeOptions added in v1.2.0 

type AnalyzeOptions struct {
	// NoCache forces a cold resolve. The cache is still written on success
	// so the next default-mode run is a hit.
	NoCache bool

	// Progress, if non-nil, receives ProgressEvents during the run. Same
	// semantics as AnalyzeWithProgress; sending PhaseCacheLoad on hit.
	Progress chan<- ProgressEvent

	// CacheRoot overrides CacheDir() for this call. Empty = use CacheDir().
	// Tests can also set LAYERX_CACHE_DIR; this field exists for callers
	// that want explicit control without environment.
	CacheRoot string
}

AnalyzeOptions controls the analyze pipeline. Zero value is valid: caching enabled, no progress channel, default cache directory.

type ArchiveExtractor added in v1.2.3 

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

ArchiveExtractor extracts file content from layers in a local image archive. Reuses findFileInLayer (daemon-independent) for the per-layer search.

func (*ArchiveExtractor) Extract added in v1.2.3 

func (e *ArchiveExtractor) Extract(ctx context.Context, imageRef string, filePath string) (*FileContent, error)

Extract is provided for interface completeness. The TUI uses ExtractFromLayer; full-image extract via container-create has no archive equivalent, so we route to the layer-walk over all layers.

func (*ArchiveExtractor) ExtractFromLayer added in v1.2.3 

func (e *ArchiveExtractor) ExtractFromLayer(ctx context.Context, imageRef string, filePath string, layerCursor int) (*FileContent, error)

ExtractFromLayer mirrors DockerExtractor.ExtractFromLayer: walk back from layerCursor toward layer 0, return the file from the most recent layer whose tar contains it as a regular entry, or surface a typed whiteout / non-regular error if encountered first.

func (*ArchiveExtractor) ExtractRaw added in v1.2.3 

func (e *ArchiveExtractor) ExtractRaw(ctx context.Context, imageRef string, filePath string) ([]byte, error)

ExtractRaw is the raw-bytes variant of Extract, same routing.

func (*ArchiveExtractor) ExtractRawFromLayer added in v1.2.3 

func (e *ArchiveExtractor) ExtractRawFromLayer(ctx context.Context, imageRef string, filePath string, layerCursor int) ([]byte, error)

ExtractRawFromLayer is the raw-bytes variant of ExtractFromLayer.

type ArchiveResolver added in v1.2.3 

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

ArchiveResolver resolves image layers from a local image archive on disk (docker save / OCI layout tarball) without contacting any container runtime.

The archive is opened lazily on each method call rather than held open by the resolver. This keeps the resolver cheap to construct and lets the caller move or delete the file between calls (the active call still finishes against the file handle it opened).

func NewArchiveResolver added in v1.2.3 

func NewArchiveResolver(path string) *ArchiveResolver

NewArchiveResolver creates a resolver that reads from the archive at path. The path is not validated here; errors surface when methods are called (so the constructor cannot fail and Resolve / Inspect / ImageID share a single file-open code path with consistent error wrapping).

func (*ArchiveResolver) ImageID added in v1.2.3 

func (r *ArchiveResolver) ImageID(ctx context.Context, imageRef string) (string, error)

ImageID returns the image's content digest, derived from the config blob's bytes. This is the same identity used by Docker and OCI registries: the sha256 of the JSON config file referenced by manifest.json. Two archives with identical image content (same config + same layers) share an ImageID regardless of where they live on disk or how the tar was rebuilt; two archives that differ in any layer or config field do not.

For OCI layouts the config path embeds the digest (blobs/sha256/<hex>) and we use it directly. For legacy docker-save layouts the filename stem (<hex>.json) is conventionally the digest but is not authoritative — a rewritten tar can keep the filename while changing the bytes — so we hash the config blob itself.

func (*ArchiveResolver) Inspect added in v1.2.3 

func (r *ArchiveResolver) Inspect(ctx context.Context, imageRef string) (*ImageMeta, error)

Inspect returns lightweight metadata (total declared layer size) by scanning the outer tar headers once. Does not read layer bodies.

"Total layer size" is summed strictly over the entries listed in the manifest's Layers — manifest.json, the config blob, and any unrelated root-level JSON are excluded. This matches what users mean by "image size" and what the spinner / status bar displays.

func (*ArchiveResolver) NewExtractor added in v1.2.3 

func (r *ArchiveResolver) NewExtractor() Extractor

NewExtractor returns an ArchiveExtractor bound to this resolver's archive path. Implements ExtractorSource so the TUI's file viewer and save-to-disk features work in archive mode.

func (*ArchiveResolver) Resolve added in v1.2.3 

func (r *ArchiveResolver) Resolve(ctx context.Context, imageRef string) ([]Layer, error)

Resolve reads the archive and returns the parsed layer list.

func (*ArchiveResolver) ResolveWithProgress added in v1.2.3 

func (r *ArchiveResolver) ResolveWithProgress(ctx context.Context, imageRef string, progress chan<- ProgressEvent) ([]Layer, error)

ResolveWithProgress reads the archive, emitting Parsing progress. There is no Pulling phase (no daemon, no network) and no Exporting phase (no ImageSave call) — archive mode goes straight to parse.

type CacheEntry added in v1.4.0 

type CacheEntry struct {
	Digest   string
	Size     int64     // bytes — size of the layers.gob file on disk
	CachedAt time.Time // mtime of layers.gob; honestly named (not "LastUsed")
	// ImageRef is the image reference the cache was originally written with
	// (e.g. "nginx:latest", "/build/app.tar"). Empty when the sidecar
	// meta.json is missing — entries written by older versions, or by
	// PruneCache which doesn't bother reading the sidecar. Display-only;
	// loadCache and PruneCache do not consult this field.
	ImageRef string
}

CacheEntry is one record from the cache root, or one removal result. Digest is the raw directory name (no "sha256:" prefix), matching how it is stored on disk and accepted by the existing cache helpers.

func ListCache added in v1.4.0 

func ListCache(root string) ([]CacheEntry, []string, error)

ListCache returns every valid digest dir under root with its size and mtime. A missing root is not an error; it returns ([], nil, nil) — the cache simply hasn't been populated yet. Foreign files at root, dirs whose names fail digest validation, and dirs whose layers.gob is missing are silently skipped (same rule as the auto-prune).

Warnings are returned as plain strings so the caller (cmd/cache.go) can render them. ListCache itself never writes to stderr.

Entries are returned sorted oldest-first by mtime. Predictable order keeps the renderer test-stable and matches PruneCache's eviction order.

type CompareResult added in v1.3.0 

type CompareResult struct {
	Before ImageSummary
	After  ImageSummary

	BeforeEfficiency EfficiencySummary
	AfterEfficiency  EfficiencySummary

	LayerDiffs  []LayerDiff
	FileDiffs   []FileDiff
	WasteDiffs  []WasteDiff
	FileSummary FileDiffSummary

	Warnings []string
}

CompareResult is the aggregate output of CompareAnalysis.

func CompareAnalysis added in v1.3.0 

func CompareAnalysis(before, after *Analysis) *CompareResult

CompareAnalysis computes a diff between two image analyses. Either input may be nil — a nil analysis is treated as an empty image (no layers, no files), so "compare against nothing" is symmetric with regular diffs. Returns nil only when both inputs are nil. CompareAnalysis never mutates its inputs.

When one side is empty (nil or zero layers), Efficiency() returns the degenerate Score=1.0 baseline for that side. To prevent that phantom baseline from making the populated side look "worse" (a spurious regression in the verdict), the EfficiencySummary deltas are zeroed when either side has no layers — the diff still surfaces every Added/Removed file, but score/waste deltas only carry meaning when both sides are real.

func (*CompareResult) IsRegression added in v1.3.0 

func (r *CompareResult) IsRegression() bool

IsRegression reports whether `after` is materially worse than `before`: wasted bytes increased OR efficiency score dropped beyond a small epsilon. Returns false on a nil receiver. Reads the precomputed delta fields so the verdict and the rendered numbers share one source of truth.

func (*CompareResult) RegressionReasons added in v1.3.0 

func (r *CompareResult) RegressionReasons() []string

RegressionReasons returns the canonical list of regression reasons, in the stable order ["efficiency", "waste"]. Empty slice when no regression. Defined alongside IsRegression so the verdict line and the gate share a single decision; callers must not recompute reasons from raw fields.

type DiffType 

type DiffType int

DiffType indicates how a file changed relative to previous layers. 

const (
	Unchanged DiffType = iota
	Added
	Modified
	Removed
)

type DockerExtractor 

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

DockerExtractor extracts files from images via the Docker daemon.

func NewDockerExtractor 

func NewDockerExtractor(cli client.APIClient) *DockerExtractor

NewDockerExtractor creates an extractor using the provided Docker client.

func (*DockerExtractor) Extract 

func (e *DockerExtractor) Extract(ctx context.Context, imageRef string, filePath string) (*FileContent, error)

Extract creates a temporary container, copies the file out, and removes the container.

func (*DockerExtractor) ExtractFromLayer added in v1.2.1 

func (e *DockerExtractor) ExtractFromLayer(ctx context.Context, imageRef string, filePath string, layerCursor int) (*FileContent, error)

ExtractFromLayer extracts a file as it exists at the given layer cursor. It walks back from layerCursor toward layer 0 looking for the most recent layer whose tar contains the path as a regular file. A whiteout encountered during the walk-back stops the search and returns an error.

func (*DockerExtractor) ExtractRaw 

func (e *DockerExtractor) ExtractRaw(ctx context.Context, imageRef string, filePath string) ([]byte, error)

ExtractRaw extracts a file's raw bytes without truncation or binary detection.

func (*DockerExtractor) ExtractRawFromLayer added in v1.2.1 

func (e *DockerExtractor) ExtractRawFromLayer(ctx context.Context, imageRef string, filePath string, layerCursor int) ([]byte, error)

ExtractRawFromLayer is the raw-bytes variant of ExtractFromLayer. No truncation, no binary detection. Used by save-to-disk.

type DockerResolver 

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

DockerResolver resolves image layers via the Docker daemon.

func (*DockerResolver) ImageID added in v1.2.0 

func (r *DockerResolver) ImageID(ctx context.Context, imageRef string) (string, error)

ImageID returns the image content digest from the Docker daemon. It does not pull; the caller is expected to ensure the image is local first (AnalyzeWithProgress does this).

func (*DockerResolver) Inspect 

func (r *DockerResolver) Inspect(ctx context.Context, imageRef string) (*ImageMeta, error)

Inspect returns lightweight image metadata without exporting the full tar. It does not pull the image — if the image is not local, it returns an error.

func (*DockerResolver) NewExtractor 

func (r *DockerResolver) NewExtractor() Extractor

NewExtractor creates an Extractor using this resolver's Docker client.

func (*DockerResolver) Resolve 

func (r *DockerResolver) Resolve(ctx context.Context, imageRef string) ([]Layer, error)

Resolve fetches the image, exports it as a tar, and parses the layer list.

func (*DockerResolver) ResolveWithProgress 

func (r *DockerResolver) ResolveWithProgress(ctx context.Context, imageRef string, progress chan<- ProgressEvent) ([]Layer, error)

ResolveWithProgress fetches the image with progress reporting via the channel.

type EfficiencyResult 

type EfficiencyResult struct {
	Score       float64
	WastedBytes int64
	WastedFiles []WastedFile
}

EfficiencyResult holds the efficiency analysis output.

func Efficiency 

func Efficiency(layers []Layer) *EfficiencyResult

Efficiency computes how much space is wasted by files appearing in multiple layers. It stacks layers internally; prefer EfficiencyFromAnalysis when the caller already has stacked trees.

A file at the same path counted across runs separated by deletion (whiteout or opaque whiteout) is NOT considered wasted: the deleted copy was properly cleaned up before the new copy appeared. Within a single run (no deletion in between), all but the last occurrence are wasted.

func EfficiencyFromAnalysis added in v1.3.0 

func EfficiencyFromAnalysis(a *Analysis) *EfficiencyResult

EfficiencyFromAnalysis is the preferred entry point when the caller already has stacked trees (which Analysis carries). Avoids re-running Stack.

Falls back to recomputing Stack(layers) if the carried StackedTrees are missing or out of sync with the layer count — defensive against an Analysis that was built or mutated outside AnalyzeWithOptions (e.g. by a test, or by a future caller that constructs an Analysis directly). The efficiency computation requires len(stacked) == len(layers) to align snapshot indices; without this guard a divergent input would produce a silently wrong score.

type EfficiencySummary added in v1.3.0 

type EfficiencySummary struct {
	Score              float64
	WastedBytes        int64
	ScoreDelta         float64
	ScoreDeltaPercent  float64
	WastedBytesDelta   int64
	WastedBytesPercent float64
}

EfficiencySummary mirrors EfficiencyResult plus deltas relative to a peer. Percent fields are 0 when their denominator is 0 (no sentinel value).

type ErrArchiveInfra added in v1.2.3 

type ErrArchiveInfra struct {
	Op    string
	Cause error
}

ErrArchiveInfra signals an infrastructure-class failure encountered while processing an archive: temp file creation, disk-full while spooling, etc. Distinct from ErrInvalidArchive — the archive may be perfectly valid; the host environment failed. Callers should surface the cause directly rather than telling the user their tarball is malformed.

func (*ErrArchiveInfra) Error added in v1.2.3 

func (e *ErrArchiveInfra) Error() string

func (*ErrArchiveInfra) Unwrap added in v1.2.3 

func (e *ErrArchiveInfra) Unwrap() error

type ErrArchiveNotFound added in v1.2.3 

type ErrArchiveNotFound struct {
	Path  string
	Cause error
}

ErrArchiveNotFound is returned when the archive file path does not exist or is not a regular file. Distinct from ErrInvalidArchive so callers can give a different message for "wrong path" vs "wrong contents".

func (*ErrArchiveNotFound) Error added in v1.2.3 

func (e *ErrArchiveNotFound) Error() string

func (*ErrArchiveNotFound) Unwrap added in v1.2.3 

func (e *ErrArchiveNotFound) Unwrap() error

type ErrArchivePermission added in v1.2.3 

type ErrArchivePermission struct {
	Path  string
	Cause error
}

ErrArchivePermission is returned when the archive file exists but the current user cannot open it (permission denied). Distinct from ErrArchiveNotFound so the user sees "fix your permissions" rather than "fix your path".

func (*ErrArchivePermission) Error added in v1.2.3 

func (e *ErrArchivePermission) Error() string

func (*ErrArchivePermission) Unwrap added in v1.2.3 

func (e *ErrArchivePermission) Unwrap() error

type ErrDaemonNotRunning 

type ErrDaemonNotRunning struct {
	Cause error
}

func (*ErrDaemonNotRunning) Error 

func (e *ErrDaemonNotRunning) Error() string

func (*ErrDaemonNotRunning) Unwrap 

func (e *ErrDaemonNotRunning) Unwrap() error

type ErrImageNotFound 

type ErrImageNotFound struct {
	Ref   string
	Cause error
}

func (*ErrImageNotFound) Error 

func (e *ErrImageNotFound) Error() string

func (*ErrImageNotFound) Unwrap 

func (e *ErrImageNotFound) Unwrap() error

type ErrInvalidArchive added in v1.2.3 

type ErrInvalidArchive struct {
	Path  string
	Cause error
}

ErrInvalidArchive is returned when the file exists and is readable but is not a valid docker-save / OCI image archive (missing manifest.json, malformed manifest, malformed config, etc).

func (*ErrInvalidArchive) Error added in v1.2.3 

func (e *ErrInvalidArchive) Error() string

func (*ErrInvalidArchive) Unwrap added in v1.2.3 

func (e *ErrInvalidArchive) Unwrap() error

type ErrNoEngineFound added in v1.4.0 

type ErrNoEngineFound struct {
	Tried []string
}

func (*ErrNoEngineFound) Error added in v1.4.0 

func (e *ErrNoEngineFound) Error() string

type ErrPodmanSocketNotSet added in v1.4.0 

type ErrPodmanSocketNotSet struct {
	Platform string
}

func (*ErrPodmanSocketNotSet) Error added in v1.4.0 

func (e *ErrPodmanSocketNotSet) Error() string

type ErrPullFailed 

type ErrPullFailed struct {
	Ref   string
	Cause error
}

func (*ErrPullFailed) Error 

func (e *ErrPullFailed) Error() string

func (*ErrPullFailed) Unwrap 

func (e *ErrPullFailed) Unwrap() error

type Extractor 

type Extractor interface {
	Extract(ctx context.Context, imageRef string, filePath string) (*FileContent, error)
	ExtractRaw(ctx context.Context, imageRef string, filePath string) ([]byte, error)
	// ExtractFromLayer returns the file as it exists at the given layer.
	// It walks back from layerCursor toward layer 0 to find the most recent
	// layer that physically contains the path. A whiteout encountered during
	// the walk-back stops the search and returns an error.
	ExtractFromLayer(ctx context.Context, imageRef string, filePath string, layerCursor int) (*FileContent, error)
	// ExtractRawFromLayer is the raw-bytes variant of ExtractFromLayer; same
	// walk-back semantics, no truncation, no binary detection.
	ExtractRawFromLayer(ctx context.Context, imageRef string, filePath string, layerCursor int) ([]byte, error)
}

Extractor retrieves file contents from a container image.

type ExtractorSource 

type ExtractorSource interface {
	NewExtractor() Extractor
}

ExtractorSource is implemented by resolvers that can produce an Extractor.

type FileContent 

type FileContent struct {
	Path      string
	Data      []byte
	Size      int64 // actual file size (may exceed len(Data) if truncated)
	Truncated bool
	Binary    bool
}

FileContent holds the result of extracting a file from an image.

type FileDiff added in v1.3.0 

type FileDiff struct {
	Path         string
	DiffType     DiffType
	BeforeSize   int64
	AfterSize    int64
	SizeDelta    int64
	ChangeReason string
}

FileDiff records a change to one file in the final stacked filesystem. ChangeReason is set only for Modified entries and lists the differing fields in the canonical order: size,mode,uid,gid,linkname,hardlink.

type FileDiffSummary added in v1.3.0 

type FileDiffSummary struct {
	AddedCount    int
	RemovedCount  int
	ModifiedCount int
	BytesAdded    int64
	BytesRemoved  int64
}

FileDiffSummary aggregates FileDiffs into counts and byte totals.

type FileNode 

type FileNode struct {
	Name              string
	Path              string
	Linkname          string
	Size              int64
	Mode              fs.FileMode
	UID               int
	GID               int
	DiffType          DiffType
	IntroducedInLayer int
	Children          []*FileNode
	IsDir             bool
	IsHardlink        bool
}

FileNode represents a single file or directory in a layer's filesystem.

func (*FileNode) AddChild 

func (n *FileNode) AddChild(child *FileNode)

func (*FileNode) FindChild 

func (n *FileNode) FindChild(name string) *FileNode

func (*FileNode) RemoveChild 

func (n *FileNode) RemoveChild(name string) bool

type FileTree 

type FileTree struct {
	Root *FileNode
}

FileTree represents the filesystem state of one or more stacked layers.

func NewFileTree 

func NewFileTree() *FileTree

func ParseLayerTar 

func ParseLayerTar(r io.Reader) (*FileTree, error)

ParseLayerTar reads a tar archive (a single layer) and builds a FileTree.

func Stack 

func Stack(layers []Layer) []*FileTree

Stack takes layers with populated Trees and returns one FileTree per layer, each representing the cumulative filesystem state at that layer with DiffType set on every node to indicate what the current layer changed.

func (*FileTree) Walk 

func (t *FileTree) Walk(fn func(*FileNode))

type ImageMeta 

type ImageMeta struct {
	Size int64
}

ImageMeta holds lightweight metadata obtainable without exporting the full image.

type ImageSummary added in v1.3.0 

type ImageSummary struct {
	ImageRef   string
	LayerCount int
	TotalSize  int64
}

ImageSummary captures top-level identity and size of an analyzed image.

type Layer 

type Layer struct {
	Index   int
	ID      string // short digest (first 12 chars of sha256)
	Size    int64
	Command string    // Dockerfile instruction that created this layer
	Tree    *FileTree // nil until M05 populates it
	// NetDelta is the merged-filesystem change at this step.
	// [0] = live file bytes after the first layer (full size, not 0).
	// [i>0] = live bytes in stacked[i] minus stacked[i-1]. Negative when
	// a layer net-removes more than it adds (cleanup, whiteout deletes).
	NetDelta int64
}

Layer holds metadata for a single image layer.

type LayerDiff added in v1.3.0 

type LayerDiff struct {
	Index          int
	BeforeSize     int64
	AfterSize      int64
	SizeDelta      int64
	BeforeNetDelta int64
	AfterNetDelta  int64
	NetDeltaDiff   int64
	BeforeCommand  string
	AfterCommand   string
	CommandsMatch  bool
}

LayerDiff is a side-by-side comparison of two layers at the same index.

Index-based matching is the only stable option for Docker layers across rebuilds: a layer inserted in the middle of a Dockerfile shifts every subsequent index. CommandsMatch and the command-divergence warning surface that condition so consumers can interpret later rows skeptically.

type Option 

type Option func(*DockerResolver)

Option configures a DockerResolver.

func WithClient 

func WithClient(cli client.APIClient) Option

WithClient injects a Docker API client (used for testing).

type ProgressEvent 

type ProgressEvent struct {
	Phase       ProgressPhase
	LayersDone  int
	LayersTotal int
	BytesCurr   int64
	BytesTotal  int64
	// Message carries human-readable diagnostic text for PhaseCacheWarn.
	// Empty for normal phases.
	Message string
}

ProgressEvent reports loading progress back to the caller.

type ProgressPhase 

type ProgressPhase int

ProgressPhase identifies what the resolver is currently doing. 

const (
	// PhaseUnknown is the zero value, used by callers to mean "no phase
	// observed yet" so a UI can avoid rendering a stale default phase
	// before the first event arrives.
	PhaseUnknown ProgressPhase = iota
	PhasePulling
	PhaseExporting
	PhaseParsing
	PhaseCacheLoad // emitted on cache hit; no live Docker work follows
	// PhaseCacheWarn is a non-fatal diagnostic: the cache load or save
	// failed with an unexpected I/O error. The run continues with live
	// data; UIs typically render Message in a status bar.
	PhaseCacheWarn
)

type PruneOptions added in v1.4.0 

type PruneOptions struct {
	TTL      time.Duration
	MaxBytes int64
	All      bool
	DryRun   bool
	Keep     string
	Now      func() time.Time
}

PruneOptions controls what PruneCache evicts. Zero value is a no-op. 

TTL > 0       remove entries whose CachedAt is older than now-TTL
MaxBytes > 0  after the TTL pass, evict oldest entries until the
              surviving total is at or below MaxBytes
All == true   ignore TTL/MaxBytes; remove every entry under root
DryRun        walk and decide, but never call os.RemoveAll
Keep          digest never to evict, regardless of other options.
              Used by saveCache to protect the just-written entry,
              even when its own size exceeds MaxBytes. The user-
              driven `cache prune --all` always passes Keep="", so
              it genuinely empties the cache.
Now           injectable clock for tests; nil → time.Now

type PruneResult added in v1.4.0 

type PruneResult struct {
	Removed  []CacheEntry
	Kept     []CacheEntry
	Warnings []string
}

PruneResult is the return value of PruneCache. 

Removed   entries that were (or, in DryRun, would be) evicted, in
          the order they were processed: TTL victims first (by
          scan order), then size-cap victims oldest-first.
Kept      entries that survived this prune, in scan order.
Warnings  user-facing strings about partial failures (RemoveAll
          errors, single-entry-exceeds-cap). cmd/ chooses how to
          render; image/ does not print.

func PruneCache added in v1.4.0 

func PruneCache(root string, opts PruneOptions) (PruneResult, error)

PruneCache applies opts and returns what it did. Best-effort: a RemoveAll failure is recorded in Warnings and skipped, never returned as the function's err. The function's err is reserved for "could not even read the cache root" — every other failure is per-entry.

The first RemoveAll failure within a single call is appended to Warnings as `cache prune partial: <err>`; subsequent failures during the same call are silently counted to preserve I-03's "fifty broken evictees should not produce fifty stderr lines" contract.

Concurrent prunes against the same root may both try to remove the same entry; the second RemoveAll returns ErrNotExist which is treated as success (Removed gets the entry, no warning).

type Resolver 

type Resolver interface {
	Resolve(ctx context.Context, imageRef string) ([]Layer, error)
	ResolveWithProgress(ctx context.Context, imageRef string, progress chan<- ProgressEvent) ([]Layer, error)
	Inspect(ctx context.Context, imageRef string) (*ImageMeta, error)
	// ImageID returns the image content digest (e.g. "sha256:abc...") for ref.
	// Implementations may return an error if the image is not local; callers
	// that want pull-on-miss must call ensure-image semantics first.
	ImageID(ctx context.Context, imageRef string) (string, error)
}

Resolver fetches image layer information from a container runtime.

func NewDockerResolver 

func NewDockerResolver(opts ...Option) (Resolver, error)

NewDockerResolver creates a resolver connected to the local Docker daemon.

func NewDockerResolverWithHost added in v1.4.0 

func NewDockerResolverWithHost(host string, opts ...Option) (Resolver, error)

type WasteDiff added in v1.3.0 

type WasteDiff struct {
	Path         string
	BeforeWasted int64
	AfterWasted  int64
	WastedDelta  int64
}

WasteDiff captures how a single path's contribution to wasted bytes shifted between two images.

type WastedFile 

type WastedFile struct {
	Path        string
	TotalWasted int64
	LayerCount  int
}

WastedFile records a file path that appears redundantly across multiple layers.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.