fix: store revalidation-only responses so etag revalidation can engage

[jeswr]

This relates to...

Discussion #4620 and PR #4624 by @steunix (this PR supersedes #4624 — full credit to @steunix for identifying the problem and taking the first pass at it; see "Relationship to #4624" below for why a fresh approach was needed).

Rationale

Responses with a validator (ETag or Last-Modified) but zero freshness lifetime — Cache-Control: no-cache or max-age=0 with no other freshness source — are never stored by the cache interceptor: determineStaleAt() returns undefined, so no entry is created, no If-None-Match is ever sent, and every request gets a full 200 from the origin. ETag + no-cache is the canonical "cache, but always validate" pattern for API servers, and RFC 9111 §3 / §5.2.2.4 explicitly allows storing these responses as long as each reuse is revalidated — undici currently gets zero 304 benefit from them.

Repro against main (Node 22), origin serving cache-control: no-cache + etag "..." (no Last-Modified):

• before: 2 requests → 2 full 200s at the origin, no conditional headers sent
• after: 2 requests → 1 full 200 + 1 conditional request answered with a 304, cached body reused

Same for cache-control: max-age=0 + etag. The already-working no-cache + Last-Modified case (stored via the heuristic-freshness branch) is unchanged, and now covered by a regression test.

Changes

Store such responses with immediate-stale semantics (three coordinated pieces in lib/handler/cache-handler.js):

1. determineStaleAt() returns 0 instead of undefined for max-age=0 / s-maxage=0 / unqualified no-cache when the response has a usable validator (isEtagUsable etag or a Last-Modified header). The new no-cache branch sits below the Last-Modified heuristic branch so it cannot shadow the existing behavior.
2. The "response is already stale" rejection in onResponseStart() is relaxed for these revalidation-only entries (zero freshness lifetime + validator) so they can actually be written to the store.
3. determineDeleteAt() retains them for a bounded 24h window: the usual revalidation buffer is proportional to the freshness lifetime, which is zero here, so the entry would otherwise be evicted immediately and never be available to revalidate. Every successful revalidation re-stores the entry, sliding the window; store-level limits (LRU / maxCount / maxSize) still apply.

The read side needs no changes: stored unqualified-no-cache entries are already forced through revalidation on every use by needsRevalidation(), and max-age=0 entries are always stale, so isStale() triggers the same conditional-request flow.

Relationship to #4624

#4624 identified exactly this problem and made determineStaleAt() return 0 for no-cache/max-age=0. Testing that diff against main showed two issues (which is why this is a fresh PR rather than a review comment):

• the entry is still rejected downstream: with staleAt = 0, now >= absoluteStaleAt is true, so onResponseStart() bails with "response is already stale" before anything is written — and even past that, determineDeleteAt() computes a delete time of staleAt + freshnessLifetime (= 0) + ≤1s padding, evicting the entry immediately (pieces 2 and 3 above address these);
• because the new no-cache → 0 branch sat above the Last-Modified heuristic branch, the currently-working no-cache + Last-Modified case stopped being cached (request pattern went from full, conditional to full, full).

Features

N/A

Bug Fixes

• Responses with Cache-Control: no-cache (unqualified) and a validator are now stored and revalidated with a conditional request on each reuse.
• Responses with Cache-Control: max-age=0 (or s-maxage=0 for shared caches) and a validator are now stored and revalidated before reuse.

Breaking Changes and Deprecations

N/A

Tests

• 3 new tests in test/interceptors/cache.js (no-cache + etag, max-age=0 + etag, and the no-cache + etag + last-modified regression guard). The first two fail on main, all three pass with this change.
• Full cache test files (test/interceptors/cache*.js, test/cache-interceptor/*): 124/124 pass.
• mnot cache-tests conformance runner (node test/cache-interceptor/cache-tests.mjs): 0 required failures before and after; the previously failing optional test cc-resp-no-cache-revalidate ("An optimal HTTP cache stores a response with Cache-Control: no-cache, but revalidates it upon use") now passes in all 4 environments (221 passed / 57 failed-optional, vs 220 / 58 on main). No test regressed.
• (Observation while verifying, left out of this PR to keep it self-contained: the cc-resp-no-cache / cc-resp-no-cache-case-insensitive skip-list entries in test/cache-interceptor/cache-tests.mjs appear stale — both pass on unmodified main when un-skipped.)

Sibling PRs from the same RFC 9111 review (each self-contained against main): #5510 (fix/cache-request-max-age-zero, the request-side max-age=0 falsy check) and #5512 (fix/cache-if-modified-since-value, validator sent on revalidation) touch the adjacent request-directive/revalidation logic; also #5511, #5513, #5514.

This change is agent-assisted (Claude Fable 5) working with @jeswr.

Status

• I have read and agreed to the Developer's Certificate of Origin
• Tested
• Benchmarked (optional)
• Documented
• Review ready
• In review
• Merge ready

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 95.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (038c4f6).

Files with missing lines	Patch %	Lines
lib/handler/cache-handler.js	95.00%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5515   +/-   ##
=======================================
  Coverage   93.44%   93.44%           
=======================================
  Files         110      110           
  Lines       37328    37363   +35     
=======================================
+ Hits        34881    34914   +33     
- Misses       2447     2449    +2     

☔ 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.