Caching Configuration

There are two caches that you can configure behavior for, the client cache (the cache in the requesting browser) and the cloud cache (the cache on our proxies) .

Both caches can be configured inside any then_action block at any level in the configuration tree. Often there will be default cache and cloud_cache blocks at the property level which will apply to all domains unless overridden within then_action blocks.

Client cache configuration

The following fields can be used to control caching in the client cache:

Field or blockDescription
policyCan be HTTP_HEADER, BYPASS, or FIXED_TTL. These are defined as follows:
  • HTTP_HEADER: Following the HTTP 1.1 caching specification, use the cache-control headers that are provided by the origin server to determine the caching policy. This is the default value.
  • BYPASS: Do not query the cache. The request is sent directly to the origin server, and we do not store the response.
  • FIXED_TTL: Use TTL values provided in the ttl parameter.

The default is HTTP_HEADER.

ttlUsed to specify the TTL only if policy is set to FIXED_TTL; not used otherwise. It consists of an integer value suffixed by either s (seconds), m (minutes), h (hours), or d (days). For example,
"ttl" : "30d"
must_revalidate

Flag to enable or disable adding a must-revalidate directive to the cache control headers sent to client when policy is FIXED_TTL.

The default is true.

override_origin_cache_control

Flag to override the origin cache-control header when the cache policy is FIXED_TTL. When not set, max-age is appended to the cache-control header sent from origin. 

The default is true.

The following example sets a policy of FIXED_TTL with the TTL specified as 30 days for the client cache.

"client_cache" : {
  "policy" : "FIXED_TTL",
  "ttl" : "30d"
}

Cloud cache configuration

The following fields and blocks can be used to control caching in the cloud cache:

Field or blockDescription
policyCan be HTTP_HEADER, BYPASS, or FIXED_TTL. These are defined as follows:
  • HTTP_HEADER: Following the HTTP 1.1 caching specification, use the cache-control headers that are provided by the origin server to determine the caching policy. This is the default value.
  • BYPASS: Do not query the cache. The request is sent directly to the origin server, and we do not store the response.
  • FIXED_TTL: Use TTL values provided in the ttl parameter.

The default is HTTP_HEADER.

ttlUsed to specify the TTL only if policy is set to FIXED_TTL; not used otherwise. It consists of an integer value suffixed by either s (seconds), m (minutes), h (hours), or d (days). For example,
"ttl" : "30d"
enable_post_cache

Flag to enable or disable storing and lookup of POST responses. If this option is set to true, POST responses are cached and subsequent POST requests which match will be looked up from cache. Note that when this option is enabled, a modifier needs to be specified in the cache_key block, so that the POST request body is used in some form as part of the cache key.

Revalidation/stale_if_error is not done for expired POST responses.

A POST response with 200 status code is cached. A POST response with non-200 status code is cached if cacheable_non_200 is specified and there is a status match.

The cache key modifier should include the POST request body in some way (for example, the md5sum of the request body). This is required to distinguish POST requests that have the same base key (i.e. same path). Currently, the validation code checks for modifier being non-empty and an Nginx variable. A constant value for modifier will cause validation to fail.

The default value is false.

post_cache_ttlThis field specifies the TTL for caching POST responses. This can be changed in on_response block since it is a cache store-specific parameter. It consists of an integer value suffixed by either s (seconds), m (minutes), or h (hours). The minimum allowed value is 1s and the maximum allowed value is 1h. The default value is 60s.
cluster_nameName of the datastore cluster. If not specified the default cluster for the customer will be used.
cache_keySpecifies how the cache lookup key is generated; see below.

The blocks can listed above are further defined below.

cache_key

This block specifies options for how the cache lookup key is generated. The fields are:

Field or blockDescription
cache_key_domainOptional field specifying hostname to use when generating the cache lookup key. There are cases when there are multiple hostnames pointing to the same content (virtual domains). This field is used to capture this information. If this is set, the cache lookup key generation logic uses cache_key_domain instead of the hostname to set the cache namespace.
drop_query_stringOptional boolean flag to drop the query from being used when generating the cache lookup key.
ignore_query_params

Specifies a list of query parameter keys to drop from the query string part of the cache lookup key. For example, if it is set to

ignore_query_params = ['bar']

then the URL

?/a/b?foo=123&bar=hello&baz=99

will be cached as

/a/b?foo=123&baz=99

When query parameters to ignore are specified, the order of the remaining query parameters is preserved.

drop_protocol

Optional boolean flag to drop the protocol from being used when generating the cache store/lookup key. We will store objects assuming the protocol is http when this field is set to true.

modifierSpecifies any additional value that should be used as part of the cache store/lookup key. If a value is specified here, it will be used in addition to the path, query string and protocol (obtained from the incoming request) for constructing the cache key. The value can be specified as either a regular string or as an Nginx variable.

Important

Be careful using drop_protocol. For example, you should never drop protocol for cacheable HTML pages. If you have any questions, please contact Support.

Also note that JavaScript Streaming does not work if the property configuration uses a cache key modifier. For example, if a customer config has the following block present:


"edge" : { "cloud_cache" : { "cache_key" : { "modifier" : "hc" } } }

then JavaScript Streaming will not work. The JS Streaming service sends the original JS as profiled JS and adds a response header, X-Instart-OriginalAlias: TRUE, to indicate this.

lookup

This block specifies options for controlling how the cached objects are fetched from the cache. The fields are:

Field or blockDescription
head_lookup

Allow cache lookup of HEAD request. This does not result in the HEAD content being stored in the cache, it only causes the cached headers of an earlier GET request to be returned as the HEAD response.

The default is false.

revalidate_if_stale

Enable revalidation for expired objects. This capability allows our service to do a lightweight check with a customer's origin web server when a static object cached in our system expires. If the object is still the same, we then update the expiry time for the existing object in our system without needing to re-download the object. Previously our system would remove and re-request objects once they expired. In the case of images, this would require us to re-run image processing operations such as transcoding on the object. This feature reduces the loading on the customer's back-end origin servers and reduces loading on our service.

The Cache-Control headers (and config) enable the proxy to determine how fresh a cached object is. Any request for a non-stale cached object will result in the cached object being sent back to the client.

Once an object is stale, we have to re-download the entire object from the origin. If the stale object has ETag and/or Last-Modified headers, it is possible for the proxy to make a GET request with If-None-match> and/or If-Modified-Since headers. If the object has not changed from the origin’s point of view, it returns a 304 response with no body instead of sending the whole (unchanged) object again.

Revalidation is triggered only when an object fetched from the cache is past its TTL. We use both ETag and Last-Modified for revalidation.

Revalidation is not triggered if

  • this option is set to false
  • if the cache policy is not HTTP_HEADER or FIXED_TTL
  • if both ETag and Last-Modified headers are not present

Revalidation is valid only for 200 status code for GET requests, and optionally for HEAD requests (the revalidated response is not stored).

This field can be true only if the effective cache policy is HTTP_HEADER or FIXED_TTL.

The default is true.

serve_stale_if_origin_error

Enables serving of stale objects if the origin returns certain error codes. We handle 500, 502, 503, 504 error codes and origin timeouts.

This field is valid only if the cached response status is 200 and for GET requests, and optionally for HEAD requests. The TTL of the cached response is not extended.

Policy should be FIXED_TTL or HTTP_HEADER.

The default is false.

stale_if_error_ttl

Used to specify the time interval until stale objects can be served from cache in case of origin errors. This will be used if the policy is FIXED_TTL or HTTP_HEADER. We do not use the value from stale-if-error in cache control. If serve_stale_if_origin_error is enabled, stale_if_error_ttl has to be set explicitly.

The value is followed by a suffix specifying the time unit:  s for seconds, m for minutes. For example, 5m sets the stale if error TTL to 5 minutes (300 seconds).

The default is 60s.

store

This block specifies options for what objects will be stored in the cache. The fields are:

Field or blockDescription
cacheable_non_200

List of HTTP status codes that we will consider cacheable, with a TTL for each. Every non-cacheable status code needs to have a corresponding TTL.

The values for status_code can be any HTTP status code except 200 and 304.

The default value is 60s; there is no maximum limit.

If a cached object with a non-200 status code has Etag or Last-Modified response headers, we do not perform revalidation when it expires. Instead we send a regular GET request to the origin and handle the response in the same way as we would a cache miss. (Note that the fetch_status field in the access log will still say expired.)

non_accept_encoding_vary_is_cacheable

Boolean flag to specify whether or not we cache responses that have a Vary header value other than accept-encoding. The common header that is used is Vary: User-Agent.

We can always cache Vary: Accept-Encoding as we are able to re-compress the content into whatever format the browser is able to handle.

The default is false.

html_is_cacheable

Whether or not we cache responses that have an HTML MIME type of

  • text/html
  • text/xhtml
  • text/xml
  • text/xml+xhtml
  • application/html
  • application/xhtml
  • application/xml
  • application/xml+xhtml

The default is false.



Examples

The following simple example sets a policy of FIXED_TTL with the TTL specified as 30 days:

"cloud_cache" : {
  "policy" : "FIXED_TTL",
  "ttl" : "30d"
 }

The following example

  • sets a policy of FIXED_TTL with the TTL specified as 365 days
  • specifies that the cache lookup key does not include the query string from the request
  • specifies that we don't revalidate expired objects
"cloud_cache": {
  "policy" : "FIXED_TTL",
  "ttl" : "365d",
  "cache_key" : {
    "drop_query_string" : true
  }
  "lookup" : {
    "revalidate_if_stale" : false
  }
}

The following example

  • sets a policy of FIXED_TTL with the TTL specified as 2 minutes
  • specifies that HTML is cacheable and that responses with a redirect status code (301 or 302) have a TTL of 10 minutes
  • allows cache lookup of HEAD request, and will serve stale content in the event of an origin error with a TTL of 2 minutes
"cloud_cache" : {
  "policy" : "FIXED_TTL",
  "ttl" : "2m",
  "store" : {
    "html_is_cacheable" : true,
    "cacheable_non_200" : [
      {
        "status_code" : 301,
        "ttl" : "600s"
      },
      {
        "status_code" : 302,
        "ttl" : "600s"
      }
    ]
  },
  "lookup" : {
    "head_lookup" : true,
    "serve_stale_if_origin_error" : true,
    "stale_if_error_ttl" : "2m"
  }
}

The following example specifies that HTTP status codes 301, 302, and 404 are stored in the cache, each with a TTL of 180 seconds.

"cloud_cache" : {
  "store" : {
    "cacheable_non_200" : [
      {
        "status_code" : 301,
        "ttl" : "180s"
      },
      {
        "status_code" : 302,
        "ttl" : "180s"
      },
      {
        "status_code" : 404,
        "ttl" : "180s"
      }
    ]
  }
}