Cache Configuration

The Cook forwards incoming requests to the Content Store and passes responses back to the requester (usually the Waiter). The Content Store web service returns data in the form of Atom XML resources, which need to be parsed and converted to JSON objects before they can be returned to the Waiter. This parsing is relatively CPU-intensive. A significant proportion of the requests the Cook handles are repeat requests for the same resources; often resources that change relatively infrequently such as publications, sections, section pages, popular tags and so on.

In order to minimize repeat requests of this kind, the Cook incorporates a cache in which ready-parsed responses are stored for re-use where possible. The cache is an LRU (least recently used) cache with ETag-based validation. This means that:

All responses are saved until the cache is full. Once the cache is full, space for new responses is created by throwing out the least-recently used old response.
The Cook uses a response's ETag to determine whether or not a cached response can still be used. An ETag is a unique ID (such as a checksum) derived from the content of a response that the server (i.e the Content Store) includes in the response header. The Cook saves this ETag in the cache along with each response. If the cache contains a response for an incoming request, the Cook includes that response's ETag in the request it forwards to the Content Store. The Content Store checks this ETag against the ETag of the current content, and if they are identical, returns an empty response indicating that the requested content has not changed. The Cook can then return the cached response. If they are not identical, a full response is returned and used to replace the old cached response.

You can control the details of how the cache behaves by adding settings to the Cook's configuration file, cook-config.yaml. All the settings must be added as children of the shared-cache property. The mostly commonly used settings are:

max

The maximum size of the cache. Once this limit it reached, an old response is thrown out every time a new response is added. The default setting is 5000 responses.

maxAge

The maximum allowed age for cache contents, specified in milliseconds. A cached response which is older than the specified age will initially be regarded as out-of-date or stale. What happens to a stale response is determined by how the stale property is set.

stale

Determines whether or not ETag validation is performed. The possible values are:

true (default): ETag validation is performed for stale responses. The Cook forwards the request to the Content Store along with the cached ETag, and if the Content Store says the ETag is still valid, the cached response is returned to the waiter. If the ETag is not valid then the new response returned from the Content Store is passed back to the Waiter and used to update the cache.
false: ETag validation is not performed for stale responses. The request is forwarded to the Content Store without an ETag. The response is returned to the Waiter and used to update the cache.

The following examples show how the maxAge and stale properties work together:

maxAge=0, stale=false: Caching is disabled.
maxAge=0, stale=true: ETag validation is performed on all cached responses.
maxAge=2000, stale=false: Cached responses under 2 seconds old are used without validation, older responses are not used at all.
maxAge=2000, stale=true: Cached responses under 2 seconds old are used without validation, ETag validation is performed on all older responses.

Here is an example cache configuration:

shared-cache:
  max: 10000 # default: 5000
  maxAge: 5000 # 5 seconds
  stale: false # default: true

The cache does have additional settings that you might find useful in some circumstances. For full information, see here. Note, however, that the Cook only supports the use of properties with simple values. Properties such as length and dispose that require functions as values are not supported.

For general information on how to add configuration properties to cook-config.yaml so that they will not be overridden by CUE Front upgrades, see Overriding Setup Defaults.