View Source http_cache_store_behaviour behaviour (http_cache_store_behaviour v0.3.0)
The behaviour for http_cache response stores
Keep in mind that for a unique combination of a request's method, URL, body and bucket, there still can be several different responses, depending on the vary and content-range headers. A so called candidate is a response that matches request information independently of these two headers. The main http_cache module is in charge of selecting a response that satisfies these two headers.
One possibility is to include vary and content-range in the key. The content-range header, if the returned response is a 206 Partial Response, is stored in the request metadata (#{parsed_headers := #{<<"content-range">> := {bytes, 3, 10, 20}}} for instance).
http_cacherequest all the potential responses (candidates) usinglist_candidates/1http_cacheselects the freshest response whosevaryandcontent-rangeheaders matchhttp_cacherequest the response withget_response/1
Link to this section Summary
Types
Alternate key attached to a stored response
The body transmitted to the backend
Request or response headers
Options for the backend store
A unique, opaque, key for a request taking into account the request's information (method, URL, body and bucket)
Opaque backend's reference to a response, returned by
http_cache:get/2 and used as a parameter by http_cache:notify_response_used/2.HTTP status
Stored HTTP response with its metadata
UNIX timestamp in seconds
Opaque URL digest as computed by the main module
Headers taken into account by vary
Callbacks
Returns a response from a response reference returned by list_candidates/1
Invalidates all responses for a given URL digest
Returns the list of candidates matching a request, via its request key
Notify that a response was used. A LRU cache, for instance, would update the timestamp the response was last used
Stores a response and associated metadata
Link to this section Types
-type alternate_key() :: term().
-type body() :: binary().
The body transmitted to the backend
This is a binary so as to optimize copying around data: an IOlist would have to be copied whereas (big) binaries are simply reference-counted.-type candidate() :: {RespRef :: response_ref(), Status :: status(), RespHeaders :: headers(), VaryHeaders :: vary_headers(), RespMetadata :: response_metadata()}.
-type headers() :: [{binary(), binary()}].
-type opts() :: any().
-type request_key() :: binary().
-type response_metadata() :: #{created := timestamp(), expires := timestamp(), grace := timestamp(), ttl_set_by := header | heuristics, parsed_headers := #{binary() => term()}, alternate_keys := [alternate_key()]}.
-type response_ref() :: term().
http_cache:get/2 and used as a parameter by http_cache:notify_response_used/2.
-type status() :: pos_integer().
-type stored_response() :: {Status :: status(), Headers :: headers(), BodyOrFile :: body() | {file, file:name_all()}, Metadata :: response_metadata()}.
Stored HTTP response with its metadata
The body can either be a binary (for example if the response is stored in memory) or a file (if the response is stored on disk).-type timestamp() :: non_neg_integer().
-type url_digest() :: binary().
-type vary_headers() :: #{binary() := binary() | undefined}.
Link to this section Callbacks
-callback get_response(RespRef :: response_ref(), Opts :: opts()) -> stored_response() | undefined.
-callback invalidate_by_alternate_key([AltKeys :: alternate_key()], Opts :: opts()) -> invalidation_result().
-callback invalidate_url(UrlDigest :: url_digest(), Opts :: opts()) -> invalidation_result().
-callback list_candidates(RequestKey :: request_key(), Opts :: opts()) -> [candidate()].
-callback notify_response_used(RespRef :: response_ref(), Opts :: opts()) -> ok | {error, term()}.
-callback put(RequestKey :: request_key(), UrlDigest :: url_digest(), VaryHeaders :: vary_headers(), Response :: http_cache_response(), RespMetadata :: response_metadata(), Opts :: opts()) -> ok | {error, term()}.