Plack Advent Calendar

Day 15: Authenticate your app with Middleware

There're lots of Plack middleware components out there, whether in Plack core distribution as well as separate distributions on CPAN. While I've been writing this Plack advent calendar lots of people have shown their interest and taken ideas out of my wishlist.

From today we'll introduce some of the nice middleware components that you can use quickly to enhance any of your PSGI ready applications.

Basic authentication

Since Plack middleware wraps an application, the best thing it can do is pre-process or post-process to do things around HTTP layers. Today let's talk about the Basic Authentication.

Adding a basic authentication can be done in multiple ways: you can do that in the web application framework layer if it's supported in your framework. In case of Catalyst it's Catalyst::Authentication::Credential::HTTP. Just like other Catalyst tools, it allows you to configure the authentication from simple to very complex, by using credential (how to authenticate: basic and/or digest) and store (how to authorize username and passwords).

Otherwise you can do the authentication in the web server layer. For instance if you run your application with Apache and mod_perl, using Apache's default mod_auth module to authenticate is pretty easy and handy for development, while it limits the ability to share "how to authenticate users" since usually you need to write your custom module to do things like database backed authentication.

Plack middleware allows web application frameworks to share such a functionality, mostly with a pretty simple Perl callback system, and Plack::Middleware::Auth::Basic is to do this for Basic authentication. And this is why most Plack standalone servers do not have an authentication system: it's best implemented as a middleware component.

Using Plack::Middleware::Auth::Basic

Just like other middleware, using Auth::Basic middleware is quite simple:

use Plack::Builder;

my $app = sub { ... };

builder {
    enable "Auth::Basic", authenticator => sub {
        my($username, $password) = @_;
        return $username eq 'admin' && $password eq 'foobar';
    };
    $app;
};

This adds a basic authentication to your application $app, and the user admin can sign in with the password foobar and nobody else. The successful signed-in user gets REMOTE_USER set in PSGI $env hash so it can be used in the applications and is logged using the standard AccessLog middleware.

Since it's a callback based, adding another authentication system such as Kerberos would be pretty trivial and easy with modules such as Authen::Simple:

use Plack::Builder;
use Authen::Simple;
use Authen::Simple::Kerberos;

my $auth = Authen::Simple->new(
    Authen::Simple::Kerberos->new(realm => ...),
);

builder {
    enable "Auth::Basic", authenticator => sub {
        $auth->authenticate(@_):
    };
    $app;
};

The same way you can use lots of Authen::Simple backends with small changes.

With URLMap

URLMap allows you to compound multiple apps into one app, so combined with Auth middleware, you can run the same application in a auth vs. non-auth mode, using different paths:

use Plack::Builder;
my $app = sub {
    my $env = shift;
    if ($env->{REMOTE_USER}) { 
        # Authenticated
    } else {
        # Unauthenticated
    }
};

builder {
    mount "/private" => builder {
        enable "Auth::Basic", authenticator => ...;
        $app;
    };
    mount "/public" => $app;
};

This way you run the same $app in "/public" and "/private" paths, while "/private" requires a basic authentication and "/public" doesn't. (Inlining $env->{REMOTE_USER}, or whatever application logic in .psgi is not really recommended -- i just used it to explain it in an obvious way)

Day 14: Use Plack::Request

Plack is not a framework per se, but is more of a toolkit that contains PSGI server implementations as well as utilities like plackup, Plack::Test and Middleware components.

Since Plack project is a revolution from HTTP::Engine, there seems a demand to write a quick web application in Request/Response style handler API. Plack::Request gives you a nice Object Oriented API around PSGI environment hash and response array, just like Rack's Rack::Request and Response objects. It could also be used as a library when writing a new middleware component, and a base class for requests/responses when you write a new web application framework based on Plack.

Use Plack::Request and Response

Plack::Request is a wrapper around PSGI environment, and the code goes like this:

use Plack::Request;

my $app = sub {
    my $req = Plack::Request->new(shift);

    my $name = $req->param('name');
    my $res  = $req->new_response(200);
    $res->content_type('text/html');
    $res->content("<html><body>Hello World</body></html>");

    return $res->finalize;
};

The only thing you need to change, if you're migrating from HTTP::Engine, is the first line of the application to create a Plack::Request out of PSGI env (shift) and then call finalize to get an array reference out of Response object.

All other methods like path_info, uri, param, redirect etc. work like HTTP::Engine::Request and Response object which is very similar to Catalyst 's Request and Response object.

