LWP::U...aching(3pm)

💖 LWP::UserAgent::Role::CHICaching — bestie's guide to caching your LWP::UserAgent with CHI 💖

okay so real talk, this page comes from the User Contributed Perl Documentation section of the manual — it's LWP::U...aching(3pm) (the name gets squished in the header, tragic, but iykyk) — and it's genuinely one of my faves so let's get into it 🫶

---

✨ NAME ✨

LWP::UserAgent::Role::CHICaching — a role that lets LWP::UserAgent cache stuff with CHI. slay.

---

🌸 SYNOPSIS 🌸

you compose it into a class, bestie. like this:

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

see? iconic. extends for the base, with for the roles, done 💅

---

🦋 DESCRIPTION 🦋

so here's the vibe: this is a role for building caching user agents. when your client makes a request to a server, sometimes the response should totally be cached — so that no actual request has to be sent at all, or maybe just a lil request to validate the cache. that's a whole HTTP 1.1 thing, it's defined, it's real, it's giving standards-compliant ✨

and this role lets you use the very flexible CHI module to manage that cache. and hey, if you want a finished class that's already done for you, go look at LWP::UserAgent::CHICaching — it's right there, ready to go 👑

💜 Attributes and Methods 💜

• cache — this is how you set the CHI object that's gonna be your cache, in the constructor. that's it, that's the job.
• request_uri — the Request-URI of the request. when it gets set, it clears the key, but honestly? you should probably just leave it alone and let it be used internally for now. it's doing its own thing 🙈
• request — it wraps LWP::UserAgent's request method. classic wrapper behaviour, love that for it.
• is_shared — a boolean that sets whether the cache can be shared. the default? it can be. shared cache main character energy fr fr.
• heuristics_opts — a hashref that gets passed to the freshness_lifetime method of HTTP::Response, and it's what determines how the heuristic lifetime behaves. but heads up bestie: by default, heuristic freshness lifetime is OFF. only standards-compliant freshness lifetimes get used (aka the ones based on the Cache-Control and Expires headers). no vibes-based caching by default, we're being rigorous 💅

🌈 Implemented elsewhere 🌈

these next ones are required</> by this role, but they're implemented somewhere else, so don't come looking for them here. for the full explanation, go check out LWP::UserAgent::Role::CHICaching::SimpleKeyGen and LWP::UserAgent::Role::CHICaching::SimpleMungeResponse.

• 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's got a Vary header, and false if not. the HTTP::Response object gets passed to it as a parameter.
• cache_set($response, $expires_in) — takes the HTTP::Response from the client plus an expires time in seconds, and sets the actual cache.
• finalize($cached) — takes the cached entry as an argument, and returns an HTTP::Response for you to hand back to the client.

---

😭 LIMITATIONS 😭

okay, the reality check portion of the page, no cap:

• it will only cache GET requests, and only successful responses. that's the limit.
• the module does not validate and does not serve stale responses, even when it would legit be allowed to. so yeah — it still does most of RFC7234, but not those bits. periodt.

---

💀 BUGS 💀

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

---

👑 AUTHOR 👑

Kjetil Kjernsmo <kjetilk@cpan.org>.

---

🎀 ACKNOWLEDGEMENTS 🎀

ngl, it was really nice looking at the code of LWP::UserAgent::WithCache while writing this.

and thanks to Matt S. Trout for rewriting this into a Role. king behaviour 💜

---

⭐ COPYRIGHT AND LICENCE ⭐

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

it's free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. so like, go wild (within the licence) 🦋

---

and that's the whole page, bestie!! 🥳 this one's from perl v5.34.0, dated 2022-05-28 — so go forth, compose your roles, cache your GETs, and remember: only successful responses, no stale serving, no exceptions. mwah 💅✨🌸