NAME

       LWP::UserAgent::Role::CHICaching - A role to allow LWP::UserAgent to cache with CHI

SYNOPSIS

       Compose it into a class, e.g.

         package LWP::UserAgent::MyCacher;
         use Moo;
         extends 'LWP::UserAgent';
         with 'LWP::UserAgent::Role::CHICaching',
              'LWP::UserAgent::Role::CHICaching::SimpleKeyGen',
              'LWP::UserAgent::Role::CHICaching::SimpleMungeResponse';

DESCRIPTION

       This is a role for creating caching user agents. When the client makes a request to the server, sometimes
       the response should be cached, so that no actual request has to be sent at all, or possibly just a
       request to validate the cache. HTTP 1.1 defines how to do this. This role makes it possible to use the
       very flexible CHI module to manage such a cache. See LWP::UserAgent::CHICaching for a finished class you
       can use.

   Attributes and Methods
       "cache"
           Used to set the "CHI" object to be used as cache in the constructor.

       "request_uri"
           The  Request-URI of the request. When set, it will clear the "key", but should probably be left to be
           used internally for now.

       "request"
           Wrapping LWP::UserAgent's request method.

       "is_shared"
           A boolean value to set whether the cache can be shared. The default is that it is.

       "heuristics_opts"
           A hashref that is passed to the "freshness_lifetime" method of HTTP::Response, and used to  determine
           the  behaviour  of  the  heuristic  lifetime.  By  default, heuristic freshness lifetime is off, only
           standards-compliant freshness lifetime (i.e. based on the "Cache-Control" and "Expires" headers)  are
           used.

   Implemented elsewhere
       The     following     are     required     by    this    role,    but    implemented    elsewhere.    See
       LWP::UserAgent::Role::CHICaching::SimpleKeyGen and  LWP::UserAgent::Role::CHICaching::SimpleMungeResponse
       for further explanations.

       "key", "clear_key"
           The key to use for a response.

       "cache_vary($response)"
           A  method  that returns true if the response may be cached even if it contains a "Vary" header, false
           otherwise. The HTTP::Response object will be passed to it as a parameter.

       "cache_set($response, $expires_in)"
           A method that takes the HTTP::Response from the client and an expires time in  seconds  and  set  the
           actual cache.

       "finalize($cached)"
           A  method  that  takes the cached entry as an argument, and will return a HTTP::Response to return to
           the client.

LIMITATIONS

       Will only cache "GET" requests, and only successful responses.

       The module does not validate and does not serve stale responses, even when it would be allowed to do  so.
       It nevertheless does most of RFC7234.

BUGS

       Please report any bugs to <https://github.com/kjetilk/p5-lwp-useragent-chicaching/issues>.

AUTHOR

       Kjetil Kjernsmo <kjetilk@cpan.org>.

ACKNOWLEDGEMENTS

       It was really nice looking at the code of LWP::UserAgent::WithCache, when I wrote this.

       Thanks to Matt S. Trout for rewriting this to a Role.

COPYRIGHT AND LICENCE

       This software is copyright (c) 2015, 2016 by Kjetil Kjernsmo.

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

perl v5.34.0                                       2022-05-28              LWP::UserAgent::Role::CHICaching(3pm)