plucky (3) Plack::Middleware::HTTPExceptions.3pm.gz

NAME

       Plack::Middleware::HTTPExceptions - Catch HTTP exceptions

SYNOPSIS

         use HTTP::Exception;

         my $app = sub {
             # ...
             HTTP::Exception::500->throw;
         };

         builder {
             enable "HTTPExceptions", rethrow => 1;
             $app;
         };

DESCRIPTION

       Plack::Middleware::HTTPExceptions is a PSGI middleware component to catch exceptions from applications
       that can be translated into HTTP status codes.

       Your application is supposed to throw an object that implements a "code" method which returns the HTTP
       status code, such as 501 or 404. This middleware catches them and creates a valid response out of the
       code. If the "code" method returns a code that is not an HTTP redirect or error code (3xx, 4xx, or 5xx),
       the exception will be rethrown.

       The exception object may also implement "as_string" or overload stringification to represent the text of
       the error. The text defaults to the status message of the error code, such as Service Unavailable for
       503.

       Finally, the exception object may implement "as_psgi", and the result of this will be returned directly
       as the PSGI response.

       If the code is in the 3xx range and the exception implements the 'location' method (HTTP::Exception::3xx
       does), the Location header will be set in the response, so you can do redirects this way.

       There are CPAN modules HTTP::Exception and HTTP::Throwable, and they are perfect to throw from your
       application to let this middleware catch and display, but you can also implement your own exception class
       to throw.

       If the thrown exception is not an object that implements either a "code" or an "as_psgi" method, a 500
       error will be returned, and the exception is printed to the psgi.errors stream.  Alternatively, you can
       pass a true value for the "rethrow" parameter for this middleware, and the exception will instead be
       rethrown. This is enabled by default when "PLACK_ENV" is set to "development", so that the StackTrace
       middleware can catch it instead.

AUTHOR

       Tatsuhiko Miyagawa

SEE ALSO

       paste.httpexceptions HTTP::Exception HTTP::Throwable