/ 
HTTP-Throwable-0.026
River stage one • 8 direct dependents • 9 total dependents
/ HTTP::Throwable

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.

SEE ALSO

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.