NAME¶
HTTP::Throwable - a set of strongly-typed, PSGI-friendly HTTP 1.1 exception
libraries
VERSION¶
version 0.018
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.
Actually, you probably want to use HTTP::Throwable::Factory, so here's a
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).
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.
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
authors 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.
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 (albiet
optionally). This is because more often then not you will not actually care
about the stack trace and therefore do not 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.
ATTRIBUTES¶
status_code¶
This is the status code integer as specified in the HTTP spec.
resason¶
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.
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".
as_string¶
This returns a string representation of the exception. This method
must
be implemented by any class consuming this role.
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.
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"
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.
SEE ALSO¶
- •
- <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>
- •
- Plack::Middleware::HTTPExceptions
AUTHORS¶
- •
- Stevan Little <stevan.little@iinteractive.com>
- •
- Ricardo Signes <rjbs@cpan.org>
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.