Artifact Registry ADR-009: refine API design after follow-up decisions

David Fernandezrequested to merge
590367-10io/adr-009-api-design-refinements into main

Why is this change being made?

Work item gitlab-org/gitlab#590367 tracks post-merge refinements to ADR-009 (API Design) for the Artifact Registry. This MR addresses the four open follow-up tasks plus one wording-alignment refinement uncovered while investigating them.

What changed

Each task is a separate commit so the history stays narrative:

  1. Drop the OCI /v2/ 401 challenge from the routing note — The OCI 401 + WWW-Authenticate redirect challenge is non-viable for the Artifact Registry because AR cannot store or expose customer GitLab instance URLs (see gitlab-org/gitlab#595150).

  2. Add the three missing npm unpublish routes — Spec S11 (note 3298683845) documents the full npm unpublish flow per libnpmpublish/lib/unpublish.js.

  3. Correct npm audit/advisory paths and methods — Per the same spec S11 review: the npm CLI calls /-/npm/v1/security/... (not /-/v1/security/...), and audits/quick is POST (not GET).

  4. Polymorphic artifact responses for remote cache state (A.2) — ADR-007's hierarchical remote tables (commit bb6a356aa5) mirror local. The same artifact endpoints now serve both kinds; on kind=remote, a nested cache sub-object surfaces upstream_checked_at / upstream_etag for the rows that track freshness (tags, package files, metadata files). DELETE evicts the cached row on remote, soft/hard-deletes the authored artifact on local. Two commits — the second (A.2) supersedes the first wording-only attempt; the trail is kept in history for context.

Tasks closed on the work item

  • Update that /v2/ challenge response is no longer necessary
  • Update the ADR given that local cache entries are no longer in scope
  • NPM missing routes
  • NPM audit route

Test plan

  • CI doc-lint pipeline green (markdownlint, vale, lychee)
  • Reviewers verify the npm route additions/corrections against libnpmpublish/lib/unpublish.js and the npm CLI's audit endpoints
  • Reviewers confirm the wording change on advisories/bulk (dropped the remote/virtual restriction) is intentional
  • Reviewers confirm the A.2 polymorphism (nested cache sub-object on remote artifact responses, DELETE = evict on remote) is the right shape; the alternative was a parallel /cache/... sub-tree
Edited by David Fernandez

Merge request reports