Movatterモバイル変換

[0]ホーム
URL:

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

Lifetime and revalidation

IMPORTANT:The content on this page uses the following versions of Compute SDKs:JavaScript SDK: 3.30.1 (current is 3.37.0, seechanges),Rust SDK: 0.11.6 (current is 0.11.12, seechanges),Go SDK: 1.5.0 (current is 1.6.1, seechanges)

WARNING: The before-send and after-send callbacks discussed on this page are part ofcustomized readthrough (HTTP) cache behavior. For the Compute JavaScript and Go SDKs, this is an opt-in feature. Seethis note for details.

Freshness and Staleness

When content is stored in Fastly's cache, it has a freshness lifetime, also known as aTTL 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 asstale. 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 thereadthrough cache this object will, unless evicted earlier due to lack of use, transit the following states:

stale phases

  1. CDN services
  2. Compute services

When a client request matches a stale object, the readthrough cache interface processes the object using the following steps:

  1. If the backend is sick (i.e. is currently failing ahealth check), and the object is within astale-while-revalidate orstale-if-error period, then the stale object will be served.
  2. Otherwise, if the object is within astale-while-revalidate period, then it will be served immediately to the client. Additionally, an asynchronous fetch to the backend will be scheduled torevalidate or replace the stale object. Seebackground revalidation process flow for details on this process.
  3. Otherwise, if the object is within astale-if-error period and your VCL explicitly returnsdeliver_stale fromvcl_miss,vcl_fetch, orvcl_error, the stale object will be served. Seeexplicitly serving stale content for details.
  4. Otherwise, the readthrough cache interface will perform ablocking fetch to the backend torevalidate or replace the stale object, and then return the resulting object to the client.

The HTTPCache-Control header directivesstale-while-revalidate andstale-if-error (which trigger the scenarios above) are HTTP standards defined inRFC 5861 - HTTP Cache-Control Extensions for Stale Content.

HINT: Setting thereq.hash_always_miss orreq.hash_ignore_busy variables totrue will disable the effects of theCache-Control directivesstale-while-revalidate andstale-if-error for that request.

WARNING: Content is not guaranteed to be stored for the entire freshness lifetime and, especially in the case of large objects that are not frequently requested, may be evicted to make space for more popular objects.

HINT: If your website were a radio station, then the CDN edge cache would be like your regional transmitter towers - essential to extend your reach to a huge audience, but useless without a signal to broadcast. Large state broadcasters have long realized this and placed local recordings of content at transmission sites "just in case" the transmitter loses its uplink to home base.

Serving content from Fastly's platform to end users is very fast, and very reliable. But this only happens, by default, when that content is available (and fresh) in the cache. Use ofstale-while-revalidate,stale-if-error and custom VCL that intercepts backend errors can significantly improve outcomes for end users.

Staleness behaviors and revalidation are supported directly by thereadthrough cache interface and can be explicitly configured using the low levelcore 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 avalidator (anETag orLast-Modified header), the readthrough cache interface will make aconditional GET request for the resource, by sending anIf-None-Match and/orIf-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 of304 Not Modified. Depending on the response, the cache will behave as follows:

  • The backend response has a status code of304 Not Modified

    If the response to a revalidation request has status304 Not Modified, this will cause the lifetime of theexisting object to be extended based on thestandard rules on calculating cache TTL, and will reset the object'sAge.

    NOTE: If the initial object's TTL was determined by anExpires header and no freshness-related headers are present on a304 response, the cache will set a TTL of2 minutes (a default TTL) for the existing object. This is because theExpires 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. CDN services
    2. Compute services

    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.

    This kind of responsedoes not triggervcl_fetch.

  • The backend response has a status code other than304 Not Modified

    1. CDN services
    2. Compute services

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

HINT: Revalidations triggered as a result of astale-while-revalidate directive happen in the background,after the stale object has already been delivered to the client. SeeStale while revalidate for details.

Disabling revalidation

In some cases an origin server may be configured to serve responses withETag orLast-Modified headers, but you prefer not to allow revalidation.

  1. CDN services
  2. Compute services
  3. Rust
  4. JavaScript
  5. Go

To disable revalidation entirely, remove theETag andLast-Modified headers from the response when it's received from the backend. This can be done invcl_fetch:

sub vcl_fetch { ... }
Fastly VCL
unsetberesp.http.etag;
unsetberesp.http.last-modified;

Alternatively, you can enable revalidation between client and Fastly's cache, whilst effectively disabling it between Fastly's cache and the backend, by modifying the value of theETag header:

sub vcl_fetch { ... }
Fastly VCL
setberesp.http.etag=beresp.http.etag"-fastly";
unsetberesp.http.last-modified;

Alternatively, you can enable revalidation between the client and Fastly's cache, whilst effectively disabling it between Fastly's cache and the backend, by modifying the value of theETag header:

  1. Rust
  2. JavaScript
  3. Go
req.set_after_send(|resp|{
ifletSome(etag)= resp.get_header_str("ETag"){
    resp.set_header("ETag",format!("{etag}-fastly"));
}
  resp.remove_header("Last-Modified");
Ok(())
});

Explicitly serving stale content

  1. CDN services
  2. Compute services

Fastly's cache honors staleness-related caching directives as indicated above, and in a VCL service, it is possible to use edge code to further control the serving of stale content.

  • Stale content can be explicitly selected(scenario 3 above), if a cached object exists and is within astale-if-error period, in the following subroutines:

    • Invcl_fetch: if the origin returns a response which isvalid HTTP, then Fastly's cache will by default serve the received object, and ifcacheable, use it to replace the stale object in cache. However, if the response is nonsensical or an error, you may prefer in that scenario to serve the stale content instead, by usingreturn(deliver_stale).
    • Invcl_error: if, during a fetch to origin, Fastly's cache encounters anetwork level error, such as finding the origin unreachable or being unable to negotiate an acceptable TLS session, an error will be triggered and VCL control flow will be moved tovcl_error directly, without runningvcl_fetch. By default, this will result in serving an error page generated by the Fastly platform to the end user, but if stale content exists in cache you can opt to use this instead by usingreturn(deliver_stale) fromvcl_error.
    • Invcl_miss: it is also possible to switch to a stale object invcl_miss, but there is unlikely to be a reason to do so.

  • The existence of stale content can be checked during the above subroutines using thestale.exists variable, which will only betrue if a cached object exists and is within astale-if-error period. Stale content in theexpired state cannot be used from VCL.

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, thestale-while-revalidate directive allows it to continue to serve the same content for up to another 60 seconds, provided that time is used torevalidate 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 additionalstale-if-error directive).

Background revalidation process flow

When a cache lookup results in a stale object that is within astale-while-revalidate period, the readthrough cache interface willfork 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.

IMPORTANT: If there is already a background revalidation in progress for the resource being requested, the stale object will be served but a new revalidation will not be triggered. Seerequest collapsing.

  1. CDN services
  2. Compute services

In a VCL service, each stage invokes VCL subroutines as follows:

Background revalidation flow

VCL subroutines executing in a background revalidation context are identifiable via thereq.is_background_fetch VCL variable.

Background revalidations will only repopulate cache if the process above is successful andberesp.cacheable is set totrue at the end ofvcl_fetch. Otherwise, the stale object will continue to be used and background revalidation will continue to be attempted on subsequent requests, until the SWR period expires.

If a background revalidation is successful, itdoes not reset theAge of the object.

Background revalidations are eligible forrequest collapsing.

Stale if error: Survive origin failure

stale-if-error is an instruction that if a backend is sick (i.e. is currently failing ahealth 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 willblock on a synchronous fetch to origin. Unlikestale-while-revalidate,stale-if-error doesn't allow for any asynchronous revalidation.

  1. CDN services
  2. Compute services

In a VCL service, whenever a request is made through the readthrough cache interface during astale-if-error window:

Once the stale period expires, the content can no longer be used as a backup and, if the origin is sick or a failure is encountered in fetching from the origin, the Fastly platform must serve an error.

If a response specifies both astale-while-revalidate and astale-if-error directive, the revalidation period comes first, and the error period is added on to it.

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 theSurrogate-Control cache-control header. It functions similarly toCache-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 asCache-Control but Fastly's cache does not support thes-maxage directive (in the context ofSurrogate-Control,s-maxage would mean the same thing asmax-age, so useSurrogate-Control: max-age).

Summary table

  1. CDN services
  2. Compute services

To summarize, these are the four possible freshness states that a piece of cached content can be in when it is matched by an incoming request:

  • Fresh: Fastly's cache has a cached copy of the content, and it's within its initial freshness lifetime
  • SWR: Fastly's cache has a stale version of the content, and it's within astale-while-revalidate period
  • SIE: Fastly's cache has a stale version, and it doesn't qualify for SWR (or that period has already expired), but it's within astale-if-error period, allowing it to be used automatically if an origin is sick.
  • None: Fastly's cache doesn't have the content or it's expired (content in this state will still allow for conditional fetches if it has anETag orLast-Modified date)

And there are also four possible states that an origin server can be in:

  • Healthy: The backend is up and working
  • Erroring: The backend is returning syntactically valid HTTP responses with response status codes in the 5xx range (e.g.,503 "service unavailable")
  • Down: The backend is unreachable, or is unable to negotiate a TCP connection
  • Sick: Fastly's cache has marked this origin as unusable because it has consistently been unable to fetch from a health check endpoint. Origins in adown orerroring state that have a health check will eventually be transitioned tosick by thehealth check.

This results in 16 possible permutations, which can be visualized as a grid to show where good things happen and where bad things happen:

Content state
FreshSWRSIENone
Origin
state		Healthy😀😀😴😴
Erroring😀😀😡😡
Down😀😀😡😡
Sick😀😀😀😡

The three possible outcomes are that the user will see the content they want served from the edge (😀), they'll get the content but including a blocking fetch to origin (😴), or they'll see an unfiltered error (😡), which could be either something generated by Fastly's platform or whatever your origin server returned.

HINT: Some of these scenarios can be improved in VCL services by adjusting the default configuration provided by Fastly platform's to be more aggressive about using stale content. For more details, see theserving stale tutorial.

Shielding considerations

If you haveshielding 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 anAge header along with the response to the edge POP, and the edge POP will not cache the response because theAge already exceeds the object's freshness TTL (specified by amax-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 beenpurged with soft purge enabled
  • where your service configuration has directly manipulated the object's TTL in edge code, such that it no longer matches themax-age defined on the object's response headers
  • where the edge POP has made aconditional GET to the shield POP and the shield POP has returned a304 (Not Modified) response
  1. CDN services
  2. Compute services

The inadvertent caching of stale content at the edgePOP due to these edge cases can easily be prevented in VCL services by disabling the use of stale content for asynchronous revalidation when a POP is acting as a shield:

sub vcl_recv { ... }
Fastly VCL
if (fastly.ff.visits_this_service>0) {
setreq.max_stale_while_revalidate=0s;
}

This code will continue to allow stale content to be used when an origin is sick. To disable that as well, setreq.max_stale_if_error to0s.

Best practices

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

  1. CDN services
  2. Compute services
  • Specify a shortstale-while-revalidate and a longstale-if-error value. If your origin is working, you don't want to subject users to content that is significantly out of date. But if your origin is down, you're probably much more willing to serve something old if the alternative is an error page.
  • Always include a validator (anETag orLast-Modified header) on responses from origin.
  • Useshielding to increase the cache hit ratio and increase the probability of having stale objects to serve.
  • Always usesoft purges to ensure stale versions of objects aren’t also evicted.
[8]ページ先頭
©2009-2025 Movatter.jp