Expiration and freshness
See how long a cached copy lives, when an expired copy may still answer, and how fragments, variations, Tiered Cache, and purges change it.
The time a cached copy answers for the origin decides two things: how fresh a response is, and how often the origin is asked. In an Application, Cache is the Platform Resource that stores the copy, and a cache setting sets that time as its time to live (TTL). The cache setting also decides what happens after the TTL ends. A purge ends a copy early. The Cache overview shows how a request reaches a cached copy, with a diagram of the cache path.
The sections cover TTL and expiration, stale cache, Large File Optimization, cache keys and variations, Tiered Cache, and purge.
TTL and expiration
A cache setting carries two TTLs. The browser TTL controls how long a visitor’s browser keeps its copy. The cache TTL controls how long Azion keeps its own. A request that the browser answers from its copy stops at the browser, and a request that Azion answers from its copy stops at Azion.
Where each TTL comes from depends on the behavior the setting selects for each copy. For Azion’s copy, the behavior is the modules.cache.behavior field. Honor cache policies (honor) keeps the Cache-Control and Expires headers of the origin and forwards them to the browser, so the origin decides how long its content lives. Override cache behavior (override) replaces those headers for Azion’s cache with Max Age, the modules.cache.max_age field. When the origin sends no TTL under Honor cache policies, Azion keeps the copy for the Max Age of the setting. The browser’s copy has its own behavior in the browser_cache.behavior field: Honor cache policies, Override cache settings, or No cache.
The copy expires when the cache TTL ends, and the next request for the object goes to the origin. When the origin returns the object, that response updates the copy. The response reports EXPIRED. A check with conditional headers can also find the copy unchanged. The response then reports REVALIDATED, and the origin confirms the copy instead of sending the object again.
A request that finds no valid copy is a cache miss. On a miss, the platform limits the work of the origin. When several requests for the same uncached object reach the same server at the same time, that server opens one connection to the origin for all of them. So, under a burst of requests for an uncached object, the origin sees one fetch per server that received the burst, not one per visitor.
The TTL is a trade between the load on the origin and the age of what a visitor sees. A long TTL answers more requests from the copy and reaches the origin less, but content the origin already changed stays in the copy until it expires. A short TTL keeps the copy close to the origin’s version, at the price of more origin fetches. For example, one Application can hold two cache settings, each applied by its own rule. Images that rarely change take a TTL of a day, and a listing that changes through the day takes a TTL of a few minutes.
Max Age has a floor and a ceiling, and Application Accelerator lowers the floor. For every TTL bound, refer to Applications limits. For how a TTL of 0 seconds differs from bypassing the cache, refer to Bypass Cache and a TTL of 0.
Stale cache
A copy past its TTL still has a use. With stale cache on in the cache setting, Azion may reuse an expired copy when a revalidation attempt fails, for one of three reasons:
- The origin returns a
5xxerror. - The connection times out, or the origin is unreachable.
- The cache-control headers of the origin are invalid or missing.
How long the expired copy may be served is the stale window. Under Honor cache policies, the window is the value of the stale-while-revalidate=<ttl> directive the origin supplies. Under Override cache behavior, or when the origin omits the directive, the window is 300 seconds.
A response served from an expired copy because the origin failed to respond reports STALE.
Stale cache shows visitors an old page instead of an error page during an origin outage, for as long as the window lasts. The cost is freshness: a visitor inside the window can receive content the origin already replaced. So a change that every visitor has to see at once is a case for a purge rather than for expiry.
Whether stale cache starts on in a new setting depends on the interface. Its field is modules.cache.stale_cache.enabled. A setting created through the API or the CLI has it off, and Azion Console turns it on for a new setting. Cache settings shows where to change it in each interface.
Large File Optimization
A large object can be cached in fragments rather than as one piece. With Large File Optimization on in the cache setting, in its modules.cache.large_file_cache.enabled field, Azion splits the file into fragments of 1,024 kB. Each fragment is delivered as the user consumes it, and it is cached on demand, at the moment it is requested. The cache key of a fragment ends in @@bytes= and the byte range of the fragment. So every fragment is an object of its own.
For example, a video of 2,097,151 bytes at https://static.example.com/media/file.mp4 becomes two fragments. They are stored under these keys:
A fragment is fetched only when a user reaches it, so a download that stops partway leaves the later fragments unfetched. The fragments that were fetched stay cached for the next request. The fragmentation applies to Azion’s cache, and to the Tiered Cache layer when the setting has Tiered Cache on.
The cost comes at purge time. One file becomes many keys, so a purge lists the key of each fragment, or uses a wildcard that ends the path of the file with *. A purge that removes some fragments and not others leaves a mix of new and old fragments in the cache. For the purge types, refer to Real-Time Purge.
Cache keys and variations
A variation is a further copy of one path, stored under its own cache key because something other than the path differs. While no variation is on, one path is one stored object. Azion builds the default key from the scheme, the host, and the path of the request. A cache setting holds its query-string variation in the cache_vary_by_querystring.behavior field, which starts at ignore and keeps the query string out of the key. When something other than the path changes the response, the cache setting names it, and the key carries a marker for it.
Four inputs can vary a copy through the modules.application_accelerator object of a cache setting:
- A query-string argument.
- A cookie.
- The device group a request falls in.
- The request method.
Two more come from elsewhere. Image Processor adds the image format when it converts an image, and Large File Optimization adds the byte range of each fragment. Each distinct value is a separate key, so each one is stored and purged separately.
Device groups belong to the Application, and Device Groups documents them. With cache_vary_by_devices, a setting delivers one version whatever the device, or keeps one copy per named group.
The method is a variation too. GET and HEAD responses are cached natively, and POST and OPTIONS responses are cached only with Application Accelerator on and the method listed in cache_vary_by_method. The body of a POST then becomes part of the key as an MD5 hash, so two different bodies posted to one path are two objects. An OPTIONS key carries the method prefix only.
A variation splits the requests for one path across several copies. Fewer requests find a copy already present, and a purge has to reach every copy. For example, a listing page that varies by a page argument stores one copy per page number, and a purge of the listing has to name each of them. For the marker each variation appends, refer to Cache keys. For the fields that turn a variation on, refer to Application Accelerator settings.
Tiered Cache
Tiered Cache is a Feature of Cache that adds a second cache layer between the data center that answers a request and the origin. When that data center holds no valid copy, it asks the Tiered Cache layer before the request goes to the origin. A valid copy in that layer answers the miss, and the origin receives no request.
Each cache setting turns the layer on in its modules.cache.tiered_cache.enabled field, and every plan includes it. The setting names a topology in modules.cache.tiered_cache.topology: the region that holds the layer, such as nearest-region or us-east-1. Tiered Cache also requires Override cache behavior. Under Honor cache policies, the API refuses the setting with 21001.
The trade is an extra hop and a floor on the TTL. A miss in the first layer travels to the second before it reaches the origin. A setting with Tiered Cache on also carries a minimum TTL. In return, fewer requests reach the origin. For the minimum, refer to Applications limits.
A Bypass Cache rule affects Azion’s cache and not the Tiered Cache layer. An Application with active Tiered Cache settings keeps caching objects in that layer for the Max Age of the cache setting. The layer is purged by cache key. When you purge an object held in both layers, purge the Tiered Cache layer first and then Cache, or the first layer refills from stale Tiered Cache content. For the purge layers, refer to Real-Time Purge.
Purge
A purge removes a stored copy before its TTL ends. Once no layer holds a copy, the next request for the object goes to the origin, the response reports MISS, and the version the origin returns is stored. A purge is queued after you confirm it, because the result takes time to propagate. It appears in the purge history once it completes across Azion’s infrastructure.
A purge finds an object by its cache key, so the purge type matters for an object that varies. A URL purge converts each URL to a cache key without considering content variation. So a copy that varies by cookie, device group, or image format survives it. A cache key purge names each variation. A wildcard purge reaches every key that matches an expression with *. Query-string variations are the exception a URL purge does reach. The arguments have to be sent in the order they were presented, or in alphabetical order when the cache setting sorts them, in its cache_vary_by_querystring.sort_enabled field.
A purge is the tool for a change that cannot wait for the TTL. Its cost is the origin fetch that refills each purged key. The more keys an object has, through variations or fragments, the more a purge has to name. For the purge types and their arguments, refer to Real-Time Purge. For the steps, refer to Purge cached content.