Extend the conformance suite so it can run against a **remote** (pull-through cache) repository, not only a hosted one. Companion to the Artifact Registry remote slices: [#286 Maven](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/286), [#287 npm](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/287), [#288 container](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/288). ## Problem Every read row in the current catalog seeds its own fixture with a write: OCI pushes into `conformance/{runID}/{slug}`, Maven deploys `com.gitlab.conformance:conformance-{runID}-{slug}`, npm publishes `@conformance/conformance-{runID}-{slug}`. On a `kind=2` repository every one of those writes answers `405`, so the tests fail at setup rather than at the behavior under test. Filtering the catalog down to "the rows remote supports" does not help: the read rows are the ones that write first. Remote conformance therefore needs a fixture source outside the repository under test, and a rule for where the suite gets it. ## Decisions to encode in the spec Agreed before drafting; the spec sub-item records them with acceptance criteria. **1. The suite seeds its own fixtures into the upstream.** A new `--upstream-url` names a writable repository that the repository under test proxies. The suite pushes the fixture there with the existing per-format client, then reads the same coordinate back through the remote repository. ``` suite --push--> hosted repo (--upstream-url) ^ | configured as the remote repo's upstream | suite --pull--> remote repo (--registry-url) ``` This keeps run-ID isolation, which is what makes a cache miss observable: a coordinate minted this run has never been fetched, so the first read is guaranteed cold. When the upstream is a hosted repository on the same registry, the existing single `--credential` covers both sides and S04's one-credential-per-run rule is unchanged. Rejected: pointing the suite at a fixed pre-existing coordinate such as `library/alpine:3.20`. It drops per-run isolation, makes cold-start unobservable, and lets an upstream content change fail a run that has nothing wrong with the registry. Worth revisiting later as an opt-in mode for validating a production remote that proxies a real public upstream. **2. The remote repository is provisioned out of band.** Creating one is S17 REST CRUD, which is Artifact Registry specific; teaching the suite to provision would bind it to one implementation. **3. Remote rows are new rows, not re-pointed hosted rows.** Each one gets its own `<format>.remote.*` slug and reuses the existing fixture builders and client methods. Hosted slugs keep their current meaning, and a run against a hosted repository is unchanged. **4. Assertions follow the AR specs, and which ones are AR-specific is recorded.** npm and Maven have no standard error vocabulary, so there is no neutral alternative beyond "some 405". The spec carries a table splitting protocol-mandated assertions from AR-specific ones, so a future second target knows exactly which rows to loosen: | Assertion | Source | | --- | --- | | `405` with an `Allow` header present on every unavailable verb, including `GET` upload-status on OCI's blob-upload routes | RFC 9110 | | Error code `method_not_allowed` (Maven), `unsupported` (npm), `UNSUPPORTED` (OCI) | S14 / S15 / S16 | | Empty `Allow` on npm dist-tag and unpublish routes, and on OCI `blobs/uploads/*` | S15 / S16 | | Maven cache-miss `200` carries no `ETag` and no checksum headers; the following hit carries both | S14 | **5. The new rows are opt-in.** They register only when `--repository-kind remote` is passed, so AR CI stays green until it chooses to run them. ## Prerequisites on the Artifact Registry side Neither is a change in this repository, and both are needed before the first remote run. 1. **A `kind=2` repository whose upstream is a hosted repository on the same instance.** `scripts/conformance/provision.sh` already seeds `kind=0`; it grows a remote alongside it. 2. **The instance's own host in `outbound_allowlist` in the CI config.** S13's upstream dialer denies loopback, RFC1918, link-local, and the host's own interface addresses ([`ipblock.go:47`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/internal/remote/upstreamhttp/ipblock.go#L47), [`dialer.go:637`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/internal/remote/upstreamhttp/dialer.go#L637)), so a self-referential upstream is blocked by default. An `outbound_allowlist` entry is checked first and returns early ([`dialer.go:621-624`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/internal/remote/upstreamhttp/dialer.go#L621-624)), which is the documented bypass for exactly this case (`config.proto:336`). Scoped to the test config; production is unaffected. ## Rough scope - New spec `docs/specs/S08-remote-contracts.md`, plus an S04 amendment for the two new flags (S04 owns the CLI input surface; S08 consumes it the way S07 does). - `Config.RepositoryKind` and `Config.UpstreamURL`; `--repository-kind` and `--upstream-url`, with validation and env bindings. - Catalog restructure. Today's `## Virtual` section mixes the two kinds: a remote proxies one upstream and caches it, a virtual aggregates several. Split into `## Remote` and `## Virtual`. Remote takes `oci.virtual.pull-through-cache-manifest`, `oci.virtual.pull-through-cache-blob`, the three `cache-ttl` rows, and the two `cache-invalidation` rows; everything else stays virtual, including `ns-query-routing` and `degraded-upstream`, which both presume several upstreams. Re-slug the moved rows to `<format>.remote.*`. Every row in these sections is `not started`, so no committed slug changes, and the moved rows stay `not started`: this slice re-files them, it does not implement them. - `Env` gains an upstream-bound client, a `requireUpstream` skip gate following the `requireCrane` precedent (`pkg/conformance/oci/env.go:238`), and a preflight that seeds one fixture and reads it back, so a pair of URLs that are not actually linked reports a configuration error instead of N failing rows. - Kind-aware `TestCatalog(cfg)` dispatch and inventory guards per kind. The `Module` interface needs no change: `TestCatalog` already takes `Config`. This work item ships no runnable remote row. It lands the seam; the first format child proves it end to end, and the plan picks which format goes first. **Out of scope:** - Virtual (`kind=1`) repositories. Aggregation across upstreams is a separate slice once S30 / S31 / S32 land. - Upstream request counting, fault injection, and stale revalidation timing. AR's own hermetic harnesses own these (S14 Step 18, S15 Step 14, S16 Step 18); reproducing them here would require the suite to run its own upstream server, which cannot work against a deployed registry. - Cache TTL expiry. Asserting it means waiting out `cache_validity_hours`. - Upstream credential handling and upstream health monitoring. Neither is client-visible. - Provisioning remote repositories. ## Open question **Who owns the two AR-side prerequisites above?** Both land in the `artifact-registry` repository, not this one. ## Status The plan is complete: [docs/plans/2026-08-21-remote-conformance.md](https://gitlab.com/gitlab-org/ops/registry-conformance/-/blob/main/docs/plans/2026-08-21-remote-conformance.md) Four bands: **A** Foundation (Steps 1-5a), **B** Maven (6-14), **C** npm (15-25), **D** OCI (26-37). Band A is format-agnostic and unblocks the other three; B, C, and D are independent of each other once A lands. | # | Step | MR | Status | Done | Assignee | Dependencies | |---|------|----|--------|------|----------|--------------| | **Band A: Foundation** | | 1 | run-ID widening to 64 bits | !258 | ~"workflow::complete" | [x] | @sylviashen | — | | 2 | `RepositoryKind` + three `Config` fields + validation | !258 | ~"workflow::complete" | [x] | @sylviashen | — | | 3 | the runner's remote-run policy surface | !258 | ~"workflow::complete" | [x] | @sylviashen | 2 | | 4a | three CLI flags + `list --repository-kind` | !258 | ~"workflow::complete" | [x] | @sylviashen | 2, 3 | | 4b | the derived `--timeout` | !259 | ~"workflow::complete" | [x] | @sylviashen | 3, 4a | | 5 | `remotefake`, the caching-proxy test double | !259 | ~"workflow::complete" | [x] | @sylviashen | — | | 5a | the shared seed-and-settle helper | !259 | ~"workflow::complete" | [x] | @sylviashen | 3 | | **Band B: Maven** | | 6 | Maven client `Allow` accessor + error code + terminal method + raw metadata bytes | !280 | ~"workflow::complete" | [x] | @sylviashen | — | | 7 | Maven env upstream client | !280 | ~"workflow::complete" | [x] | @sylviashen | 2, 3 | | 8 | Maven kind-aware catalog + per-kind guard | !280 | ~"workflow::complete" | [x] | @sylviashen | 2, 4a | | 9 | `maven.remote.preflight`, the walking skeleton | !281 | ~"workflow::complete" | [x] | @sylviashen | 1, 3, 5, 5a, 6, 7, 8 | | 10 | `maven.remote.artifact-relay` | !282 | ~"workflow::complete" | [x] | @sylviashen | 9 | | 11 | `maven.remote.metadata-relay` + `sidecar-synthesis` | !282 | ~"workflow::complete" | [x] | @sylviashen | 6, 9 | | 12 | `maven.remote.repeat-read` + `cold-fill-header-subset` | !282 | ~"workflow::complete" | [x] | @sylviashen | 9 | | 13 | `maven.remote.not-found` + `write-refused` | !282 | ~"workflow::complete" | [x] | @sylviashen | 5, 6, 8, 9 | | 14 | Maven strict-equality flip | !283 | ~"workflow::complete" | [x] | @sylviashen | 8, 9, 10, 11, 12, 13 | | **Band C: npm** | | 15 | S06 `HEAD` amendment | !260 | ~"workflow::complete" | [x] | @sylviashen | — | | 16 | npm client gaps | !261 | ~"workflow::complete" | [x] | @sylviashen | 15 | | 17 | npm env upstream client | !261 | ~"workflow::complete" | [x] | @sylviashen | 2, 3 | | 18 | npm kind-aware catalog + protocol baseline + guard | !261 | ~"workflow::complete" | [x] | @sylviashen | 2, 4a | | 19 | `npm.remote.preflight` | !261 | ~"workflow::complete" | [x] | @sylviashen | 1, 3, 5, 5a, 16, 17, 18 | | 20 | `npm.remote.packument-relay` | !263 | ~"workflow::complete" | [x] | @sylviashen | 19 | | 21 | `npm.remote.tarball-url-rewritten` + `tarball-relay` | !263 | ~"workflow::complete" | [x] | @sylviashen | 19 | | 22 | `npm.remote.dist-tags-relay` + `repeat-read` | !263 | ~"workflow::complete" | [x] | @sylviashen | 19 | | 23 | `npm.remote.not-found` + `write-refused-publish` | !263 | ~"workflow::complete" | [x] | @sylviashen | 5, 16, 18, 19 | | 24 | `npm.remote.write-refused-dist-tag` + `write-refused-unpublish` | !263 | ~"workflow::complete" | [x] | @sylviashen | 16, 19 | | 25 | npm strict-equality flip | !263 | ~"workflow::complete" | [x] | @sylviashen | 18, 19, 20, 21, 22, 23, 24 | | **Band D: OCI** | | 26 | OCI client gaps | !266 | ~"workflow::complete" | [x] | @sylviashen | — | | 27 | OCI env upstream client | !266 | ~"workflow::complete" | [x] | @sylviashen | 2, 3 | | 28 | OCI catalog split + kind branch + guard | !266 | ~"workflow::complete" | [x] | @sylviashen | 2, 4a | | 29 | extract the shared `Range` + `Docker-Content-Digest` matchers | !266 | ~"workflow::complete" | [x] | @sylviashen | — | | 30 | `oci.remote.preflight` | !266 | ~"workflow::complete" | [x] | @sylviashen | 1, 3, 5, 5a, 26, 27, 28 | | 31 | `oci.remote.pull-through-cache-manifest` + `manifest-relay-digest` | !271 | ~"workflow::complete" | [x] | @sylviashen | 30 | | 32 | `oci.remote.pull-through-cache-blob` + `blob-range` | !271 | ~"workflow::complete" | [x] | @sylviashen | 29, 30 | | 33 | `oci.remote.head-parity` + `docker-content-digest` | !271 | ~"workflow::complete" | [x] | @sylviashen | 29, 30 | | 34 | `oci.remote.tag-list-proxy` + `referrers-proxy` | !272 | ~"workflow::complete" | [x] | @sylviashen | 30 | | 35 | `oci.remote.repeat-read` + `not-found` | !272 | ~"workflow::complete" | [x] | @sylviashen | 28, 30 | | 36 | `oci.remote.write-refused-manifest` + `write-refused-blob-upload` | !272 | ~"workflow::complete" | [x] | @sylviashen | 26, 28, 30 | | 37 | OCI strict-equality flip | !273 | ~"workflow::in review" | [ ] | @sylviashen | 28, 30, 31, 32, 33, 34, 35, 36 | ## Children Created after the plan merges, since the plan decides their breakdown and order: - Maven remote rows (companion to AR [#286](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/286)) - npm remote rows (companion to AR [#287](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/287)) - OCI remote rows (companion to AR [#288](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/288)) ## Related - [#33](https://gitlab.com/gitlab-org/ops/registry-conformance/-/work_items/33) Library-integration handoff: `pkg/conformance` for AR integration tests - [S13](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S13-virtual-remote-foundation.md) virtual and remote foundation