feat(cache): revalidate and serve stale responses - #19
Merged
Merged
Conversation
Owner
Author
|
@codex review, and also report simplification opportunities in the changed code as P1: logic that duplicates an existing helper, dead code, needless indirection or abstraction, and conditionals or loops with a shorter equivalent. Flag one only when the shorter version behaves the same, and show the replacement code. Do not flag style, naming or formatting. |
A stale response with an ETag or Last-Modified stays stored for up to --cache-ttl-seconds more, so the proxy can revalidate it with a conditional request. Responses with s-maxage now count as proxy-revalidate, as RFC 9111 section 5.2.2.10 requires, so they are never served stale.
jamiehdev
force-pushed
the
feat/cache-revalidation
branch
from
September 27, 2026 16:14
65af2b0 to
06c1696
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The cache now keeps stale responses that have a validator or a stale window. It revalidates them with conditional requests and no longer fetches them again in full. It honours
stale-while-revalidateandstale-if-error(RFC 5861) and never servesmust-revalidate,proxy-revalidateors-maxageresponses stale (RFC 9111 section 4.3).Changes
ETagorLast-Modified, the grace is--cache-ttl-seconds. Without one, the grace is the larger stale window, capped at the same value. The byte bound still applies.GETfor a stale response sendsIf-None-MatchandIf-Modified-Sincefrom the stored validators. A 304 updates the stored fields and freshness, and the client gets 200 with the stored body, markedX-Shadowstep-Cache: REVALIDATED.stale-while-revalidate, the client gets the stale response (STALE) and one background task per entry revalidates it. The task builds its request like a miss does.stale-if-error, a 500, 502, 503 or 504, a refused connection or a timeout gets the stale response./healthaddsrevalidations,staleandbackground_refreshes.hit_rationow counts every response whose body came from the cache.Verification
tests/integration/revalidation.rsholds 15 tests. Twelve fail onmainand pass here. Three guard behaviour thatmainalready has: eviction without a validator or stale window, an error outsidestale-if-error, andmust-revalidatewith an origin 503. The suite passed five runs in a row.Risks
Responses with
s-maxagenow carryproxy-revalidatesemantics, so their stale windows have no effect.