extract

package
v0.4.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package extract walks the files of a single image layer without writing them to disk. It records whiteouts so that callers can tell which files are still visible in the final image filesystem and which were deleted by a later layer but are still shipped with the image.

Index

Constants

View Source
const (
	SigMaxFileSize  = "meles.Limits.MaxFileSize"
	SigUnsupported  = "meles.Unsupported.TarEntry"
	SigEngineTooBig = "meles.Limits.StreamMaxLength"
	SigTrailingData = "meles.Unsupported.TrailingData"
)

Signatures of skipped files, in the style of the engine's Heuristics.Limits.Exceeded.* results, so that ignore rules can name them.

View Source
const TrailingDataPath = "/(data after the end of the archive)"

TrailingDataPath stands for the data after the end of a tar archive, which is no file and has no path of its own.

Variables

View Source
var ErrLimitExceeded = errors.New("limit exceeded")

ErrLimitExceeded is returned (wrapped) when a layer exceeds a hard limit. A layer that exceeds a hard limit is never reported as clean.

Functions

func CleanPath

func CleanPath(name string) string

CleanPath turns a tar entry name into a clean absolute path. Traversal such as "../../etc/passwd" stays inside the layer root.

func HiddenBy

func HiddenBy(p string, i int, layers []*Layer) (int, string)

HiddenBy returns the index of the first layer after layer i that hides path p in the final filesystem, and how it does so ("overwritten", "whiteout" or "opaque"). It returns -1 if p is still visible. A whiteout entry with content is hidden by its own layer.

Types

type File

type File struct {
	Path    string
	Size    int64
	Content io.Reader
}

File is a regular file of a layer. Content is only valid during the callback passed to Walk.

type Layer

type Layer struct {
	// Entries holds all non-directory entries by absolute path.
	Entries map[string]bool
	// Whiteouts holds paths deleted by a .wh.<name> entry.
	Whiteouts map[string]bool
	// Opaques holds directories whose lower-layer content is hidden by a
	// .wh..wh..opq entry.
	Opaques map[string]bool
	// Hidden holds whiteout entries that carry content. A container runtime
	// never unpacks them, but the content is shipped in the layer.
	Hidden  map[string]bool
	Skipped []Skipped
	// Files is the number of regular files passed to the callback.
	Files int
	// Bytes is the number of uncompressed bytes read.
	Bytes int64
}

Layer is everything Walk learned about a layer apart from file contents.

func Walk

func Walk(r io.Reader, lim Limits, fn func(File) error) (*Layer, error)

Walk reads the uncompressed layer tarball r and calls fn for every regular file within the limits. Whiteout entries are recorded; those with content are passed to fn as well, because the name of an entry must not decide whether its content is scanned. Walk reads r to the end: content after the end of the archive cannot be attributed to a file and is reported as skipped.

type Limits

type Limits struct {
	// MaxFileSize skips (and reports) regular files larger than this.
	// 0 means no limit.
	MaxFileSize int64
	// MaxLayerSize is a hard limit on the uncompressed size of a layer.
	// 0 means no limit.
	MaxLayerSize int64
	// MaxFiles is a hard limit on the number of entries in a layer.
	// 0 means no limit.
	MaxFiles int
}

Limits protect against tar bombs and oversized files.

type Skipped

type Skipped struct {
	Path   string `json:"path"`
	Size   int64  `json:"size"`
	Reason string `json:"reason"`
	// Signature names the reason: SigMaxFileSize, SigUnsupported,
	// SigEngineTooBig, SigTrailingData or the engine's
	// Heuristics.Limits.Exceeded.*.
	Signature string `json:"signature"`
	// SHA256 of the file content, hex.
	SHA256 string `json:"sha256,omitempty"`
}

Skipped is a file that was not scanned.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL