Configuring Object Caching with the Performance & Delivery Rule Builder

Important

The rule builder only works with the V2 config framework. If you see the text "configuration is not supported" on the Performance & Delivery Rules screen, you will need to have Instart migrate your configuration format. Please contact your account executive to initiate this migration. If you have the V1 configuration format, you will continue to have limited self-service control over your caching policy and over performance features JavaScript Streaming, Image Transcoding, and Brotli Compression until your configuration is updated. Refer to Delivery and Performance Configuration Overview for details.

This document describes how to use the Performance & Delivery Rules builder to create rules to control the caching of objects.

For general information about the Performance & Delivery Rules screen, see Configuring Performance & Delivery Rules in the Portal. For a detailed description of how caching is handled by the platform, see How the Instart Platform Handles Caching.

In the rule builder screen, select criteria you want to use to decide to set up caching rules. Then specify Cache Lookup and/or Cache Store settings.

For example, here we set Drop query string and Drop protocol to true for the cache lookup key, and set the Client caching policy to Bypass and the Cloud caching policy to a Fixed TTL of 12 minutes:

These settings are described below.

Cache lookup

These settings define the way the cache lookup key is created. By default, an object's path, protocol, and query string (if present) are all used to generate a lookup key to identify the cached object.

The settings you can make are

Drop query string

Set to True, the query string will not be included in the cache lookup key.

Custom allows you to ignore a specified portion of the query string.

Drop protocol

Set to True, the protocol will not be included in the cache lookup key.

Additional modifier

You can further specify an object's cache lookup key by including additional cache key modifiers in the rule. You can, for example, specify that if a particular cookie, or header, is present in the request, the service will incorporate these in creating the cache key.

Cache store

These settings define the way cache policy that is applied to cached objects.

There are three possible policy settings for a caching rule:

  • HTTP header-based (default)
  • Fixed TTL (time to live)
  • Bypass

HTTP header-based

If configured in this way, we cache the response based on the response headers. We defer to our customer’s origin headers as being authoritative and act appropriately based on their HTTP response headers.

  • Only HTTP Status 200 responses to GET requests are cached.
  • HTML MIME types text/html, text/xml, text/xml+xhtml, text/xhtml and application/html, application/xml, application/xml+xhtml, application/xhtml are not cached by default. We can enable caching of HTML MIME types in the configuration if desired.
    Vary: responses that vary on headers other than accept-encoding are cached by default. We can modify this in the configuration if desired.
  • We support revalidation with the origin by default.
  • The following header directives will never be cached:
    • Cache-Control: no-cache
    • Cache-Control: no-store
    • Cache-Control: private
    • Pragma: no-cache
    • Vary: *

If Cache-Control: no-cache=<list of headers> or Cache-Control: private=<list of headers>, we only prevent the specified headers from being cached. This does not cause the response itself to be uncacheable.

  • A response must have at least one of the following headers to be cached. If cache directive headers are missing, then the response is not cached.
    • Cache-Control: max-age
    • Cache-Control: s-maxage
    • Cache-Control: public
    • Expires

Note

Responses without Cache-Control headers may be cached – see below.

The max-age, s-maxage TTL is calculated as follows:

max-age TTL = (value of max_age) – (value of the Age header if present)

max-age TTL = now − (value of Date header) if only the Date header is present

The Expires TTL is calculated as follows:

Expires TTL = (value of the Expires header) − now.

If the response has Cache-Control: public, but no other caching directives, then it is cached by default for a predefined time (7200 seconds) set globally for the Instart service.

For request headers: Cache-busting request headers (for example, a request with Cache-Control: no-cache or Pragma: no-cache) will not bypass the cache by default. This can be changed in the configuration if desired.

Fixed Time to Live (TTL)

If configured in this way, we cache the response with a given fixed TTL that is specified in the configuration. This overrides all Cache-Control headers, including Cache-Control: private, Cache-Control: no_cache, Cache-Control: no_store, Cache-Control: s-maxage, Cache-Control: max-age, and Expires.

  • All HTTP Status 200 responses to GET requests are cached.
  • HTML MIME types text/html, text/xml, text/xml+xhtml, text/xhtml and application/html, application/xml, application/xml+xhtml, application/xhtml are not cached by default. We can enable caching of HTML MIME types in the configuration if desired.
  • Vary: responses that vary on headers other than accept-encoding are cached by default. We can disable this in the configuration if desired.
  • Cache object lifetime is TTL + retrieval_time, where retrieval_time is the time that the proxy first downloads the object from the origin server.

Bypass

Caching can be bypassed, in which case we go straight to the origin server, and we do not store the response.