Ubuntu Manpage: HTTP::Throwable - a set of strongly-typed, PSGI-friendly HTTP 1.1 exception libraries

Provided by: libhttp-throwable-perl_0.026-1_all

NAME

       HTTP::Throwable - a set of strongly-typed, PSGI-friendly HTTP 1.1 exception libraries

VERSION

       version 0.026

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.

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

   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.

AUTHORS

       •   Stevan Little <stevan.little@iinteractive.com>

       •   Ricardo Signes <rjbs@cpan.org>

CONTRIBUTORS

       •   Brian Cassidy <bricas@cpan.org>

       •   Chris Prather <chris@prather.org>

       •   Fitz Elliott <felliott@fiskur.org>

       •   Karen Etheridge <ether@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.