Caching

Environments and Caching #

Edge and Shield Caching #

• 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.

Default Caching Policy #

Caching a Response #

Cache Directives (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.

• 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 an Expires header, then the Cache-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 #

CDN-as-Code #

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 #

Customizing the Cache Key #

• 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

• Add the page and filters 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 the page and filters query string parameters.
  Add a query string parameter by typing its name and pressing ENTER.
  • CDN-as-Code:
    JavaScript./routes.js

    Copy

    1router.get('/some/path', {
    2  caching: {
    3    // Other options...
    4    cache_key_query_string: {
    5      include: ['page', 'filters'],
    6    },
    7  },
    8});

• Add the language and currency 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}
  • CDN-as-Code:
    JavaScript./routes.js

    Copy

    1router.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}
  • CDN-as-Code:
    JavaScript./routes.js

    Copy

    1router.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});

Caching Responses for POST and PUT Requests #

• Rules: Create a rule that sets the Enable Caching for Methods feature to POST, PUT, or both HTTP methods.
• CDN-as-Code:
  JavaScript./routes.js

  Copy

  1router.get('/some/path', {
  2  caching: {
  3      "enable_caching_for_methods": ["POST", "PUT"],
  4    }
  5});

Caching Private Responses #

• Rules: Create a rule that enables the Ignore Origin No Cache feature.
• CDN-as-Code:
  JavaScript

  Copy

  1router.get('/some/path', {
  2  caching: {
  3    ignore_origin_no_cache: true,
  4  },
  5});

Client Caching #

• Cache directives, such as Cache-Control: max-age and Expires.
• Set Client Max Age feature.

Revalidation #

• 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 unconditional GET request to the origin.

Cache Hit Ratio Optimization #

• 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.js

    Copy

    1new 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 #

• Rules: Create a rule that enables the Bypass Cache feature for the desired set of traffic.
• CDN-as-Code:
  JavaScript./routes.js

  Copy

  1new 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? #

Caching During Development #

1edgio dev --cache