Plack::Request and Plack

Plack::Request is available as part of Plack on CPAN. Your framework can use Plack::Request to handle parameters and can also make it run on other PSGI server implementations such as mod_psgi.

Use Plack::Request or not?

Directly using Plack::Request in the .psgi code is quite handy to quickly write and test your code but not really recommended for a large scale application. It's exactly like writing a 1000 lines of .cgi script where you could factor out the application code into a module (.pm files). The same thing applies to .psgi file: it's best to create an application class by using and possibly extending Plack::Request, and then have just a few lines of code in .psgi file with Plack::Builder to configure middleware components.

Plack::Request is also supposed to be used from a web application framework to adapt to PSGI interface.

Day 13: use Plack::Test to test your application

Testing

There are many ways to test web applications, either with a live server or using a mock request technique. Some web application frameworks allow you to write an unit test using one of those methods, but the way you write tests differ per framework of your choice.

Plack::Test gives you an unified interface to test any web applications and frameworks that is compatible to PSGI using both mock request and live HTTP server.

Using Plack::Test

Using Plack::Test is pretty simple and it's of course compatible to the Perl's standard testing protocol TAP and Test::More.

use Plack::Test;
use Test::More;
use HTTP::Request;

my $app = sub {
    return [ 200, [ 'Content-Type', 'text/plain' ], [ "Hello" ] ];
};

test_psgi $app, sub {
    my $cb = shift;

    my $req = HTTP::Request->new(GET => 'http://localhost/');
    my $res = $cb->($req);

    is $res->code, 200;
    is $res->content, "Hello";
};

done_testing;

Create or load PSGI application like usual (you can use Plack::Util's load_psgi function if you want to load an app from a .psgi file), and call test_psgi function to test the application. The second argument is a callback that acts as a testing client.

You can use the named parameters as well, like the following.

test_psgi app => $app, client => sub { ... }

The client code takes a callback ($cb), which you can pass an HTTP::Request object that would return HTTP::Response object, like normal LWP::UserAgent would do, and you can make as many requests as you want, and test various attributes and response details.

Save that code as .t file and use the tool such as prove to run the tests.

use HTTP::Request::Common

This is not required, but recommended to use HTTP::Request::Common when you want to make an HTTP request, since it's more obvious and less code to write:

use HTTP::Request::Common;

test_psgi $app, sub {
    my $cb = shift;
    my $res = $cb->(GET "/");
    # ...
};

Notice that you can even omit the scheme and hostname, which would default to http://localhost/ anyway.

Run in a server/mock mode

By default the test_psgi function's callback runs as a Mock HTTP request mode, turning a HTTP::Request object into a PSGI env hash and then run the PSGI application, and returns the response as a HTTP::Response object.

You can change this to live HTTP mode, by setting either a) the package variable $Plack::Test::Impl or b) the environment variable PLACK_TEST_IMPL to the string Server.

use Plack::Test;
$Plack::Test::Impl = "Server";

test_psgi ... # the same code

By using the environment variable, you don't really need to change the .t code:

env PLACK_TEST_IMPL=Server prove -l t/test.t

This will run the PSGI application using the Standalone server backend and uses LWP::UserAgent to send the live HTTP request. You don't need to modify your testing client code, and the callback would automatically adjust host names and port numbers depending on the test configuration.

Test your web application framework with Plack::Test

Once again, the beauty of PSGI and Plack is that everything written to run for the PSGI interface can be used for any web application frameworks that speaks PSGI. By running your web application framework in PSGI mode, you can also use Plack::Test:

use Plack::Test;
use MyCatalystApp;

MyCatalystApp->setup_engine('PSGI');
my $app = sub { MyCatalystApp->run(@_) };

test_psgi $app, sub {
    my $cb = shift;
    # ...
};
done_testing;

You can of course do the same thing against any frameworks that supports PSGI.

Day 12: Maps multiple apps with mount and URLMap

Hello World! but anyone else?

Throughout the advent calendar we most of the time use the simplest web application using the "Hello World" example, like

my $app = sub {
    return [ 200, [], [ "Hello World" ] ];
};

what about more complex examples, like you have multiple applications, each of which inherit from one of the web application frameworks, and use one of apache magic like mod_alias etc.

Plack::App::URLMap

Plack::App::URLMap allows you to composite multiple PSGI applications into one application, to dispatch requests to multiple applications using the URL path, or even with virtual host based dispatch.

