PSGI - interface between web servers and perl web applications

Not so long ago, the specification of the interface between web servers and applications / frameworks on perl PSGI - the Perl Web Server Gateway Interface Specification . PSGI adds a layer of abstraction, allowing you not to worry about a specific way to connect to a web server, and implement a single interface for the specification. You can launch such an application on servers that support PSGI - at the moment it is Plack (a set of servers and utilities), nginx (with a patch for PSGI support and embedded perl) and Apache with mod_psgi.

Applications

A PSGI application is a function that takes as its argument a reference to the hash with environment variables and returns the response.

Request

The hash passed to the application contains variables whose names are similar to the header names in CGI - REQUEST_METHOD, SCRIPT_NAME, QUERY_STRING, etc., as well as the headers from the HTTP request (starting with HTTP_, for example HTTP_HHT). In addition, the hash should contain PSGI-specific variables:

• psgi.version: Reference to array [1.0] containing the version of PSGI.
• psgi.url_scheme: http or https, depending on the request.
• psgi.input: input stream.
• psgi.errors: error output stream.
• psgi.multithread: true if the application can be called in another thread of the same process.
• psgi.multiprocess: true if the application can be called in another process.

Also hash can contain additional variables:

• psgi.run_once: true if expected (but not guaranteed) that the application will be called only once before the process is complete (usually true only if the application is connected to the server via CGI).
• psgi.nonblocking: true if the application is called in the event loop.
• psgi.streaming: true if the server supports deferred responses and streaming.

An application can analyze environment variables, and take into account server features or complete its execution if the server does not support what the application needs (for example, the application being launched is non-blocking, and the server is written in synchronous style).

Answer

In general, an application should return a link to an array of three elements — the HTTP response code, headers, and the response body. The HTTP response code must be an integer number of at least 100. Headers are transmitted as a link to an array, and the Content-Type header must be present (except for answers 1xx, 204 or 304). The response body can be a link to an array of strings (or the entire answer without line-by-line separation), either an IO :: Handle-like object or a file descriptor. If a deferred response is required, the application can return the function to which the callback will be passed for the answer.
')

Sample application

This is the simplest PSGI application:

sub { [ 200 , [ 'Content-Type' => 'text/plain' ] , [ 'Hi, ' . shift -> { REMOTE_ADDR } ] ] }

Middleware

Middleware is similar to a normal application, but it takes 2 arguments — environment variables and the response of the PSGI application. Middleware can be used to analyze this data (for example, the usual access log maintenance) or their modification. Here is an example of middleware that adds the X-PSGI-Used header to the response:

my $app = sub { [ 200 , [ 'Content-Type' => 'text/plain' ] , [ 'Hi, ' . shift -> { REMOTE_ADDR } ] ] } <br/>
my $middleware = sub { <br/>
my $env = shift ; <br/>
my $res = $app -> ( $env ) ; <br/>
push @ { $res -> [ 1 ] } , 'X-PSGI-Used' => 1 ; <br/>
return $res ; <br/>
} ;

For Plack on CPAN, there is a rather large set of diverse middleware .

Servers

The server ensures the launch of the PSGI application and must compile a hash with environment variables and pass it to the application, as well as process the response. Now there are several PSGI servers:

• Plack is a set of middleware and servers, most of which are wrappers over existing Perl modules. In addition, there are several servers in the same namespace that are not present in the Plack distribution on the CPAN: AnyEvent , FCGI :: EV , Danga :: Socket , Coro , POE, and ServerSimple . Starting a PSGI application on Plack is simple:
  

  plackup --server Coro --port 9090 --host 127.0.0.1 test.psgi

• nginx patch for psgi support
• mod_psgi for Apache
• Perlbal
• some other servers

Separately, I would like to mention Plack :: Server :: AnyEvent and Plack :: Server :: Coro - these servers support file AIO, so small non-blocking PSGI applications based on them can be used to distribute statics with no blocks at all, while AIO support is not ready in nginx.

Framework support

Now there is support for PSGI in all popular web frameworks: Catalyst , CGI :: Application , HTTP :: Engine , Dancer , Mason , Squatting , Continuity , Maypole , Tatsumaki

Links

PSGI / Plack website
PSGI Specification for CPAN
PSGI :: FAQ
Plack on CPAN