/ 
Plack-Middleware-Return-MultiLevel-0.002
River stage zero No dependents
/ Plack::Middleware::Return::MultiLevel

TITLE

Plack::Middleware::Return::MultiLevel - Escape a PSGI app from anywhere in the stack

SYNOPSIS

use Plack::Builder;
use Plack::Middleware::Return::MultiLevel::Utils
  qw/return_to_level return_to_default_level/;

my $app = builder {
  enable "Return::MultiLevel";

  mount "/default" => sub {
    my $env = shift;
    return_to_default_level($env, [200, ['Content-Type', 'text/plain'], ['default']]);
  };

  mount '/layers' => builder {
    enable "Return::MultiLevel", level_name=>'one';
    enable "Return::MultiLevel", level_name=>'two';

    mount '/one' => sub {
      my $env = shift;
      return_to_level($env, 'one', [200, ['Content-Type', 'text/plain'], ['one']]);
    };

    mount '/two' => sub {
      my $env = shift;
      return_to_level($env, 'two', [200, ['Content-Type', 'text/plain'], ['two']]);
    };

  };

};

DESCRIPTION

Sometimes when in a PSGI application you want an easy way to escape out of the current callstack. For example you might wish to immediately end processing and return a 'NotFound' or 'ServerError' type response. In those cases you might use the core middleware Plack::Middleware::HTTPExceptions, which allows you to throw an exception object that matches a duck type (has methods code and as_string or as_psgi). That middleware wraps everything in an eval and looks for exception objects of that type, and converts them to a response.

Plack::Middleware::Return::MultiLevel is an alternative approach to solving this problem. Instead of throwing an exception, it uses Return::MultiLevel to set a 'callback' point that you can jump to at any time. If you don't like using exceptions for control flow, or you have code that does a lot of exception catching, you might prefer this approach.

Unlike Plack::Middleware::HTTPExceptions you don't need to return an object matching a ducktype, you can just return any standard, acceptable PSGI response.

CONSTANTS

This class defines the following constants

PSGI_KEY

PSGI environment key under which your return callback are stored.

DEFAULT_LEVEL_NAME

The default level name used if you choose not to explicitly name your return level target.

METHODS

This class defines the following methods.

prepare_app

Sets instance defaults

call

Used by plack to call the middleware

return

my $mw = Plack::Middleware::Return::MultiLevel->new;

#...

$mw->return([200, ['Content-Type', 'text/plain'], ['returned']]);

Returns to the callpoint set by Return::MultiLevel. You should pass this args suitable for a PSGI response.

Since the return callback is also stored in the $psgi_env, you are more likely to use methods from Plack::Middleware::Return::MultiLevel::Utils rather than storing the middleware object.

AUTHOR

John Napiorkowski email:jjnapiork@cpan.org

SEE ALSO

Return::MultiLevel, Plack, Plack::Middleware, Plack::Middleware::Return::MultiLevel::Utils

COPYRIGHT & LICENSE

Copyright 2014, John Napiorkowski email:jjnapiork@cpan.org

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.