Cache
Store copies of the responses to the requests received by an Application, and answer later requests from them without asking the origin.
Cache is a Platform Resource that stores copies of the responses to the requests received by your Applications, on Azion’s distributed infrastructure. A cache is a store of response copies between clients and the origin, the server that holds the content. It answers repeated requests with those copies.
The first request for an object reaches the origin, and the cache stores the response under a key built from the request. Later requests with the same key get the stored copy. The copy lasts until its time to live (TTL), a period in seconds, ends. The origin then answers only the first request and the requests that arrive after the copy expires.
Cache is always on in an Application. It stores only the responses to the requests that a Rules Engine rule with the Set Cache Policy behavior matches. That rule applies a cache setting, which holds the TTLs and decides how Azion stores and varies each copy. Cache can store a response whether the origin or a Function builds it. Each copy stays in the data center that stored it. Use Cache to keep static files in the data center nearest to your user, serve large videos in fragments with Large File Optimization, answer with an expired copy through stale cache while the origin is down, or remove a copy with Real-Time Purge when the origin changes.
Quickstart Cache referenceRequest path
Creating a cache setting caches nothing: a request reaches a stored copy only through a rule that applies the setting.
Solid arrows carry the request, and dotted arrows carry the response. Each label starts with the number of its step below.
- The client’s request reaches an Application, and the Application’s Request Phase rules run in order.
- When a Set Cache Policy rule applies a cache setting, Cache builds the cache key from the request and from every variation the setting names.
- When Cache holds a valid copy under that key, the data center that received the request answers from it. The response reports
HIT. - Otherwise, the Connector that a Set Connector rule sets routes the request to the origin, and the response reports
MISS. Cache may store the response under the key for later requests. - When no rule applies a cache setting, or a Bypass Cache rule matches, the request goes to the origin past Cache. Bypass Cache requires Application Accelerator. With Bypass Cache, nothing is stored, and the response reports
-orBYPASSinx-cache.
A stored copy answers until its TTL ends or a purge removes it. The status comes back in the x-cache header of a response to a request sent with Pragma: azion-debug-cache. For every status and the debug headers, refer to Cache keys.
For TTL and expiration, stale cache, Large File Optimization, cache keys and variations, Tiered Cache, and purge, refer to Expiration and freshness.
Cache setting structure
Cache acts through a cache setting. The setting holds how long Azion and the browser keep a copy, what Azion does with an expired copy, and what makes two requests different. To keep each response for 300 seconds in Azion’s cache and for one day in the browser, send this cache setting as the body of POST /v4/workspace/applications/<application-id>/cache_settings:
browser_cachedecides what a visitor’s browser keeps.honorforwards theCache-ControlandExpiresheaders of the origin.overridereplaces them withmax_age, in seconds.no-cacheturns browser caching off.modules.cachedecides what Azion keeps. Withbehaviorset tooverride,max_agereplaces the headers of the origin. Underhonor, Azion keeps those headers. When the origin sends no TTL, Azion keeps the response for themax_ageof the setting.stale_cache,large_file_cache, andtiered_cacheturn on stale cache, fragments of 1,024 kB, and a second cache layer in the region thattopologynames. Stale cache can serve an expired copy when Azion cannot confirm the copy with the origin. A body that leaves one of the three fields out gets that field off.tiered_cachealso requires theoverridebehavior.- A cache setting acts only once a Request Phase rule applies that cache setting with
{ "type": "set_cache_policy", "attributes": { "value": <cache-setting-id> } }. You can also build the same setting in Azion Console, as Cache quickstart shows.
If you set Cache-Control headers at your origin, the model transfers: honor keeps them, and override replaces them.
Scope and limits
- Application: Cache is always on in an Application, in its
modules.cache.enabledfield in the API, which refusesfalsewith31001. Main Settings shows its switch locked on in Azion Console, with the noteAutomatically enabled in all accounts.A new Application has no cache settings and no rules, so Cache starts storing copies once a Set Cache Policy rule applies a cache setting. - Expired copies: with stale cache on, in the
modules.cache.stale_cache.enabledfield of a cache setting, Azion may serve an expired copy when it cannot confirm the copy with the origin. The response then reportsSTALE. A setting created through Azion API or Azion CLI has it off, while Azion Console turns it on for a new setting. Cache settings shows where to change it in each interface. For when an old page is better than an error, refer to Applications best practices. - Large files: Large File Optimization, the
modules.cache.large_file_cache.enabledfield of a cache setting, caches a large object in fragments of 1,024 kB. It is off in a new cache setting. Each fragment is fetched when a user reaches it and stored under a key of its own, so a purge of the file has to name every fragment or use a wildcard. - 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. Each cache setting turns it on in its
modules.cache.tiered_cache.enabledfield, and every plan includes it. A data center that holds no valid copy asks that layer before the request goes to the origin. Tiered Cache requires theoverridebehavior and a minimum TTL. A Bypass Cache rule acts on Azion’s cache only, so the Tiered Cache layer keeps caching objects for the Max Age of the cache setting. - Keys and variation: Azion builds the default cache key from the scheme, the host, and the path, so one path is one stored object, and the query string stays out of the key. Varying a copy by query string, cookie, device group, or method takes Application Accelerator. Image Processor adds the format of a converted image to the key.
- Purge: Real-Time Purge is a Platform Resource that removes a stored copy before its TTL ends, by URL, by cache key, or by wildcard. Azion queues a purge after you confirm it, because the result takes time to propagate. The purge history lists the purge once it completes. A copy that varies by cookie, device group, or image format survives a URL purge, and a cache key or wildcard purge reaches it.
- Code: code that reads and writes cached entries runs in a Function and calls Cache API, because Cache itself cannot run code.
- Interfaces: you create cache settings on the Cache Settings tab of an Application in Azion Console, through Azion API at
/v4/workspace/applications/<application-id>/cache_settings, and with Azion CLI commands such asazion create cache-setting.azion.config.jsdeclares a setting as an entry of itscachearray, Azion Lib creates one withcreateCacheSetting, and Azion Terraform Provider manages one with theazion_application_cache_settingresource. A purge is sent from Real-Time Purge in Azion Console, toPOST /v4/workspace/purge/<purge-type>, or withazion purge. - Observability: a request sent with
Pragma: azion-debug-cachereceives two headers.x-cachecarries the cache status, andx-cache-keycarries the key of the copy. Real-Time Metrics shows Cache and Tiered Cache traffic, and Real-Time Events carries a Tiered Cache dataset. - Limits: a single cached object can reach 10 GB. Max Age, the
modules.cache.max_agefield of a cache setting, takes 60 seconds to one year. With Application Accelerator on, Azion API accepts down to 0 seconds. For every bound of a cache setting, a cached object, and a purge request, refer to Applications limits. For the rates, refer to Pricing, and for what each plan includes, to Azion pricing. - Terms: the Applications glossary defines the words the Cache pages give a specific meaning, such as cache setting, cache key, cache status, and stale cache.