fix: implement proper stale-while-revalidate behavior per RFC 5861 #4492
Conversation
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
The stale-while-revalidate cache directive was not working as intended. Instead of returning stale content immediately and revalidating in the background, it was performing synchronous revalidation, defeating the primary purpose of reducing latency. This fix: - Returns stale content immediately when within the stale-while-revalidate window - Performs background revalidation asynchronously to update the cache - Updates tests to reflect the correct RFC 5861 behavior Fixes #4471 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matteo Collina <hello@matteocollina.com>
Replace manual Promise creation with setTimeout from timers/promises for cleaner and more idiomatic async delays in tests. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matteo Collina <hello@matteocollina.com>
…lidation setImmediate doesn't work properly with fake timers in tests, causing background revalidation to not trigger. process.nextTick works correctly with both real time and fake timers. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matteo Collina <hello@matteocollina.com>
Uzlopak
reviewed
Aug 31, 2025
ShogunPanda
approved these changes
Sep 1, 2025
Co-authored-by: Aras Abbasi <aras.abbasi@googlemail.com>
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.
Summary
This PR fixes the
stale-while-revalidatecache directive implementation to comply with RFC 5861. Previously, it was performing synchronous revalidation, which defeated the primary purpose of reducing latency.Fixes #4471
Changes
withinStaleWhileRevalidateWindow()helper function determines if a stale response is within the revalidate windowsetImmediate()Test Plan
stale-while-revalidate returns stale immediately and revalidates in background (RFC 5861)stale-while-revalidate updates cache after background revalidationBehavior Before/After
Before
When a cached response was stale but within the
stale-while-revalidatewindow:After
When a cached response is stale but within the
stale-while-revalidatewindow:RFC Compliance
This implementation follows RFC 5861 Section 3 which states:
🤖 Generated with Claude Code