Implement the referrers API

[rosvik]

• https://opencontainers.org/posts/blog/2024-03-13-image-and-distribution-1-1/#referrers-api
• https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers

[rosvik]

Implementation suggestion by Claude

---

Spoiler

Referrers API: Implementation Options & Plan

Background

The spec describes the referrers API as a way to find manifests whose subject field points at a given <digest>. The challenge for Container Cubby is that the current storage model has no index: manifests are plain sha256:<hash>.json files inside a namespace directory, with no metadata about cross-references. This is exactly the problem flagged in README.md line 144 ("not being an obvious way to support it without slowly reading all manifests per namespace on disk").

Three implementation options

Option A — On-demand directory scan (simple, slow)

Implement GET /v2/<name>/referrers/<digest> by walking the namespace directory at request time:

1. List containers/<name>/sha256:*.json
2. For each manifest file, parse it and look at subject.digest
3. Build the descriptor list, applying the artifactType fallback rules

• Pros: trivial code change, no schema migration, no consistency to maintain, no extra disk usage. Reuses existing helpers (file::read_dir, serde_json::from_reader, prune already does similar walks in src/storage/prune.rs).
• Cons: O(N) JSON parses per request where N is the number of manifests in the namespace. Hot namespaces with hundreds of tags + index children will be measurably slow. Filter by artifactType does not save IO. Cold-cache reads on a spinning disk are particularly bad.

Option B — Single referrers index file per subject (compact, but locking)

Maintain containers/<name>/sha256:<subject_hex>.referrers.json containing the entire image-index payload for that subject. Update it atomically on every PUT/DELETE manifest.

• Pros: single file read per GET; smallest on-disk footprint; pagination is a slice of an in-memory array.
• Cons: every concurrent PUT against the same subject must serialize to avoid lost updates (read-modify-write). Implementing this safely without a database means file locking (flock) or atomic-rename rebuilds, which doesn't compose cleanly with the rest of this codebase. Migration also requires a one-shot scan.

Option C — Per-subject directory of descriptor cache files (recommended)

Add a new on-disk index that mirrors the project's existing "files-and-symlinks-as-state" philosophy:

containers/rosvik/container-cubby/
├── latest.json                          [Tag -> Manifest symlink]
├── sha256:<manifest>.json               [Manifest]
├── sha256:<sbom>.json                   [Manifest with subject -> sha256:<manifest>]
├── sha256:<blob>.blob                   [BlobLink]
└── referrers/
    └── sha256:<subject>/
        ├── sha256:<sbom>.json           [Cached descriptor]
        └── sha256:<sig>.json            [Cached descriptor]

Each cached descriptor file is the small JSON descriptor that the spec wants in the response, with artifactType already resolved at write time:

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:<sbom>",
  "size": 1234,
  "artifactType": "application/vnd.example.sbom.v1",
  "annotations": { "...": "..." }
}

• Pros:
  • GET is O(R) where R is the actual referrer count; no manifest parsing at request time.
  • One file per referrer means no locking — concurrent PUTs touch disjoint files. Idempotent: the filename is the referrer's own digest, so re-uploads overwrite cleanly.
  • Filtering by artifactType reads only the small descriptor files.
  • Cleanly backfillable — a one-shot rebuild walks the existing namespace directories.
  • Matches the project's filesystem-as-database style (already used for tags and blob links).
• Cons:
  • Small write amplification on PUT (one extra small JSON file per referrer).
  • Descriptor data is duplicated between the manifest and the cache file (acceptable: the cache is rebuildable from manifests).
  • Needs migration for existing data.

Recommendation: Option C

It is the only one of the three that delivers good GET performance while keeping the codebase database-free, lock-free, and consistent with the existing storage model. Option A can be added on top as a fallback for un-migrated namespaces (hybrid mode) if desired, but it is not required.

Implementation outline (Option C)

New file type and storage helpers

Extend FileType in src/storage/path.rs with Referrer and add a builder for containers/<name>/referrers/<subject>/<referrer>.json. Add helpers in src/storage/mod.rs:

• write_referrer(name, subject_digest, referrer_descriptor) -> io::Result<()>
• delete_referrer(name, subject_digest, referrer_digest) -> io::Result<()>
• list_referrers(name, subject_digest) -> io::Result<Vec<Descriptor>>

Hook into PUT manifest

In src/storage/manifest.rs Manifest::create_manifest, after the manifest file is written: if the parsed manifest exposes a subject, build a descriptor for the new manifest and call write_referrer. Resolve artifactType per spec:

• Image manifest: use artifactType if set, else fall back to config.mediaType.
• Image index: use artifactType if set, else omit.

Hook into DELETE manifest

In storage::delete_manifest (src/storage/mod.rs): before deleting the manifest file, parse it to read its subject (if any) and remove the matching descriptor file from referrers/<subject>/. If the manifest is unparsable, fall back to the prune sweep.

New endpoint

Add get_referrers in src/main.rs routed at /v2/{name}/referrers/{digest}:

• 400 if digest fails is_safe_digest.
• Read containers/<name>/referrers/<digest>/. If missing, return 200 with an empty manifests array (the spec REQUIRES 200 even when there are no referrers).
• Deserialize each descriptor JSON, optionally filter by ?artifactType=, sort by digest for stable pagination.
• Page via ?n=<int>&last=<digest> (mirroring tags/list); emit Link: rel="next" when truncated.
• If filter was applied, emit OCI-Filters-Applied: artifactType.
• Content-Type: application/vnd.oci.image.index.v1+json, body is the image index payload.

Backfill for existing data

Add referrers::rebuild_all() in src/storage/ (sibling of prune.rs) that walks every containers/<name> directory, parses every sha256:*.json, and writes the descriptor cache files for any manifest with a subject. Trigger options (pick one):

• One-shot, gated by an env var (e.g., REBUILD_REFERRERS=1 on startup).
• A cargo run --bin rebuild-referrers style helper.
• Lazy: if the referrers/ directory is missing for a namespace at GET time, do a one-time rebuild for that namespace and cache the result. Slightly more code, but no operator action needed.

Tests

Add fixtures and tests covering:

• Manifest with subject -> descriptor cache file is created.
• Multiple referrers -> all listed; filter by artifactType narrows correctly.
• Image index referrer -> artifactType is omitted when not in the manifest.
• Image manifest referrer with no artifactType -> falls back to config.mediaType.
• Unknown subject digest -> 200 with empty manifests.
• Invalid digest syntax -> 400.
• Delete manifest -> descriptor cache file is removed.
• Backfill walks an existing namespace and produces the same result as a fresh ingest.

Documentation

Update the conformance table in README.md (end-12a/12b -> implemented), and document the new on-disk layout in the Storage section. Mention the rebuild trigger.

Data flow

flowchart LR
    Client -->|"PUT /v2/name/manifests/digest"| PutManifest
    PutManifest -->|writes| ManifestFile["sha256:referrer.json"]
    PutManifest -->|"if subject present"| Cache["referrers/sha256:subject/sha256:referrer.json"]
    Client -->|"GET /v2/name/referrers/subject"| GetReferrers
    GetReferrers -->|"read_dir + parse small JSONs"| Cache
    GetReferrers -->|"filter, sort, paginate"| Response["application/vnd.oci.image.index.v1+json"]

Loading

[rosvik]

Another option could be a on-demand directory scan + in memory cache per manifest SHA. First request will be slow, but subsequent requests to the same namespace will be fast. Doesn't need to create any files on disk, and the memory footprint shouldn't be too big. Could add a step to the prune process if needed to reduce memory footprint.