Integralist/Example System Contract for Caching Behaviours.md

## Example System Contract for Caching Behaviours.md

      
    Raw
  

              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