Add stale-while-revalidate support with on_stale refresh hook

[matthutchinson]

Summary

• Add support for the Cache-Control: stale-while-revalidate=<seconds> directive so stale cache entries can still be served during a bounded grace window.
• Add a configurable :on_stale callback hook (proc.call(request:, env:, cached_response:)) that runs when a stale response is served, enabling callers to trigger asynchronous cache refreshes.
• Adds test coverage, updates docs, and provides a runnable example showing background refresh behavior.

NOTE: This change does not trigger any async fetch when a request arrives in the stale period, it only calls your own code via the on_stale hook. It is therefore up to the developer to provide their own async fetching method.

Related issue: #84

Why

Today, once a cached response becomes stale, the middleware must synchronously revalidate it before responding. That is correct for strict freshness, but it can increase latency and reduce resiliency for endpoints where slightly stale data is acceptable.

stale-while-revalidate is a standard HTTP cache directive that allows a better tradeoff:

• callers get immediate responses from cache,
• the cache can still be refreshed for subsequent requests.

See this explanation for more info, and this diagram.

This PR adds that behavior while preserving existing semantics for non-SWR responses.

---

How it works

1) Parse SWR directive

• Faraday::HttpCache::CacheControl now exposes #stale_while_revalidate.

2) Determine SWR eligibility

• Faraday::HttpCache::Response now exposes:
  • #stale_while_revalidate? → true when response is stale but still inside SWR window,
  • #stale_while_revalidate → parsed grace window in seconds.

3) Middleware request flow

• Faraday::HttpCache now accepts :on_stale (or an equivalent init block).
• In #process, behavior is now:
  • fresh entry: serve from cache (unchanged),
  • stale but SWR-eligible: serve cached response immediately, trace status as :stale, invoke on_stale callback,
  • otherwise stale: keep existing must_revalidate path (unchanged).

4) Callback contract

When serving a stale response in the SWR window, middleware invokes:

on_stale.call(request:, env:, cached_response:)

• request: Faraday::HttpCache::Request
• env: current Faraday::Env
• cached_response: Faraday::HttpCache::Response

Callback errors are rescued and logged, so they do not break response serving.

5) Instrumentation/logging

• Add :stale to cache statuses so instrumentation can distinguish SWR-served requests from fresh/valid hits.

Tests

Added/updated coverage for:

• CacheControl SWR parsing,
• response SWR eligibility logic,
• middleware stale-serve + callback invocation + callback error safety,
• behavior when SWR window has expired,
• instrumentation status reporting as :stale.

Also added test server endpoints to exercise SWR flows.

Docs and example

• Update README with:
  • SWR behavior explanation,
  • :on_stale usage and callback arguments,
  • :stale instrumentation status.
• Add runnable example: examples/stale_while_revalidate.rb demonstrating stale serving and background refresh triggering.
• Update changelog in Unreleased.

Backward compatibility

• The new :on_stale arg is optional
• Existing caching/revalidation behavior remains unchanged when stale-while-revalidate is not present.

[matthutchinson]

Hi @georgeguimaraes 👋

Curious if you've had some time to look at this PR.

I'm a staff developer at Shopify working in their Carts team, we're currently building out the UCP agentic checkout protocol (see here).

We make heavy use of this gem and would like to add an optional hook for the stale-while-revalidate directive.

This change implements the stale window calculation and triggering of a new optional block for revalidation.
The plumbing of the actual revalidate request is left to the developer to implement (see example).

Let me know if you have any questions, or if I can make any useful amendments -- Thanks!

[matthutchinson]

cc @garaujodev

[georgeguimaraes]

Thanks!! ❤️ 💚 💙 💛 💜

I'll be honest with you, when we created this gem, stale-while-revalidate was the reason since we had to implement this every time in some codebases. However, plans change :)

Thanks a lot!

[georgeguimaraes]

let me cook a new release

[matthutchinson]

Thanks @georgeguimaraes !