13. Cache Control

This section describes features that influence how the CTL CDN caches content.

13.1. Query String Handling

Configuration Definition: Match Rule
Configuration Application: Match Rule
Default Behavior: Off/Disabled
Limitations: None
Version: 16.1

By default, the CTL CDN includes any query string parameters included in the request URL as part of an object cache key. Depending on whether the query strings are dynamic or unique to the requesting client, considering them as part of the cache key can have a negative impact on a property’s cache hit rate. If query strings are dynamic or unique to the requesting client but do not influence the actual returned content, it may be desirable to exclude query string parameters from the request URL. Query string handling can be managed via a Boolean operator or via a Lua script for more granular control.

The Boolean operator QSHMode simply includes or excludes query string parameters. When enabled, it ignores all query string parameters present in the request URL when looking in the cache for the object. QSHMode is configured per match rule as shown below:

"matchGroups": [
  {
    "id": 184286,
    "matchRules": [
      {
        "expression": "/",
        "id": 1842860,
        "features": {
           "qshMode": {
            "value": true
          }
        }
      }
    ]
  }
]

For more granular control, a Lua script can be crafted to influence which parameters are included/excluded from the URL when performing cache lookups.

13.2. Cache Control Header Over-ride

Configuration Definition: Match Rule
Configuration Application: Match Rule
Default Behavior: Off/Disabled
Limitations: None
Version: 16.1

The Cache Control Header Over-ride (CCHO) feature allows for any origin provided Cache Control information to be over-ridden, if present, or applied, if absent, from Origin responses to fill requests. This is accomplished by applying the CCHO feature to a Match Rule as shown in the example below:

"matchGroups": [
  {
    "id": 184286,
    "matchRules": [
      {
        "expression": "/",
        "id": 1842860,
        "features": {
          "ccho": {
            "value": {
              "int": {
                "cachePolicy": "as-is"
              },
              "ext": {
                "force": true,
                "cachePolicy": "no-cache"
              }
            }
          }
        }
      }
    ]
  }
]

The CCHO feature can have both and internal (int) and external (ext) policy. The internal CCHO policy instructs the CDN as to how it should cache the object. The external policy instructs the CDN as to what information to include in the response send to the client, influencing how the client caches the received content.

Both the ‘int’ and ‘ext’ cachePolicy can take either an integer value, or one of ‘as-is’, ‘no-cache’ and ‘no-store’. Integer values are used to define the actual cache policy and may optionally be followed by one of the letters s,m,h,d,w or y to indicate that the value is expressed in units of seconds, minutes, hours, days, weeks or years respectively. If no units are specified, the value is assumed to be expressed in seconds. Years are defined as 365 days; no attempt is made to correct for leap years.

When the int cachePolicy is set to a positive number, it is interpreted as if it were a max-age header when determining the internal cache lifetime.

Note

The minimum value currently allowed for the int cachePolicy is 30 seconds. If a lower value is needed, please contact CDN support for assistance.

If the int cachePolicy is set to “no-cache”, the resource is pre-expired at the CDN Node – that is, it is cached but the next request for it will trigger a revalidation to the origin. This matches the meaning of “Cache-Control: no-cache”.

Setting the int cachePolicy to “no-store” will prevent the resource from being cached in the CDN Nodes (ie, it behaves as if the origin server had added a “Cache-Control: no-store” header).

Setting the ext cachePolicy to a positive value, will result in a ‘Cache-Control: max-age’ and/or an ‘Expires:’ header being added to the resource, with the values set appropriately given the Date: at the time the resource is served from cache, and the value of ‘ext’. (The ‘Expires:’ header is currently being added to the resources served from cache based on the time of resource load and max-age).

If the ext cachePolicy is set to ‘no-cache’, then an explicit ‘no-cache’ policy is added when the resource is served from the cache - ie, both ‘Pragma: no-cache’ and ‘Cache-Control: no-cache’ headers are added.

Finally, if the ext cachePolicy is set to “no-store”, a ‘Cache-Control: no-store’ header is added, together with a ‘Pragma: no-cache’ for older caches.

Ext cachePolicy manipulation is NOT performed if the resource had a cache control policy when served from the origin server, unless the optional ‘force’ attribute is added to the ext policy definition. In that case, any existing cache headers are removed in favour of the external headers added due to the values of the ext cachePolicy.

13.3. Stale Content Control

Configuration Definition: N/A
Configuration Application: Match Rule
Default Behavior: Off/Disabled
Limitations: None
Version: 19.9

The Stale Content Control feature allows the CDN to serve stale content to client requests, as described in rfc5861. This is a performance optimization and may not work well for all content types.

The CTL CDN supports both Cache-Control extensions - stale-if-error and stale-while-revalidate. Control for the use of these extensions is managed under a match rule as described in the following sections.

Note that using a stale cached response can also be enabled directly via the Origin servers response header, for a specified number of seconds after the response became stale. This has lower priority than using the feature definitions defined below. Specifically, the feature works as follows:

  • If the feature is disabled, the CDN will NOT serve stale content. However, the CDN will honor any Cache-Control extensions provided by the origin.
  • If the feature is enabled, the provided configuration will take precedence over any corresponding Cache-Control extensions provided by the origin.

13.3.1. stale-if-error

The stale-if-error feature allows the CDN to return a stale response when an error – e.g., a 500 Internal Server Error, a network segment, or DNS failure – is encountered, rather than returning a “hard” error to the client. This improves availability.

"staleContentControl":
{
  "features":
  {
    {
      value:
      {
        staleIfError:
        {
          enabled: true,
          http_5xx_errors: false,
          http_4xx_errors: true
        }
      }
    }
  }
}

At least one of the error conditions must be selected for the configuration to be valid.

  • 4xx - http_403 | http_404 | http_429
  • 5xx - http_500 | http_502 | http_503 | http_504

In both cases, errors or timeouts when trying to communicate with an upstream (intra CDN and to Origin) are consider an eligible error for serving stale content.

13.3.2. stale-while-revalidate

The stale-while-revalidate feature allows the CDN to immediately return a stale response while it revalidates the stale content it in the background, thereby hiding latency (both in the network and on the server) from clients.

"staleContentControl":
{
  "features":
  {
    {
      value:
      {
        staleWhileRevalidate:
        {
          enabled: true
        },
      }
    }
  }

When enabled the CDN will return cached, but stale, content to the client while revalidating the object in the background for the next request.