---
name: "LWP::UserAgent::Role::CHICaching"
section: "3pm"
platform: "linux"
package: "liblwp-useragent-chicaching-perl"
version: "0.04-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/LWP::UserAgent::Role::CHICaching"
---

# LWP::UserAgent::Role::CHICaching(3pm)

A role to allow LWP::UserAgent to cache with CHI

## 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.