Skip to main content

HTTP Caching

Konifer exposes highly-customizable Cache-Control headers. Due to the relative nature of the API, no assumptions are made regarding the appropriate Cache-Control header to apply to an asset.

Cache-Control Configuration​

The Cache-Control header can be configured per-path. The following options are available:

PropertyDescriptionAllowed InputDefault
enabledWhether the Cache-Control header should be returnedBooleanfalse
max-ageSet the max-age descriptorInteger > 0
s-maxageSet the max-age descriptorInteger > 0
visibilitySet the visibility of the cached assetpublic, private
revalidateCache control revalidationmust-revalidate, proxy-revalidate, no-cache
stale-while-revalidateSet the stale-while-revalidate descriptorInteger > 0
stale-if-errorSet the stale-if-error descriptorInteger > 0
immutableWhether to set the immutable descriptorBooleanfalse
caution

Konifer does not validate proper semantic Cache-Control configurations.

Usage​

To configure, specify properties within the cache-control block of your path configuration. You can explore more about the proper usage of Cache-Control header directives.

{
paths = {
"/users" {
cache-control {
enabled = true
max-age = 1000000
s-maxage = 2000000
immutable = true
}
}
}
}

ETags​

ETags and conditional requests are enabled for content and download, regardless of cache-control configuration. Each ETag identifies the selected representation and changes when its variant or asset metadata changes. Raw pixels use weak validators (W/); image formats use strong validators.

A matching If-None-Match returns 304 Not Modified without a response body. When both If-None-Match and If-Modified-Since are supplied, If-None-Match takes precedence. See the MDN ETag header documentation for more information.