KeyCDN Now Supports Stale-While-Revalidate and Stale-If-Error

KeyCDN is happy to announce that we now support both stale-while-revalidate and stale-if-error extension Cache-Control directives. Both of these directives aim to further improve content delivery performance by delivering stale assets to users in the event that assets need to be revalidated or if there is a problem fetching them.

Both of these extension directives were introduced in RFC 5861 to provide better control over the use of stale responses from cache headers. In this article, you'll learn more about both directives, how they benefit you as a CDN user, and how you can implement them.

stale-while-revalidate directive explained

The stale-while-Revalidate directive helps provide faster and more streamlined caching as it allows for the asset revalidation process to happen in the background. When this directive is present in the HTTP response header, it tells caches that they can continue serving the current (stale) assets while an asynchronous validation is attempted.

For example, let's say you have a JavaScript asset with the following max-age directive:

Cache-Control: max-age=2592000

In this case, the cache will continue serving the same JavaScript asset for a time period of 30 days, as defined by the max-age value. Once that 30 day period is up, the cache needs to check the origin server to see whether the file has changed. This takes time and causes the user to have to wait longer in order to see the newly validated asset.

On the other hand, if the stale-while-revalidate directive is present and the max-age value has expired, users will continue to be delivered the same asset while the cache validates that asset in the background. Therefore, let's say you have a response header such as:

Cache-Control: max-age=2592000, stale-while-revalidate=86400

The above tells the cache to deliver the same asset for 30 days and once that period is up, it has 1 additional day to validate the asset asynchronously from the origin server. This means that not only will users receive the latest version of an asset, but they will also experience a faster load time.

stale-if-error directive explained

The stale-if-error directive is used to prevent errors and ultimately, broken pages. Taking the same max-age value as above, let's say that we want to add the stale-if-error directive with a value of 7 days. This would result in the following:

Cache-Control: max-age=2592000, stale-if-error=604800

With the above Cache-Control header directives active, an asset is said to be fresh for 30 days. However, after the 30 day period has expired, the asset must be validated from the origin server. Upon validation, if the origin server returns an error (e.g. 500, 502, 503, or 504 error code) then the cache will continue serving stale content for up to 7 more days, thus resulting in a continued 200 HTTP status.

After the age of the asset is greater than the max-age and stale-if-error values combined (in this case, 3,196,800 seconds) then the cache must deliver the error message through to the user.

Implementing stale-while-revalidate and stale-if-error

To enable support for the stale-while-revalidate and stale-if-error directives within the KeyCDN dashboard you will need to set the Ignore Cache Control setting to disabled. Then, define the Cache-Control directives on the origin server. KeyCDN will simply honor the behavior you have defined on your origin server. The following two examples show how to add these directives to either your Nginx or Apache web server.

Nginx

The following snippet can be added to your Nginx configuration file. The example below uses a max-age value of 30 days, a stale-if-revalidate value of 1 day, and a stale-if-error value of 7 days. These values are simply an example and you can modify them as to your specifications.

location ~* \.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$ {
    add_header Cache-Control "max-age=2592000, stale-while-revalidate=86400, stale-if-error=604800";
}

Apache

The following snippet can be added to your Apache configuration file to tell the server to set the Cache-Control header directive values to the same as the example above. Again, these values are an example and should be modified to suit your needs.

<filesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$">
    Header set Cache-Control "max-age=2592000, stale-while-revalidate=86400, stale-if-error=604800"
</filesMatch>

Now that you've specified the stale-while-revalidate and stale-if-error directives within your Cache-Control header, you can check one of your CDN assets with a simple curl command to see if the directives are present. Be sure to replace cdn.yourwebsite.com with your actual Zone Alias or Zone URL.

curl -I https://cdn.yourwebsite.com/path/to/your/asset.js

Depending on your configuration you may receive a different cache status from KeyCDN in the X-Cache response header. Consider the following:

• If Ignore Cache Control is set to enabled: X-Cache will return STALE and update the asset in the background once the max-age value expires.
• If Ignore Cache Control is set to disabled: X-Cache will return REVALIDATED once the max-age value expires.
• If Ignore Cache Control is set to disabled but stale-while-revalidate is defined on the origin: X-Cache will return STALE and update the asset in the background once the max-age value expires.

Additional notes

Below are a few additional notes about both of these extension directives:

• If the validation fails after the period defined in stale-while-revalidate then the cached response will be handled normally. Similarly, if the time period defined in stale-if-error expires, then the error status will be passed through to the client.
• Kenji Baheux started a great discussion on the chromium-dev thread about suggestion values for stale-while-revalidate.
• stale-while-revalidate differs from prefetching as prefetching always refreshes assets once they become stale whether or not they are being requested. The stale-while-revalidate directive, on the other hand, avoids this creation of needless network traffic by serving stale content while revalidating in the background but only based on user request.

Summary

The stale-while-revalidate and stale-if-error directives are both great ways to easily improve the caching performance of your assets and strengthen the resilience of your pages. KeyCDN automatically supports these directives on all Pull Zones and therefore there is nothing that needs to be modified in your KeyCDN dashboard.

By simply adding these directives to your origin server and defining values that you see fit, you'll be able to validate assets more efficiently and avoid broken pages.