View Source http_cache_store behaviour (http_cache v0.1.0)
The behaviour for 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
header. A so called candidate is a response that matches request information. The main http_cache
module is in charge of selecting a response according to the vary header.
http_cache
request all the potential responses (candidates) usinglist_candidates/1
http_cache
selects the freshest response whose vary header matcheshttp_cache
request the response withget_response/1
Link to this section Summary
Types
The body transmitted to the backend
Options for the backend store
A unique, opaque, key for a request taking into account the request's information (method, URL, body and bucket)
Stored HTTP response with its metadata
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
.Opaque URL digest as computed by the main module
Normalized headers on which the response varies
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 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 :: http_cache:status(), RespHeaders :: http_cache:headers(), VaryHeaders :: vary_headers(), RespMetadata :: response_metadata()}.
-type opts() :: any().
-type request_key() :: binary().
-type response() :: {Status :: http_cache:status(), Headers :: http_cache: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 response_metadata() :: #{created := http_cache:timestamp(), expires := http_cache:timestamp(), grace := http_cache:timestamp(), ttl_set_by := header | heuristics, parsed_headers := #{binary() => term()}, alternate_keys := [http_cache:alternate_key()]}.
-type response_ref() :: http_cache_store:response_ref().
http_cache:get/2
and used as a parameter by http_cache:notify_response_used/2
.
-type url_digest() :: binary().
-type vary_headers() :: #{binary() := binary() | undefined}.
Link to this section Callbacks
-callback get_response(RespRef :: response_ref(), Opts :: opts()) -> response() | undefined.
-callback invalidate_by_alternate_key([AltKeys :: http_cache:alternate_key()], Opts :: opts()) -> http_cache:invalidation_result().
-callback invalidate_url(UrlDigest :: url_digest(), Opts :: opts()) -> http_cache: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()}.