HTTP::Throwable(3pm)

💖 HTTP::Throwable 💖

okay bestie, welcome to the HTTP::Throwable page — it's part of the User Contributed Perl Documentation, and honestly? it's giving strongly-typed, PSGI-friendly HTTP 1.1 exception libraries. a whole set of them. slay.

---

✨ VERSION ✨

this is version 0.028. periodt.

---

🌸 SYNOPSIS 🌸

ACHTUNG 🚨 the interface for HTTP::Throwable has changed significantly between 0.005 and 0.010. further backward incompatibilities may appear in the next few weeks, as the interface is refined. this notice will be removed when it has stabilized. (so like... buckle up bestie, the vibes are still settling 💀)

okay so actually, you probably want to use HTTP::Throwable::Factory, so here's a lil sample of how that works:

use HTTP::Throwable::Factory qw(http_throw http_exception);

# you can just throw a generic exception...
HTTP::Throwable::Factory->throw({
    status_code => 500,
    reason      => 'Internal Server Error',
    message     => 'Something has gone very wrong!'
});

# or with a little sugar...
http_throw({
    status_code => 500,
    reason      => 'Internal Server Error',
    message     => 'Something has gone very wrong!'
});

# ...but it's much more convenient to throw well-defined exceptions, like
# this:

http_throw(InternalServerError => {
  message => 'Something has gone very wrong!',
});

# or you can use the exception objects as PSGI apps:
builder {
    mount '/old' => http_exception(MovedPermanently => { location => '/new' }),
    # ...
};

---

🦋 DESCRIPTION 🦋

HTTP-Throwable provides a set of strongly-typed, PSGI-friendly exception implementations corresponding to the HTTP error status code (4xx-5xx) as well as the redirection codes (3xx). iconic behavior, honestly.

this particular package (HTTP::Throwable) is the shared role for all the exceptions involved. it's not intended that you use HTTP::Throwable directly, although you can, and instructions for using it correctly are given below. instead, you probably want to use HTTP::Throwable::Factory, which will assemble exception classes from roles needed to build an exception for your use case. 💅

for example, you can throw a redirect:

use HTTP::Throwable::Factory qw(http_throw);

http_throw(MovedPermanently => { location => '/foo-bar' });

...or a generic fully user-specified exception...

http_throw({
  status_code => 512,
  reason      => 'Server on fire',
  message     => "Please try again after heavy rain",
});

for a list of pre-defined, known errors, see "WELL-KNOWN TYPES" below. these types will have the correct status code and reason, and will understand extra status-related arguments like redirect location or authentication realms. no cap. 🔥

for information on using HTTP::Throwable directly, see "COMPOSING WITH HTTP::THROWABLE", below.

💜 HTTP::Exception

this module is similar to HTTP::Exception with a few, well uhm, exceptions. first, we are not implementing the 1xx and 2xx status codes — it is this author's opinion that those, not being errors or an exception control flow (redirection), should not be handled with exceptions. and secondly, this module is very PSGI friendly in that it can turn your exception into a PSGI response with just a method call. 🎀

all that said, HTTP::Exception is a wonderful module and if that better suits your needs, then by all means, use it. we're not gatekeeping. 🫶

🧚 Note about Stack Traces

it should be noted that even though these are all exception objects, only the 500 Internal Server Error error actually includes the stack trace (albeit optionally). this is because more often then not you will not actually care about the stack trace and therefore do not [want] the extra overhead. if you do find you want a stack trace though, it is as simple as adding the StackTrace::Auto role to your exceptions. 🌈

---

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

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 like, don't come for us if it breaks on your ancient perl, bestie 🙈)

---

👑 ATTRIBUTES 👑

💅 status_code

this is the status code integer as specified in the HTTP spec.

💅 reason

this is the reason phrase as specified in the HTTP spec.

💅 message

this is an additional message string that can be supplied, which may be used when stringifying or building an HTTP response.

💅 additional_headers

this is an arrayref of pairs that will be added to the headers of the exception when converted to a HTTP message.

---

✨ METHODS ✨

🌸 status_line

this returns a string that would be used as a status line in a response, like "404 Not Found". cute, right?

🌸 as_string

this returns a string representation of the exception. this method must be implemented by any class consuming this role. mandatory. no skips. 💀

🌸 as_psgi

this returns a representation of the exception object as PSGI response.

