HTTP::...actory(3pm)

💖 HTTP::Throwable::Factory 💖

okay bestie, so this is a page from the User Contributed Perl Documentation (the 3pm crew 🎀), and it's all about HTTP::Throwable::Factory — version 0.028 — the little factory that throws HTTP::Throwables for you. yes. for you. specifically. 🫶

---

✨ NAME ✨

HTTP::Throwable::Factory — a factory that throws HTTP::Throwables for you 💅

🌸 VERSION 🌸

version 0.028

🦋 OVERVIEW 🦋

so HTTP::Throwable is a role, and what that role does is make it super easy to build exceptions that, once thrown, can be turned into PSGI-style HTTP responses. iconic behaviour honestly.

but here's the catch, bestie: because HTTP::Throwable and all its related roles are, well, roles, they can't be instantiated or thrown directly. nope. not happening. instead, they have to be built into classes first. 😭 and that's literally the whole job of HTTP::Throwable::Factory — it builds classes out of the roles you need for the exception you want to throw. main character energy.

you can use the factory to either build or throw an exception, and that exception can be generic or specific. building and throwing are very similar — the only difference is whether or not the newly built object is thrown or returned. that's it. that's the difference.

• wanna throw an exception? use the throw method on the factory. 🔥
• wanna just return it? use the new_exception method. ✨

in the examples below we're just gonna use throw, because we're dramatic like that.

to throw a generic exception — one where you have to specify the status code and reason, plus any other headers — you pass throw a hashref of arguments that get passed to the exception class's constructor:

HTTP::Throwable::Factory->throw({
    status_code => 301,
    reason      => 'Moved Permanently',
    additional_headers => [
      Location => '/new',
    ],
});

to throw a specific type of exception, you include an exception type identifier, like this:

HTTP::Throwable::Factory->throw(MovedPermanently => { location => '/new' });

the type identifier is (by default) the end of a role name in the form HTTP::Throwable::Role::Status::IDENTIFIER. the full list of such included roles lives in the HTTP::Throwable docs. go look, iykyk. 📚

🎀 Exports 🎀

you can import routines called http_throw and http_exception that work exactly like the throw and new_exception methods respectively — except they're not called as methods. wild, i know. for example:

use HTTP::Throwable::Factory 'http_exception';

builder {
    mount '/old' => http_exception('Gone'),
};

---

🌈 PERL VERSION 🌈

this library should run on perls released even a long time ago. it should work on any version of perl released in the last five years. ngl, that's a pretty generous window.

although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. the version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. 💀 so don't come for them about it.

---

👑 SUBCLASSING 👑

one of the big benefits of using HTTP::Throwable::Factory is that you can subclass it to change the kind of exceptions it provides. slay.

if you subclass it, you can change its behavior by overriding the following methods — and they're listed here in the order of likelihood that you'd want to override them, most likely first. considerate of them tbh. 🫶

💜 extra_roles

this method returns a list of role names that will be included in any class built by the factory. by default, it includes only HTTP::Throwable::Role::TextBody, to satisfy HTTP::Throwable's requirements for methods needed to build a body.

this is the method you're most likely to override in a subclass. ⭐

💜 roles_for_ident

💜 roles_for_status_code

💜 roles_for_no_ident

these methods convert the exception type identifier to a role to apply. for example, if you call:

Factory->throw(NotFound => { ... })

...then roles_for_ident is called with NotFound as its argument. roles_for_status_code is used if the string is three ASCII digits.

if throw is called without a type identifier, roles_for_no_ident is called.

by default, roles_for_ident returns HTTP::Throwable::Role::Status::$ident, and roles_for_no_ident returns HTTP::Throwable::Role::Generic and HTTP::Throwable::Role::BoringText.

💜 base_class

this is the base class that will be subclassed and into which all the roles will be composed. by default, it's Moo::Object, the universal base Moo class. classic. ✨

💜 core_roles

this method returns the roles that are expected to be applied to every HTTP::Throwable exception. heads up though: this method's results might change over time, and you are encouraged not to alter it. 🙈

---

💖 AUTHORS 💖

• Stevan Little <stevan.little@iinteractive.com>
• Ricardo Signes <cpan@semiotic.systems>

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2011 by Infinity Interactive, Inc.

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

---

and that's the whole vibe check, bestie 🦋 this was documented with perl v5.36.0 and dated 2023-01-24 — so yeah, a little vintage, but still eating. periodt. 💅🎀🌸