Struct http_cache_semantics::CachePolicy

pub struct CachePolicy { /* fields omitted */ }

Identifies when responses can be reused from a cache, taking into account HTTP RFC 7234 rules for user agents and shared caches. It's aware of many tricky details such as the Vary header, proxy revalidation, and authenticated responses.

Methods

impl CachePolicy

pub fn new<Req: RequestLike, Res: ResponseLike>(
    req: &Req,
    res: &Res,
    opts: CachePolicyOptions
) -> Self

Cacheability of an HTTP response depends on how it was requested, so both request and response are required to create the policy.

pub fn is_storable(&self) -> bool

Returns true if the response can be stored in a cache. If it's false then you MUST NOT store either the request or the response.

pub fn satisfies_without_revalidation<Req: RequestLike>(
    &self,
    req: &Req,
    now: SystemTime
) -> bool

Returns whether the cached response is still fresh in the context of the new request.

If it returns true, then the given request matches the original response this cache policy has been created with, and the response can be reused without contacting the server.

If it returns false, then the response may not be matching at all (e.g. it's for a different URL or method), or may require to be refreshed first. Either way, the new request's headers will have been updated for sending it to the origin server.

pub fn cached_response(&self, now: SystemTime) -> Parts

Updates and filters the response headers for a cached response before returning it to a client. This function is necessary, because proxies MUST always remove hop-by-hop headers (such as TE and Connection) and update response's Age to avoid doubling cache time.

It returns response "parts" without a body. You can upgrade it to a full response with Response::from_parts(parts, BYOB)

pub fn age(&self, now: SystemTime) -> Duration

Value of the Age header, in seconds, updated for the current time.

pub fn max_age(&self) -> Duration

Value of applicable max-age (or heuristic equivalent) in seconds. This counts since response's Date.

For an up-to-date value, see time_to_live().

pub fn time_to_live(&self, now: SystemTime) -> Duration

Returns approximate time in milliseconds until the response becomes stale (i.e. not fresh).

After that time (when time_to_live() <= 0) the response might not be usable without revalidation. However, there are exceptions, e.g. a client can explicitly allow stale responses, so always check with satisfies_without_revalidation().

pub fn is_stale(&self, now: SystemTime) -> bool

Stale responses shouldn't be used without contacting the server (revalidation)

pub fn revalidation_request<Req: RequestLike>(
    &self,
    incoming_req: &Req
) -> Parts

Headers for sending to the origin server to revalidate stale response. Allows server to return 304 to allow reuse of the previous response.

Hop by hop headers are always stripped. Revalidation headers may be added or removed, depending on request.

It returns request "parts" without a body. You can upgrade it to a full response with Request::from_parts(parts, BYOB) (the body is usually ()).

pub fn revalidated_policy<Req: RequestLike, Res: ResponseLike>(
    &self,
    request: &Req,
    response: &Res,
    response_time: SystemTime
) -> RevalidatedPolicy

Creates CachePolicy with information combined from the previews response, and the new revalidation response.

Returns {policy, modified} where modified is a boolean indicating whether the response body has been modified, and old cached body can't be used.

Trait Implementations

impl Debug for CachePolicy

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CachePolicy

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Serialize for CachePolicy

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.