The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTTP-Promise-v0.5.1
River stage one • 1 direct dependent • 2 total dependents
1 ++
/ HTTP::Promise::Headers::CacheControl

NAME

HTTP::Promise::Headers::CacheControl - Cache-Control Header Field

SYNOPSIS

    use HTTP::Promise::Headers::CacheControl;
    my $cc = HTTP::Promise::Headers::CacheControl->new || 
        die( HTTP::Promise::Headers::CacheControl->error, "\n" );

VERSION

    v0.1.0

DESCRIPTION

The following is an extract from Mozilla documentation.

The Cache-Control HTTP header field holds directives (instructions) — in both requests and responses — that control caching in browsers and shared caches (e.g. Proxies, CDNs).

METHODS

The following known properties can be set with those methods. If you want to remove a property, simply set a value of undef.

When you set a new property, it will be added at the end.

If you want to set or get non-standard property, use the "property" method

This class keeps track of the order of the properties set to ensure repeatability and predictability.

as_string

Returns a string representation of the Cache-Control object.

immutable

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The immutable response directive indicates that the response will not be updated while it's fresh.

    Cache-Control: public, max-age=604800, immutable

max_age

If a value is provided, this takes an integer, and set the property to that value. If it exists already, it simply change the property value, otherwise it adds it at the end.

When no value is provided, this returns the numeric value of that property if it exists, or an empty string otherwise.

The max-age=N response directive indicates that the response remains fresh until N seconds after the response is generated.

    Cache-Control: max-age=604800

This is used in request and in response.

max_stale

If a value is provided, this takes an integer, and set the property to that value. If it exists already, it simply change the property value, otherwise it adds it at the end.

When no value is provided, this returns the numeric value of that property if it exists, or an empty string otherwise.

The max-stale=N request directive indicates that the client allows a stored response that is stale within N seconds.

    Cache-Control: max-stale=3600

min_fresh

The min-fresh=N request directive indicates that the client allows a stored response that is fresh for at least N seconds.

    Cache-Control: min-fresh=600

must_revalidate

If a value is provided, this takes an integer, and set the property to that value. If it exists already, it simply change the property value, otherwise it adds it at the end.

When no value is provided, this returns the numeric value of that property if it exists, or an empty string otherwise.

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The must-revalidate response directive indicates that the response can be stored in caches and can be reused while fresh. If the response becomes stale, it must be validated with the origin server before reuse.

Typically, must-revalidate is used with max-age.

    Cache-Control: max-age=604800, must-revalidate

must_understand

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The must-understand response directive indicates that a cache should store the response only if it understands the requirements for caching based on status code.

must-understand should be coupled with no-store for fallback behavior.

    Cache-Control: must-understand, no-store

no_cache

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The no-cache response directive indicates that the response can be stored in caches, but the response must be validated with the origin server before each reuse, even when the cache is disconnected from the origin server.

    Cache-Control: no-cache

This is used in request and in response.

no_store

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The no-store response directive indicates that any caches of any kind (private or shared) should not store this response.

    Cache-Control: no-store

This is used in request and in response.

no_transform

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

Some intermediaries transform content for various reasons. For example, some convert images to reduce transfer size. In some cases, this is undesirable for the content provider.

no-transform indicates that any intermediary (regardless of whether it implements a cache) shouldn't transform the response contents.

only_if_cached

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The client indicates that cache should obtain an already-cached response. If a cache has stored a response, it's reused.

params

Returns the array object used by this header field object containing all the properties set.

private

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The private response directive indicates that the response can be stored only in a private cache (e.g. local caches in browsers).

    Cache-Control: private

property

Sets or gets an arbitrary property.

    $h->property( community => 'UCI' );
    my $val = $h->property( 'community' );

See also rfc7234, section 5.2.3

properties

Returns the hash object used as a repository of properties.

proxy_revalidate

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The proxy-revalidate response directive is the equivalent of must-revalidate, but specifically for shared caches only.

public

This takes a boolean value. When the value is true, this property is set if it does not already exist, and if false, it is removed.

If no value is provided, it returns true if the property is already set and false if it is not.

The public response directive indicates that the response can be stored in a shared cache. Responses for requests with Authorization header fields must not be stored in a shared cache; however, the public directive will cause such responses to be stored in a shared cache.

    Cache-Control: public

s_maxage

The s-maxage response directive also indicates how long the response is fresh for (similar to max-age) — but it is specific to shared caches, and they will ignore max-age when it is present.

    Cache-Control: s-maxage=604800

stale_if_error

The stale-if-error response directive indicates that the cache can reuse a stale response when an origin server responds with an error (500, 502, 503, or 504).

    Cache-Control: max-age=604800, stale-if-error=86400

stale_while_revalidate

The stale-while-revalidate response directive indicates that the cache could reuse a stale response while it revalidates it to a cache.

    Cache-Control: max-age=604800, stale-while-revalidate=86400

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

See rfc7234, section 5.2, rfc8246, section 2 and Mozilla documentation

HTTP::Promise, HTTP::Promise::Request, HTTP::Promise::Response, HTTP::Promise::Message, HTTP::Promise::Entity, HTTP::Promise::Headers, HTTP::Promise::Body, HTTP::Promise::Body::Form, HTTP::Promise::Body::Form::Data, HTTP::Promise::Body::Form::Field, HTTP::Promise::Status, HTTP::Promise::MIME, HTTP::Promise::Parser, HTTP::Promise::IO, HTTP::Promise::Stream, HTTP::Promise::Exception

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.