[Proposed Feature] Send Cache-Control on proxied object responses

[cholmes]

Description of Feature:

Send a Cache-Control header on proxied object responses.

Responses today carry ETag and Last-Modified but no Cache-Control:

$ curl -sI https://data.source.coop/<repo>/collection.json
HTTP/2 200
content-type: application/json
etag: "6f56127110ec18360b527bcb3e0b707a"
last-modified: Tue, 15 Sep 2026 09:18:59 GMT
cf-cache-status: DYNAMIC
server: cloudflare

Without Cache-Control, RFC 9111 §4.2.2
permits a cache to pick its own freshness lifetime, and the common heuristic is
10% of the time since Last-Modified. A file untouched for ten days is then
treated as fresh for a day. Browsers apply this to fetch(), so a client that
re-reads metadata after a publish can get the previous version with no error and
no way to tell.

We hit this on a STAC catalog served from Source Cooperative. After publishing
updated item JSON, a browser kept returning the pre-publish bodies — different
ETags for the same URL — while curl returned current ones. The app dropped
26 of 27 archives from its picker, because each item looked like it advertised
no tileset. We now fetch the collection with a cache-busting query parameter
and key the item URLs off a version string in it, so a publish changes every
item URL. That works, but it is a workaround for a missing header, and the
collection itself is now uncacheable.

Revalidation already works, so the fix is cheap:

$ curl -sI -H 'If-None-Match: "6f56127110ec18360b527bcb3e0b707a"' \
    https://data.source.coop/<repo>/collection.json
HTTP/2 304      # 0 bytes

S3 stores Cache-Control as object metadata and returns it on GET and HEAD, so
the proxy can pass through whatever the object carries. Objects we have checked
do not set it:

$ aws s3api head-object --bucket <bucket> --key <repo>/collection.json
{ "ContentType": "application/json", ... }   # no CacheControl

Two options, not exclusive:

1. Pass through Cache-Control from the object. Publishers then choose per
   file — max-age=31536000, immutable for data that is rewritten under a new
   name, no-cache for metadata that is overwritten in place. This costs the
   proxy one header copy.
2. Send a default when the object sets none. no-cache is the safe one: it
   permits storing but requires revalidation, and revalidation is already a
   304 with an empty body.

Option 2 alone fixes the correctness problem. Option 1 lets publishers get
caching back for immutable data.

What value is this feature adding to Source Cooperative?

• Clients stop reading stale metadata after a publish. This is currently silent:
  the response is a 200 with a plausible body, so nothing downstream detects it.
• Publishers stop working around it with cache-busting query strings, which
  force a full transfer every time and make caching impossible for anyone.
• Whole-object reads of small metadata — STAC JSON, READMEs, styles, TileJSON —
  become correctly cacheable by browsers and downstream caches, on the
  publisher's terms instead of a heuristic's.

Note

Scope, and how this relates to #188. This header alone does not make
ranged reads edge-cacheable, and an earlier version of this issue claimed it
did. Cloudflare's Cache API refuses to store a 206
(docs), and
the proxy deliberately sets RequestCache::NoStore on any subrequest carrying
a Range header (ForwardRequest::should_bypass_cache in multistore) so a
partial response can never poison the full-object cache entry. Making ranged
reads of large objects (COG, GeoParquet, PMTiles) fast is #188's job —
chunk-aligned caching inside the worker — and the two are complementary rather
than overlapping: #188 governs what the worker's own cache holds, this issue
governs what the proxy tells downstream caches.

[cholmes]

Did a Claude review:

Review fixes (57267a2)

• 304s no longer get the header. RFC 9111 §4.3.4 merges a 304's headers
  into the stored response, so injecting there overwrote a publisher's
  max-age=31536000, immutable — honoured on the original 200 — with
  no-cache one revalidation later. Same override the passthrough rule
  forbids, just deferred a round-trip. default_cache_control now takes the
  response status.
• Control-plane reads get the default instead of being exempt. The
  carve-out assumed those endpoints manage their own caching, but
  multistore-oidc-provider serves discovery and JWKS via
  ProxyResult::json, which sets only content-type — the exact header-less
  state this PR fixes. A JWKS cached past an OIDC_PROVIDER_KID_PREVIOUS
  rotation rejects tokens signed by the new key. Passthrough still protects
  any value those endpoints might send. path and is_control_plane are
  dropped as unused.
• configured is trimmed before the is-empty test, so
  DEFAULT_CACHE_CONTROL=" " disables the default rather than emitting a
  blank, directive-less header.
• Ranged-read integration test accepts 200 as well as 206, matching the
  three pre-existing range tests — a backend may ignore Range, and the test
  would have failed before reaching the header it exists to check.