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. AnETag
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 thisETag
in the cache along with each response. If the cache contains a response for an incoming request, the Cook includes that response'sETag
in the request it forwards to the Content Store. The Content Store checks thisETag
against theETag
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 cachedETag
, and if the Content Store says theETag
is still valid, the cached response is returned to the waiter. If theETag
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 anETag
. 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.