Loading
docs(specs): spec S17 phase 3 format artifact reads
📋 What does this MR do?
Patches S17: REST management API with Phase 3: format artifact reads — the read-only artifact surface beneath a hosted repository, per ADR-009's format-specific artifact APIs.
🗺️ Surface
13 GET endpoints under /api/v1/:slug/repositories/:repository_name/:format/:
| Formats | Endpoints |
|---|---|
docker, oci |
Images (list, detail), image tags (list, detail), manifests (list) |
maven, npm |
Packages (list, detail), versions (list, detail), files (list, detail) |
npm |
Dist-tags (list, detail) |
The :format segment is the repository's format value; ADR-009 predates the Docker/OCI format split and is amended via the handbook in a follow-up.
🎯 Key decisions (full reasoning in the spec's Resolutions)
- Stored fields only. Responses serialize stored columns plus three single-row joins (blob size, tag manifest digest, dist-tag version); no read-time aggregates, so every list stays one index-ordered keyset scan.
- Specced against the live schema. No soft-delete filtering on container tables (the columns do not exist there),
versions_countcap semantics documented, tag-join invariants derived from the S11/S12 transactional delete paths. - Three new keyset indexes on
(namespace_id, <parent>_id, created_at, id)back thecreated_at desclist defaults:maven_versions(partial, live rows),container_manifestspartial (WHERE subject_digest IS NULL, the default referrer-excluding manifests list), andcontainer_manifestsfull (theinclude_referrers=trueview); ADR-007's index list is amended via the handbook. - Deferred with documented follow-ups: per-artifact sizes and download counts (S18/S22), npm package.json metadata (waits for the monolith S06 artifact-detail spec), the remote-kind
cacheobject (S13).
✅ Status
Spec status is Approved; the merge is the approval signal per the repo gate. Open Questions: none. markdownlint and Vale pass; the mermaid flowchart renders.
Related to #312 (closed)
Edited by David Fernandez