Skip to content

Instantly share code, notes, and snippets.

  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
What would you like to do?
[Example System Contract for Caching Behaviours] #system #contract #architecture #design #interface #SLA #fastly #cdn


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


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.


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


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.


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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment