PSGI Applications

The PSGI spec defines a PSGI application.

A PSGI application is a Perl code reference. It takes exactly one argument, the environment, and returns an array reference containing exactly three values.

The three values are a status, headers, and a body. Here is an example:

my $app = sub {
    my $env = shift;
    return [
        '200',
        [ 'Content-Type' => 'text/plain' ],
        [ "Hello World" ], # or IO::Handle-like object
    ];
};

The PSGI environment hash

The PSGI environment hash is a hashref with many keys. But mostly it is the data (headers, body, etc) from an HTTP::Request which has been parsed and put into a hash for convenient access.

Middleware

A middleware component takes a PSGI application and runs it, passing in the PSGI environment hash. But before it runs the app, it gets to modify the environment if it wants to. And after running the app, it can modify the response if it wants to.

Plack::Middleware

Middleware is a wrapper around a PSGI app. More than one middleware can be wrapped around an app, creating a series of layers like an onion. What makes the middleware onion a somewhat unusual construct is the event driven / callback nature of it. Lets look at how its implemented.

All middleware inherits from Plack::Middleware which is an itsy bitsy (teeny weeny) module. The middleware onion is created with just 2 short subroutines (notice the call() and prepare_app() subs are written by middleware authors):

sub wrap {
    my($self, $app, @args) = @_;
    if (ref $self) {
        $self->{app} = $app;
    } else {
        $self = $self->new({ app => $app, @args });
    }
    return $self->to_app;
}

sub to_app {
    my $self = shift;
    $self->prepare_app;
    return sub { $self->call(@_) };
}

How do these subs work together? The middleware onion is sometimes constructed as follows:

my $app = MyWebApp->new->to_app;
$app = Plack::Middleware::A->wrap($app);
$app = Plack::Middleware::B->wrap($app);
$app = Plack::Middleware::C->wrap($app);

But it might be more clear to write it this way

my $app0 = MyWebApp->new->to_app;           # $app0->($env) runs the web app
$app1 = Plack::Middleware::A->wrap($app0);  # $app1->($env) calls P::M::A->call() which calls $app0->($env)
$app2 = Plack::Middleware::B->wrap($app1);  # $app2->($env) calls P::M::B->call() which calls $app1->($env)
$app3 = Plack::Middleware::C->wrap($app2);  # $app3->($env) calls P::M::C->call() which calls $app2->($env)
                                            # When the server receives a request it calls $app3->($env)

So when an event occurs – for example the PSGI server sees a new request – it passes the event to the app. The app is a chain of callbacks which run each other. This is clearly an example of event driven programming.

Plack::Component and Plack::App

Plack::Middleware inherits from Plack::Component. So the most common use of Plack::Component is in middleware.

Plack::Component can also be used as a tool for creating PSGI applications. It has a light dusting of code, but mostly its an interface which is implemented by modules in the Plack::App namespace. For example Plack::App::File is a web app which serves static files from a root directory, and Plack::App::URLMap is a web app which maps multiple web apps to multiple urls.

But notice that I am not required to use Plack::Component to create a PSGI application. A PSGI application is just a code reference. The PSGI spec does not say that a PSGI application is a reference to code that inherits from Plack::Component.

The nice thing about using Plack::Component to build my app is that it provides a common interface for all PSGI apps. Whenever I see $app, I can rely on that behavior. This is clearly important for middleware. And it feels good from a design point of view.

But its not required and it adds some complexity.