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

💖 LWP::U...rmined(3pm) 💖

okay bestie, first things first: the header up top says LWP::U...rmined(3pm) (the terminal truncates it, it's shorter than it wants to be, don't worry about it), it comes from User Contributed Perl Documentation, and it's living in the perl v5.36.0 world, dated 2022-10-13. We'll do the cute sign-off at the end, promise. 🫶

---

✨ NAME ✨

LWP::UserAgent::Determined — a virtual browser that retries errors 💅

---

🌸 SYNOPSIS 🌸

use strict;
use LWP::UserAgent::Determined;
my $browser = LWP::UserAgent::Determined->new;
my $response = $browser->get($url, headers... );

---

🦋 DESCRIPTION 🦋

so this class is literally just like LWP::UserAgent — it's a subclass of it, that's the whole basis — except when you use it to grab a web page and you hit a possibly-temporary error (think a DNS lookup timeout, the classic), it'll wait a few seconds and retry a few times. determined behavior. main character energy. no giving up on the first try. 😤

it also adds some methods for controlling exactly which errors count as retry-worthy, and how many waits and how many seconds each, but ngl you usually do not need to bother with those, because the default settings are relatively sane. 👑

---

🎀 METHODS 🎀

this module inherits all of LWP::UserAgent's methods, and adds the following. periodt.

$timing_string = $browser->timing(); and $browser->timing( "10,30,90" )

the timing method gets or sets the string that controls how many times it should retry, and how long the pauses should be. 🕰️

• if you specify empty-string, this means not to retry at all.
• if you specify a string consisting of a single number, like "10", that means: if the first request doesn't succeed, then $browser->get(...) (or any other method based on request or simple_request) should wait 10 seconds and try again — and if that fails, then it's final. one shot, one retry, done. 💀
• if you specify a string with several numbers in it (like "10,30,90"), then that means $browser can retry as that many times (i.e., one initial try, plus a maximum of the three retries, because three numbers there), and that it should wait first those numbers of seconds each time. So $browser->timing( "10,30,90" ) basically means:

try the request; return it unless it's a temporary-looking error;
sleep 10;
retry the request; return it unless it's a temporary-looking error;
sleep 30;
retry the request; return it unless it's a temporary-looking error;
sleep 90  the request;
return it;

the default value is "1,3,15". 🌈

$http_codes_hr = $browser->codes_to_determinate();

this returns the hash that is the set of HTTP codes that merit a retry (like 500 and 408, but unlike 404 or 200). you can delete or add entries like so: ✂️➕

$http_codes_hr = $browser->codes_to_determinate();
delete $http_codes_hr->{408};
$http_codes_hr->{567} = 1;

(you can actually set a whole new hashset with $browser->codes_to_determinate($new_hr), but there's usually no benefit to that as opposed to the above. like, at all. 🙈)

the current default is 408 (Timeout) plus some 5xx codes. 💜

$browser->before_determined_callback() / $browser->before_determined_callback( \&some_routine ); / $browser->after_determined_callback() / $browser->after_determined_callback( \&some_routine );

these read (first two) or set (second two) callbacks that are called before the actual HTTP/FTP/etc request is made. by default, these are set to undef, meaning nothing special is called. if you want to alter try requests, or inspect responses before any retrying is considered, you can set up these callbacks. very customizable of you. 🧚

the arguments passed to these routines are:

0. the current $browser object
1. an arrayref to the list of timing pauses (based on $browser->timing)
2. the duration of the number of seconds we'll pause if this request fails this time, or undef if this is the last chance.
3. the value of $browser->codes_to_determinate
4. an arrayref of the arguments we pass to LWP::UserAgent::simple_request (the first of which is the request object)
5. (and, only for after_determined_callback, the response we just got.)

example use, because a demo ate 💅:

$browser->before_determined_callback( sub {
  print "Trying ", $_[4][0]->uri, " ...\n";
});

---

⭐ IMPLEMENTATION ⭐

this class works by overriding LWP::UserAgent's simple_request method with its own around-method that just loops. see the source of this module; it's straightforward. relatively. 😭 (okay that last word is doing a lot of heavy lifting, but that's literally what the manpage says.)

---

🔥 SEE ALSO 🔥

• LWP
• LWP::UserAgent

iykyk. 👑

---

🌟 COPYRIGHT AND DISCLAIMER 🌟

Copyright 2004, Sean M. Burke, all rights reserved. this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🎀

this program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. (translation: it's free, it's generous, it is not promising you anything, bestie.) 🫶

---

💜 AUTHOR 💜

Originally created by Sean M. Burke, "sburke@cpan.org"

Currently maintained by Jesse Vincent "jesse@fsck.com"

---

okay that's the whole page!! ✨ this beauty is perl v5.36.0, dated 2022-10-13, and honestly? iconic. go retry that request, you've got this. 🌸💖🦋