imagefs

package

v0.30.7 Latest Latest Go to latest Published: May 21, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/deckhouse/deckhouse-cli

Links

Open Source Insights

Documentation ¶

Overview ¶

Package imagefs reads the filesystem of an OCI/Docker image as the merged view that a running container would see, and extracts it to disk with path-traversal and absolute-symlink-rewrite protection.

Whiteouts (.wh.* markers and .wh..wh..opq opaque markers) are honored: files explicitly deleted in an upper layer are invisible in the result.

NOT a Go fs.FS implementation - the API surface is purpose-built for the `d8 cr fs` subcommands (MergedFS / ReadFile / ExtractMerged).

Index ¶

Variables
func NormalizeScopePath(raw string) string
func ReadFile(img v1.Image, filePath string) ([]byte, error)
func WalkTar(rc io.Reader, fn func(*tar.Header, io.Reader) error) error
func Whiteout(name string) (string, bool)
type Entry
- func FilterBySubpath(entries []Entry, subpath string) []Entry
- func MergedFS(img v1.Image) ([]Entry, error)
- func (e Entry) IsDir() bool
type EntryType
type ExtractStats
- func ExtractMerged(ctx context.Context, img v1.Image, destDir string) (ExtractStats, error)

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrFileTooLarge = errors.New("file too large")

ErrFileTooLarge signals that a file's size exceeds the in-memory cap imposed by ReadFile to bound peak RSS when serving `fs cat`.

View Source

var ErrNotFound = errors.New("not found")

ErrNotFound signals an unknown layer reference or a missing file.

View Source

var ErrNotRegularFile = errors.New("not a regular file")

ErrNotRegularFile signals that a path exists but is not a regular file.

View Source

var ErrStopWalk = errors.New("stop walk")

ErrStopWalk stops a WalkTar iteration without surfacing as an error.

Functions ¶

func NormalizeScopePath ¶

func NormalizeScopePath(raw string) string

NormalizeScopePath canonicalizes a user-supplied PATH argument used to scope `fs ls`/`fs tree` output. Leading "./" or "/" is stripped, the path is Clean'd, trailing whitespace is trimmed, and an empty result is normalized to ".".

func ReadFile ¶

func ReadFile(img v1.Image, filePath string) ([]byte, error)

ReadFile returns the content of filePath in the merged FS. Layers are scanned top-down; a whiteout found before a matching entry causes ErrNotFound.

func WalkTar ¶

func WalkTar(rc io.Reader, fn func(*tar.Header, io.Reader) error) error

WalkTar reads a tar stream and invokes fn for each entry. Returning ErrStopWalk stops iteration without propagating as an error.

The function is the shared tar-traversal primitive used by all readers and the extractor. Callers pass the io.Reader obtained from v1.Layer.Uncompressed().

func Whiteout ¶

func Whiteout(name string) (string, bool)

Whiteout classifies a tar entry name as:

opaque marker (whole directory deleted from lower layers): returns (dir, true)
regular whiteout (single entry deleted): returns (targetPath, false)
not a whiteout: returns ("", false)

Types ¶

type Entry ¶

type Entry struct {
	Path     string      `json:"path"`
	Type     EntryType   `json:"type"`
	Size     int64       `json:"size"`
	Mode     fs.FileMode `json:"-"`
	ModeStr  string      `json:"mode"`
	Linkname string      `json:"linkname,omitempty"`
}

func FilterBySubpath ¶

func FilterBySubpath(entries []Entry, subpath string) []Entry

FilterBySubpath returns entries whose tar-relative path is at or under subpath. An empty or "."-equivalent subpath returns the entries unchanged.

func MergedFS ¶

func MergedFS(img v1.Image) ([]Entry, error)

MergedFS returns the effective filesystem contents of img: layers applied bottom-up, whiteouts (single-file and opaque) honored. Entries are sorted by Path.

func (Entry) IsDir ¶

func (e Entry) IsDir() bool

type EntryType ¶

type EntryType string

const (
	TypeFile     EntryType = "file"
	TypeDir      EntryType = "dir"
	TypeSymlink  EntryType = "symlink"
	TypeHardlink EntryType = "hardlink"
	TypeWhiteout EntryType = "whiteout"
	TypeOther    EntryType = "other"
)

type ExtractStats ¶

type ExtractStats struct {
	Files     int
	Dirs      int
	Symlinks  int
	Hardlinks int
	TotalSize int64
}

ExtractStats summarizes how many entries were materialized.

func ExtractMerged ¶

func ExtractMerged(ctx context.Context, img v1.Image, destDir string) (ExtractStats, error)

ExtractMerged writes the merged filesystem of img into destDir, honoring whiteouts top-down. Paths attempting to escape destDir are rejected.

Cancellation is checked between layers and at every tar entry, so a Ctrl-C from the cobra command interrupts a multi-GB extraction within the next entry boundary instead of running to completion.

Source Files ¶

View all Source files

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