11/03/2024
In the world of delivering content quickly, keeping things fresh and up-to-date is key. That's where purging mechanisms come in—they help content delivery networks (CDNs) and caching systems manage what gets stored and for how long. In this guide, we'll walk you through the different ways content can be purged, like clearing out old stuff or refreshing specific pages.
Why purging ?
If you want to make sure everyone sees the latest version of something on a website, like a new headline, you might need to « purge » or clear out the old version from the cache. It’s like refreshing a page to see the newest updates. So, if you change the headline on a webpage and you want everyone to see the change immediately, you’ll need to purge the cached version. That way, when people visit the page again, they’ll see the updated headline right away.
Different ways to purge
With Fastly, you’ve got a couple of ways to purge content from the cache.
Single URL purge
One option is to purge a single URL. In simple terms, you just point to the URL you want to refresh, and it gets cleared out from the cache. The cool part? It happens super quick! (about 150 milliseconds)
Surrogate Key Purge
Another way to purge is by using something called a Surrogate Key Purge.
This method relies on surrogate keys, which are like tags attached to articles or media files. Using this technique, you can clear out all the URLs associated with a specific tag, category, or the URLs affected by recent changes you’ve made live.
Another neat thing about this approach is that you can purge multiple URLs in one go by purging using multiple surrogate keys.
Purge All
Another option is to purge everything, which means removing all cached items under a service configuration. However, this approach comes with a risk. If you get too many requests to your origin server all at once, it could overload your server, almost like a self-inflicted DDoS attack.
How the Hash key is used to purge-all
The parameters used to generate the hash key are:
The host like : fastly.antoinebrossault.com e.g : 21357f4e1d9a
The URL : /hello e.g : 13a7bc88b63d
And a generation ID : 1 - e.g : 1
Hash for fastly.antoinebrossault.com/hello = 21357f4e1d9a-13a7bc88b63d-1
When you execute a purge-all command, the generation number is incremented by one. As a result, for the subsequent request, the hash will be different, causing a cache miss.
For example, the previous hash could be 21357f4e1d9a-13a7bc88b63d-0, and after the purge, the hash becomes 21357f4e1d9a-13a7bc88b63d-1.
The crucial point to grasp is that a purge-all command doesn’t actually remove the object from the cache. Instead, it alters the hash associated with the object, effectively making it unreachable.
Soft Purge
Another way to purge content is by using a soft-purge method, where instead of rendering the object unreachable by altering the hash, you mark the object as stale. This means the object can still be accessed, even though it has been invalidated.
But when might you use this? Well, consider content where serving the absolute latest version isn’t crucial, such as a logo. In this case, the stale object can still be served for a specified period that you determine.
The available options for this method are:
- Stale-While-Revalidate
- Stale-if-error
Stale-While-Revalidate
Cache-Control: max-age=3600, stale-while-revalidate=3600
When a user visits the website to view a product page, the site fetches and caches the product details to ensure fast loading times for subsequent visitors. However, product information, such as pricing, availability, or reviews, may change frequently due to updates from suppliers or customer feedback.
In this scenario, the website implements the Stale-While-Revalidate strategy. When a user requests a product page, the cached version is served immediately, even if it’s slightly outdated (stale). At the same time, the server initiates a revalidation process to fetch the latest product information from the database or external sources.
Stale-if-error
Cache-Control: max-age=3600, stale-if-error=3600
When a user visits the news website to read an article, the server fetches and caches the HTML content of the article to ensure quick loading times for subsequent visitors. However, occasional server issues or network disruptions may result in temporary errors when attempting to fetch the latest version of an article.
In this scenario, the news website implements the Stale-if-error strategy. When a user requests to read an article, the cached version of the HTML page is served immediately. If the server encounters an error while trying to fetch the latest version of the article (e.g., due to server overload or database connection issues), the website continues to serve the cached version of the article HTML instead of displaying an error message to the user.
How to purge on Fastly ?
To perform a purge, you have several options available. You can use the user interface (UI), where you can either purge a single URL, purge by surrogate key, or initiate a purge-all operation.
Purge from the UI
Purge from the API
To purge content via the API, you can use the following call:
curl -X PURGE "https://fastly.antoinebrossault.com/"
As demonstrated in this video, the initial joke is served from the cache. By default, on the origin server, each HTTP call refreshes the joke. Here, I’m manually triggering a cache refresh using the API.
This call typically doesn’t require protection, but if desired, you can activate an option that requires an API key:
curl -X POST <url> -H "Fastly-Key:<Fastly APIKey>"
In the second call, replace <url> with the appropriate endpoint and <Fastly APIKey> with your Fastly API key.
Purge all
Here’s the code I use in my example app to run a purge all based on service :
const axios = require('axios');
require('dotenv').config()
const axiosConfig = {
headers: {
'Fastly-Key': process.env.FASTLYAPI,
'Accept': 'application/json'
}
};
exports.purgeAll = async (serviceID) => {
try {
const response = await axios.post(
`https://api.fastly.com/service/${serviceID}/purge_all`,
{},
axiosConfig
);
console.log('Purge request sent successfully:', response.data);
return response.data; // Return the response data if needed
} catch (error) {
console.error('Error purging all:', error.response.data);
throw error; // Re-throw the error if needed
}
}
Purge by Surrogate keys
curl -X POST -H "Fastly-Key:<Fastly API Key>"
https://api.fastly.com/service/<service_D>/purge/-H
'Surrogate-Key: key_1 key_2 key_3 key_4'
Options to authorize purge
Conditionally block purge calls by:
- Require Fastly Auth (key)
- Allowlist or Blocklist IPs
- Block via Geolocation
Limits on Purging
Purge by Service
Purges are limited by Service, so any content on different services will require separate purges.
Purge-All is Rate Limited
Authenticated users API calls are rate-limited to 1000 per hour.
Tokens
Account Tokens can limit the scope of purge privileges to:
- Account
- Service
- Purge type
