Set Vary: Accept-Encoding on GzipMiddleware responses

[SyniRon]

GzipMiddleware negotiates compression on Accept-Encoding but never sets a Vary: Accept-Encoding response header. A shared cache in front of the service (the nginx proxy cache, a CDN) keys on the URL alone, so it can hand a gzipped body to a client that did not advertise gzip, or the reverse, because nothing tells it the response varied by encoding.

This is pre-existing and now covers both surfaces the middleware fronts:

• /api responses (the chain in rest/rest.go).
• The docs surface, after Serve the docs assets gzip-compressed (3.6 MB Scalar bundle ships uncompressed) #218 wrapped DocsHandler in the same middleware.

Surfaced during the #227 review.

Why this is its own change:

• The header belongs in GzipMiddleware (rest/gzip.go) so both surfaces pick it up from one place.
• Adding a response header changes the /api wire contract, so contract/goldens/ (and openapi/openapi.yaml if it documents response headers) need updating in the same change.
• Worth confirming what the nginx layer already does with Vary and cache keys, so the header actually changes behavior in production rather than being cosmetic.

Not urgent.

[SyniRon]

This was generated by AI during triage.

Agent Brief

Category: bug
Summary: GzipMiddleware negotiates compression on Accept-Encoding but never emits Vary: Accept-Encoding, so a shared cache can serve a gzipped body to a client that did not negotiate it.

Current behavior:
GzipMiddleware picks the response encoding from the request's Accept-Encoding: one URL yields a gzipped body (with Content-Encoding: gzip) for a gzip client and an identity body for everyone else. It never sets Vary: Accept-Encoding. A shared cache (a CDN, or an nginx with proxy_cache) that keys on the URL alone treats both variants as one entry, so it can hand a gzipped body to a client that cannot decode it, or the reverse.

This is latent. It only bites when a shared cache that stores these responses sits in front of the service. With nothing more than a TLS-terminating reverse proxy and no CDN, the header is inert today. Setting it is still correct, because the origin selected the representation by proactive negotiation and is the right place to declare that.

The middleware now fronts two surfaces, so one fix covers both: the /api JSON responses, and the docs surface (the Scalar UI plus the served spec, wrapped in the same middleware at #227).

Desired behavior:
Every response that passes through GzipMiddleware advertises Vary: Accept-Encoding, on the gzip branch and the identity pass-through alike, across both surfaces. The header is appended rather than written over an existing Vary.

Key interfaces:

• GzipMiddleware is the one place the header belongs, so both surfaces inherit it. Set it for every request the middleware handles, not only when gzip is chosen. If only the gzipped variant carries Vary, the identity variant can be cached without it and mis-served. Use Header().Add("Vary", "Accept-Encoding") rather than Set, so any existing value survives.
• Bodyless final statuses (204, 304) already get their Content-Encoding stripped here. Vary is a cache-keying hint and is fine to keep on them, but match that existing handling on purpose rather than by accident.

Contract handling (the issue body's assumption here is off):
Do not add Vary to the golden corpus. The golden header allowlist (contractHeaders) leaves out new-stack-only response headers on purpose. The comment beside it explains this for Cache-Control, and Vary is the same shape: a header the frozen old-stack goldens were never recorded with. Adding it to the allowlist would pin its absence across the corpus and break replay. Instead:

• Pin Vary with a rest/ test modelled on the existing Cache-Control header test (cachecontrol_test.go). Assert the header is present for a gzip request and a non-gzip request, on both the /api and docs surfaces.
• Document the header in the per-response headers: blocks in openapi/openapi.yaml, next to the existing Cache-Control entries.

Acceptance criteria:

• Every response through GzipMiddleware carries Vary: Accept-Encoding on the gzip and identity paths, for /api and docs.
• The header is appended, not written over an existing Vary.
• A rest/ test pins the header for gzip and non-gzip requests on both surfaces.
• openapi/openapi.yaml documents the header in the response headers blocks.
• The golden corpus is unchanged and Vary stays off the contractHeaders allowlist.
• go build ./... && go vet ./... && go test ./... passes.

Out of scope:

• The nginx and CDN cache configuration. Whether this fix changes production behavior today depends on whether a shared cache fronts the service, which lives in the gitignored live config and needs a human to confirm. It does not block this change.
• Re-recording the golden corpus.
• Any change to the gzip negotiation logic, or the hijack-faithfulness work tracked in rest: gzip close-log hijack faithfulness — distinguish clean takeover from abandoned-output corruption #181.