Implement Cache-Control: stale-while-revalidate

2 files changed, 30 insertions, 1 deletions

diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index ab79b24..b0628fb 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -120,6 +120,29 @@ In addition to HTTP error codes, `stale_if_error` also applies to python excepti
 [Errors and Exceptions](https://2.python-requests.org/en/master/user/quickstart/#errors-and-exceptions)
 for more details on request errors in general.
 
+(stale-while-revalidate)=
+## Asynchronous Revalidation
+You can use the `stale_while_revalidate` option to improve performance when refreshing responses.
+This will cause an expired cached response to be returned initially, while a non-blocking request is
+sent to refresh the response for the next time it's requested.
+
+```{note}
+While the corresponding response header `Cache-Control: stale-while-revalidate` only applies to
+{ref}`conditional-requests`, requests-cache extends this behavior to other refresh requests as well
+(even if a validator is not available).
+```
+
+You may either set this to `True` to do this regardless of the cached response's age:
+```python
+session = CachedSession(stale_while_revalidate=True)
+```
+
+Or specify a maximum staleness value you are willing to accept:
+```python
+# Use a cached response while revalidating, if it expired 5 minutes ago or less
+session = CachedSession(stale_while_revalidate=timedelta(minutes=5))
+```
+
 ## Removing Expired Responses
 
 ### Manual Removal
diff --git a/docs/user_guide/headers.md b/docs/user_guide/headers.md
index 0ce1ee4..3b3e8e9 100644
--- a/docs/user_guide/headers.md
+++ b/docs/user_guide/headers.md
@@ -26,6 +26,10 @@ requests-cache repo:
 True
 ```
 
+```{note}
+Also see {ref}`stale-while-revalidate` for a variation of this behavior.
+```
+
 ## Cache-Control
 `Cache-Control` **request** headers will always be used if present. This is mainly useful if you are
 adding requests-cache to an existing application or library that already sends requests with cache
@@ -62,11 +66,13 @@ The following headers are currently supported:
 - `If-Modified-Since`: Automatically added for revalidation, if `Last-Modified` is available
 
 **Response headers:**
+- `Cache-Control: immutable`: Cache the response with no expiration
 - `Cache-Control: max-age`: Used as the expiration time in seconds
 - `Cache-Control: must-revalidate`: When used in combination with `max-age=0`, revalidate immediately.
 - `Cache-Control: no-cache`: Revalidate with the server before using a cached response
 - `Cache-Control: no-store` Skip writing to the cache
-- `Cache-Control: immutable`: Cache the response with no expiration
+- `Cache-Control: stale-if-error`: Same behavior as request header
+- `Cache-Control: stale-while-revalidate`: If expired by less than this many seconds, return the stale response immediately and send an asynchronous revalidation request
 - `Expires`: Used as an absolute expiration datetime
 - `ETag`: Validator used for conditional requests
 - `Last-Modified`: Validator used for conditional requests