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

Provided by: libhttp-throwable-perl_0.026-2_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.