in theory, it accepts a PSGI environment as its only argument, but currently the environment is ignored. (it's giving "we'll get to it" energy 😭)

🌸 to_app

this is the standard Plack convention for Plack::Components. it will return a CODE ref which expects the $env parameter and returns the results of as_psgi. 🔥

🌸 &{}

we overload &{} to call to_app, again in keeping with the Plack::Component convention.

---

🌈 WELL-KNOWN TYPES 🌈

below is a list of the well-known types recognized by the factory and shipped with this distribution. the obvious 4xx and 5xx errors are included but we also include the 3xx redirection status codes. this is because, while not really an error, the 3xx status codes do represent an exceptional control flow.

the implementation for each of these is in a role with a name in the form HTTP::Throwable::Role::Status::STATUS-NAME. for example, Gone is HTTP::Throwable::Role::Status::Gone. when throwing the exception with the factory, just pass Gone. simple as. 💅

🎀 Redirection 3xx

this class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request. the action required MAY be carried out by the user agent without interaction with the user if and only if the method used in the second request is GET or HEAD.

• 300 HTTP::Throwable::Role::Status::MultipleChoices
• 301 HTTP::Throwable::Role::Status::MovedPermanently
• 302 HTTP::Throwable::Role::Status::Found
• 303 HTTP::Throwable::Role::Status::SeeOther
• 304 HTTP::Throwable::Role::Status::NotModified
• 305 HTTP::Throwable::Role::Status::UseProxy
• 307 HTTP::Throwable::Role::Status::TemporaryRedirect

🎀 Client Error 4xx

the 4xx class of status code is intended for cases in which the client seems to have erred. except when responding to a HEAD request, the server SHOULD include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. these status codes are applicable to any request method. user agents SHOULD display any included entity to the user.

• 400 HTTP::Throwable::Role::Status::BadRequest
• 401 HTTP::Throwable::Role::Status::Unauthorized
• 403 HTTP::Throwable::Role::Status::Forbidden
• 404 HTTP::Throwable::Role::Status::NotFound
• 405 HTTP::Throwable::Role::Status::MethodNotAllowed
• 406 HTTP::Throwable::Role::Status::NotAcceptable
• 407 HTTP::Throwable::Role::Status::ProxyAuthenticationRequired
• 408 HTTP::Throwable::Role::Status::RequestTimeout
• 409 HTTP::Throwable::Role::Status::Conflict
• 410 HTTP::Throwable::Role::Status::Gone
• 411 HTTP::Throwable::Role::Status::LengthRequired
• 412 HTTP::Throwable::Role::Status::PreconditionFailed
• 413 HTTP::Throwable::Role::Status::RequestEntityTooLarge
• 414 HTTP::Throwable::Role::Status::RequestURITooLong
• 415 HTTP::Throwable::Role::Status::UnsupportedMediaType
• 416 HTTP::Throwable::Role::Status::RequestedRangeNotSatisfiable
• 417 HTTP::Throwable::Role::Status::ExpectationFailed

🎀 Server Error 5xx

response status codes beginning with the digit "5" indicate cases in which the server is aware that it has erred or is incapable of performing the request. except when responding to a HEAD request, the server SHOULD include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. user agents SHOULD display any included entity to the user. these response codes are applicable to any request method.

• 500 HTTP::Throwable::Role::Status::InternalServerError
• 501 HTTP::Throwable::Role::Status::NotImplemented
• 502 HTTP::Throwable::Role::Status::BadGateway
• 503 HTTP::Throwable::Role::Status::ServiceUnavailable
• 504 HTTP::Throwable::Role::Status::GatewayTimeout
• 505 HTTP::Throwable::Role::Status::HTTPVersionNotSupported

---

🫶 COMPOSING WITH HTTP::THROWABLE 🫶

in general, we expect that you'll use HTTP::Throwable::Factory or a subclass to throw exceptions. you can still use HTTP::Throwable directly, though, if you keep these things in mind:

HTTP::Throwable is mostly concerned about providing basic headers and a PSGI representation. it doesn't worry about the body or a stringification. you must provide the methods body and body_headers and as_string. 🔥

the body method returns the string (of octets) to be sent as the HTTP entity. that body is passed to the body_headers method, which must return an arrayref of headers to add to the response. these will generally include the Content-Type and Content-Length headers.

the as_string method should return a printable string, even if the body is going to be empty.

for convenience, these three methods are implemented by the roles HTTP::Throwable::Role::TextBody and HTTP::Throwable::Role::NoBody. obsessed. 💖

---

💀 SEE ALSO 💀

• <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>
• Plack::Middleware::HTTPExceptions

---

👑 AUTHORS 👑

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

---

💜 CONTRIBUTORS 💜

• Andrew Fresh <andrew@afresh1.com>
• Brian Cassidy <bricas@cpan.org>
• Chris Prather <chris@prather.org>
• Edward Betts <edward@4angle.com>
• Fitz Elliott <felliott@fiskur.org>
• Karen Etheridge <ether@cpan.org>
• Ricardo Signes <rjbs@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 page bestie, you ate that 🍓✨ — this was HTTP::Throwable(3pm) from perl v5.36.0, dated 2023-01-24. go forth and throw some exceptions, you main character 💅🌈