my $app1 = sub {
    return [ 200, [], [ "Hello John" ] ];
};

my $app2 = sub {
    return [ 200, [], [ "Hello Bob" ] ];
};

So you have two apps, one is to say hi to John and another to Bob, and say if you want to run this two application on the same server. With Plack::App::URLMap, you can do this.

use Plack::App::URLMap;
my $app = Plack::App::URLMap->new;
$app->mount("/john" => $app1);
$app->mount("/bob"  => $app2);

There you go. Your app now dispatches all requests beginning with /john to $app1 which says "Hello John" and /bob to $app2, which is to say "Hello Bob". As a result, all requests to unmapped paths, like the root ("/") gives you 404.

The environment variables such as PATH_INFO and SCRIPT_NAME are automatically adjusted so it just works like when your application is mounted using Apache's mod_alias or CGI scripts. Your application framework should always use PATH_INFO to dispatch requests, and concatenate with SCRIPT_NAME to build links.

mount in DSL

This mount interface with Plack::App::URLMap is quite useful, so we decided to add to Plack::Builder DSL itself, which is again an inspiration by Rack::Builder, using the syntax mount:

use Plack::Builder;
builder {
    mount "/john" => $app1;
    mount "/bob"  => builder {
        enable "Auth::Basic", authenticator => ...;
        $app2;
    };
};

Requests to '/john' is handled exactly the same way with the normal URLMap. But this example uses builder for "/bob", so it enables the basic authentication to display the "Hello Bob" page. This should be syntactically equivalent to:

$app = Plack::App::URLMap->new;
$app->mount("/john", $app1);

$app2 = Plack::Middleware::Auth::Basic->wrap($app2, authenticator => ...);
$app->mount("/bob",  $app2);

but obviously, with less code to write and more obvious to understand what's going on.

Multi tenant frameworks

Of course you can use this URLMap and mount API to run multiple framework applications on one server. Imagine you have three applications, "Foo" which is based on Catalyst, "Bar" which is based on CGI::Application and "Baz" which is based on Squatting. Do this:

# Catalyst
use Foo;
Foo->setup_engine('PSGI');

my $app1 = sub { Foo->new->run(@_) };

# CGI::Application
use Bar;
use CGI::Application::PSGI;
my $app2 = sub { 
    my $app = Bar->new({ QUERY => CGI::PSGI->new(shift) });
    CGI::Application::PSGI->run($app);
};

# Squatting
use Baz 'On::PSGI';
Baz->init;
my $app3 = sub { Baz->psgi(shift) };

builder {
    mount "/foo" => $app1;
    mount "/bar" => $app2;
    mount "/baz" => $app3;
};

And now you have three applications, each of which inherit from different web framework, running on the same server (via plackup or other Plack::Server::* implementations) mapped on different paths.

Day 11: Using Plack::Builder

Yesterday we saw how to enable Plack middleware components in .psgi file, using its wrap class method. The way you use the middleware and then wrap the $app with wrap is tedious and not intuitive, so we have a DSL (Domain Specific Language) to make it much easier, and that is Plack::Builder.

Using Plack::Builder

The way you use Plack::Builder is so easy. Just use the keywords builder and enable:

my $app = sub { 
    return [ 200, [], [ "Hello World" ] ];
};

use Plack::Builder;
builder {
    enable "JSONP";
    enable "Auth::Basic", authenticator => sub { ... };
    enable "Deflater";
    $app;
};

This takes the original application ($app) and wraps it with Deflater, Auth::Basic and JSONP middleware components (inner to outer). So it's equivalent to:

$app = Plack::Middleware::Deflater->wrap($app);
$app = Plack::Middleware::Auth::Basic->wrap($app, authenticator => sub { });
$app = Plack::Middleware::JSONP->wrap($app);

but without lots of useing the module which is anti DRY.

Outer to Inner, Top to the bottom

Notice that the order of middleware wrapping is in reverse? The builder/enable DSL allows you to wrap application so the line close to the original $app is inner, while the first one in the top is outer. You can compare that with the onion picture and see that it's more obvious: something closer to the application is inner.

enable takes the middleware name without the Plack::Middleware:: prefix but in case you want to enable some other namespace, like MyFramework::PSGI::MW::Foo, you can say:

enable "+MyFramework::PSGI::MW::Foo";

the key here is to use the plus (+) sign to indicate that it is a fully qualified class name.

What's happening behind

