fix(compress): set Vary: Accept-Encoding on negotiated responses

[arhxam]

What

Make the compress middleware add Accept-Encoding to the response's Vary header for every response it negotiates — both the compressed responses and the identity responses it leaves alone.

Why

compress negotiates gzip/deflate from the request's Accept-Encoding header, but the response is never marked as varying on that header. This is a cache-correctness bug in both directions:

• A shared cache (CDN, reverse proxy) can store the compressed body from one request and serve it to a client that sent a different/absent Accept-Encoding, handing that client a body it cannot decode.
• It can equally store the identity body served to a client that sent no Accept-Encoding, and then serve that to a gzip-capable client.

Per RFC 9110 §12.5.5, any response whose content is selected using a request header must list that header in Vary, and the spec explicitly names Accept-Encoding "or lack thereof" as a determining factor — so the absence of the header is itself part of the negotiation. This is standard behaviour for compression middleware (e.g. Express compression, @fastify/compress). The sibling middlewares in this repo already do this for their own negotiated headers — cors sets Vary: Origin and cache manages Vary — so compress was the outlier.

How

Vary is updated immediately after the eligibility checks, before the encoding is negotiated, so it covers both outcomes:

• no existing Vary → Vary: Accept-Encoding
• existing Vary: Cookie → Vary: Cookie, Accept-Encoding
• Vary already containing Accept-Encoding, or Vary: * → left unchanged (no duplicates)

Responses that are never eligible for compression (206, already-encoded, HEAD, below threshold, non-compressible type, no-transform) are untouched.

The header is written through ctx.header(), which recreates the response when a handler returned a fetch() response. On Node that recreation inherits the immutable header guard from the original response and the write can still throw, so there is a fallback that rebuilds the response around a fresh Headers instance. See this comment for the details — it looks like a latent Context.header bug worth fixing separately.

Verification

• Full suite: 4625 passed | 35 skipped, 145 files.
• 8 tests in the Vary Header block (set when compressing, append to existing Vary, no duplicate, Vary: * untouched, identity response with absent Accept-Encoding, identity response with an unsupported encoding, not-eligible response gets no Vary, immutable-header response).
• 2 tests in runtime-tests/node covering a real fetch() response, compressed and identity.
• Both immutable-header tests were mutation-checked: they fail if the fallback is removed.
• prettier --check, eslint, and tsc -p tsconfig.spec.json — clean.

Checklist

• Add tests
• Run tests
• format:fix && lint:fix
• Document the code (comments referencing the RFC)

[usualoma]

Hi @arhxam,

Thanks for creating PR.

I think the identity response needs to carry Vary: Accept-Encoding as well:

With the current placement, Vary is only added after compression has been selected. When Accept-Encoding is missing or unsupported, the middleware returns without it, allowing a shared cache to reuse that identity response for a later request that accepts gzip. RFC 9110 §12.5.5 gives Accept-Encoding as an example and explicitly includes the header’s absence (“or lack thereof”) as a determining factor.

I’d lean toward:

• Adding Vary after the initial eligibility checks, but before the !encoding return.
• Having the helper accept the Context and use ctx.header(...) instead of mutating res.headers directly. ctx.res can have immutable headers when a handler returns a fetch() response, while ctx.header() creates a mutable response when necessary.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.10%. Comparing base (224d2f5) to head (b44fddb).
⚠️ Report is 31 commits behind head on next.

Additional details and impacted files

@@           Coverage Diff           @@
##             next    #5137   +/-   ##
=======================================
  Coverage   79.09%   79.10%           
=======================================
  Files         154      154           
  Lines       10783    10787    +4     
  Branches     2253     2255    +2     
=======================================
+ Hits         8529     8533    +4     
  Misses       2254     2254           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[arhxam]

Thanks for the review @usualoma — both points addressed in eef5bc7.

1. Vary on identity responses. Moved the call above the !encoding return, so it now runs right after the eligibility checks and applies whether or not compression is selected. You're right that the "or lack thereof" wording makes the identity response part of the negotiated set — the missing-Accept-Encoding case was the more dangerous one, since that's exactly the response a shared cache would then hand to a gzip-capable client.

2. ctx.header() instead of mutating res.headers. Switched, and the helper now takes the Context. One thing I want to flag, because it changed the shape of the fix:

ctx.header() on its own is not sufficient here — it still throws on a fetch() response under Node. Context.header recreates the response with createResponseInstance((this.#res as Response).body, this.#res), i.e. new Response(body, res), and in undici that constructor inherits the immutable header guard from the original response:

const r = await fetch(url)
r.headers.set('x', '1')                        // TypeError: immutable
new Response(r.body, r).headers.set('x', '1')  // TypeError: immutable  <- the ctx.header() path

(Curiously, a second round trip is mutable — new Response(inner.body, inner) where inner was itself constructed. That's why the existing compress path happens to work: ctx.res = ... goes through the res setter, which constructs one more time.)

Concretely: with only ctx.header('Vary', vary), the existing runtime-tests/node case Should be compressed a fetch response fails with a 500 (TypeError: immutable). I verified this by reverting the fallback and re-running.

So the helper prefers ctx.header() and falls back to rebuilding the response around a fresh Headers instance when the write is rejected:

try {
  ctx.header('Vary', vary)
} catch {
  const headers = new Headers(ctx.res.headers)
  headers.set('Vary', vary)
  ctx.res = new Response(ctx.res.body, {
    status: ctx.res.status,
    statusText: ctx.res.statusText,
    headers,
  })
}

This looks like a latent bug in Context.header rather than something specific to compress — happy to open a separate issue/PR for it if you'd like, and drop the fallback here once it's fixed.

Tests (now 8 in the Vary Header block, plus 2 runtime tests):

• identity response with no Accept-Encoding -> Vary: Accept-Encoding
• identity response with an unsupported encoding (br) -> Vary: Accept-Encoding
• response not eligible for compression (image/png) -> no Vary
• Vary: * left unchanged
• response with immutable headers -> Vary still set (unit test, plus a real fetch() identity case in runtime-tests/node)

Verification: full suite 4625 passed | 35 skipped, plus prettier --check, eslint, and tsc -p tsconfig.spec.json clean. I also mutation-checked the two new immutable-header tests — both fail if the fallback is removed, so they're not vacuous.

[yusukebe]

Hey @usualoma

I merged the main branch to update the @hono/node-server that is applied with the patch honojs/node-server#382. So we don't need to handle the error for ctx.header('Vary', vary). I updated the code for it and added some refactoring by myself. Can you review this?