Caching creates a copy of the requested content on our edge servers. This dramatically reduces the distance that the data has to travel to fulfill all future requests.
Environments and Caching
Each environment provides a separate edge cache for the most recent deployment. Although older deployments do not support edge caching, you may re-enable it by rolling back to that version.
Edge and Shield Caching
Edgio may cache your content on our:
- Edge Points-of-Presence (POP): An edge POP handles receives and responds to requests for your content.
- Shield POP: A shield POP reduces your network bandwidth and the load on your origin server by providing an intermediate caching layer between the edge of our network (aka edge POPs) and your web servers. This means that if a request cannot be served from cache by an edge POP, then it will be forwarded to a shield POP. Funneling requests to a shield POP maximizes your cache hit ratio.
There is very little difference in time to first byte (TTFB) for responses served from an edge or shield POP. In either case, the response is served nearly instantly (typically 25-100ms). Concurrent requests for the same URL on different POPs that result in a cache miss will be coalesced at the shield POP. If you have configured your origin to only use a shield POP, then it will only submit a single request at a time to your origin servers for each cacheable URL.
Default Caching Policy
By default, only
GET
requests that result in a 200 OK
response are eligible to be cached. For these requests, our edge servers cache content according to the cache instructions (aka cache directives) provided by the origin server. If an origin server does not provide cache directives, then it will be assigned a time to live (TTL) of 7 days (i.e., Cache-Control: max-age=604800
). Content is considered fresh until its TTL has expired.Once the asset has been cached on a POP, all future requests from the region served by that POP will be served directly from that POP while the cached content’s TTL has not expired. Once the TTL has expired, an edge server from that POP may revalidate the asset with the origin server. If the asset has not been modified, then the cached content’s TTL on that edge server will be updated to reflect the origin’s cache instructions or a default TTL of 7 days. Otherwise, a new version of the asset will be retrieved and cached on the edge server.
Caching a Response
Define a caching policy through response headers or by setting up a rule or route with caching features.
Cache Directives (Response Headers)
The amount of time that an asset will be cached on our edge servers is determined by the response headers returned by the origin server when a client requests it. By default, our CDN honors the following response headers:
-
Cache-Control: private: Prevents our edge servers from caching the response.
-
Cache-Control: no-store: Prevents our edge servers from caching the response.
-
Cache-Control: no-cache: Requires our edge servers or the client to revalidate cached content.
-
Pragma: no-cache: Requires our edge servers or the client to revalidate cached content.
-
Cache-Control: s-maxage: Determines the requested content’s time-to-live (TTL) on our edge servers. TTL identifies the amount of time that cached content can be served without revalidation.This response header is ignored if the response contains any of the above response headers.
-
Cache-Control: max-age: Determines the requested content’s TTL on the user agent and our edge servers.This response header is ignored if the response contains any of the above response headers.
-
Expires: Defines an expiration date for the requested content’s TTL. The requested content will be considered stale after the specified date/time.If this directive has been assigned an invalid value, including zero, then it will be ignored for the request in question.This response header is ignored if the response contains any of the above response headers.
Key information:
- By default, content will only be cached after a POP receives two
GET
requests that result in a 200 OK response. - By default, Edgio honors an origin server’s cache directives. Allow Edgio to override those directives by creating a rule with the Ignore Origin No Cache feature enabled for the desired status code (e.g.,
200 OK
). - The above directives are ordered according to precedence. Higher directives take precedence over lower directives. In other words, if an asset contains both a
Cache-Control
and anExpires
header, then theCache-Control
header will take precedence. - Please refer to your web server’s documentation for more information on how to configure these settings.
- You may override a web server’s cache policy by creating a rule or route.
Rules
Set or override a cache policy by creating a rule that identifies the desired set of requests and the caching policy that will be applied to them. Commonly used features for defining a caching policy are listed below.
Feature | Usage |
---|---|
Bypass Cache | Use this feature to disable caching on our network. |
Bypass Client Cache | Use this feature to instruct the client to bypass cache. |
Set Client Max-Age | Use this feature to define how long a client must wait before revalidating cached content with our edge servers. |
Set Max-Age | Use this feature to define how long an edge server must wait before revalidating cached content with the origin. |
CDN-as-Code
Add the caching feature to your route:
JavaScript
1router.get('/some/path', {2 caching: {3 max_age: '86400s',4 stale_while_revalidate: '3600s',5 service_worker_max_age: '3600s',6 bypass_client_cache: true,7 },8 headers: {9 set_response_headers: {10 'x-sw-cache-control': 'max-age=3600',11 },12 },13});
Cache Key
Our edge servers use cache keys to determine whether a cached response exists for a specific request. Specifically, they calculate a cache key for each request. They then use this cache key to check for a cached response.
By default, our edge servers use the following syntax when calculating a cache key:
//http/80<ACCOUNT ID>/<ORIGIN CONFIGURATION>/<DEPLOYMENT VERSION>/<RELATIVE PATH>:/hs-<URI HASH>
Definitions for the above placeholder values are provided below.
Placeholder | Description |
---|---|
<ACCOUNT ID> | Indicates your unique customer account ID. |
<ORIGIN CONFIGURATION> | Indicates the name of the origin configuration associated with the request. Deploying a CDN-as-code configuration automatically generates the following system-defined origin configurations: edgio_static , edgio_permanent_static , edgio_serverless , and edgio_image_optimizer . Your CDN-as-code configuration determines the origin configuration that will be applied to the cache key. View how Edgio maps your code to these origin configurations from the Rules page. Returns origin when an origin configuration is inapplicable to a request. |
<DEPLOYMENT VERSION> | Indicates the version of the deployment for the configuration that served the request whose response was cached. |
<RELATIVE PATH> | Indicates the relative path to the requested content. This relative path starts directly after the hostname. By default, query strings are ignored by the caching mechanism and therefore they will be excluded from the cache key. If a query string is recorded in the cache key, it will be converted to its hash equivalent. After which, it will be inserted between the name of the requested asset and its file extension (e.g., assetHashValue.html). |
<URI HASH> | Indicates a hash of the request URI. |
Syntax:
x-ec-cache-key: <CACHE KEY>
Example:
x-ec-cache-key: //http/800001/web/21/images/foo.jpg:/hs-5041808438894094098
Customizing the Cache Key
If your web application relies on query string parameter(s), request header(s), or cookie(s) when generating a response, then you should customize the cache key to include those elements.
Key information:
-
Customize the cache key for a specific set of requests by implementing either of the following features within a rule or route:
-
Cache Key Query String: Use this feature if you need to include one or more query string parameters in the cache key.CDN-as-code: cache_key_query_string
-
Rewrite Cache Key: Use this feature if you require additional control over how a cache key is calculated.CDN-as-code: cache_key_rewrite
-
-
Defining custom cache keys too broadly impacts performance and lowers your cache hit ratio.We strongly recommend that you restrict this customization to a specific set of traffic (e.g., dynamic responses) and only add the specific critieria that influence the response provided to the client.For example, if the response varies according to a single query string parameter, then you should only add that query string parameter to your cache key. Adding additional query string parameters may cause too much segmentation for your cached content and thus reduce your cache hit ratio.
Sample Custom Cache Key Implementations
Examples of how to customize the cache key are provided below.
-
Add the
page
andfilters
query string parameters to the cache key using either of the following methods:- Rules: Create a rule that sets the Cache Key Query String feature to
Include
thepage
andfilters
query string parameters.
Add a query string parameter by typing its name and pressingENTER
.-
CDN-as-Code:JavaScript./routes.js1router.get('/some/path', {2 caching: {3 // Other options...4 cache_key_query_string: {5 include: ['page', 'filters'],6 },7 },8});
- Rules: Create a rule that sets the Cache Key Query String feature to
-
Add the
language
andcurrency
cookies to the cache key using either of the following methods:-
Rules: Create a rule that defines the Rewrite Cache Key feature as indicated below:
- Source: Set this to option to the relative path for the set of requests whose cache key will be rewritten.
/some/path/(.*)
- Destination: Set this option to the cache key’s replacement pattern.
/some/path/$1-%{cookie_language}-%{cookie_currency}
- Source: Set this to option to the relative path for the set of requests whose cache key will be rewritten.
-
CDN-as-Code:JavaScript./routes.js1router.get('/some/path', {2 caching: {3 // Other options...4 cache_key_rewrite: {5 source: '^/some/path/(.*)$',6 destination: '^/some/path/(.*)-%{cookie_language}-%{cookie_currency}$',7 },8 },9});
-
-
Customize the cache key by the country from which the request originated.
-
Rules: Create a rule that defines the Rewrite Cache Key feature as indicated below:
- Source: Set this to option to the relative path for the set of requests whose cache key will be rewritten.
/some/path/(.*)
- Destination: Set this option to the cache key’s replacement pattern.
/some/path/$1-%{geo_country}
- Source: Set this to option to the relative path for the set of requests whose cache key will be rewritten.
-
CDN-as-Code:JavaScript./routes.js1router.get('/some/path', {2 caching: {3 // Other options...4 cache_key_rewrite: {5 source: '^/some/path/(.*)$',6 destination: '/some/path/$1-%{geo_country}',7 },8 },9});
-
Use feature variables to dynamically construct the cache key’s replacement pattern. However, you may not use response metadata when defining a cache key.
Caching Responses for POST and PUT Requests
By default, Edgio only caches responses for
GET
requests. Cache the response for POST
, PUT
, or both HTTP methods using either of the following methods:- Rules: Create a rule that sets the Enable Caching for Methods feature to
POST
,PUT
, or both HTTP methods. - CDN-as-Code:
JavaScript./routes.js1router.get('/some/path', {2 caching: {3 "enable_caching_for_methods": ["POST", "PUT"],4 }5});
Caching Private Responses
By default, Edgio does not cache the response when it contains certain cache directives (e.g.,
Cache-Control: private
). Instruct our CDN to ignore these cache directives through either of the following methods:- Rules: Create a rule that enables the Ignore Origin No Cache feature.
- CDN-as-Code:
JavaScript1router.get('/some/path', {2 caching: {3 ignore_origin_no_cache: true,4 },5});
Client Caching
Content can be cached on our network or the client’s machine. Define how long content is cached on a client’s machine through:
- Cache directives, such as
Cache-Control: max-age
andExpires
. - Set Client Max Age feature.
A user may clear a web browser’s cache to force the web server to request a new version from our network.
Revalidation
Revalidation is the process through which an edge server checks the origin to find out whether a newer version of the requested cached content exists. If the origin indicates that the requested content has not changed, then our edge servers will serve cached content to the client and then update its TTL according to the provided cache instructions.
Our edge servers can only perform a revalidation when the following conditions are true:
-
The requested content is stale.
-
The cached response contains one of the following headers:
Last-Modified
(preferred)ETag
header
If either response header is not found, then our edge servers will perform an unconditionalGET
request to the origin.
Cache Hit Ratio Optimization
There are many factors that influence cache hit ratio, such as:
-
Your caching policy. You need to identify the set of content that should be cached and how long it should be cached.The length of time that content should be cached is known as time to live (TTL). TTL should vary according to how often your content is updated. Setting a short TTL leads to more cache revalidations, while a long TTL could lead to stale content being served.
-
Dynamic responses. If the response varies by query string parameter(s), request header(s), or cookies, then you will need to customize your cache key to include the criteria that influences the response provided to the client.We strongly recommend that you restrict this customization to a specific set of traffic (e.g., dynamic responses) and only add the specific critieria that influence the response provided to the client.
-
Geographic distribution of your users. Clusters of users within the same geographic region typically result in a higher cache hit ratio than users distributed throughout the world.
-
Cache invalidation (purging). Purging your content affects your cache hit ratio, since new requests will result in cache misses until that content is cached. If related content is updated at the same cadence, then it may make sense to use surrogate keys (aka cache tags) to selectively target cached content when purging.
-
Serving stale content during revalidation. Once configured, our edge servers can immediately respond to stale content with cached content instead of waiting for revalidation to complete. After our edge servers revalidate cached content, they will respond to new requests with an up-to-date version of your cached content. This feature balances performance with the need to serve the latest version of your content.Set up this feature using one of the following methods:
-
Rules: Create a rule that configures the Stale While Revalidate feature to extend the amount of time that an edge server may serve stale content past the expiration of an asset’s TTL.
-
CDN-as-Code:JavaScript./routes.js1new Router()2 .get('/', {3 caching: {4 "max_age": "10h",5 "stale_while_revalidate": "10m",6 }7 })Once both TTL and the Stale While Revalidate time has been exceeded, our edge servers must wait for revalidation to complete before providing a response to the client.For example, if the
max-age
interval is set to 10 hours and Stale While Revalidate feature is set to 10 minutes, then cached content older than 10 hours and 10 minutes must be revalidated before an edge server may provide a response.
-
Preventing a Response from being Cached
There are certain cases under which you may wish to disable caching. For example, caching should be disabled for requests that typically generate unique responses. You may disable caching for these types of requests using either of the following methods:
- Rules: Create a rule that enables the Bypass Cache feature for the desired set of traffic.
- CDN-as-Code:
JavaScript./routes.js1new Router()2 .get('/random-numbers', {3 caching: {4 "bypass_cache": true,5 },6 })
How do I know if a response was served from the cache?
Responses served from cache contain the x-cache: HIT response header.
Caching During Development
By default, caching is disabled during local development. This configuration prevents stale responses from being served after making changes to your code or upstream APIs. Enable caching during local development by passing the
--cache
option when running the Edgio CLI in development mode:Bash
1edgio dev --cache
The cache will automatically be cleared when you make changes to your router.