mtree

Documentation

Overview

Package mtree renders an mtree(8) specification describing the metadata of one or more container image layers.

Inputs are processed in order and may be interleaved (see WriteMulti / Input):

• Tar inputs (a possibly-compressed layer blob, or a compact stream reconstructed with zero-filled bodies) are read as tar streams; passing several is equivalent to concatenating them into one stream. Each regular file's sha256digest is supplied by a ContentDigester (hashed content for a materialized tar; the recorded CAS reference digest or inlined bytes for a compact stream). Hardlinks (tar TypeLink) are replaced by a copy of the entry they point at, so "link" is emitted only for symlinks.
• Mtree inputs are existing mtree specs; their entries are folded in as though they came from a tar. Their paths are re-normalized to the configured layout and their keywords are filtered down to the requested option set (e.g. a stray nlink is stripped if nlink was not requested).

Two layouts are supported (Options.Layout):

• "tar" emits one entry per input entry, in order, keeping whiteout markers verbatim and never synthesizing intermediate directories.
• "oci_layer_filesystem_applied_changeset" applies every input (tar and mtree) to an in-memory filesystem as an OCI changeset -- synthesizing missing parent directories and applying whiteout (".wh.<name>") and opaque-whiteout (".wh..wh..opq") markers -- and serializes the resulting tree in a stable, path-sorted order.

Output is deterministic and host-independent: header keyword values come straight from the tar header (never the host filesystem or an /etc/passwd lookup), extended attributes are emitted in sorted order, and the entry order is fixed by the layout. The mtree data model, escaping (govis), spec parsing, and text rendering all come from github.com/vbatts/go-mtree; only the per-entry keyword selection is done here, so the result stays byte-stable across operating systems (unlike go-mtree's own tar streamer).

Index

• Constants
• func Decompress(r io.Reader) (io.Reader, error)
• func HashContent(_ *tar.Header, content io.Reader) ([]byte, error)
• func Write(r io.Reader, w io.Writer, opts Options, digester ContentDigester) error
• func WriteFromUncompressedTar(r io.Reader, w io.Writer) error
• func WriteMulti(w io.Writer, opts Options, inputs []Input) error
• type ContentDigester
• type Input
• type InputKind
• type Options
  • func DefaultOptions() Options
• type ParsedEntry
  • func ParseEntries(r io.Reader) ([]ParsedEntry, error)

Constants

const (
	// LayoutTar emits one mtree entry per input entry, in input order.
	LayoutTar = "tar"
	// LayoutOCIChangeset applies the inputs as an OCI changeset to an empty
	// filesystem and serializes the resulting tree in a stable order.
	LayoutOCIChangeset = "oci_layer_filesystem_applied_changeset"
)

Layout values for Options.Layout.

Functions

func Decompress

func Decompress(r io.Reader) (io.Reader, error)

Decompress returns a reader over the uncompressed tar bytes of r, sniffing the gzip and zstd magic numbers (and otherwise treating the input as a plain tar). Compression is detected by content, not file extension.

func HashContent

func HashContent(_ *tar.Header, content io.Reader) ([]byte, error)

HashContent is the default ContentDigester: it reads the whole content and returns its sha256. Use it when the real file bytes are available (e.g. a materialized tar blob).

func Write

func Write(r io.Reader, w io.Writer, opts Options, digester ContentDigester) error

Write renders a single uncompressed tar input. It is a convenience wrapper around WriteMulti.

func WriteFromUncompressedTar

func WriteFromUncompressedTar(r io.Reader, w io.Writer) error

WriteFromUncompressedTar reads an uncompressed tar from r and writes a deterministic mtree specification (with DefaultOptions and content digests hashed from each file) to w.

func WriteMulti

func WriteMulti(w io.Writer, opts Options, inputs []Input) error

WriteMulti renders the ordered inputs to a single mtree spec on w.

Types

type ContentDigester

type ContentDigester func(hdr *tar.Header, content io.Reader) ([]byte, error)

ContentDigester computes the sha256 of a regular file's content for the sha256digest keyword. It is called once per regular file with a non-zero size, with the tar reader positioned at that file's content. An implementation must EITHER read exactly the file's content from `content` (e.g. to hash inline bytes) OR return a precomputed digest without reading from `content` (leaving the body for the tar reader to skip). Returning a nil digest omits the sha256digest keyword for that entry.

type Input

type Input struct {
	Kind InputKind
	// Reader is an uncompressed tar (TarInput) or an mtree spec (MtreeInput).
	Reader io.Reader
	// Digester supplies content digests for TarInput regular files. Ignored for
	// MtreeInput.
	Digester ContentDigester
}

Input is one ordered source of entries.

type InputKind

type InputKind int

InputKind identifies how an Input's Reader is interpreted.

const (
	// TarInput reads the Reader as an uncompressed tar stream.
	TarInput InputKind = iota
	// MtreeInput reads the Reader as an existing mtree spec.
	MtreeInput
)

type Options

type Options struct {
	// PathPrefix is prepended to every entry path. It must be "" or "./". With
	// "" (bare tar paths), directory entries get a trailing "/" so they remain
	// full-path (not relative) entries.
	PathPrefix string
	// Keywords is the ordered list of fields to emit, on a best-effort basis.
	// Supported: type, size, mode, uid, uname, gid, gname, sha256, time, link,
	// nlink, xattr. Unknown names are ignored.
	Keywords []string
	// Layout is one of LayoutTar or LayoutOCIChangeset.
	Layout string
}

Options controls how the inputs are rendered as an mtree spec.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default mtree rendering options.

type ParsedEntry

type ParsedEntry struct {
	// Path is the canonical entry path: no leading "./", no trailing "/". The
	// filesystem root is reported as ".".
	Path string
	// Keywords maps each mtree keyword to its (still vis-encoded, for paths/links)
	// value. Common keys: type, size, mode, uid, uname, gid, gname, sha256digest,
	// time, link, nlink, and xattr.<name>.
	Keywords map[string]string
}

ParsedEntry is a single filesystem entry read back from an mtree spec: its path is decoded (vis-unescaped, canonicalized) and its keywords are collected into a map (keyword -> value, e.g. "type"->"file", "mode"->"0644", "uid"->"0", "sha256digest"->"<hex>"). It is the read counterpart of the WriteMulti renderer.

func ParseEntries

func ParseEntries(r io.Reader) ([]ParsedEntry, error)

ParseEntries parses an mtree(8) specification (as produced by this package) into a flat list of entries with decoded paths and collected keywords. It uses the same path decoding and keyword handling as the renderer, so it round-trips WriteMulti output regardless of the operating system.