.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTTP::Throwable 3pm"
.TH HTTP::Throwable 3pm "2013-11-20" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::Throwable \- a set of strongly\-typed, PSGI\-friendly HTTP 1.1 exception libraries
.SH "VERSION"
.IX Header "VERSION"
version 0.018
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fB\s-1ACHTUNG\s0\fR:  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.
.PP
\&\fIActually\fR, you probably want to use HTTP::Throwable::Factory, so here's a
sample of how that works:
.PP
.Vb 1
\&  use HTTP::Throwable::Factory qw(http_throw http_exception);
\&
\&  # you can just throw a generic exception...
\&  HTTP::Throwable::Factory\->throw({
\&      status_code => 500,
\&      reason      => \*(AqInternal Server Error\*(Aq,
\&      message     => \*(AqSomething has gone very wrong!\*(Aq
\&  });
\&
\&  # or with a little sugar...
\&  http_throw({
\&      status_code => 500,
\&      reason      => \*(AqInternal Server Error\*(Aq,
\&      message     => \*(AqSomething has gone very wrong!\*(Aq
\&  });
\&
\&
\&  # ...but it\*(Aqs much more convenient to throw well\-defined exceptions, like
\&  # this:
\&
\&  http_throw(InternalServerError => {
\&    message => \*(AqSomething has gone very wrong!\*(Aq,
\&  });
\&
\&  # or you can use the exception objects as PSGI apps:
\&  builder {
\&      mount \*(Aq/old\*(Aq => http_exception(MovedPermanently => { location => \*(Aq/new\*(Aq }),
\&      # ...
\&  };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
HTTP-Throwable provides a set of strongly-typed, PSGI-friendly exception
implementations corresponding to the \s-1HTTP\s0 error status code (4xx\-5xx) as well
as the redirection codes (3xx).
.PP
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.
.PP
For example, you can throw a redirect:
.PP
.Vb 1
\&  use HTTP::Throwable::Factory qw(http_throw);
\&
\&  http_throw(MovedPermanently => { location => \*(Aq/foo\-bar\*(Aq });
.Ve
.PP
\&...or a generic fully user-specified exception...
.PP
.Vb 5
\&  http_throw({
\&    status_code => 512,
\&    reason      => \*(AqServer on fire\*(Aq,
\&    message     => "Please try again after heavy rain",
\&  });
.Ve
.PP
For a list of pre-defined, known errors, see \*(L"WELL-KNOWN \s-1TYPES\*(R"\s0 below.
These types will have the correct status code and reason, and will
understand extra status-related arguments like redirect location or authentication realms.
.PP
For information on using HTTP::Throwable directly, see \*(L"\s-1COMPOSING WITH
HTTP::THROWABLE\*(R"\s0, below.
.SS "HTTP::Exception"
.IX Subsection "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 \s-1PSGI\s0 friendly in that
it can turn your exception into a \s-1PSGI\s0 response with just a
method call.
.PP
All that said HTTP::Exception is a wonderful module and if that
better suits your needs, then by all means, use it.
.SS "Note about Stack Traces"
.IX Subsection "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.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "status_code"
.IX Subsection "status_code"
This is the status code integer as specified in the \s-1HTTP\s0 spec.
.SS "resason"
.IX Subsection "resason"
This is the reason phrase as specified in the \s-1HTTP\s0 spec.
.SS "message"
.IX Subsection "message"
This is an additional message string that can be supplied, which \fImay\fR
be used when stringifying or building an \s-1HTTP\s0 response.
.SS "additional_headers"
.IX Subsection "additional_headers"
This is an arrayref of pairs that will be added to the headers of the
exception when converted to a \s-1HTTP\s0 message.
.SH "METHODS"
.IX Header "METHODS"
.SS "status_line"
.IX Subsection "status_line"
This returns a string that would be used as a status line in a response,
like \f(CW\*(C`404 Not Found\*(C'\fR.
.SS "as_string"
.IX Subsection "as_string"
This returns a string representation of the exception.  This method
\&\fBmust\fR be implemented by any class consuming this role.
.SS "as_psgi"
.IX Subsection "as_psgi"
This returns a representation of the exception object as \s-1PSGI\s0
response.
.PP
In theory, it accepts a \s-1PSGI\s0 environment as its only argument, but
currently the environment is ignored.
.SS "to_app"
.IX Subsection "to_app"
This is the standard Plack convention for Plack::Components.
It will return a \s-1CODE\s0 ref which expects the \f(CW$env\fR parameter
and returns the results of \f(CW\*(C`as_psgi\*(C'\fR.
.SS "&{}"
.IX Subsection "&{}"
We overload \f(CW\*(C`&{}\*(C'\fR to call \f(CW\*(C`to_app\*(C'\fR, again in keeping with the
Plack::Component convention.
.SH "WELL-KNOWN TYPES"
.IX Header "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.
.PP
The implementation for each of these is in a role with a name in the
form \f(CW\*(C`HTTP::Throwable::Role::Status::STATUS\-NAME\*(C'\fR.  For example, \*(L"Gone\*(R"
is \f(CW\*(C`HTTP::Throwable::Role::Status::Gone\*(C'\fR.  When throwing the exception
with the factory, just pass \*(L"Gone\*(R"
.SS "Redirection 3xx"
.IX Subsection "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 \s-1MAY\s0 be carried out by the user agent without
interaction with the user if and only if the method used in the
second request is \s-1GET\s0 or \s-1HEAD.\s0
.IP "300 HTTP::Throwable::Role::Status::MultipleChoices" 4
.IX Item "300 HTTP::Throwable::Role::Status::MultipleChoices"
.PD 0
.IP "301 HTTP::Throwable::Role::Status::MovedPermanently" 4
.IX Item "301 HTTP::Throwable::Role::Status::MovedPermanently"
.IP "302 HTTP::Throwable::Role::Status::Found" 4
.IX Item "302 HTTP::Throwable::Role::Status::Found"
.IP "303 HTTP::Throwable::Role::Status::SeeOther" 4
.IX Item "303 HTTP::Throwable::Role::Status::SeeOther"
.IP "304 HTTP::Throwable::Role::Status::NotModified" 4
.IX Item "304 HTTP::Throwable::Role::Status::NotModified"
.IP "305 HTTP::Throwable::Role::Status::UseProxy" 4
.IX Item "305 HTTP::Throwable::Role::Status::UseProxy"
.IP "307 HTTP::Throwable::Role::Status::TemporaryRedirect" 4
.IX Item "307 HTTP::Throwable::Role::Status::TemporaryRedirect"
.PD
.SS "Client Error 4xx"
.IX Subsection "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
\&\s-1HEAD\s0 request, the server \s-1SHOULD\s0 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 \s-1SHOULD\s0 display any included entity
to the user.
.IP "400 HTTP::Throwable::Role::Status::BadRequest" 4
.IX Item "400 HTTP::Throwable::Role::Status::BadRequest"
.PD 0
.IP "401 HTTP::Throwable::Role::Status::Unauthorized" 4
.IX Item "401 HTTP::Throwable::Role::Status::Unauthorized"
.IP "403 HTTP::Throwable::Role::Status::Forbidden" 4
.IX Item "403 HTTP::Throwable::Role::Status::Forbidden"
.IP "404 HTTP::Throwable::Role::Status::NotFound" 4
.IX Item "404 HTTP::Throwable::Role::Status::NotFound"
.IP "405 HTTP::Throwable::Role::Status::MethodNotAllowed" 4
.IX Item "405 HTTP::Throwable::Role::Status::MethodNotAllowed"
.IP "406 HTTP::Throwable::Role::Status::NotAcceptable" 4
.IX Item "406 HTTP::Throwable::Role::Status::NotAcceptable"
.IP "407 HTTP::Throwable::Role::Status::ProxyAuthenticationRequired" 4
.IX Item "407 HTTP::Throwable::Role::Status::ProxyAuthenticationRequired"
.IP "408 HTTP::Throwable::Role::Status::RequestTimeout" 4
.IX Item "408 HTTP::Throwable::Role::Status::RequestTimeout"
.IP "409 HTTP::Throwable::Role::Status::Conflict" 4
.IX Item "409 HTTP::Throwable::Role::Status::Conflict"
.IP "410 HTTP::Throwable::Role::Status::Gone" 4
.IX Item "410 HTTP::Throwable::Role::Status::Gone"
.IP "411 HTTP::Throwable::Role::Status::LengthRequired" 4
.IX Item "411 HTTP::Throwable::Role::Status::LengthRequired"
.IP "412 HTTP::Throwable::Role::Status::PreconditionFailed" 4
.IX Item "412 HTTP::Throwable::Role::Status::PreconditionFailed"
.IP "413 HTTP::Throwable::Role::Status::RequestEntityTooLarge" 4
.IX Item "413 HTTP::Throwable::Role::Status::RequestEntityTooLarge"
.IP "414 HTTP::Throwable::Role::Status::RequestURITooLong" 4
.IX Item "414 HTTP::Throwable::Role::Status::RequestURITooLong"
.IP "415 HTTP::Throwable::Role::Status::UnsupportedMediaType" 4
.IX Item "415 HTTP::Throwable::Role::Status::UnsupportedMediaType"
.IP "416 HTTP::Throwable::Role::Status::RequestedRangeNotSatisfiable" 4
.IX Item "416 HTTP::Throwable::Role::Status::RequestedRangeNotSatisfiable"
.IP "417 HTTP::Throwable::Role::Status::ExpectationFailed" 4
.IX Item "417 HTTP::Throwable::Role::Status::ExpectationFailed"
.PD
.SS "Server Error 5xx"
.IX Subsection "Server Error 5xx"
Response status codes beginning with the digit \*(L"5\*(R" indicate
cases in which the server is aware that it has erred or is
incapable of performing the request. Except when responding to
a \s-1HEAD\s0 request, the server \s-1SHOULD\s0 include an entity containing
an explanation of the error situation, and whether it is a
temporary or permanent condition. User agents \s-1SHOULD\s0 display
any included entity to the user. These response codes are applicable
to any request method.
.IP "500 HTTP::Throwable::Role::Status::InternalServerError" 4
.IX Item "500 HTTP::Throwable::Role::Status::InternalServerError"
.PD 0
.IP "501 HTTP::Throwable::Role::Status::NotImplemented" 4
.IX Item "501 HTTP::Throwable::Role::Status::NotImplemented"
.IP "502 HTTP::Throwable::Role::Status::BadGateway" 4
.IX Item "502 HTTP::Throwable::Role::Status::BadGateway"
.IP "503 HTTP::Throwable::Role::Status::ServiceUnavailable" 4
.IX Item "503 HTTP::Throwable::Role::Status::ServiceUnavailable"
.IP "504 HTTP::Throwable::Role::Status::GatewayTimeout" 4
.IX Item "504 HTTP::Throwable::Role::Status::GatewayTimeout"
.IP "505 HTTP::Throwable::Role::Status::HTTPVersionNotSupported" 4
.IX Item "505 HTTP::Throwable::Role::Status::HTTPVersionNotSupported"
.PD
.SH "COMPOSING WITH HTTP::THROWABLE"
.IX Header "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:
.PP
HTTP::Throwable is mostly concerned about providing basic headers and a
\&\s-1PSGI\s0 representation.  It doesn't worry about the body or a
stringification.  You \fBmust\fR provide the methods \f(CW\*(C`body\*(C'\fR and
\&\f(CW\*(C`body_headers\*(C'\fR and \f(CW\*(C`as_string\*(C'\fR.
.PP
The \f(CW\*(C`body\*(C'\fR method returns the string (of octets) to be sent as the \s-1HTTP\s0
entity.  That body is passed to the \f(CW\*(C`body_headers\*(C'\fR method, which must
return an arrayref of headers to add to the response.  These will
generally include the Content-Type and Content-Length headers.
.PP
The \f(CW\*(C`as_string\*(C'\fR method should return a printable string, even if the
body is going to be empty.
.PP
For convenience, these three methods are implemented by the roles
HTTP::Throwable::Role::TextBody and HTTP::Throwable::Role::NoBody.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
<http://www.w3.org/Protocols/rfc2616/rfc2616\-sec10.html>
.IP "\(bu" 4
Plack::Middleware::HTTPExceptions
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Stevan Little <stevan.little@iinteractive.com>
.IP "\(bu" 4
Ricardo Signes <rjbs@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011 by Infinity Interactive, Inc..
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.