CacheControl
The Cache-Control HTTP header field holds directives (instructions) — in both requests and responses — that control caching in browsers and shared caches (e.g. Proxies, CDNs).
§Properties
The immutable response directive indicates that the response will not be updated while it's fresh.
Cache-Control: public, max-age=604800, immutable
A modern best practice for static resources is to include version/hashes in their URLs, while never modifying the resources — but instead, when necessary, updating the resources with newer versions that have new version-numbers/hashes, so that their URLs are different. That’s called the cache-busting pattern.
<script src=https://example.com/react.0.0.0.js></script>
When a user reloads the browser, the browser will send conditional requests for validating to the origin server. But it's not necessary to revalidate those kinds of static resources even when a user reloads the browser, because they're never modified. immutable tells a cache that the response is immutable while it's fresh, and avoids those kinds of unnecessary conditional requests to the server.
When you use a cache-busting pattern for resources and apply them to a long max-age, you can also add immutable to avoid revalidation.
The max-age=N response directive indicates that the response remains fresh until N seconds after the response is generated.
Cache-Control: max-age=604800
Indicates that caches can store this response and reuse it for subsequent requests while it's fresh.
Note that max-age is not the elapsed time since the response was received, but instead the elapsed time since the response was generated on the origin server. So if the other cache(s) on the path the response takes store it for 100 seconds (indicated using the Age response header field), the browser cache would deduct 100 seconds from its freshness lifetime.
Cache-Control: max-age=604800
Age: 100
The max-stale=N request directive indicates that the client allows a stored response that is stale within N seconds.
Cache-Control: max-stale=3600
In the case above, if the response with Cache-Control: max-age=604800 was stored on caches 3 hours ago, the cache couldn't reuse that response.
Clients can use this header when the origin server is down or too slow and can accept cached responses from caches even if they are a bit old.
Note that the major browsers do not support requests with max-stale.
The max-stale=N request directive indicates that the client allows a stored response that is stale within N seconds.
Cache-Control: max-stale=3600
In the case above, if the response with Cache-Control: max-age=604800 was stored on caches 3 hours ago, the cache couldn't reuse that response.
Clients can use this header when the origin server is down or too slow and can accept cached responses from caches even if they are a bit old.
Note that the major browsers do not support requests with max-stale.
The min-fresh=N request directive indicates that the client allows a stored response that is fresh for at least N seconds.
Cache-Control: min-fresh=600
In the case above, if the response with Cache-Control: max-age=3600 was stored in caches 51 minutes ago, the cache couldn't reuse that response.
Clients can use this header when the user requires the response to not only be fresh, but also requires that it won't be updated for a period of time.
Note that the major browsers do not support requests with min-fresh.
The must-revalidate response directive indicates that the response can be stored in caches and can be reused while fresh. Once it becomes stale, it must be validated with the origin server before reuse.
Typically, must-revalidate is used with max-age.
Cache-Control: max-age=604800, must-revalidate
HTTP allows caches to reuse stale responses when they are disconnected from the origin server. must-revalidate is a way to prevent that, so that the cache either revalidates the stored response with the origin server, or if that's not possible it generates a 504 (Gateway Timeout) response.
The no-cache response directive indicates that the response can be stored in caches, but must be validated with the origin server before each reuse — even when the cache is disconnected from the origin server.
Cache-Control: no-cache
If you want caches to always check for content updates while reusing stored content when it hasn't changed, no-cache is the directive to use. It does this by requiring caches to revalidate each request with the origin server.
Note that no-cache does not mean "don't cache". no-cache allows caches to store a response, but requires them to revalidate it before reuse. If the sense of "don't cache" that you want is actually "don't store", then no-store is the directive to use.
The no-store response directive indicates that any caches of any kind (private or shared) should not store this response.
Cache-Control: no-store
Some intermediaries transform content for various reasons. For example, some convert images to reduce transfer size. In some cases, this is undesirable for the content provider.
No-transform indicates that any intermediary (regardless of whether it implements a cache) shouldn't transform the response contents.
The client indicates that cache should obtain an already-cached response. If a cache has stored a response, it’s reused.
The private response directive indicates that the response can be stored only in a private cache (e.g. local caches in browsers).
Cache-Control: private
You should add the private directive for user-personalized content — in particular, responses received after login, and sessions managed via cookies.
If you forget to add private to a response with personalized content, then that response can be stored in a shared cache and end up being used by multiple users, which can cause personal information to leak.
The proxy-revalidate response directive is the equivalent of must-revalidate, but specifically for shared caches only.
Responses for requests with Authorization header fields must not be stored in a shared cache. But the public directive will cause such responses to be stored in a shared cache.
Cache-Control: public
In general, when pages are under Basic Auth or Digest Auth, the browser sends requests with the Authorization header. That means the response is access-controlled for restricted users (who have accounts), and it's fundamentally not shared-cacheable, even if it has max-age.
You can use the public directive to unlock that restriction.
Cache-Control: public, max-age=604800
Note that, s-maxage or must-revalidate also unlock that restriction.
If a request doesn’t have an Authorization header, or you are already using s-maxage or must-revalidate in the response, then you don't need to use public.
The stale-if-error response directive indicates that the cache can reuse a stale response when an origin server responds with an error (500, 502, 503, or 504).
Cache-Control: max-age=604800, stale-if-error=86400
In the example above, the response is fresh for 7 days (604800s). After 7 days it becomes stale, but it can be used for an extra 1 day (86400s) if the server responds with an error.
After a period of time, the stored response became stale normally. That means the client will receive an error response as-is if the origin server sends it.
The stale-while-revalidate response directive indicates that the cache could reuse a stale response while it revalidates it to a cache.
Cache-Control: max-age=604800, stale-while-revalidate=86400
In the example above, the response is fresh for 7 days (604800s). After 7 days, it becomes stale but the cache is allowed to reuse it for any requests that are made in the following day (86400s) — provided that they revalidate the response in the background.
Revalidation will make the cache be fresh again, so it appears to clients that it was always fresh during that period — effectively hiding the latency penalty of revalidation from them.
If no request happened during that period, the cache became stale and the next request will revalidate normally.