Module repository 

Content-addressable repository for composefs objects.

This module provides a repository abstraction for storing and retrieving content-addressed objects, splitstreams, and images with fs-verity verification and garbage collection support.

Repository Layout

A composefs repository is a directory with the following structure:

repository/
├── objects/                  # Content-addressed object storage
│   ├── 4e/                   # First byte of fs-verity hash (hex)
│   │   └── 67eaccd9fd...     # Remaining bytes of hash
│   └── ...
├── images/                   # Composefs (erofs) image tracking
│   ├── 4e67eaccd9fd... → ../objects/4e/67eaccd9fd...
│   └── refs/
│       └── myimage → ../../4e67eaccd9fd...
└── streams/                  # Splitstream storage
    ├── oci-config-sha256:... → ../objects/XX/YYY...
    ├── oci-layer-sha256:... → ../objects/XX/YYY...
    └── refs/                 # Named references (GC roots)
        └── mytarball → ../../oci-layer-sha256:...

Object Storage

All content is stored in objects/ using fs-verity hashes as filenames, split into 256 subdirectories (00-ff) by the first byte for filesystem efficiency. Objects are immutable and deduplicated by content. Every file must have fs-verity enabled (except in “insecure” mode).

Images vs Streams

The repository distinguishes between two types of derived content:

• Images (images/): Composefs/erofs filesystem images that can be mounted. These are tracked separately for security: only images produced by the repository (via mkcomposefs) should be mounted, to avoid exposing the kernel’s filesystem code to untrusted data.

• Streams (streams/): Splitstreams storing arbitrary data (e.g., OCI image layers and configs). Symlinks map content identifiers to objects.

References (GC Roots)

Both images/refs/ and streams/refs/ contain named symlinks that serve as garbage collection roots. Any object reachable from a ref is protected from GC. Refs can be organized hierarchically (e.g., refs/myapp/layer1).

See Repository::name_stream for creating stream refs.

Garbage Collection

The repository supports garbage collection via Repository::gc(). Objects not reachable from any reference are deleted. The GC algorithm:

1. Walks all references in images/refs/ and streams/refs/ to find roots
2. Transitively follows stream references to find all reachable objects
3. Deletes unreferenced objects, images, and streams

fs-verity Integration

When running on a filesystem that supports fs-verity (ext4, btrfs, etc.), objects are stored with fs-verity enabled, providing kernel-level integrity verification. In “insecure” mode, fs-verity is not required, allowing operation on filesystems like tmpfs or overlayfs.

Concurrency

The repository uses advisory file locking (flock) to coordinate concurrent access. Opening a repository acquires a shared lock, while garbage collection requires an exclusive lock. This ensures GC cannot run while other processes have the repository open.

For more details, see the repository design documentation.

Modules

known_features

Set of feature flags understood by this version of the code.

Structs

FeatureFlags

Feature flags for a composefs repository.

FsckResult

Results from a filesystem consistency check.

GcResult

Statistics from a garbage collection operation.

ImportContext

Per-operation context for Repository::ensure_object_from_file.

RepoMetadata

Repository metadata stored in meta.json at the repository root.

Repository

A content-addressable repository for composefs objects.

Enums

FeatureCheck

Result of checking repository feature compatibility.

FsckError

A structured error found during a filesystem consistency check.

ObjectStoreMethod

How an object was stored in the repository.

RepositoryOpenError

Errors that can occur when opening a repository.

Constants

REPO_FORMAT_VERSION

The current repository format version.

REPO_METADATA_FILENAME

The filename used for repository metadata.

Functions

infer_repo_algorithm

Infer the repository algorithm by examining existing object filenames.

read_repo_algorithm

Read the fs-verity algorithm from a repository’s meta.json.

reset_metadata

Remove algorithm-specific data from a repository directory.

system_path

Return the default path for the system-global composefs repository.

user_path

Return the default path for the user-owned composefs repository.