/ 
Mason-Plugin-PSGIHandler-0.03
River stage zero No dependents
/ Mason::Plugin::PSGIHandler

NAME

Mason::Plugin::PSGIHandler - PSGI handler for Mason

SYNOPSIS

# Quick start:
mason_psgi_setup myapp

# app.psgi
use Mason;
use Plack::Builder;
my $interp = Mason->new(
     plugins => ['PSGIHandler', ...],
     comp_root => '/path/to/comp_root/',
     data_dir => '/path/to/data_dir/',
);
my $app = sub {
    my $env = shift;
    $interp->handle_psgi($env);
};
builder {
    # Include PSGI middleware here
    $app;
};

DESCRIPTION

Provides a PSGI handler for Mason. It allows Mason to handle requests directly from any web servers that support PSGI.

Run path

The top-level run path is taken from the method "path" in Plack::Request. So in a simple Plack configuration like the one above, a URL like

/foo/bar

would result in

$interp->run("/foo/bar");

However, if you mounted your Mason app under "/mason",

builder {
    mount "/mason" => builder {
        $app;
    };
    mount "/other" => $other_app;
    ...
};

then the "/mason" portion of the URL would get stripped off in the top-level run path.

Run parameters

The top-level run parameters are taken from the method "parameters" in Plack::Request, which combines GET and POST parameters. So

/foo/bar?a=5&b=6

would generally result in

$interp->run("/foo/bar", a=>5, b=>6);

If there are multiple values for a parameter, generally only the last value will be kept, as per Hash::MultiValue. However, if the corresponding attribute in the page component is declared an ArrayRef, then all values will be kept and passed in as an arrayref. For example, if the page component /foo/bar.m has these declarations:

<%args>
$.a
$.b => (isa => "Int")
$.c => (isa => "ArrayRef");
$.d => (isa => "ArrayRef[Int]");
</%args>

then this URL

/foo/bar?a=1&a=2&b=3&b=4&c=5&c=6&d=7&d=8

would result in

$interp->run("/foo/bar", a=>2, b=>4, c=>[5,6], d => [7,8]);

You can always get the original Hash::MultiValue object from $m->request_args. e.g.

my $hmv = $m->request_args;
# get all values for 'e'
$hmv->get_all('e');

Plack request object

A Mason::Plack::Request is constructed from the plack environment and made available in $m->req. This is a thin subclass of Plack::Request and provides information such as the URL and incoming HTTP headers. e.g.

my $headers = $m->req->headers;
my $cookie = $m->req->cookies->{'foo'};

Plack response object

An empty Mason::Plack::Response is constructed and made available in $m->res. Your Mason components are responsible for setting the status and headers, by calling $m->res->status and $m->res->headers or utility methods that do so. e.g.

$m->res->content_type('text/plain');
$m->res->cookies->{foo} = { value => 123 };

$m->redirect('http://www.google.com/', 301)  # sets header/status and aborts
$m->clear_and_abort(404);   # sets status and aborts

If the Mason request finishes successfully, the Mason output becomes the plack response body; any value explicitly set in $m->res->body is ignored and overwritten. $m->res->status is set to 200 if it hasn't already been set.

If the top-level component path cannot be found, $m->res->status is set to 404. All other runtime errors fall through to be handled by Plack, i.e. with Plack::Middleware::StackTrace in development mode or a 500 error response in deployment mode.

INTERP METHODS

handle_psgi ($env)

Takes a PSGI environment hash, calls an appropriate Mason request as detailed above, and returns a standard PSGI response array.

REQUEST METHODS

req ()

A reference to the Mason::Plack::Request.

res ()

A reference to the Mason::Plack::Response.

redirect (url[, status])

Sets headers and status for redirect, then clears the Mason buffer and aborts the request. e.g.

$m->redirect("http://somesite.com", 302);

is equivalent to

$m->res->redirect("http://somesite.com", 302);
$m->clear_and_abort();
not_found ()

Sets the status to 404, then clears the Mason buffer and aborts the request. Equivalent to

$m->res->status(404);
$m->clear_and_abort();
abort (status)
clear_and_abort (status)

These methods are overriden to set the response status before aborting, if status is provided. e.g. to send back a NOT FOUND result:

$m->clear_and_abort(404);

This is equivalent to

$m->res->status(404);
$m->clear_and_abort();

SUPPORT

The mailing list for Mason and Mason plugins is mason-users@lists.sourceforge.net. You must be subscribed to send a message. To subscribe, visit https://lists.sourceforge.net/lists/listinfo/mason-users.

You can also visit us at #mason on irc://irc.perl.org/#mason.

Bugs and feature requests will be tracked at RT:

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mason-Plugin-PSGIHandler
bug-mason-plugin-psgihandler@rt.cpan.org

The latest source code can be browsed and fetched at:

http://github.com/jonswar/perl-mason-plugin-psgihandler
git clone git://github.com/jonswar/perl-mason-plugin-psgihandler.git

SEE ALSO

Mason, http://plackperl.org/|PSGI