{\ttfamily Cache\+Policy} tells when responses can be reused from a cache, taking into account \href{http://httpwg.org/specs/rfc7234.html}{\texttt{ HTTP RFC 7234}} rules for user agents and shared caches. It\textquotesingle{}s aware of many tricky details such as the {\ttfamily Vary} header, proxy revalidation, and authenticated responses.\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11676}{}\doxysection{Usage}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11676}
Cacheability of an HTTP response depends on how it was requested, so both {\ttfamily request} and {\ttfamily response} are required to create the policy.


\begin{DoxyCode}{0}
\DoxyCodeLine{const policy = new CachePolicy(request, response, options);}
\DoxyCodeLine{}
\DoxyCodeLine{if (!policy.storable()) \{}
\DoxyCodeLine{    // throw the response away, it's not usable at all}
\DoxyCodeLine{    return;}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// Cache the data AND the policy object in your cache}
\DoxyCodeLine{// (this is pseudocode, roll your own cache (lru-\/cache package works))}
\DoxyCodeLine{letsPretendThisIsSomeCache.set(request.url, \{policy, response\}, policy.timeToLive()); }

\end{DoxyCode}



\begin{DoxyCode}{0}
\DoxyCodeLine{// And later, when you receive a new request:}
\DoxyCodeLine{const \{policy, response\} = letsPretendThisIsSomeCache.get(newRequest.url);}
\DoxyCodeLine{}
\DoxyCodeLine{// It's not enough that it exists in the cache, it has to match the new request, too:}
\DoxyCodeLine{if (policy \&\& policy.satisfiesWithoutRevalidation(newRequest)) \{}
\DoxyCodeLine{    // OK, the previous response can be used to respond to the `newRequest`.}
\DoxyCodeLine{    // Response headers have to be updated, e.g. to add Age and remove uncacheable headers.}
\DoxyCodeLine{    response.headers = policy.responseHeaders();}
\DoxyCodeLine{    return response;}
\DoxyCodeLine{\} }

\end{DoxyCode}


It may be surprising, but it\textquotesingle{}s not enough for an HTTP response to be \href{\#yo-fresh}{\texttt{ fresh}} to satisfy a request. It may need to match request headers specified in {\ttfamily Vary}. Even a matching fresh response may still not be usable if the new request restricted cacheability, etc.

The key method is {\ttfamily satisfies\+Without\+Revalidation(new\+Request)}, which checks whether the {\ttfamily new\+Request} is compatible with the original request and whether all caching conditions are met.\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11677}{}\doxysubsection{Constructor options}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11677}
Request and response must have a {\ttfamily headers} property with all header names in lower case. {\ttfamily url}, {\ttfamily status} and {\ttfamily method} are optional (defaults are any URL, status {\ttfamily 200}, and {\ttfamily GET} method).


\begin{DoxyCode}{0}
\DoxyCodeLine{const request = \{}
\DoxyCodeLine{    url: '/',}
\DoxyCodeLine{    method: 'GET',}
\DoxyCodeLine{    headers: \{}
\DoxyCodeLine{        accept: '*/*',}
\DoxyCodeLine{    \},}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{const response = \{}
\DoxyCodeLine{    status: 200,}
\DoxyCodeLine{    headers: \{}
\DoxyCodeLine{        'cache-\/control': 'public, max-\/age=7234',}
\DoxyCodeLine{    \},}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{const options = \{}
\DoxyCodeLine{    shared: true,}
\DoxyCodeLine{    cacheHeuristic: 0.1,}
\DoxyCodeLine{    immutableMinTimeToLive: 24*3600*1000, // 24h}
\DoxyCodeLine{    ignoreCargoCult: false,}
\DoxyCodeLine{\}; }

\end{DoxyCode}


If {\ttfamily options.\+shared} is {\ttfamily true} (default), then the response is evaluated from a perspective of a shared cache (i.\+e. {\ttfamily private} is not cacheable and {\ttfamily s-\/maxage} is respected). If {\ttfamily options.\+shared} is {\ttfamily false}, then the response is evaluated from a perspective of a single-\/user cache (i.\+e. {\ttfamily private} is cacheable and {\ttfamily s-\/maxage} is ignored).

{\ttfamily options.\+cache\+Heuristic} is a fraction of response\textquotesingle{}s age that is used as a fallback cache duration. The default is 0.\+1 (10\%), e.\+g. if a file hasn\textquotesingle{}t been modified for 100 days, it\textquotesingle{}ll be cached for 100$\ast$0.1 = 10 days.

{\ttfamily options.\+immutable\+Min\+Time\+To\+Live} is a number of milliseconds to assume as the default time to cache responses with {\ttfamily Cache-\/\+Control\+: immutable}. Note that \href{http://httpwg.org/http-extensions/immutable.html}{\texttt{ per RFC}} these can become stale, so {\ttfamily max-\/age} still overrides the default.

If {\ttfamily options.\+ignore\+Cargo\+Cult} is true, common anti-\/cache directives will be completely ignored if the non-\/standard {\ttfamily pre-\/check} and {\ttfamily post-\/check} directives are present. These two useless directives are most commonly found in bad Stack\+Overflow answers and PHP\textquotesingle{}s \char`\"{}session limiter\char`\"{} defaults.\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11678}{}\doxysubsection{$<$tt$>$storable()$<$/tt$>$}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11678}
Returns {\ttfamily true} if the response can be stored in a cache. If it\textquotesingle{}s {\ttfamily false} then you MUST NOT store either the request or the response.\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11679}{}\doxysubsection{$<$tt$>$satisfies\+Without\+Revalidation(new\+Request)$<$/tt$>$}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11679}
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 {\ttfamily true}, then the given {\ttfamily 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\textquotesingle{}t be returned without being updated, see {\ttfamily response\+Headers()}.

If it returns {\ttfamily false}, then the response may not be matching at all (e.\+g. it\textquotesingle{}s for a different URL or method), or may require to be refreshed first (see {\ttfamily revalidation\+Headers()}).\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11680}{}\doxysubsection{$<$tt$>$response\+Headers()$<$/tt$>$}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11680}
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 {\ttfamily TE} and {\ttfamily Connection}) and update response\textquotesingle{}s {\ttfamily Age} to avoid doubling cache time.


\begin{DoxyCode}{0}
\DoxyCodeLine{cachedResponse.headers = cachePolicy.responseHeaders(cachedResponse); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11681}{}\doxysubsection{$<$tt$>$time\+To\+Live()$<$/tt$>$}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11681}
Returns approximate time in {\itshape milliseconds} until the response becomes stale (i.\+e. not fresh).

After that time (when {\ttfamily 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 {\ttfamily satisfies\+Without\+Revalidation()}.\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11682}{}\doxysubsection{$<$tt$>$to\+Object()$<$/tt$>$/$<$tt$>$from\+Object(json)$<$/tt$>$}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11682}
Chances are you\textquotesingle{}ll want to store the {\ttfamily Cache\+Policy} object along with the cached response. {\ttfamily obj = policy.\+to\+Object()} gives a plain JSON-\/serializable object. {\ttfamily policy = Cache\+Policy.\+from\+Object(obj)} creates an instance from it.\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11683}{}\doxysubsection{Refreshing stale cache (revalidation)}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11683}
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.\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11684}{}\doxysubsubsection{$<$tt$>$revalidation\+Headers(new\+Request)$<$/tt$>$}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11684}
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.


\begin{DoxyCode}{0}
\DoxyCodeLine{updateRequest.headers = cachePolicy.revalidationHeaders(updateRequest); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11685}{}\doxysubsubsection{$<$tt$>$revalidated\+Policy(revalidation\+Request, revalidation\+Response)$<$/tt$>$}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11685}
Use this method to update the cache after receiving a new response from the origin server. It returns an object with two keys\+:


\begin{DoxyItemize}
\item {\ttfamily policy} — A new {\ttfamily Cache\+Policy} with HTTP headers updated from {\ttfamily revalidation\+Response}. You can always replace the old cached {\ttfamily Cache\+Policy} with the new one.
\item {\ttfamily modified} — Boolean indicating whether the response body has changed.
\begin{DoxyItemize}
\item If {\ttfamily false}, then a valid 304 Not Modified response has been received, and you can reuse the old cached response body.
\item If {\ttfamily true}, you should use new response\textquotesingle{}s body (if present), or make another request to the origin server without any conditional headers (i.\+e. don\textquotesingle{}t use {\ttfamily revalidation\+Headers()} this time) to get the new resource.
\end{DoxyItemize}
\end{DoxyItemize}


\begin{DoxyCode}{0}
\DoxyCodeLine{// When serving requests from cache:}
\DoxyCodeLine{const \{oldPolicy, oldResponse\} = letsPretendThisIsSomeCache.get(newRequest.url);}
\DoxyCodeLine{}
\DoxyCodeLine{if (!oldPolicy.satisfiesWithoutRevalidation(newRequest)) \{}
\DoxyCodeLine{    // Change the request to ask the origin server if the cached response can be used}
\DoxyCodeLine{    newRequest.headers = oldPolicy.revalidationHeaders(newRequest);}
\DoxyCodeLine{}
\DoxyCodeLine{    // Send request to the origin server. The server may respond with status 304}
\DoxyCodeLine{    const newResponse = await makeRequest(newResponse);}
\DoxyCodeLine{}
\DoxyCodeLine{    // Create updated policy and combined response from the old and new data}
\DoxyCodeLine{    const \{policy, modified\} = oldPolicy.revalidatedPolicy(newRequest, newResponse);}
\DoxyCodeLine{    const response = modified ? newResponse : oldResponse;}
\DoxyCodeLine{}
\DoxyCodeLine{    // Update the cache with the newer/fresher response}
\DoxyCodeLine{    letsPretendThisIsSomeCache.set(newRequest.url, \{policy, response\}, policy.timeToLive());}
\DoxyCodeLine{}
\DoxyCodeLine{    // And proceed returning cached response as usual}
\DoxyCodeLine{    response.headers = policy.responseHeaders();}
\DoxyCodeLine{    return response;}
\DoxyCodeLine{\} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11686}{}\doxysection{Yo, FRESH}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11686}
\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11687}{}\doxysubsection{Used by}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11687}

\begin{DoxyItemize}
\item \href{https://imageoptim.com/api}{\texttt{ Image\+Optim API}}, \href{https://github.com/zkat/make-fetch-happen}{\texttt{ make-\/fetch-\/happen}}, \href{https://www.npmjs.com/package/cacheable-request}{\texttt{ cacheable-\/request}}, \href{https://github.com/npm/registry-fetch}{\texttt{ npm/registry-\/fetch}}, \href{https://github.com/pornel/http-cache-semantics/network/dependents}{\texttt{ etc.}}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11688}{}\doxysubsection{Implemented}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11688}

\begin{DoxyItemize}
\item {\ttfamily Cache-\/\+Control} response header with all the quirks.
\item {\ttfamily Expires} with check for bad clocks.
\item {\ttfamily Pragma} response header.
\item {\ttfamily Age} response header.
\item {\ttfamily Vary} response header.
\item Default cacheability of statuses and methods.
\item Requests for stale data.
\item Filtering of hop-\/by-\/hop headers.
\item Basic revalidation request
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11689}{}\doxysubsection{Unimplemented}\label{md_sfcode_node_modules_http_cache_semantics_README_autotoc_md11689}

\begin{DoxyItemize}
\item Merging of range requests, If-\/\+Range (but correctly supports them as non-\/cacheable)
\item Revalidation of multiple representations 
\end{DoxyItemize}