If you're curious what Plack::Builder is doing, take a look at the code and see what's happening. The builder takes the code block and executes the code, and take the result (return value of the last statement) as an original application ($app), and then returns the wrapped application by applying Middleware in the reverse order. So it is important to have $app in the last line inside the builder block, and have the builder statement as the final statement in .psgi file as well.

Thanks, Rack

This idea of Plack::Builder is totally an inspiration by Rack::Builder. You can see that they use the use keyword but obviously we can's use that in Perl :) so we chose enable instead. You can see that they have map which is to map applications to a different path, and we'll talk about its equivalent in Plack tomorrow ;)

Day 10: Using Plack middleware

Middleware

Middleware is a concept in PSGI (as always, stolen from Python's WSGI and Ruby's Rack) where we define components that plays the both side of a server and an application.

This picture illustrates the middleware concept very well. The PSGI application is in the core of the Onion layers, and middleware components wrap the original application in return, and they preprocess as a request comes in (outer to inner) and then postprocess the response as a response goes out (inner to outer).

Lots of functionalities can be added to the PSGI application by wrapping it with a middleware component, from HTTP authentication, capturing errors to logging output or wrapping JSON output with JSONP.

Plack::Middleware

Plack::Middleware is a base class for middleware components and it allows you to write middleware really simply but in a reusable fashion.

Using Middleware components written with Plack::Middleware is easy, just wrap the original application with wrap method:

my $app = sub { [ 200, ... ] };

use Plack::Middleware::StackTrace;
$app = Plack::Middleware::StackTrace->wrap($app);

This example wraps the original application with StackTrace middleware (which is actually enabled by default using plackup) with the wrap method. So when the wrapped application throws an error, the middleware component catches the error to display a beautiful HTML page using Devel::StackTrace::AsHTML.

Some other middleware components take parameters, in which case you can pass the parameters as a hash after $app, like:

my $app = sub { ... };

use Plack::Middleware::MethodOverride;
$app = Plack::Middleware::MethodOverride->wrap($app, header => 'X-Method');

Installing multiple middleware components is tedious especially since you need to use those modules first, and we have a quick solution for that using a DSL style syntax.

use Plack::Builder;
my $app = sub { ... };

builder {
    enable "StackTrace";
    enable "MethodOverride", header => 'X-Method';
    enable "Deflater";
    $app;
};

We'll see more about Plack::Builder tomorrow.

Middleware and Frameworks

The beauty of Middleware is that it can wrap any PSGI application. It might not be obvious from the code examples, but the wrapped application can be anything, which means you can run your existing web application in the PSGI mode and apply middleware components to it. For instance, with CGI::Application:

use CGI::Application::PSGI;
use WebApp;

my $app = sub {
    my $env = shift;
    my $app = WebApp->new({ QUERY => CGI::PSGI->new($env) });
    CGI::Application::PSGI->run($app);
};

use Plack::Builder;
builder {
    enable "Auth::Basic", authenticator => sub { $_[1] eq 'foobar' };
    $app;
};

This will enable the Basic authentication middleware to CGI::Application based application. You can do the same with any other frameworks that supports PSGI.

Day 9: Running CGI scripts on Plack

For the couple of days we've been talking about how to convert existing CGI based applications to PSGI, and then run them as a PSGI application. Today we'd show you the ultimate way to run any CGI scripts as a PSGI application, most of the time unmodified.

CGI::PSGI is a subclass of CGI.pm to allow you a very easy migration from CGI.pm with only a few lines of code changes to run it on PSGI environment. But what about a messy or legacy CGI script that just prints to STDOUT a lot and is not easy to fix?

CGI::Emulate::PSGI is a module to run any CGI based perl program in a PSGI environment. Whatever messy/old script that prints stuff to STDOUT or directly reads HTTP headers from %ENV would just work because that's what CGI::Emulate::PSGI tries to emulate. The original POD of CGI::Emulate::PSGI was illustrating it like:

use CGI::Emulate::PSGI;
CGI::Emulate::PSGI->handler(sub {
    do "/path/to/foo.cgi";
    CGI::initialize_globals() if &CGI::initialize_globals;
});

to run existing CGI application that may or may not use CGI.pm (CGI.pm caches lots of environment variables so it needs initialize_globals() call to clear out the previous request variables).

A few days ago on my flight from San Francisco to London to attend London Perl Workshop I was hacking on something more intelligent, that is to take any CGI scripts and compiles it into a subroutine. The module is named CGI::Compile and should be best used combined with CGI::Emulate::PSGI.

