Make cold blob ETags reusable for conditional downloads

perfloop-oss/distribution · Overfetching

https://perfloop.ai/t/oss/case_tfpc98zgsw

Verdict

VERIFIED · settled 2026-11-11 · merged as distribution/distribution#5072

What happened: The check fails before this change and passes with it.

Hypothesis

The first proxy download returns an unquoted entity tag, the HTTP token used to validate a cached response. Reusing that token after the blob enters local storage returns the unchanged body instead of a bodyless 304 response. This wastes downstream transfer and local serving work for such conditional requests; their frequency and blob sizes are unknown.

copyContent calls setResponseHeaders, which assigns dgst.String() directly to Etag at proxyblobstore.go:43. The warm path delegates to the local blob server, which emits the same digest with the quotes required for a valid entity tag. This is a response-identity mismatch across a normal cold-to-warm transition, not a request for new cache policy. The blob API explicitly asks for ETag-based HTTP caching in docs/content/spec/api.md:466-483.

checkProperty call_ibIaXCw4edjpa868JdCO6e8u ran the stored check on prop_bkyj3fa3pp at f49f48736337e8fc9f7816a044819b0f7967d557: `go test -count=1 -v -run=^TestPerfloopProxyETagRoundTrip$ ./registry/proxy`. It failed on both fixed payloads, one byte and 65 bytes. The cold response's verbatim ETag produced 200 and the full fixture body on the next warm request. The quoted token from a later ordinary warm GET produced 304 with no body in both controls. The one-byte payload "x" is the smallest stored replay. There were no mutations, evictions, concurrent callers or generated replay files; the deterministic inputs are already in the check file. This measures statuses and fixture body counts, not production transfer cost.

Prior repair hyp_xp0vtshdv2 concerns formatting costs in the storage blob server, whose ETag is already quoted. It does not repair the proxy header. The actual proxy hunks of https://github.com/distribution/distribution/pull/5052 change copy dispatch for early errors, and https://github.com/distribution/distribution/pull/4946 changes upload digest selection; neither changes this header. The bounded owner history includes the header-propagation change at https://github.com/distribution/distribution/commit/04182455, and the accepted source still contains the unquoted assignment. No separate patch-review venue is named beyond GitHub in the contribution guidance.

The first Case check can replay the same unchanged-blob sequence and show that the cold token now yields 304 without transferring the blob, while cold/warm full GETs retain byte, length and digest identity. The current native test and its placement are provisional proof support, not an additional frozen layout requirement. This is independent of avoiding cold HEAD downloads: the failing request here is a later GET served from an already populated local cache.

Change to test: Emit a valid, consistently quoted strong ETag for ordinary proxy copies so a validator returned by a cold GET can be reused verbatim against the warm cache. Preserve the digest header, full-GET content and existing Range pass-through behavior.

Where it lives

perfloop-oss/distribution · registry/proxy/proxyblobstore.go

Evidence

The check fails before this change and passes with it: `For unchanged empty, one-byte and 65-byte blobs initially absent from the local proxy cache, a successful cold GET emits the same quoted digest ETag as a warm GET, and reusing that cold ETag verbatim in If-None-Match on the next GET returns 304 with no body.`

Checks: 3 of 3 passed. Verification: no defect found.

Timeline