Simplify evaluateRequest API

Author: kornelski

README.md

@@ -1,4 +1,4 @@
-# Can I cache this? [![Build Status](https://travis-ci.org/kornelski/http-cache-semantics.svg?branch=master)](https://travis-ci.org/kornelski/http-cache-semantics)
+# Can I cache this?
 
 This library 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 also implements `stale-if-error` and `stale-while-revalidate` from [RFC 5861](https://tools.ietf.org/html/rfc5861).
@@ -90,7 +90,7 @@ Returns `true` if the response can be stored in a cache. If it's `false` then yo
 
 ### `satisfiesWithoutRevalidation(newRequest)`
 
-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.
+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 `responseHeaders()`.
 
@@ -112,7 +112,98 @@ After that time (when `timeToLive() <= 0`) the response may still be usable in c
 
 ### `toObject()`/`fromObject(json)`
 
-Chances are you'll want to store the `CachePolicy` object along with the cached response. `obj = policy.toObject()` gives a plain JSON-serializable object. `policy = CachePolicy.fromObject(obj)` creates an instance from it.
+You'll want to store the `CachePolicy` object along with the cached response. `obj = policy.toObject()` gives a plain JSON-serializable object. `policy = CachePolicy.fromObject(obj)` creates an instance from it.
+
+## Complete Usage
+
+### `evaluateRequest(newRequest)`
+
+Returns an object telling what to do next — optional `revalidation`, and optional `response` from cache. Either one of these properties will be present. Both may be present at the same time.
+
+```js
+{
+    // If defined, you must send a request to the server.
+    revalidation: {
+        headers: {}, // HTTP headers to use when sending the revalidation response
+        // If true, you MUST wait for a response from the server before using the cache
+        // If false, this is stale-while-revalidate. The cache is stale, but you can use it while you update it asynchronously.
+        synchronous: bool,
+    },
+    // If defined, you can use this cached response.
+    response: {
+        headers: {}, // Updated cached HTTP headers you must use when responding to the client
+    },
+}
+```
+
+### Example
+
+```js
+let cached = cacheStorage.get(incomingRequest.url);
+
+// Cache miss - make a request to the origin and cache it
+if (!cached) {
+    const newResponse = await makeRequest(incomingRequest);
+    const policy = new CachePolicy(incomingRequest, newResponse);
+
+    cacheStorage.set(
+        incomingRequest.url,
+        { policy, body: newResponse.body },
+        policy.timeToLive()
+    );
+
+    return {
+        // use responseHeaders() to remove hop-by-hop headers that should not be passed through proxies
+        headers: policy.responseHeaders(),
+        body: newResponse.body,
+    }
+}
+
+// There's something cached, see if it's a hit
+let { revalidation, response } = cached.policy.evaluateRequest(incomingRequest);
+
+// Revalidation always goes first
+if (revalidation) {
+    // It's very important to update the request headers to make a correct revalidation request
+    incomingRequest.headers = revalidation.headers; // Same as cached.policy.revalidationHeaders()
+
+    // The cache may be updated immediately or in the background,
+    // so use a Promise to optionally defer the update
+    const updatedResponsePromise = makeRequest(incomingRequest).then(() => {
+        // Refresh the old response with the new information, if applicable
+        const { policy, modified } = cached.policy.revalidatedPolicy(incomingRequest, newResponse);
+
+        const body = modified ? newResponse.body : cached.body;
+
+        // Update the cache with the newer response
+        if (policy.storable()) {
+            cacheStorage.set(
+                incomingRequest.url,
+                { policy, body },
+                policy.timeToLive()
+            );
+        }
+
+        return {
+            headers: policy.responseHeaders(), // these are from the new revalidated policy
+            body,
+        }
+    });
+
+    if (revalidation.synchronous) {
+        // If synchronous, then you MUST get a reply from the server first
+        return await updatedResponsePromise;
+    }
+
+    // If not synchronous, it can fall thru to returning the cached response,
+    // while the request to the server is happening in the background.
+}
+
+return {
+    headers: response.headers, // Same as cached.policy.responseHeaders()
+    body: cached.body,
+}
+```
 
 ### Refreshing stale cache (revalidation)
 
@@ -124,7 +215,7 @@ The following methods help perform the update efficiently and correctly.
 
 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.
+Use this method when updating cache from the origin server. Also available in `evaluateRequest(newRequest).revalidation.headers`.
 
 ```js
 updateRequest.headers = cachePolicy.revalidationHeaders(updateRequest);
@@ -135,45 +226,9 @@ updateRequest.headers = cachePolicy.revalidationHeaders(updateRequest);
 Use this method to update the cache after receiving a new response from the origin server. It returns an object with two keys:
 
 -   `policy` — A new `CachePolicy` with HTTP headers updated from `revalidationResponse`. 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. This is also affected by `stale-if-error`.
-    -   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 `revalidationHeaders()` this time) to get the new resource.
--   `headers`  — updated response headers to use when returning the response to the client.
-
-```js
-// When serving requests from cache:
-const { cachedPolicy, cachedBody } = letsPretendThisIsSomeCache.get(
-    newRequest.url
-);
-
-if (!cachedPolicy.satisfiesWithoutRevalidation(newRequest)) {
-    // Change the request to ask the origin server if the cached response can be used
-    newRequest.headers = cachedPolicy.revalidationHeaders(newRequest);
-
-    // Send request to the origin server. The server may respond with status 304
-    const newResponse = await makeRequest(newRequest);
-
-    // Create updated policy and combined response from the old and new data
-    const { policy, modified } = cachedPolicy.revalidatedPolicy(
-        newRequest,
-        newResponse
-    );
-    const body = modified ? newResponse.body : oldBody;
-
-    // Update the cache with the newer/fresher response
-    letsPretendThisIsSomeCache.set(
-        newRequest.url,
-        { policy, body },
-        policy.timeToLive()
-    );
-
-    // Make a new response from the cached or revalidated data
-    return {
-        headers: policy.responseHeaders()
-        body,
-    }
-}
-```
+-   `modified` — Boolean indicating whether the response body has changed, and you should use the new response body sent by the server.
+    -   If `true`, you should use the new response body, and you can replace the old cached response with the updated one.
+    -   If `false`, then you should reuse the old cached response body. Either a valid 304 Not Modified response has been received, or an error happened and `stale-if-error` allows falling back to the cache.
 
 # Yo, FRESH
 
@@ -182,6 +237,7 @@ if (!cachedPolicy.satisfiesWithoutRevalidation(newRequest)) {
 ## Used by
 
 -   [ImageOptim API](https://imageoptim.com/api), [make-fetch-happen](https://github.com/zkat/make-fetch-happen), [cacheable-request](https://www.npmjs.com/package/cacheable-request) ([got](https://www.npmjs.com/package/got)), [npm/registry-fetch](https://github.com/npm/registry-fetch), [etc.](https://github.com/kornelski/http-cache-semantics/network/dependents)
+-   [Rust version of this library](https://lib.rs/crates/http-cache-semantics).
 
 ## Implemented
 
@@ -195,6 +251,7 @@ if (!cachedPolicy.satisfiesWithoutRevalidation(newRequest)) {
 -   Filtering of hop-by-hop headers.
 -   Basic revalidation request
 -   `stale-if-error`
+-   `stale-while-revalidate`
 
 ## Unimplemented
 

index.js

@@ -224,46 +224,69 @@ module.exports = class CachePolicy {
         }
     }
 
+    /**
+     * Checks if the request matches the cache and can be satisfied from the cache immediately,
+     * without having to make a request to the server.
+     *
+     * This doesn't support `stale-while-revalidate`. See `evaluateRequest()` for a more complete solution.
+     */
     satisfiesWithoutRevalidation(req) {
         const result = this.evaluateRequest(req)
         return !result.revalidation;
     }
 
-    _evaluateRequestHitResult(stale = false, revalidation = undefined) {
+    _evaluateRequestHitResult(revalidation) {
         return {
             response: {
                 headers: this.responseHeaders(),
-                stale,
             },
             revalidation,
         }
     }
 
-    _evaluateRequestRevalidation(request, synchronous= true) {
+    _evaluateRequestRevalidation(request, synchronous) {
         return {
             synchronous,
-            request: {
-                headers: this.revalidationHeaders(request),
-            },
+            headers: this.revalidationHeaders(request),
         };
     }
 
     _evaluateRequestMissResult(request) {
         return {
-            revalidation: this._evaluateRequestRevalidation(request),
+            response: undefined,
+            revalidation: this._evaluateRequestRevalidation(request, true),
         }
     }
 
+    /**
+     * Checks if the given request matches this cache entry, and how the cache can be used to satisfy it. Returns an object with:
+     *
+     * ```
+     * {
+     *     // If defined, you must send a request to the server.
+     *     revalidation: {
+     *         headers: {}, // HTTP headers to use when sending the revalidation response
+     *         // If true, you MUST wait for a response from the server before using the cache
+     *         // If false, this is stale-while-revalidate. The cache is stale, but you can use it while you update it asynchronously.
+     *         synchronous: bool,
+     *     },
+     *     // If defined, you can use this cached response.
+     *     response: {
+     *         headers: {}, // Updated cached HTTP headers you must use when responding to the client
+     *     },
+     * }
+     * ```
+     */
     evaluateRequest(req) {
         this._assertRequestHasHeaders(req);
 
         // In all circumstances, a cache MUST NOT ignore the must-revalidate directive
         if (this._rescc['must-revalidate']) {
-            return false;
+            return this._evaluateRequestMissResult(req);
         }
 
         if (!this._requestMatches(req, false)) {
-            return false;
+            return this._evaluateRequestMissResult(req);
         }
 
         // When presented with a request, a cache MUST NOT reuse a stored response, unless:
@@ -285,27 +308,24 @@ module.exports = class CachePolicy {
 
         // the stored response is either:
         // fresh, or allowed to be served stale
-        let revalidation;
-        const stale = this.stale();
-        if (stale) {
-            let allowsStale = false;
-            if (requestCC['max-stale'] && !this._rescc['must-revalidate']) {
-                if (requestCC['max-stale'] === true || requestCC['max-stale'] > this.age() - this.maxAge()) {
-                    allowsStale = true;
-                }
-            // Allow stale-while-revalidate queries to be served stale
-            // even if must-revalidate is set as the revalidation should be happening in the background
-            } else if (this.useStaleWhileRevalidate()) {
-                revalidation = this._evaluateRequestRevalidation(req, false);
-                allowsStale = true;
+        if (this.stale()) {
+            // If a value is present, then the client is willing to accept a response that has
+            // exceeded its freshness lifetime by no more than the specified number of seconds
+            const allowsStaleWithoutRevalidation = 'max-stale' in requestCC &&
+                (true === requestCC['max-stale'] || requestCC['max-stale'] > this.age() - this.maxAge());
+
+            if (allowsStaleWithoutRevalidation) {
+                return this._evaluateRequestHitResult(undefined);
             }
 
-            if (!allowsStale) {
-                return this._evaluateRequestMissResult(req);
+            if (this.useStaleWhileRevalidate()) {
+                return this._evaluateRequestHitResult(this._evaluateRequestRevalidation(req, false));
             }
+
+            return this._evaluateRequestMissResult(req);
         }
 
-        return this._evaluateRequestHitResult(stale, revalidation);
+        return this._evaluateRequestHitResult(undefined);
     }
 
     _requestMatches(req, allowHeadMethod) {
@@ -507,6 +527,10 @@ module.exports = class CachePolicy {
         return Math.round(Math.max(0, age, staleIfErrorAge, staleWhileRevalidateAge) * 1000);
     }
 
+    /**
+     * If true, this cache entry is past its expiration date.
+     * Note that stale cache may be useful sometimes, see `evaluateRequest()`.
+     */
     stale() {
         return this.maxAge() <= this.age();
     }
@@ -515,6 +539,7 @@ module.exports = class CachePolicy {
         return this.maxAge() + toNumberOrZero(this._rescc['stale-if-error']) > this.age();
     }
 
+    /** See `evaluateRequest()` for a more complete solution */
     useStaleWhileRevalidate() {
         const swr = toNumberOrZero(this._rescc['stale-while-revalidate']);
         return swr > 0 && this.maxAge() + swr > this.age();