-type alternate_key() :: term().

Alternate key attached to a stored response

-type headers() :: [{binary(), binary()}].

Request or response headers

-type opts() ::
    #{store := module(),
      alternate_keys => [alternate_key()],
      allow_stale_while_revalidate => boolean(),
      allow_stale_if_error => boolean(),
      auto_accept_encoding => boolean(),
      auto_compress => boolean(),
      auto_decompress => boolean(),
      bucket => term(),
      compression_threshold => non_neg_integer(),
      origin_unreachable => boolean(),
      default_ttl => non_neg_integer(),
      default_grace => non_neg_integer(),
      ignore_query_params_order => boolean(),
      max_ranges => non_neg_integer(),
      prevent_set_cookie => auto | boolean(),
      request_time => non_neg_integer(),
      store_opts => http_cache_store_behaviour:opts(),
      type => type()}.

Options passed to the functions of this module

• alternate_keys: alternate keys associated with the stored request. Requests can then be invalidated by alternate key with invalidate_by_alternate_key/2. Use by cache/3 and cache/4.
• allow_stale_while_revalidate: allows returning valid stale response while revalidating. Used by get/2. Defaults to false.
• allow_stale_if_error: allows returning valid stale response when an error occurs. See https://datatracker.ietf.org/doc/html/rfc5861#section-3. Used by get/2. Defaults to false.

• auto_accept_encoding: automatically selects an acceptable response based on accept-encoding and content-encoding headers.

  Compressed response vary on the exact value accept-encoding header. For example, gzip, brotli, brotli, gzip, brotli,gzip and gzip;q=1.0, brotli;q=1.0 are equivalent but considered different because their string representation do not match. So, if a response of a request with the accept-encoding: gzip is cached, none of the abovementionned variations would result in returning the cached response. When set to true, this options allows automatically returning acceptable content when available even when headers don't exactly match.

  Doesn't take priority into account (except for priority 0 which is discarded).

  Used by get/2. Defaults to false.

• auto_compress: automatically compresses decompressed text responses with gzip. This can help with reducing the size of stored content. Moreover, most browsers do support gzip encoding.

  When this option is used, auto_decompress is automatically set to true as well.

  Does not compress responses with strong etags (see https://bz.apache.org/bugzilla/show_bug.cgi?id=63932).

  Used by cache/3 and cache/4. Defaults to false.

• auto_compress_mime_types: the list of mime-types that are compressed when auto_compress is used.

  Used by cache/3 and cache/4. Defaults to [<<"text/html">>, <<"text/css">>, <<"text/plain">>, <<"text/xml">>, <<"text/javascript">>, <<"application/javascript">>, <<"application/json">>, <<"application/ld+json">>, <<"application/xml">>, <<"application/xhtml+xml">>, <<"application/rss+xml">>, <<"application/atom+xml">>, <<"image/svg+xml">>, <<"font/ttf">>, <<"font/eot">>, <<"font/otf">>, <<"font/opentype">> ]

• auto_decompress: automatically decompresses stored gzip responses when the client does not support compression.

  Does not decompress responses with strong etags (see https://bz.apache.org/bugzilla/show_bug.cgi?id=63932).

  Used by get/2, cache/3 and cache/4. Defaults to false.
• bucket: an Erlang term to differentiate between different caches. For instance, when what needs to use several private caches, this option can be used to differentiate the cached responses and prevent them from being mixed up, potentially leaking private data. Used by get/2, cache/3 and cache/4. Defaults to the atom default.

• compression_threshold: compression threshold in bytes. Compressing a very tiny response can result in actually bigger response (in addition to the performance hit of compression it).

  Although there's no additional cost when this library serves a compressed file, but it has a cost on the client that has to decompress it.

  This is why the default value is so high: we want to make sure that it's worth performing compression and decompression.

  See further discussion: https://webmasters.stackexchange.com/questions/31750/what-is-recommended-minimum-object-size-for-gzip-performance-benefits.

  Used by cache/3 and cache/4. Defaults to 1000.
• origin_unreachable: indicates that the current cache using this library is unable to reach the origin server. In this case, a stale response can be returned even if the HTTP cache headers do not explicitely allow it. Used by get/2. Defaults to false.
• default_ttl: the default TTL, in seconds. This value is used when no TTL information is found in the response, but the response is cacheable by default (see https://datatracker.ietf.org/doc/html/rfc7231#section-6.1). Used by cache/3 and cache/4. Defaults to 120.
• default_grace: the amount of time an expired response is kept in the cache. Such a response is called a stale response, and can be returned in some circumstances, for instance when the origin server returns an 5xx error and stale-if-error header is used. Use by cache/3 and cache/4. Defaults to 120.
• ignore_query_params_order: when a response is cached, a request key is computed based on the method, URL and body. This option allows to keep the same request key for URLs whose parameters are identical, but in different order. This helps increasing cache hit if URL parameter order doesn't matter. Used by get/2, cache/3 and cache/4. Defaults to false.
• max_ranges: maximum number of range sets accepted when responding to a range request. This is limited to avoid DOS attack by a client. See https://datatracker.ietf.org/doc/html/rfc7233#section-6.1. Used by get/2. Defaults to 100.
• prevent_set_cookie: when set to auto, raises when the set-cookie is used on shared caches. When set to true, always raises in this case. When set to false, never raises even for shared caches. Used by cache/3 and cache/4. Defaults to auto.
• store: required, the store backend's module name. Used by all functions, no defaults.
• store_opts: the store backend's options. Used by all functions, defaults to [].
• type: cache type. shared or private. A CDN is an example of a shared cache. A browser cache is an example of a private cache. Used by get/2, cache/3 and cache/4. Defaults to shared.
• request_time: the time the request was initiated, as a UNIX timestamp in seconds. Setting this timestamp helps correcting the age of the request between the time the request was made and the time the response was received and cached, which can be several seconds. Used by cache/3 and cache/4.