my $sub = CGI::Compile->compile("/path/to/script.cgi");
my $app = CGI::Emulate::PSGI->handler($sub);

There's also Plack::App::CGIBin Plack application to run existing CGI scripts written in Perl as PSGI applications, suppose you have bunch of CGI scripts in /path/to/cgi-bin, you'll run the server with:

> plackup -MPlack::App::CGIBin -e 'Plack::App::CGIBin->new(root => "/path/to/cgi-bin"))'

And that will mount the path /path/to/cgi-bin, so suppose you have foo.pl in that directory, you can access http://localhost:5000/foo.pl to run the CGI application as a PSGI over the plackup, just like the scripts running on Apache mod_perl Registry mechanism.

Day 8: Adapting web frameworks to PSGI

The biggest benefit of PSGI in terms of web application framework developers is that, once you adapt your framework to run on PSGI, you forget and throw away everything else that you needed to deal with, say, handle the differences between bunch of FastCGI servers or CGI.

Similarly, if you have a large scale web application, open source or proprietary, you probably have your own web application framework (or a base class or whatever).

Today's entry discusses how to convert existing web application framework to adapt to the PSGI interface.

CGI.pm based framework

In Day 7 we saw how to run CGI::Application based application in PSGI, using CGI::Application::PSGI. CGI::Application, as the name suggests, uses CGI.pm, so using CGI::PSGI instead and define a new runner class is the easiest to go.

package CGI::Application::PSGI;
use strict;
use CGI::PSGI;

sub run {
    my($class, $app) = @_;

    # HACK: deprecate HTTP header generation
    # -- CGI::Application should support some flag to turn this off cleanly
    my $body = do {
        no warnings 'redefine';
        local *CGI::Application::_send_headers = sub { '' };
        local $ENV{CGI_APP_RETURN_ONLY} = 1;
        $app->run;
    };

    my $q    = $app->query;
    my $type = $app->header_type;

    my @headers = $q->psgi_header($app->header_props);
    return [ @headers, [ $body ] ];
}

This is quite simple, isn't it? CGI::Application's run() method usually returns the whole output, including HTTP headers and content body. As you can see, the module does some gross hack to disable the header generation since you can use psgi_header method of CGI::PSGI to generate the status code and HTTP headers as an array ref.

I've implemented PSGI adapters for Mason and Maypole and the code was pretty much look alike.

• Create CGI::PSGI out of $env and set that instead of the default CGI.pm instance
• Disable HTTP header generation if needed
• Runs the app main dispatcher
• Extracts the HTTP headers to be sent, use psgi_header to generate the status and headers
• Extracts the response body (content)

Adapter based framework

If the framework in question already uses adapter based approaches to abstract server environments, it'd be much easier to adapt to PSGI, by reusing most of the CGI adapter code. Here's the code to adapt Squatting to PSGI. Squatting uses Squatting::On::* namespace to adapt to environments like mod_perl, FastCGI or even other frameworks like Catalyst or HTTP::Engine. It was extremely easy to write Squatting::On::PSGI:

package Squatting::On::PSGI;
use strict;
use CGI::Cookie;
use Plack::Request;
use Squatting::H;

my %p;
$p{init_cc} = sub {
  my ($c, $env)  = @_;
  my $cc       = $c->clone;
  $cc->env     = $env;
  $cc->cookies = $p{c}->($env->{HTTP_COOKIE} || '');
  $cc->input   = $p{i}->($env);
  $cc->headers = { 'Content-Type' => 'text/html' };
  $cc->v       = { };
  $cc->status  = 200;
  $cc;
};

# \%input = i($env)  # Extract CGI parameters from an env object
$p{i} = sub {
  my $r = Plack::Request->new($_[0]);
  my $p = $r->params;
  +{%$p};
};

# \%cookies = $p{c}->($cookie_header)  # Parse Cookie header(s).
$p{c} = sub {
  +{ map { ref($_) ? $_->value : $_ } CGI::Cookie->parse($_[0]) };
};

