1. Home
2. Guides
3. Core concepts
4. Edge state and caching
5. Cache interfaces

Freshness and Staleness

When content is stored in Fastly's cache, it has a freshness lifetime, also known as a TTL or "time to live". This is the period of time during which the cache will serve the content in response to a compatible request, without revalidating it with the origin server.

Once the freshness lifetime expires, the content will no longer be served directly and unconditionally from cache, but the expiry does not prompt the object to be deleted. Instead, it will be marked as stale. The way objects are treated once they transition to a stale state can be customized.

Objects may have one of three distinct types of stale state, in addition to being fresh. As an example, consider an object arriving from the backend with the following response header:

Cache-Control: max-age=300, stale-while-revalidate=60, stale-if-error=86400

When processed by the readthrough cache this object will, unless evicted earlier due to lack of use, transit the following states:

Staleness behaviors and revalidation are supported directly by the readthrough cache interface and can be explicitly configured using the low level core cache interface. The simple cache interface does not support staleness or revalidation.

Revalidation

When a backend fetch is triggered by a cache object being stale, if the object has a validator (an ETag or Last-Modified header), the readthrough cache interface will make a conditional GET request for the resource, by sending an If-None-Match and/or If-Modified-Since header as appropriate (if both validators are present, both headers are sent). If the stale object does not have a validator, the backend request will be a normal fetch to load the entire object.

If the readthrough cache interface makes a conditional request in this way, it will expect a backend response which may or may not have a status code of 304 Not Modified. Depending on the response, the cache will behave as follows:

• The backend response has a status code of 304 Not Modified

  If the response to a revalidation request has status 304 Not Modified, this will cause the lifetime of the existing object to be extended based on the standard rules on calculating cache TTL, and will reset the object's Age.

  NOTE: If the initial object's TTL was determined by an Expires header and no freshness-related headers are present on a 304 response, the cache will set a TTL of 2 minutes (a default TTL) for the existing object. This is because the Expires header value identifies a fixed point in time while other freshness header values are given as times relative to the time that the response was received.

  1. VCL
  2. Compute

  No other aspects of the existing cached response will be modified. For example, this means that after successfully revalidating, future requests for the object will receive the headers that were attached to the original response from the backend that populated the cache, not the headers present on the revalidation response.

  In a VCL service, this kind of response does not trigger vcl_fetch.

• The backend response has a status code other than 304 Not Modified

  1. VCL
  2. Compute

  Any response to a revalidation request other than 304 will be processed normally, trigger vcl_fetch, and (if cacheable) will replace the stale object in cache.

Disabling revalidation

In some cases an origin server may be configured to serve responses with ETag or Last-Modified headers, but you prefer not to allow revalidation.

unset beresp.http.etag;
unset beresp.http.last-modified;

set beresp.http.etag = beresp.http.etag "-fastly";
unset beresp.http.last-modified;

Explicitly serving stale content

Stale while revalidate: Eliminate origin latency

stale-while-revalidate tells caches that they may continue to serve a response after it becomes stale for up to the specified number of seconds, provided that they work asynchronously in the background to fetch a new one. For example, an origin server may provide a response with the following headers:

Cache-Control: max-age=300, stale-while-revalidate=60
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Upon receiving this response, Fastly's cache will store and reuse that response for up to 5 minutes (max-age=300) as normal. Once that freshness lifetime expires, the stale-while-revalidate directive allows it to continue to serve the same content for up to another 60 seconds, provided that time is used to revalidate the cached content with the origin server in the background. As soon as a new response is available, it will replace the stale content and its own cache freshness rules will take effect. However, if the 60-second revalidation period expires, and it has not been possible to get the updated content, the stale version will no longer be usable in this manner (it may remain stale for a further period of time if it has an additional stale-if-error directive).

Background revalidation process flow

When a cache lookup results in a stale object that is within a stale-while-revalidate period, the readthrough cache interface will fork the request into two paths. One path will serve the stale object to the current client, while the second will asynchronously fetch the object from the origin.

If a background revalidation is successful, it does not reset the Age of the object.

Background revalidations are eligible for request collapsing.

Stale if error: Survive origin failure

stale-if-error is an instruction that if a backend is sick (i.e. is currently failing a health check), a stale response may be used instead of outputting an error - which helps always guarantee a nice user experience even during periods of server instability.

Cache-Control: max-age=300, stale-if-error=86400

In the above example, Fastly's cache will store and serve the fresh content for 5 minutes, just like the previous example, but this time, when the 5 minutes has expired, the next request for this content will block on a synchronous fetch to origin. Unlike stale-while-revalidate, stale-if-error doesn't allow for any asynchronous revalidation.

Applying staleness directives only to Fastly's cache

stale-* directives apply to all caching HTTP clients, not just CDNs and other non-browser clients. While stale-serving in browsers is also useful, if you are trying to apply stale behaviors only to Fastly's cache, consider using the Surrogate-Control cache-control header. It functions similarly to Cache-Control, but overrides it if the two are both present and is removed by Fastly's cache automatically, so you can control the stale logic for it independently of browsers.

Surrogate-Control: max-age=300, stale-while-revalidate=60, stale-if-error=86400
Cache-Control: max-age=60

Surrogate-Control has the same spec as Cache-Control but Fastly's cache does not support the s-maxage directive (in the context of Surrogate-Control, s-maxage would mean the same thing as max-age, so use Surrogate-Control: max-age).

Summary table

Shielding considerations

If you have shielding enabled in your service, the shield POP may serve stale content to the edge POP, which should avoid caching that content as fresh. By default, the right thing happens because the shield POP will send an Age header along with the response to the edge POP, and the edge POP will not cache the response because the Age already exceeds the object's freshness TTL (specified by a max-age directive).

However, in some circumstances, stale content served from a shield POP to an edge POP may be cached as if fresh:

• when it has been purged with soft purge enabled
• where your service configuration has directly manipulated the object's TTL in edge code, such that it no longer matches the max-age defined on the object's response headers
• where the edge POP has made a conditional GET to the shield POP and the shield POP has returned a 304 (Not Modified) response

if (fastly.ff.visits_this_service > 0) {
  set req.max_stale_while_revalidate = 0s;
}

Best practices

The following practices are recommended to get the most out of stale content: