Update docs

Author: kornelski

Cargo.toml

@@ -29,6 +29,7 @@ with_serde = ["dep:serde", "dep:http-serde"]
 
 [package.metadata.docs.rs]
 targets = ["x86_64-unknown-linux-gnu"]
+rustdoc-args = ["--generate-link-to-definition"]
 
 [badges]
 maintenance = { status = "passively-maintained" }

README.md

@@ -1,6 +1,6 @@
 # Can I cache this?
 
-`CachePolicy` tells when responses can be reused from a cache, taking into account [HTTP RFC 7234](http://httpwg.org/specs/rfc7234.html) rules for user agents and shared caches. It's aware of many tricky details such as the `Vary` header, proxy revalidation, and authenticated responses.
+`CachePolicy` tells when responses can be reused from a cache, taking into account [HTTP RFC 7234/9111](http://httpwg.org/specs/rfc9111.html) rules for user agents and shared caches. It's aware of many tricky details such as the `Vary` header, age updates, proxy revalidation, and authenticated responses.
 
 ## Usage
 
@@ -12,57 +12,42 @@ The key method is `before_request(new_request)`, which checks whether the `new_r
 
 ### Options
 
-If `options.shared` is `true` (default), then the response is evaluated from a perspective of a shared cache (i.e. `private` is not cacheable and `s-maxage` is respected). If `options.shared` is `false`, then the response is evaluated from a perspective of a single-user cache (i.e. `private` is cacheable and `s-maxage` is ignored). `shared: true` is recommended for HTTP clients.
+If `options.shared` is `true` (default), then the response is evaluated from a perspective of a shared cache (i.e. `private` is not cacheable and `s-maxage` is respected). If `options.shared` is `false`, then the response is evaluated from a perspective of a single-user cache (i.e. `private` is cacheable and `s-maxage` is ignored). `shared: true` is recommended for HTTP proxies, and `false` for single-user clients.
 
-`options.cache_heuristic` is a fraction of response's age that is used as a fallback cache duration. The default is 0.1 (10%), e.g. if a file hasn't been modified for 100 days, it'll be cached for 100\*0.1 = 10 days.
+`options.cache_heuristic` is a fraction of response's age that is used as a fallback cache duration. The default is 0.1 (10%), e.g. if a file hasn't been modified for 100 days, it'll be cached for 100×0.1 = 10 days.
 
 `options.immutable_min_time_to_live` is a duration to assume as the default time to cache responses with `Cache-Control: immutable`. Note that [per RFC](http://httpwg.org/http-extensions/immutable.html) these can become stale, so `max-age` still overrides the default.
 
 If `options.ignore_cargo_cult` is true, common anti-cache directives will be completely ignored if the non-standard `pre-check` and `post-check` directives are present. These two useless directives are most commonly found in bad StackOverflow answers and PHP's "session limiter" defaults.
 
-### `storable()`
+### `is_storable()`
 
 Returns `true` if the response can be stored in a cache. If it's `false` then you MUST NOT store either the request or the response.
 
 ### `before_request(new_request)`
 
 This is the most important method. Use this method to check whether the cached response is still fresh in the context of the new request.
 
-If it returns `true`, then the given `request` matches the original response this cache policy has been created with, and the response can be reused without contacting the server. Note that the old response can't be returned without being updated, see `cached_response()`.
+If it returns `Fresh`, then the given `request` matches the original response this cache policy has been created with, and the response can be reused without contacting the server. This will contain an updated, filtered set of response headers to return to clients receiving the cached response. This processing is necessary, because proxies MUST always remove hop-by-hop headers (such as `TE` and `Connection`) and update response's `Age` to avoid doubling cache time.
 
-If it returns `false`, then the response may not be matching at all (e.g. it's for a different URL or method), or may require to be refreshed first (see `revalidation_request()`).
-
-### `cached_response()`
-
-Returns updated, filtered set of response headers to return to clients receiving the cached response. This function is necessary, because proxies MUST always remove hop-by-hop headers (such as `TE` and `Connection`) and update response's `Age` to avoid doubling cache time.
+If it returns `Stale`, then the response may not be matching at all (e.g. it's for a different URL or method), or may require to be refreshed first. The variant will contain HTTP headers for making a revalidation request to the server.
 
 ### `time_to_live()`
 
-Returns approximate time until the response becomes stale (i.e. not fresh).
+Returns approximate time until the response becomes stale (i.e. not fresh). This is equivalent of `max-age`, but with appropriate time correction applied.
 
-After that time (when `time_to_live() <= 0`) the response might not be usable without revalidation. However, there are exceptions, e.g. a client can explicitly allow stale responses, so always check with `before_request()`.
+After that time (when `time_to_live() == Duration::ZERO`) the response might not be usable without revalidation. However, there are exceptions, e.g. a client can explicitly allow stale responses, so always check with `before_request()`.
 
 ### Refreshing stale cache (revalidation)
 
 When a cached response has expired, it can be made fresh again by making a request to the origin server. The server may respond with status 304 (Not Modified) without sending the response body again, saving bandwidth.
 
-The following methods help perform the update efficiently and correctly.
-
-#### `revalidation_request(new_request)`
-
-Returns updated, filtered set of request headers to send to the origin server to check if the cached response can be reused. These headers allow the origin server to return status 304 indicating the response is still fresh. All headers unrelated to caching are passed through as-is.
-
-Use this method when updating cache from the origin server.
-
 #### `after_response(revalidation_request, revalidation_response)`
 
-Use this method to update the cache after receiving a new response from the origin server. It returns an object with:
-
--   `policy` — A new `CachePolicy` with HTTP headers updated from `revalidation_response`. You can always replace the old cached `CachePolicy` with the new one.
--   `modified` — Boolean indicating whether the response body has changed.
-    -   If `false`, then a valid 304 Not Modified response has been received, and you can reuse the old cached response body.
-    -   If `true`, you should use new response's body (if present), or make another request to the origin server without any conditional headers (i.e. don't use `revalidation_request()` this time) to get the new resource.
+Use this method to update the cache after receiving a new response from the origin server. It returns `Modified`/`NotModified` object with a new `CachePolicy` with HTTP headers updated from `revalidation_response`. You can always replace the old cached `CachePolicy` with the new one.
 
+    -  If `NotModified`, then a valid 304 Not Modified response has been received, and you can reuse the old cached response body.
+    -  If `Modified`, you should replace the old cached body with the new response's body.
 
 # Yo, FRESH
 

src/lib.rs

@@ -120,7 +120,7 @@ pub struct CacheOptions {
     pub shared: bool,
     /// `cache_heuristic` is a fraction of response's age that is used as a
     /// fallback cache duration. The default is 0.1 (10%), e.g. if a file
-    /// hasn't been modified for 100 days, it'll be cached for 100*0.1 = 10
+    /// hasn't been modified for 100 days, it'll be cached for 100×0.1 = 10
     /// days.
     pub cache_heuristic: f32,
     /// `immutable_min_time_to_live` is a duration to assume as the
@@ -296,11 +296,11 @@ impl CachePolicy {
     /// Returns whether the cached response is still fresh in the context of
     /// the new request.
     ///
-    /// If it returns `true`, then the given request matches the original
+    /// If it returns `Fresh`, then the given request matches the original
     /// response this cache policy has been created with, and the response can
     /// be reused without contacting the server.
     ///
-    /// If it returns `false`, then the response may not be matching at all
+    /// If it returns `Stale`, then the response may not be matching at all
     /// (e.g. it's for a different URL or method), or may require to be
     /// refreshed first. Either way, the new request's headers will have been
     /// updated for sending it to the origin server.
@@ -586,13 +586,17 @@ impl CachePolicy {
         default_min_ttl
     }
 
-    /// Returns approximate time in _milliseconds_ until the response becomes
-    /// stale (i.e. not fresh).
+    /// Returns approximate time until the response becomes
+    /// stale (i.e. not fresh). This is the correct way of getting the current `max-age` value.
     ///
-    /// After that time (when `time_to_live() <= 0`) the response might not be
+    /// After that time (when `time_to_live() == Duration::ZERO`) the response might not be
     /// usable without revalidation. However, there are exceptions, e.g. a
     /// client can explicitly allow stale responses, so always check with
     /// `before_request()`.
+    ///
+    /// If you're storing responses in a cache/database, keep them approximately for
+    /// the `time_to_live` duration plus some extra time to allow for revalidation
+    /// (an expired response is still useful).
     pub fn time_to_live(&self, now: SystemTime) -> Duration {
         self.max_age()
             .checked_sub(self.age(now))
@@ -612,6 +616,8 @@ impl CachePolicy {
     ///
     /// It returns request "parts" without a body. You can upgrade it to a full
     /// response with `Request::from_parts(parts, BYOB)` (the body is usually `()`).
+    ///
+    /// You don't need this if you use [`before_request()`]
     fn revalidation_request<Req: RequestLike>(&self, incoming_req: &Req) -> http::request::Parts {
         let mut headers = Self::copy_without_hop_by_hop_headers(incoming_req.headers());