Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture

This chapter describes the internal components and the overall build pipeline. The following chapters cover layer construction, OCI configuration and manifests, and output formats in more detail.

The standalone rib build CLI and the cargo rib build integration converge on the same pipeline:

rib build   ─────────────┐
                         ├──► ImageBuildSpec ──► BuildRequest
cargo rib build ─► cargo ┘                         │
                                                   ▼
                         ┌────────────────────────────────────┐
                         │ base image + parallel COPY build   │
                         └─────────────────┬──────────────────┘
                                           ▼
                                      ImageBundle
                                           │
                         ┌─────────────────┼─────────────────┐
                         ▼                 ▼                 ▼
                    OCI archive      Docker archive       registry

Once an ImageBuildSpec exists, the request source no longer affects image processing.

Module responsibilities

ModuleResponsibility
cliParses standalone CLI options into a build specification
cargo_integrationCoordinates cli, config, plan, and process for arguments, metadata, build planning, and Cargo execution
app::specDefines settings, merges transport overrides, and validates build requests
app::buildCoordinates the build
app::runtimeInitializes tracing and handles interruption signals
builder::copyParses --copy, expands globs, and resolves image destinations
builder::layerCreates a deterministic tar/gzip layer and its identifiers
imageStores the platform, base image, and layer sources
image::assembleProduces the final configuration, manifest, and ImageBundle
registryWraps oci-client, preserves manifest bytes, and delegates retry policy to registry::retry
app::pushChooses blob reuse, cross-repository mount, or upload
blobLayerStore shares local files, cache lookup, and downloads; concurrent requests for a digest share one download
cacheVerifies cached base layers and publishes complete entries atomically
archiveWrites OCI and Docker archives
authReads Docker configuration and explicit credentials, and canonicalizes registry names
progressProvides terminal, CI-line, and quiet progress modes

The rib and cargo-rib binaries delegate to rib::run() and rib::run_cargo(), keeping lifecycle and error handling shared. These entry points are internal to the binaries and are not a supported, stable library API.

Request normalization

Standalone options become BuildArgs and then ImageBuildSpec. Cargo integration builds the same specification after merging [package.metadata.rib] with CLI values. BuildRequest::try_from validates the main invariants before network or filesystem work starts:

  • --jobs is greater than zero;
  • at least one --to destination is present;
  • --platform matches <os>/<arch>[/<variant>];
  • every --label is a key=value pair;
  • a port without a protocol receives /tcp;
  • --creation-time is epoch, now, or valid RFC 3339;
  • the exact word scratch denotes an empty base; everything else is parsed as an oci_client::Reference.

Downstream components therefore consume one validated request type regardless of the entry point.

Two independent initial branches

Fetching base metadata and creating local layers are independent and run concurrently. The network branch is absent for scratch:

registry base                            scratch
─────────────                            ───────
fetch manifest + config ──┐              create empty config ──┐
                           ├─► assemble                          ├─► assemble
build COPY layers ─────────┘              build COPY layers ────┘

Only the base manifest and configuration are downloaded at this point. Base layer bytes are fetched later for a self-contained archive or when a target registry cannot reuse a layer.

Async and blocking boundaries

Registry access uses the asynchronous oci-client API. Filesystem traversal, tar creation, and gzip compression are CPU- and disk-bound, so every --copy runs in tokio::task::spawn_blocking rather than on Tokio worker threads.

A semaphore of size --jobs limits simultaneous layer builders. Separate semaphores with the same numeric limit constrain later blob downloads and uploads. Results carry their original indices and are reordered before assembly, so completion timing cannot change manifest layer order.

Assembly as the model boundary

Before assembly, the system holds base descriptors/configuration and local Layer values with their digest, diff_id, and temporary storage. The assembler combines them into:

ImageBundle {
    config,
    config_bytes,
    config_digest,
    manifest_bytes,
    manifest_digest,
    layers: Vec<LayerSource>,
}

All registry and archive outputs consume the same bundle and ordered layer list. Every destination in one invocation consequently has the same manifest digest.

Temporary-data lifecycle

A built layer owns an Arc<LayerStorage> for a temporary directory containing layer.tar.gz and, only when a Docker archive is requested, layer.tar. Cloning an image bundle shares these files rather than copying them.

Downloaded base layers are indexed by digest and reused across destinations in one run. Without --cache, temporary data is removed when its last owner is dropped. With --cache, base blobs remain under .rib-cache or --cache-path and are verified by digest before reuse. Built COPY layers are not cached between runs. Verification runs on the blocking pool. Downloads use private staging files and publish atomically after validation, so complete blobs are never truncated. Each reader opens a separate file with its own cursor.

Errors and cancellation

Errors at parsing, layer building, download, assembly, archive writing, and registry publication boundaries receive contextual messages. If a --copy worker fails, a shared cancellation token stops the remaining wrappers; the coordinator waits for them and returns the original contextual error.

Blocking COPY, archive, and decompression writers check cancellation between writes. Ctrl-C and, on Unix, SIGTERM cancel the top-level operation. Temporary directories are owned by RAII values and are cleaned when work is cancelled or fails; an archive is persisted only after its cancellation-safe write finishes.

The oci-client and oci-spec boundary

oci-client is used only for registry transport: authentication, manifest resolution, blob checks, mounts, uploads, and downloads. oci-spec is the canonical in-memory model for platform, descriptors, configuration, and manifest assembly. Adapter code converts registry values once at the boundary, so archive generation and assembly do not depend on registry transport types.