Crate oci_image

Expand description

OCI container images on disk.

ImageRef and Digest: references with Docker’s defaults, strict sha256: digests that are safe as file names.
apply_layer_file / apply_layer: one-pass layer unpack with OCI whiteout and opaque-directory rules, a decoder thread ahead of the tar reader and a pool of file writers. Every write is relative to a directory descriptor resolved beneath the rootfs (openat2 RESOLVE_BENEATH, or an O_NOFOLLOW walk): nothing lands outside it, whatever the layer holds or another process changes meanwhile. Gzip layers decode on all the caller’s threads with lgz’s one-pass streaming decoder (any gzip, no flush points needed; small layers on one core with zlib-rs, by lgz’s own threshold); zstd layers with libzstd (feature zstd, on by default).
changes and decoder: the same whiteout rules as events over an in-memory blob, for scanners that keep their own view of the files.
LayerStore: verified blobs by digest and one flattened rootfs per layer chain.
Overlay: upper/work/merged directories and overlayfs mount data for a container on top of a rootfs.

Registry pulls and pushes live in oci-image-store (its pull, behind a Registry trait), which writes into a LayerStore as well.

Structs§

BlobWriter: A blob being written; hashed as it goes, placed by BlobWriter::commit, removed if dropped uncommitted.
Digest: A sha256:<hex> content digest. Parsing is strict (64 lowercase hex digits), so a digest is always safe to use as a file name.
GcStats: What LayerStore::gc removed.
Hasher: Incremental sha256, for blobs that arrive in chunks.
ImageLayer: One layer of an image: its blob (compressed) digest and its diff_id (the digest of the uncompressed tar, from the image config).
ImageRef: A parsed image reference such as busybox, nginx:1.27 or ghcr.io/org/app@sha256:..., with Docker’s defaults filled in.
LayerStore: A content-addressed store of layer blobs, unpacked layers and images:
Overlay: The directories of one overlay mount: read-only lower layers (top first), and the container’s own upper, work and merged directories.
UnpackOptions: How to unpack layers.
UnpackStats: What one layer unpack did.

IN_FLIGHT: The most file bytes held in memory for the writer pool.
OPEN_FILES: The most files open and waiting for the writer pool.
SMALL_FILE: Regular files up to this size go to the writer pool; larger ones are streamed to disk on the unpacking thread.
ZSTD_OFF: What a zstd layer meets when this crate is built without its zstd feature.

apply_layer: Apply one uncompressed layer tar onto rootfs.
apply_layer_file: Apply the layer blob at blob (plain, gzip or zstd) onto rootfs.
apply_layer_file_digest: apply_layer_file, also returning the sha256 of the uncompressed tar (the layer’s diff_id). On the lgz path it is computed on one more thread from the decoder’s in-order output, beside the tar reader: no extra pass.
chain_id: The id of a stack of layers: sha256 over their digests, one per line.
changes: Walk an uncompressed layer tar in order, classifying whiteouts, for readers that keep their own view of the filesystem (scanners, catalogers). Entries whose path would escape the root, and whiteouts of . or .., are skipped.
decoder: A streaming tar reader over an in-memory blob of any supported compression.
entry_path: Clean relative path of a tar entry, or None if it would escape (or is the root itself).