PlugCacheControl (Plug.CacheControl v0.2.1)
A plug for overwriting the default cache-control
header. The plug supports
all the response header directives defined in RFC7234, section
5.2.2.
The plug takes a directives
option which can specify either static or
dynamic header directives. Static directives are useful when you don't need
per-request directives. Static directives are defined very similarly to a
struct's key.
plug Plug.CacheControl, directives: [:public, max_age: {1, :hour}]
As seen in the above example, directive names with hyphens are mapped to atoms by replacing the hyphens with underscores.
Boolean directives like public
, private
, must-revalidate
, no-store
and
so on can be included in the header value by simply including them in the
directives list e.g. no need for explicit no_store: true
value. Note that as
per the standard, no-cache
can also specify one or more fields. This is
supported via the definition below.
plug Plug.CacheControl, directives: [no_cache: ["somefield", "otherfield"]]
The public
and private
directives also have somewhat special handling so
you won't need to explicitly define private: false
when you've used
:public
in the "boolean section" of the directives list. Another important
thing is that if a directive is not included in the directives list, the
directive will be omitted from the header's value.
The values of the directives which have a delta-seconds values can be defined directly as an integer representing the delta-seconds.
plug Plug.CacheControl, directives: [:public, max_age: 3600]
A unit tuple can also be used to specify delta-seconds. The supported time
units are second
, seconds
, minute
, minutes
, hour
, hours
, day
,
days
, week
, weeks
, year
, years
. The following example shows how unit
tuples can be used as a conveniece to define delta-seconds.
plug Plug.CacheControl,
directives: [
:public,
max_age: {1, :hour},
stale_while_revalidate: {20, :minutes}
]
Dynamic directives are useful when you might want to derive cache control directives per-request. Maybe there's some other header value which you care about or a dynamic configuration governing caching behaviour, dynamic directives are the way to go.
plug Plug.CacheControl, directives: &__MODULE__.dyn_cc/1
# ...somewhere in the module...
defp dyn_cc(_conn) do
[:public, max_age: Cache.get(:max_age)]
end
As seen in the previous example, the only difference between static and dynamic directives definition is that the latter is a unary function which returns a directives list. The exact same rules that apply to the static directives apply to the function's return value.