Parses Cache-Control and other headers. Helps building correct HTTP caches and proxies. 

Parses Cache-Control and other headers. Helps building correct HTTP caches and proxies

kornel

http-cache-semantics

const statusCodeCacheableByDefault = [200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501];

// This implementation does not understand partial responses (206)

const understoodStatuses = [200, 203, 204, 300, 301, 302, 303, 307, 308, 404, 405, 410, 414, 501];

const hopByHopHeaders = {'connection':true, 'keep-alive':true, 'proxy-authenticate':true, 'proxy-authorization':true, 'te':true, 'trailer':true, 'transfer-encoding':true, 'upgrade':true};

    // Since the old body is reused, it doesn't make sense to change properties of the body

    'content-length': true, 'content-encoding': true, 'transfer-encoding': true,

    // TODO: When there is more than one value present for a given directive (e.g., two Expires header fields, multiple Cache-Control: max-age directives),

    // the directive's value is considered invalid. Caches are encouraged to consider responses that have invalid freshness information to be stale

    const parts = header.trim().split(/\s*,\s*/); // TODO: lame parsing

        const [k,v] = part.split(/\s*=\s*/, 2);

        cc[k] = (v === undefined) ? true : v.replace(/^"|"$/g, ''); // TODO: lame unquoting

        parts.push(v === true ? k : k + '=' + v);

    constructor(req, res, {shared, cacheHeuristic, immutableMinTimeToLive, ignoreCargoCult, _fromObject} = {}) {

            this._fromObject(_fromObject);

            throw Error("Response headers missing");

        this._assertRequestHasHeaders(req);

        this._isShared = shared !== false;

        this._cacheHeuristic = undefined !== cacheHeuristic ? cacheHeuristic : 0.1; // 10% matches IE

        this._immutableMinTtl = undefined !== immutableMinTimeToLive ? immutableMinTimeToLive : 24*3600*1000;

        this._status = 'status' in res ? res.status : 200;

        this._rescc = parseCacheControl(res.headers['cache-control']);

        this._method = 'method' in req ? req.method : 'GET';

        this._noAuthorization = !req.headers.authorization;

        this._reqHeaders = res.headers.vary ? req.headers : null; // Don't keep all request headers if they won't be used

        this._reqcc = parseCacheControl(req.headers['cache-control']);

        // Assume that if someone uses legacy, non-standard uncecessary options they don't understand caching,

        // so there's no point stricly adhering to the blindly copy&pasted directives.

        if (ignoreCargoCult && "pre-check" in this._rescc && "post-check" in this._rescc) {

            delete this._rescc['pre-check'];

            delete this._rescc['post-check'];

            delete this._rescc['no-cache'];

            delete this._rescc['no-store'];

            delete this._rescc['must-revalidate'];

            this._resHeaders = Object.assign({}, this._resHeaders, {'cache-control': formatCacheControl(this._rescc)});

            delete this._resHeaders.expires;

            delete this._resHeaders.pragma;

        // When the Cache-Control header field is not present in a request, caches MUST consider the no-cache request pragma-directive

        // as having the same effect as if "Cache-Control: no-cache" were present (see Section 5.2.1).

        if (!res.headers['cache-control'] && /no-cache/.test(res.headers.pragma)) {

            this._rescc['no-cache'] = true;

        // The "no-store" request directive indicates that a cache MUST NOT store any part of either this request or any response to it.

        return !!(!this._reqcc['no-store'] &&

            // A cache MUST NOT store a response to any request, unless:

            // The request method is understood by the cache and defined as being cacheable, and

            ('GET' === this._method || 'HEAD' === this._method || ('POST' === this._method && this._hasExplicitExpiration())) &&

            // the response status code is understood by the cache, and

            understoodStatuses.includes(this._status) &&

            understoodStatuses.indexOf(this._status) !== -1 &&

            // the "no-store" cache directive does not appear in request or response header fields, and

            // the "private" response directive does not appear in the response, if the cache is shared, and

            (!this._isShared || !this._rescc.private) &&

            // the Authorization header field does not appear in the request, if the cache is shared,

            (!this._isShared || this._noAuthorization || this._allowsStoringAuthenticated()) &&

                // contains an Expires header field, or

                this._resHeaders.expires ||

                // contains a max-age response directive, or

                // contains a s-maxage response directive and the cache is shared, or

                // contains a public response directive.

                this._rescc.public || this._rescc['max-age'] || this._rescc['s-maxage'] ||

                // has a status code that is defined as cacheable by default

                statusCodeCacheableByDefault.includes(this._status)

                statusCodeCacheableByDefault.indexOf(this._status) !== -1

        // 4.2.1 Calculating Freshness Lifetime

        return (this._isShared && this._rescc['s-maxage']) ||

            throw Error("Request headers missing");

        // When presented with a request, a cache MUST NOT reuse a stored response, unless:

        // the presented request does not contain the no-cache pragma (Section 5.4), nor the no-cache cache directive,

        // unless the stored response is successfully validated (Section 4.3), and

        const requestCC = parseCacheControl(req.headers['cache-control']);

        if (requestCC['no-cache'] || /no-cache/.test(req.headers.pragma)) {

        if (requestCC['max-age'] && this.age() > requestCC['max-age']) {

        if (requestCC['min-fresh'] && this.timeToLive() < 1000*requestCC['min-fresh']) {

        // the stored response is either:

        // fresh, or allowed to be served stale

            const allowsStale = requestCC['max-stale'] && !this._rescc['must-revalidate'] && (true === requestCC['max-stale'] || requestCC['max-stale'] > this.age() - this.maxAge());

        return this._requestMatches(req, false);

    _requestMatches(req, allowHeadMethod) {

        // The presented effective request URI and that of the stored response match, and

        return (!this._url || this._url === req.url) &&

            (this._host === req.headers.host) &&

            // the request method associated with the stored response allows it to be used for the presented request, and

            (!req.method || this._method === req.method || (allowHeadMethod && 'HEAD' === req.method)) &&

            // selecting header fields nominated by the stored response (if any) match those presented, and

        //  following Cache-Control response directives (Section 5.2.2) have such an effect: must-revalidate, public, and s-maxage.

        return this._rescc['must-revalidate'] || this._rescc.public || this._rescc['s-maxage'];

        // A Vary header field-value of "*" always fails to match

        if (this._resHeaders.vary === '*') {

        const fields = this._resHeaders.vary.trim().toLowerCase().split(/\s*,\s*/);

            if (req.headers[name] !== this._reqHeaders[name]) return false;

    _copyWithoutHopByHopHeaders(inHeaders) {

            if (hopByHopHeaders[name]) continue;

            headers[name] = inHeaders[name];

            const tokens = inHeaders.connection.trim().split(/\s*,\s*/);

            const warnings = headers.warning.split(/,/).filter(warning => {

                return !/^\s*1[0-9][0-9]/.test(warning);

                headers.warning = warnings.join(',').trim();

  "description": "Parses Cache-Control and other headers. Helps building correct HTTP caches and proxies",

  "repository": "https://github.com/pornel/http-cache-semantics.git",

    "compile": "babel -d node4/ index.js; babel -d node4/test test",

    "test": "npm run compile; mocha node4/test"

  "author": "Kornel Lesiński <kornel@geekhood.net> (https://kornel.ski/)",

# Can I cache this? [![Build Status](https://travis-ci.org/pornel/http-cache-semantics.svg?branch=master)](https://travis-ci.org/pornel/http-cache-semantics)

`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.

Cacheability of an HTTP response depends on how it was requested, so both `request` and `response` are required to create the policy.

const policy = new CachePolicy(request, response, options);

    // throw the response away, it's not usable at all

// Cache the data AND the policy object in your cache

// (this is pseudocode, roll your own cache (lru-cache package works))

letsPretendThisIsSomeCache.set(request.url, {policy, response}, policy.timeToLive());

// And later, when you receive a new request:

const {policy, response} = letsPretendThisIsSomeCache.get(newRequest.url);

// It's not enough that it exists in the cache, it has to match the new request, too:

if (policy && policy.satisfiesWithoutRevalidation(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();

It may be surprising, but it's not enough for an HTTP response to be [fresh](#yo-fresh) to satisfy a request. It may need to match request headers specified in `Vary`. Even a matching fresh response may still not be usable if the new request restricted cacheability, etc.

The key method is `satisfiesWithoutRevalidation(newRequest)`, which checks whether the `newRequest` is compatible with the original request and whether all caching conditions are met.

Request and response must have a `headers` property with all header names in lower case. `url`, `status` and `method` are optional (defaults are any URL, status `200`, and `GET` method).

        'cache-control': 'public, max-age=7234',

    immutableMinTimeToLive: 24*3600*1000, // 24h

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).

`options.cacheHeuristic` 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.immutableMinTimeToLive` is a number of milliseconds 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.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.

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.

### `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.

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()`.

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 `revalidationHeaders()`).

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.

cachedResponse.headers = cachePolicy.responseHeaders(cachedResponse);

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()`.

		{
		"name": "http-cache-semantics",
		"version": "3.7.1",
		"version": "3.7.3",
		"description": "Parses Cache-Control and other headers. Helps building correct HTTP caches and proxies",
		"main": "index.js",
		"repository": "https://github.com/pornel/http-cache-semantics.git",
		"main": "node4/index.js",
		"scripts": {
		"test": "mocha"
		"compile": "babel -d node4/ index.js; babel -d node4/test test",
		"prepublish": "npm run compile",
		"test": "npm run compile; mocha node4/test"
		},
		"files": [
		"node4/index.js",
		"index.js",
		@@ -17,4 +20,6 @@ "test"
		"devDependencies": {
		"babel-cli": "^6.24.0",
		"babel-preset-env": "^1.3.2",
		"mocha": "^3.2.0"
		}
		}

Improved metrics

Worsened metrics

		@@ -100,3 +100,3 @@ 'use strict';
		// the response status code is understood by the cache, and
		understoodStatuses.includes(this._status) &&
		understoodStatuses.indexOf(this._status) !== -1 &&
		// the "no-store" cache directive does not appear in request or response header fields, and
		@@ -117,3 +117,3 @@ !this._rescc['no-store'] &&
		// has a status code that is defined as cacheable by default
		statusCodeCacheableByDefault.includes(this._status)
		statusCodeCacheableByDefault.indexOf(this._status) !== -1
		));
		@@ -120,0 +120,0 @@ }

		@@ -1,2 +0,2 @@
		# Can I cache this?
		# Can I cache this? [![Build Status](https://travis-ci.org/pornel/http-cache-semantics.svg?branch=master)](https://travis-ci.org/pornel/http-cache-semantics)

		@@ -3,0 +3,0 @@ `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.