## Summary S13's `Fetch` seam withholds things the remote format slices need. Each one gates an acceptance criterion in the S16 container remote spec, and one is a gap S14 carried as well. They are grouped here because they land in the same seam — `internal/remote/fetch.go` and the closed forwardable-header allowlist in `internal/remote/operations.go` — not because they have to ship together. **One of the three has since been delivered.** Gap 3 shipped through the alternative this issue offered — a separate channel rather than an allowlist exemption — as part of the Maven remote cold-fill work. Gap 1 lands with [!1808](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1808) and gap 2 with [!1807](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1807); the gap table says where each stands and what holds on either side of its merge. None of them blocks S16 from shipping. Each affected criterion degrades to behavior the spec already describes; while a gap is open its criterion carries a **gated** marker in S16, and the MR that closes the gap removes that marker. What they block is asserting the un-degraded behavior. | Gap | Where it stands | | --- | --- | | 1. Expected digest on the cache-fill commit | [!1808](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1808). Until it merges, `Fetch` commits with `nil`. | | 2. Pre-commit `Docker-Content-Digest` cross-check | [!1807](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1807), stacked behind !1808. The "make the header readable" half is **dropped** — see below. | | 3. `Content-Length` on a raw stream hit | Delivered on `main` as `FetchResult.ContentLength`, and Maven consumes it. Open only across `Standalone.Serve`. | The work ships as three MRs, in this order: [!1806](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1806) (spec corrections, no code), then !1808 (gap 1), then !1807 (gap 2). Each is scoped so a reviewer can check one claim. ## 1. Expected digest on the cache-fill commit **Status:** the S13 seam lands with [!1808](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1808). While that MR is open, `Fetch` commits with `nil` and no caller can name a digest; once it merges, `FetchOptions.ExpectedDigest` reaches `Session.Commit`, and what remains is container-side wiring, tracked in S16's Follow-ups rather than here. **Gap:** a proxied container manifest is digest-verified before its fill commits, and S13's Fetch commits without an expected digest. The S06 seam already does the work. `pgSession.Commit(expectedDigest *digest.Digest, opts ...BlobCommitOption)` (`internal/storage/pg_session.go`) compares the supplied digest against the computed one and fails with `ErrDigestMismatch`, rolling the fill back. `cacheFillTee.completeFill` (`internal/remote/fetch.go`) passed `nil` when this was filed, on the reasoning stated in the comment above the call: "an upstream commits to no digest upfront, and an ETag is not one, so the server-computed SHA-256 is authoritative." !1808 narrows that to the unset case and passes the caller's digest when one was named. That reasoning is right for Maven and npm and wrong for container: a pull by digest names the digest in the request path, so there *is* a reference value. **Ask:** a per-request expected digest on `Fetch` that reaches the existing `Commit` argument. Not new verification machinery. When this was filed `FetchOptions` carried `IfNoneMatch`, `Transform`, `BodyKind`, and `MaxBodyBytes`, and no field for this; !1808 adds `ExpectedDigest`. **Without it:** the by-digest guarantee in S16's Digest verification — a mismatched body is never committed — cannot be met on the manifest path, because the fill commits before the handler can compare. The seam alone does not close it: until the container fills pass the digest, the comparison still runs after the commit, which is what S16's Follow-ups bullet on that wiring records. **Scope:** container-only. Neither sibling fetches by digest. ## 2. `Docker-Content-Digest` readable, plus a pre-commit comparison **Status:** the pre-commit comparison lands with [!1807](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1807). While that MR is open, no file in `internal/remote` reads `Docker-Content-Digest` and a disagreeing header on a tag resolution goes undetected; once it merges, the fill reads the header behind a per-fetch opt-in and compares it against the staged bytes before the commit, so a contradicted fill is discarded rather than finalized and disowned afterwards. **Gap:** S16's tag-fetch cross-check fails the request when the upstream's `Docker-Content-Digest` disagrees with the computed sha256. S13's Fetch result exposes upstream headers only through a closed allowlist (`forwardableHeaders`, `internal/remote/operations.go`), which still holds the same four entries — `Content-Type`, `ETag`, `Cache-Control`, `Last-Modified` — and omits that header. The allowlist now has a second reader. S13 Step 11 extracted `safeHeadersFrom`, a package-level applier shared by `FetchResult.SafeHeaders` and `ServeResult.SafeHeaders` so the two result types cannot drift on what client-safe means. Anything done here reaches both. This is the third header the allowlist withholds from S16, after `Content-Encoding` — resolved by discriminating on the Fetch status instead, and being ratified as a deliberate rule in [!1789](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1789) — and `Content-Length` in gap 3 below. **Ask:** a pre-commit hook, and **only** that. This entry originally asked for the allowlist exemption *plus* the hook, and the exemption half has since been dropped as unnecessary. **Why the readable half is dropped.** The "make it readable" wording is left over from a design where the *handler* did the comparing. Once the comparison runs inside the fill, no caller needs the value — S16 says so in three places: the upstream's digest is "a cross-check only, never the stored value"; the response header is "service-generated, not relayed"; and a `HEAD` reports it "from the committed fill, never from the upstream's own". A slice needs the verdict, and the verdict arrives as the fill's error, whose message names both digests. Keeping the exemption would have cost a `raw` flag on `FetchResult`, a sixth parameter on `NewFetchResult`, a second allowlist, and signature churn in `internal/format/maven`, `internal/virtual`, and `internal/remote/remotetest` — for a contract with no reader. If a future handler does need the upstream's claimed value (an error detail, say), reopen this rather than assuming the allowlist is the way. **Without it:** an upstream sending a disagreeing `Docker-Content-Digest` on a tag resolution goes undetected, and the fill commits on the computed sha256 — the state that holds while [!1807](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1807) is open. **Scope:** container-only, and once [!1807](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1807) lands that is by construction rather than by circumstance. The comparison runs only on a fetch that sets `FetchOptions.CrossCheckUpstreamDigest`, which the container manifest fetch does and no Maven or npm fetch does, so a sibling fill cannot be failed by the header even where an upstream — or a proxy in front of it — emits one. The container blob fetch does not set it either: a blob names its own digest, so the commit is the authority there. ## 3. `Content-Length` on a raw stream hit **Status: delivered for `FetchResult`; open for `ServeResult`.** **Original gap:** S16's cold-fill blob `GET` forwards the upstream's `Content-Length`, and the closed allowlist omits it. The ask was "that one exemption, or a separate channel for the raw case." **What shipped:** the separate channel. `FetchResult.ContentLength int64` (`internal/remote/operations.go`) carries the upstream body's declared length on a stream hit, and is `-1` when there is none — chunked, decompressed by the upstream client, or a body whose declared length exceeded the response-body cap. Its own doc says it never travels through `SafeHeaders`, so the allowlist stayed closed and the framing-header argument for keeping it closed is untouched. It landed with the Maven remote fill work (`feat(remote): step 14 part 1 — stream digests in the fetch pipeline's cache-fill tee`). Maven already consumes it on both cold-fill paths — `streamArtifactFill` in `internal/format/maven/remote_artifact.go` and the metadata equivalent in `internal/format/maven/remote_metadata.go` — each setting `Content-Length` only when the value is non-negative. S14's spec no longer marks its cold-fill criterion gated or names this gap. **What is still open:** `ServeResult` (`internal/remote/serve.go`) has no equivalent field, so a slice composing `Standalone.Serve` cannot read the length. Maven reaches `FetchResult` directly; npm's packument path is the only `Standalone.Serve` caller today and transforms its body, so it would not forward the value anyway. `internal/format/oci` reaches neither seam yet, so which of the two the container cold fill composes is undecided — and that decides whether `ServeResult` needs the field. **Without it:** nothing for Maven. For the container cold-fill blob `GET`, still nothing until S16's fill path lands and picks a seam. **Scope:** shared. The Maven half is done. ## Spec text that has gone stale S16 still describes gap 3 as unavailable in three places, and each needs the correction when this issue is worked: - the `Content-Length` bullet under API Contracts ("S13 does not hand it over today"); - the cold-fill forwarding criterion under Manifest and blob proxy, marked **gated**; - the gap 3 bullet under Follow-ups. S13's own spec describes none of this. Its Fetch operation table still reads `StreamHit{body, status, etag}` with no length, so `FetchResult.ContentLength` is shipped code with no spec text behind it — the same shape as the header allowlist, which S13 has never described either. ## Pointers - `docs/specs/S16-container-remote.md` — Follow-ups, plus the criteria marked **gated** under Cache integrity and body caps and Manifest and blob proxy. - `docs/specs/S14-maven-remote.md` — the cold-fill allowance behind gap 3, now ungated. - `internal/remote/fetch.go`, `internal/remote/operations.go`, `internal/remote/serve.go`, `internal/storage/pg_session.go`. Related to #288 and #286.