Stale cache response without background revalidation in HttpClient Cache plugin

Support for stale-while-revalidate

The Ktor HttpClient Cache plugin does not natively support the stale-while-revalidate directive for automatic background refreshing. In Ktor 2.x and 3.x, the plugin follows a synchronous revalidation flow: if a cached response is stale (exceeds max-age), the client performs a conditional request using If-None-Match or If-Modified-Since before returning the response to the application.

Implementation Gap

While the plugin respects basic RFC 7234 expiration logic, it lacks the asynchronous dispatcher required to serve a stale response immediately while simultaneously triggering a network request to update the cache in the background. Consequently, the stale-while-revalidate header is effectively ignored by the default plugin implementation.

Extending CacheStorage for Asynchronous Refresh

Because the HttpCache plugin is designed around a request-response pipeline, implementing background revalidation requires moving the refresh logic outside the primary request flow. You can achieve this by implementing a custom CacheStorage or wrapping the client.

To implement this behavior, follow these steps:

1. Custom Storage Wrapper: Create a wrapper around your CacheStorage implementation that intercepts store and find calls.
2. Stale Detection: When find returns a response that is stale but within the stale-while-revalidate window, return the cached response immediately to the caller.
3. Async Trigger: Launch a separate coroutine (using a dedicated CoroutineScope) to perform a fresh httpClient.get() for that specific URI.
4. Concurrency Control: Use a Mutex or a map of active refreshes to ensure that multiple simultaneous requests for the same stale resource do not trigger redundant background network calls.

Verification

To verify if your implementation (or a specific Ktor version) is performing background revalidation, use a network proxy (e.g., Charles or Fiddler):

• Blocking (Default): The request is sent $ ightarrow$ the server responds (or 304) $ ightarrow$ the client receives the data.
• Background (Custom): The client receives the cached data immediately $ ightarrow$ a separate network request is observed shortly after.

Diagnostic Detail Needed: Are you using a custom CacheStorage implementation, or the default in-memory storage? The approach to intercepting the stale window differs depending on where the storage logic resides.