http-cache-semantics - npm Package Compare versions

Comparing version 3.4.0 to 3.5.0

index.js

@@ -123,7 +123,11 @@ 'use strict';
 
-    satisfiesWithoutRevalidation(req) {
+    _assertRequestHasHeaders(req) {
         if (!req || !req.headers) {
             throw Error("Request headers missing");
         }
+    }
 
+    satisfiesWithoutRevalidation(req) {
+        this._assertRequestHasHeaders(req);
+
         // When presented with a request, a cache MUST NOT reuse a stored response, unless:
@@ -154,2 +158,6 @@ // the presented request does not contain the no-cache pragma (Section 5.4), nor the no-cache cache directive,
 
+        return this._requestMatches(req, false);
+    }
+
+    _requestMatches(req, allowHeadMethod) {
         // The presented effective request URI and that of the stored response match, and
@@ -159,3 +167,3 @@ return (!this._url || this._url === req.url) &&
             // the request method associated with the stored response allows it to be used for the presented request, and
-            (!req.method || this._method === req.method) &&
+            (!req.method || this._method === req.method || (allowHeadMethod && 'HEAD' === req.method)) &&
             // selecting header fields nominated by the stored response (if any) match those presented, and
@@ -345,2 +353,27 @@ this._varyMatches(req);
     }
+
+    revalidationHeaders(incoming_req) {
+        this._assertRequestHasHeaders(incoming_req);
+        if (!this._resHeaders.etag && !this._resHeaders['last-modified']) {
+            return incoming_req.headers; // no validators available
+        }
+        // revalidation allowed via HEAD
+        if (!this._requestMatches(incoming_req, true)) {
+            return incoming_req.headers; // not for the same resource
+        }
+
+        const headers = Object.assign({}, incoming_req.headers);
+
+        /* MUST send that entity-tag in any cache validation request (using If-Match or If-None-Match) if an entity-tag has been provided by the origin server. */
+        if (this._resHeaders.etag) {
+            headers['if-none-match'] = this._resHeaders.etag;
+        }
+        /* SHOULD send the Last-Modified value in non-subrange cache validation requests (using If-Modified-Since) if only a Last-Modified value has been provided by the origin server.
+        Note: This implementation does not understand partial responses (206) */
+        if (this._resHeaders['last-modified'] && this.storable()) {
+            headers['if-modified-since'] = this._resHeaders['last-modified'];
+        }
+
+        return headers;
+    }
 };

package.json

 {
   "name": "http-cache-semantics",
-  "version": "3.4.0",
-  "description": "Parses Cache-Control headers and friends",
+  "version": "3.5.0",
+  "description": "Parses Cache-Control and other headers. Helps building correct HTTP caches and proxies",
   "main": "index.js",
@@ -10,7 +10,11 @@ "repository": "https://github.com/pornel/http-cache-semantics.git",
   },
+  "files": [
+    "index.js",
+    "test"
+  ],
   "author": "Kornel Lesiński <[e-mail]> (https://kornel.ski/)",
   "license": "BSD-2-Clause",
   "devDependencies": {
-    "mocha": "^2.4.5"
+    "mocha": "^3.2.0"
   }
 }

README.md

 # Can I cache this?
 
-`CachePolicy` can tell when responses can be reused from 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](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.
 
@@ -28,3 +28,5 @@ ## Usage
 if (policy && policy.satisfiesWithoutRevalidation(newRequest)) {
-    // OK, the previous `response` can be used to respond to the `newRequest`
+    // OK, the previous response can be used to respond to the `newRequest`.
+    // Response headers have to be updated, e.g. to add Age and remove uncacheable headers.
+    response.headers = policy.responseHeaders();
     return response;
@@ -61,2 +63,3 @@ }
     cacheHeuristic: 0.1,
+    ignoreCargoCult: false,
 };
@@ -69,3 +72,3 @@ ```
 
-If `options.ignoreCargoCult` is true, common anti-cache directives will be completely ignored if the `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.
+If `options.ignoreCargoCult` 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.
 
@@ -76,4 +79,6 @@ ### `storable()`
 
-### `satisfiesWithoutRevalidation(request)`
+### `satisfiesWithoutRevalidation(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 `responseHeaders()`.
@@ -85,14 +90,14 @@
 
-Returns updated, filtered set of response headers. Proxies MUST always remove hop-by-hop headers (such as `TE` and `Connection`) and update response age to avoid doubling cache time.
+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 `Age` to avoid doubling cache time.
 
-### `stale()`
+### `revalidationHeaders()`
 
-Returns `true` if the response is stale (i.e. not fresh).
+Returns updated, filtered set of request headers to send to the origin server to check if the cached response can be reused. With this set of headers, the origin server may return status 304 indicating the response is still fresh.
 
-It generally means the response can't be used any more without revalidation with the server. However, there are exceptions, e.g. a client can explicitly allow stale responses.
-
 ### `timeToLive()`
 
-Returns number of *milliseconds* until the response becomes stale. After that time (when `timeToLive() <= 0`) the response won't be usable without revalidation.
+Returns approximate time in *milliseconds* until the response becomes stale (i.e. not fresh).
 
+After that time (when `timeToLive() <= 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 `satisfiesWithoutRevalidation()`.
+
 ### `toObject()`/`fromObject(json)`
@@ -108,11 +113,15 @@
 
-* `Expires` with check for bad clocks
-* `Cache-Control` response header
-* `Pragma` response header
-* `Age` response header
-* `Vary` response header
-* Default cacheability of statuses and methods
+* `Cache-Control` response header with all the quirks.
+* `Expires` with check for bad clocks.
+* `Pragma` response header.
+* `Age` response header.
+* `Vary` response header.
+* Default cacheability of statuses and methods.
+* Requests for stale data.
+* Filtering of hop-by-hop headers.
+* Basic revalidation request
 
 ## Unimplemented
 
-* No support for revalidation
+* Revalidation of multiple representations
+* Updating of response after revalidation

test/ok.js

@@ -65,2 +65,3 @@ 'use strict';
     assertCached(false, 418);
+    assertCached(false, 429);
 
@@ -67,0 +68,0 @@ assertCached(false, 500);

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Lines of code

1098

increased by9.91%

Number of lines in readme file

122

increased by7.96%

Worsened metrics

Total package byte prevSize

54708

decreased by-38.25%

Number of package files

9

decreased by-10%

No dependency changes