sub psgi {
  my ($app, $env) = @_;

  $env->{PATH_INFO} ||= "/";
  $env->{REQUEST_PATH} ||= do {
      my $script_name = $env->{SCRIPT_NAME};
      $script_name =~ s{/$}{};
      $script_name . $env->{PATH_INFO};
  };
  $env->{REQUEST_URI} ||= do {
    ($env->{QUERY_STRING})
      ? "$env->{REQUEST_PATH}?$env->{QUERY_STRING}"
      : $env->{REQUEST_PATH};
  };

  my $res;
  eval {
      no strict 'refs';
      my ($c, $args) = &{ $app . "::D" }($env->{REQUEST_PATH});
      my $cc = $p{init_cc}->($c, $env);
      my $content = $app->service($cc, @$args);

      $res = [
          $cc->status,
          [ %{ $cc->{headers} } ],
          [ $content ],
      ];
  };

  if ([email protected]) {
      $res = [ 500, [ 'Content-Type' => 'text/plain' ], [ "<pre>[email protected]</pre>" ] ];
  }

  return $res;
}

This is very straightforward, especially when compared with Squatting::On::CGI. It's almost line-by-line copy and some adjustment to use Plack::Request to parse parameters instead of CGI.pm.

Similarly Catalyst uses Catalyst::Engine abstraction and Catalyst::Engine::PSGI is the adapter to run Catlayst on PSGI, which most of the code is copied from CGI.

mod_perl centric frameworks

Some frameworks are centered around mod_perl's API, in which case we can't take the approaches like we've seen here. Instead, you should probably start by mocking Apache::Request APIs using a fake/mock object. Patric Donelan, a WebGUI developer explains his approach to make mod_perl-like API in his blog post that you might be interested in, and the mock request class linked would be a good start.

Day 7: Use web application framework in PSGI

Since we started this Plack and PSGI project in September, there have been lots of feedbacks from the authors of most popular frameworks, like Catalyst, Jifty and CGI::Application.

CGI::Application is one of the most "traditional" CGI-based web application framework, and it's using CGI.pm exclusively to handle web server environments just like we discussed yesterday.

Mark Stosberg, the current maintainer of CGI::Application and I have been collaborating on adding PSGI support to CGI::Application. We thought of multiple approaches, including adding a native PSGI support to CGI.pm, but we ended up implementing CGI::PSGI as a CGI.pm wrapper and then CGI::Application::PSGI to run existing CGI::Application unmodified in a PSGI compatible mode.

All you have to do is to install CGI::Application::PSGI from CPAN and write a .psgi file that looks like this:

use CGI::Application::PSGI;
use WebApp;

my $app = sub {
    my $env = shift;
    my $app = WebApp->new({ QUERY => CGI::PSGI->new($env) });
    CGI::Application::PSGI->run($app);
};

and use plackup to run the application with a standalone server or any other backends.

Similarly, most web frameworks that "supports" PSGI provides a plugin, engine or adapter to make the framework run on PSGI mode. For instance, Catalyst has a Catalyst::Engine::* web server abstraction and Catalyst::Engine::PSGI is the engine to adapt Catalyst to run on PSGI.

The point is that with "PSGI support" from web frameworks, your application doesn't need to be modified, most of the times any single lines of code. And then by switching to PSGI you'll have lots of benefits like being able to use toolchain like plackup, Plack::Test and middleware which we'll discuss later in the future advent entries.

Day 6: Convert CGI apps to PSGI

The most popular web server environments to run web applications, for Perl, has been CGI, FastCGI and mod_perl. CGI.pm is one of the Perl core module that happens to runs fine on any of those environments (with some tweaks). That means most web applications and frameworks somehow uses CGI.pm to deal with the environment differences because it's the easiest.

CGI::PSGI is a CGI module subclass that makes it easy to migrate existing CGI.pm based applications to PSGI. Imagine you have the following CGI application:

use CGI;

my $q = CGI->new;
print $q->header('text/plain'),
    "Hello ", $q->param('name');

This is a very simple CGI application, and converting this to PSGI is easy using the CGI::PSGI module:

use CGI::PSGI;

my $app = sub {
    my $env = shift;
    my $q = CGI::PSGI->new($env);
    return [ 
        $q->psgi_header('text/plain'),
        [ "Hello ", $q->param('name') ],
    ];
};

CGI::PSGI->new($env) takes the PSGI environment hash and creates an instance of CGI::PSGI, which is a subclass of CGI.pm. All methods including param(), query_string etc. do the right thing to get the values from PSGI environment rather than CGI's ENV values.

psgi_header is an utility method to work just like CGI's header method, and returns the status code and an array reference containing the list of HTTP headers.

Tomorrow, I'll talk about how to convert existing web frameworks that uses CGI.pm, using CGI::PSGI.