[Example System Contract for Caching Behaviours]

View original Gist on GitHub

Tags: #system #contract #architecture #design #interface #SLA #fastly #cdn

Example System Contract for Caching Behaviours.md

Caching

• Cache-Control: used if provided, otherwise default will be set.
• Surrogate-Control: augmented if provided, otherwise default will be set.

Augmentation

Perimeter will augment the provided Surrogate-Control by appending stale-while-revalidate and stale-if-error directives if they are not defined.

See also “Extensions” section below.

Defaults

If no Cache-Control nor Surrogate-Control is provided, Perimeter will use the following default caching/stale directives:

• Cache-Control: no-store
• Surrogate-Control: max-age=%d, stale-while-revalidate=%d, stale-if-error=%d

Note: %d is a placeholder for the actual value set in Perimeter’s config.yml

Exceptions

There are a few exceptions to the defaults defined above:

• Static file requests (i.e. proxied to AWS S3) will have a longer max-age (it uses the stale-if-error value).
• Smoke requests (see smoke_path in config.yml) disables all caching.

Extensions

Both Cache-Control and Surrogate-Control have additional directives related to serving stale content, which are not part of the core HTTP caching standards document. These are stale-while-revalidate and stale-if-error.

Fastly CDN supports both of these extension directives via Surrogate-Control, but client compatibility (i.e. web browser support) via Cache-Control is less consistent.

Perimeter will only augment Surrogate-Control, it will not augment Cache-Control.

Status Codes

The CDN will only cache the following status code responses:

• 200 OK
• 203 Non-Authoritative Information
• 300 Multiple Choices
• 301 Moved Permanently
• 302 Moved Temporarily
• 404 Not Found
• 410 Gone