HTTP::Throwable - A set of strongly-typed, PSGI-friendly HTTP 1.1 exception classes
version 0.004
use HTTP::Throwable; # you can use this directly, but ... HTTP::Throwable->throw( status_code => 500, reason => 'Internal Server Error', message => 'Something has gone very wrong!' ); # ... it is more useful for subclassing package InternalServerError; use Moose; extends 'HTTP::Throwable'; with 'StackTrace::Auto'; # it is 500 so include the stack trace has '+status_code' => ( default => 500 ); has '+reason' => ( default => 'Internal Server Error' ); around 'as_string' => sub { my $next = shift; my $self = shift; $self->$next() . "\n\n" . $self->stack_trace->as_string; }; # and better yet, just use the provided subclasses # see the SUBCLASSES section below for a list HTTP::Throwable::InternalServerError->throw( message => 'Something has gone very wrong!' ); # and lastly, the exception objects themselves # also are PSGI apps builder { mount '/old' => HTTP::Throwable::MovedPermanently->new( location => '/new' ); # ... };
This module a set of strongy-typed, PSGI-friendly exception classes corresponding to the HTTP error status code (4xx-5xx) as well as the redirection codes (3xx).
This particular package is the base object for all the HTTP::Throwable subclasses. While you can easily use this object in your code, you likely want to use the appropriate subclass for the given error as they will provide the status-code, reason and enforce any required headers, see the SUBCLASSES seciton below for more details.
NOTE: We have also included some of the documentation from the HTTP 1.1 spec where appropriate.
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.
It should be noted that even though these are all exception objects, only the 500 Internal Server Error subclass actually includes the stack trace. 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 subclassing and applying the StackTrace::Auto role.
This is the status code integer as specified in the HTTP spec.
This is the reason phrase as specified in the HTTP spec.
This is an additional message string that can be supplied
This returns a string representation of the exception made up of the status code, the reason and the message.
This returns a representation of the exception object as PSGI response. It will build the content-type and content-length headers and include the result of as_string in the body.
as_string
This will also optionally take an $env parameter, though nothing actually uses this, it is mostly there to support future possiblities.
$env
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.
as_psgi
We overload &{} to call to_app, again in keeping with the Plack::Component convention.
&{}
to_app
Below is a list of the subclasses you will find available in 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.
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.
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.
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.
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
Stevan Little <stevan.little@iinteractive.com>
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.
To install HTTP::Throwable, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTTP::Throwable
CPAN shell
perl -MCPAN -e shell install HTTP::Throwable
For more information on module installation, please visit the detailed CPAN module installation guide.