Repository files navigation

This library tells when responses can be reused from a cache, taking into accountHTTP RFC 7234/9111 rules for user agents and shared caches.It also implementsstale-if-error andstale-while-revalidate fromRFC 5861.It's aware of many tricky details such as theVary header, proxy revalidation, and authenticated responses.

CachePolicy is a metadata object that is meant to be stored in the cache, and it will keep track of cacheability of the response.

Cacheability of an HTTP response depends on how it was requested, so bothrequest andresponse are required to create the policy.

constpolicy=newCachePolicy(request,response,options);if(!policy.storable()){// throw the response away, it's not usable at allreturn;}// 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,body:response.body},// you only need to store the response body. CachePolicy holds the headers.policy.timeToLive());

// And later, when you receive a new request:const{ policy, body}=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.return{headers:policy.responseHeaders(),        body,}}// Cache miss. See revalidationHeaders() and revalidatedPolicy() for advanced usage.

It may be surprising, but it's not enough for an HTTP response to befresh to satisfy a request. It may need to match request headers specified inVary. Even a matching fresh response may still not be usable if the new request restricted cacheability, etc.

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

Request and response must have aheaders property with all header names in lower case.url,status andmethod are optional (defaults are any URL, status200, andGET method).

constrequest={url:'/',method:'GET',headers:{accept:'*/*',},};constresponse={status:200,headers:{'cache-control':'public, max-age=7234',},};constoptions={shared:true,cacheHeuristic:0.1,immutableMinTimeToLive:24*3600*1000,// 24hignoreCargoCult:false,};

Ifoptions.shared istrue (default), then the response is evaluated from a perspective of a shared cache (i.e.private is not cacheable ands-maxage is respected). Ifoptions.shared isfalse, then the response is evaluated from a perspective of a single-user cache (i.e.private is cacheable ands-maxage is ignored).shared: true is recommended for HTTP clients.

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 withCache-Control: immutable. Note thatper RFC these can become stale, somax-age still overrides the default.

Ifoptions.ignoreCargoCult is true, common anti-cache directives will be completely ignored if the non-standardpre-check andpost-check directives are present. These two useless directives are most commonly found in bad StackOverflow answers and PHP's "session limiter" defaults.

Returnstrue if the response can be stored in a cache. If it'sfalse then you MUST NOT store either the request or the response.

Use this method to check whether the cached response is still fresh in the context of the new request.

If it returnstrue, then the givenrequest 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, seeresponseHeaders().

If it returnsfalse, 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 (seerevalidationHeaders()).

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 asTE andConnection) and update response'sAge to avoid doubling cache time.

cachedResponse.headers=cachePolicy.responseHeaders();

Suggests a time inmilliseconds for how long this cache entry may be useful. This is not freshness, so always check withsatisfiesWithoutRevalidation(). This time may be longer than response'smax-age to allow forstale-if-error andstale-while-revalidate.

After that time (whentimeToLive() <= 0) the response may still be usable in certain cases, e.g. if client can explicitly allows stale responses.

You'll want to store theCachePolicy object along with the cached response.obj = policy.toObject() gives a plain JSON-serializable object.policy = CachePolicy.fromObject(obj) creates an instance from it.

Returns an object telling what to do next — optionalrevalidation, and optionalresponse from cache. Either one of these properties will be present. Both may be present at the same time.

{// 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},}

letcached=cacheStorage.get(incomingRequest.url);// Cache miss - make a request to the origin and cache itif(!cached){constnewResponse=awaitmakeRequest(incomingRequest);constpolicy=newCachePolicy(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 proxiesheaders:policy.responseHeaders(),body:newResponse.body,}}// There's something cached, see if it's a hitlet{ revalidation, response}=cached.policy.evaluateRequest(incomingRequest);// Revalidation always goes firstif(revalidation){// It's very important to update the request headers to make a correct revalidation requestincomingRequest.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 updateconstupdatedResponsePromise=makeRequest(incomingRequest).then(()=>{// Refresh the old response with the new information, if applicableconst{ policy, modified}=cached.policy.revalidatedPolicy(incomingRequest,newResponse);constbody=modified ?newResponse.body :cached.body;// Update the cache with the newer responseif(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 firstreturnawaitupdatedResponsePromise;}// 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,}

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.

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. Also available inevaluateRequest(newRequest).revalidation.headers.

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 newCachePolicy with HTTP headers updated fromrevalidationResponse. You can always replace the old cachedCachePolicy with the new one.
• modified — Boolean indicating whether the response body has changed, and you should use the new response body sent by the server.
  • Iftrue, you should use the new response body, and you can replace the old cached response with the updated one.
  • Iffalse, then you should reuse the old cached response body. Either a valid 304 Not Modified response has been received, or an error happened andstale-if-error allows falling back to the cache.

• ImageOptim API,make-fetch-happen,cacheable-request (got),npm/registry-fetch,etc.
• Rust version of this library.

• 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
• stale-if-error
• stale-while-revalidate

• Merging of range requests,If-Range (but correctly supports them as non-cacheable)
• Revalidation of multiple representations

Per the RFC, the cache should take into account the time between server-suppliedDate and the time it received the response. The RFC-mandated behavior creates two problems:

• Servers with incorrectly set timezone may add several hours to cache age (or more, if the clock is completely wrong).
• Even reasonably correct clocks may be off by a couple of seconds, breakingmax-age=1 trick (which is useful for reverse proxies on high-traffic servers).

Previous versions of this library had an option to ignore the server date if it was "too inaccurate". To support themax-age=1 trick the library also has to ignore dates that pretty accurate. There's no point of having an option to trust dates that are only a bit inaccurate, so this library won't trust any server dates.max-age will be interpreted from the time the response has been received, not from when it has been sent. This will affect onlyRFC 1149 networks.