1PSGI(3) User Contributed Perl Documentation PSGI(3)
2
6 PSGI - Perl Web Server Gateway Interface Specification
7
9 This document specifies a standard interface between web servers and
10 Perl web applications or frameworks, to promote web application
11 portability and reduce the duplicated efforts by web application
12 framework developers.
13 Keep in mind that PSGI is not Yet Another web application framework.
15 PSGI is a specification to decouple web server environments from web
16 application framework code. PSGI is also not the web application API.
17 Web application developers (end users) are not supposed to run their
18 web applications directly using the PSGI interface, but instead are
19 encouraged to use frameworks that support PSGI, or use the helper
20 implementations like Plack (more on that later).
21
23 Servers
24 Servers are web servers that accept HTTP requests, dispatch the
25 requests to the web applications and return the HTTP response to
26 the clients. In PSGI specification it's a Perl process that's
27 running inside an HTTP server (e.g. mod_perl in Apache), a daemon
28 process called from a web server (e.g. FastCGI daemon) or a pure
29 perl HTTP server.
30 Servers are also called PSGI implementations as well as Backends.
32 Applications
34 Applications are web applications that actually get HTTP requests
35 and return HTTP response. In PSGI it's a code reference: see below.
36 Middleware
38 Middleware is a PSGI application, which is a code reference, but
39 also runs like a server to run other applications. It can be
40 thought of a plugin to extend PSGI application: see below.
41 Framework developers
43 Framework developers are authors of web application frameworks.
44 They need to write adapters (or engines) to read PSGI input, then
45 run the application logic and returns PSGI response to the server.
46 Web application developers
48 Web application developers are developers who write code that uses
49 one of the web application framework that uses PSGI interface. They
50 usually don't need to deal with nor care about PSGI protocol at
51 all.
52
54 Applications
55 A PSGI application is a Perl code reference. It takes exactly one
56 argument, the environment and returns an array reference of exactly
57 three values.
58 sub app {
60 my $env = shift;
61 return [
62 '200',
63 [ 'Content-Type' => 'text/plain' ],
64 [ "Hello World" ], # or IO::Handle-like object
65 ];
66 }
67 The Environment
69 The environment MUST be a hash reference that includes CGI-like
71 headers. The application is free to modify the environment. The
72 environment is required to include these variables (adopted from
73 PEP333, Rack and JSGI) except when they'd be empty, but see below:
74 · "REQUEST_METHOD": The HTTP request method, such as "GET" or "POST".
76 This cannot ever be an empty string, and so is always required.
77 · "SCRIPT_NAME": The initial portion of the request URL's path that
79 corresponds to the application, so that the application knows its
80 virtual "location". This may be an empty string if the application
81 corresponds to the "root" of the server.
82 · "PATH_INFO": The remainder of the request URL's "path", designating
84 the virtual "location" of the request's target within the
85 application. This may be an empty string if the request URL targets
86 the application root and does not have a trailing slash. This value
87 should be URI decoded by servers to be compatible to RFC 3875.
88 · "REQUEST_URI": The undecoded, raw request URL line. It is the raw
90 URI path and query part that appears in the HTTP "GET /...
91 HTTP/1.x" line and doesn't contain URI scheme and host names.
92 Unlike "PATH_INFO", this value SHOULD NOT be decoded by servers and
94 hence it is an application's responsibility to properly decode
95 paths to map URL to application handlers, when using "REQUEST_URI"
96 over "PATH_INFO".
97 · "QUERY_STRING": The portion of the request URL that follows the
99 "?", if any. May be empty, but is always required.
100 · "SERVER_NAME", "SERVER_PORT": When combined with "SCRIPT_NAME" and
102 "PATH_INFO", these variables can be used to complete the URL. Note,
103 however, that "HTTP_HOST", if present, should be used in preference
104 to "SERVER_NAME" for reconstructing the request URL. "SERVER_NAME"
105 and "SERVER_PORT" can never be empty strings, and so are always
106 required.
107 · "SERVER_PROTOCOL": The version of the protocol the client used to
109 send the request. Typically this will be something like "HTTP/1.0"
110 or "HTTP/1.1" and may be used by the application to determine how
111 to treat any HTTP request headers.
112 · "HTTP_" Variables: Variables corresponding to the client-supplied
114 HTTP request headers (i.e., variables whose names begin with
115 "HTTP_"). The presence or absence of these variables should
116 correspond to the presence or absence of the appropriate HTTP
117 header in the request.
118 If there are multiple header lines sent with the same key, the
120 server should treat them as if they're sent in one line, i.e.
121 combine them with ", " as in RFC 2616.
122 In addition to this, the PSGI environment MUST include these PSGI-
124 specific variables:
125 · "psgi.version": An array ref [1,0] representing this version of
127 PSGI.
128 · "psgi.url_scheme": A string "http" or "https", depending on the
130 request URL.
131 · "psgi.input": the input stream. See below.
133 · "psgi.errors": the error stream. See below.
135 · "psgi.multithread": true if the application may be simultaneously
137 invoked by another thread in the same process, false otherwise.
138 · "psgi.multiprocess": true if an equivalent application object may
140 be simultaneously invoked by another process, false otherwise.
141 The PSGI environment MAY include these optional PSGI variables:
143 · "psgi.run_once": true if the server expects (but does not
145 guarantee!) that the application will only be invoked this one
146 time during the life of its containing process. Normally, this will
147 only be true for a server based on CGI (or something similar).
148 · "psgi.nonblocking": true if the server is calling the application
150 in an non-blocking event loop.
151 · "psgi.streaming": true if the server supports callback style
153 delayed response and streaming writer object.
154 The server or the application can store its own data in the
156 environment, too. The keys MUST contain at least one dot, and should be
157 prefixed uniquely. The prefix "psgi." is reserved for use with the PSGI
158 core implementation and other accepted extensions and MUST NOT be used
159 otherwise. The environment MUST NOT contain the keys
160 "HTTP_CONTENT_TYPE" or "HTTP_CONTENT_LENGTH" (use the versions without
161 "HTTP_"). The CGI keys (named without a period) MUST have a scalar
162 variable containing strings. There are the following restrictions:
163 · "psgi.version" MUST be an array of integers.
165 · "psgi.url_scheme" MUST be a scalar variable containing either the
167 string "http" or "https".
168 · There MUST be a valid input stream in "psgi.input".
170 · There MUST be a valid error stream in "psgi.errors".
172 · The "REQUEST_METHOD" MUST be a valid token.
174 · The "SCRIPT_NAME", if non-empty, MUST start with "/"
176 · The "PATH_INFO", if non-empty, MUST start with "/"
178 · The "CONTENT_LENGTH", if given, MUST consist of digits only.
180 · One of "SCRIPT_NAME" or "PATH_INFO" MUST be set. "PATH_INFO" should
182 be "/" if "SCRIPT_NAME" is empty. "SCRIPT_NAME" should never be
183 "/", but should instead be empty.
184 The Input Stream
186 The input stream in "psgi.input" is an IO::Handle-like object which
188 streams the raw HTTP POST or PUT data. If it is a file handle then it
189 MUST be opened in binary mode. The input stream MUST respond to "read"
190 and MAY implement "seek".
191 The built-in filehandle or IO::Handle based objects should work fine
193 everywhere. Application developers SHOULD NOT inspect the type or class
194 of the stream, but instead just call "read" to duck type.
195 Application developers SHOULD NOT use the built-in "read" function to
197 read from the input stream, because "read" function only works with the
198 real IO object (a glob ref based file handle or PerlIO) and makes duck
199 typing difficult. Web application framework developers, if they know
200 the input stream will be used with the built-in read() in any upstream
201 code they can't touch, SHOULD use PerlIO or tie handle to work around
202 with this problem.
203 read
205 $input->read($buf, $len [, $offset ]);
206 Returns the number of characters actually read, 0 at end of file,
208 or undef if there was an error.
209 seek
211 $input->seek($pos, $whence);
212 Returns 1 on success, 0 otherwise.
214 The Error Stream
216 The error stream in "psgi.errors" is an IO::Handle-like object to print
218 errors. The error stream must implement "print".
219 The built-in filehandle or IO::Handle based objects should work fine
221 everywhere. Application developers SHOULD NOT inspect the type or class
222 of the stream, but instead just call "print" to duck type.
223 print
225 $errors->print($error);
226 Returns true if successful.
228 The Response
230 The response MUST be a three element array reference if the application
232 wants to directly return the HTTP response.
233 An application MAY choose to return other type of responses such as a
235 code reference, to delay the response only if the server supports the
236 streaming (See below).
237 Status
239 HTTP status code, is an integer and MUST be greater than or equal to
241 100.
242 Headers
244 The headers must be an array reference (and NOT a hash reference!)
246 containing key and value pairs. Its number of elements MUST be even.
247 The header MUST NOT contain a "Status" key, contain keys with ":" or
248 newlines in their name, contain keys that end in "-" or "_" but only
249 contain keys that consist of letters, digits, "_" or "-" and start with
250 a letter. The value of the header must be a scalar value that contain a
251 string. The value string MUST NOT contain characters below chr(37)
252 except chr(32) (whitespace).
253 If the same key name appears multiple times in an array ref, those
255 header lines MUST be sent to the client separately (e.g. multiple
256 "Set-Cookie" lines).
257 Content-Type
259 There MUST be a "Content-Type" except when the "Status" is 1xx, 204 or
261 304, in which case there MUST be none given.
262 Content-Length
264 There MUST NOT be a "Content-Length" header when the "Status" is 1xx,
266 204 or 304.
267 If the Status is not 1xx, 204 or 304 and there is no "Content-Length"
269 header, servers MAY calculate the content length by looking at Body, in
270 case it can be calculated (i.e. if it's an array ref of body chunk or a
271 real file handle), and append to the outgoing headers.
272 Body
274 The response body is returned from the application in one of following
276 two types of scalar variable.
277 · An array reference containing body as lines.
279 my $body = [ "Hello\n", "World\n" ];
281 Note that the elements in an array reference are NOT REQUIRED to
283 end in a newline. The servers SHOULD just write each elements as is
284 to the client, and SHOULD NOT care if the line ends with newline or
285 not.
286 So, when you have a big chunk of HTML in a single scalar $body,
288 [ $body ]
290 is a valid response body.
292 · An IO::Handle-like object or a built-in filehandle.
294 open my $body, "</path/to/file";
296 open my $body, "<:via(SomePerlIO)", ...;
297 my $body = IO::File->new("/path/to/file");
298 my $body = SomeClass->new(); # mock class that implements getline() and close()
300 Servers SHOULD NOT check the type or class of the body but instead
302 just call "getline" (i.e. duck type) to iterate over the body and
303 call "close" when done.
304 Servers MAY check if the body is a real filehandle using "fileno"
306 and "Scalar::Util::reftype" and if it's a real filehandle that has
307 a file descriptor, it MAY optimize the file serving using
308 techniques like sendfile(2).
309 The body object MAY respond to "path" method to return the local
311 file system path, which MAY be used by some servers to switch to
312 more efficient file serving method using the file path instead of a
313 file descriptor.
314 Servers are RECOMMENDED to set $/ special variable to the buffer
316 size when reading content from $body using "getline" method, in
317 case it's a binary filehandle. Applications, when it returns a mock
318 object that implements "getline" are NOT REQUIRED to respect the $/
319 value.
320 Delayed Reponse and Streaming Body
322 PSGI interface allows applications and servers optionally handle
323 callback-style response (instead of three-element array reference) to
324 delay the HTTP response and stream content (server push).
325 To enable delayed response, an application SHOULD check if
327 "psgi.streaming" environment is true, and in that case, MAY return a
328 callback that is passed another callback (response starter) as its
329 first argument, and pass the three element response to the callback.
330 my $app = sub {
332 my $env = shift;
333 # Delays response until it fetches content from the network
335 return sub {
336 my $respond = shift;
337 fetch_content_from_server(sub {
338 my $content = shift;
339 # ...
340 $respond->([ 200, $headers, [ $content ] ]);
341 });
342 };
343 };
344 Similarly, an application MAY omit the third element (the body) in the
346 callback to get a response writer object, that implements "write",
347 "poll_cb" and "close" method to push the response body.
348 my $app = sub {
350 my $env = shift;
351 # immediately starts the response and stream the content
353 return sub {
354 my $respond = shift;
355 my $writer = $respond->([ 200, [ 'Content-Type', 'application/json' ]]);
356 wait_for_events(sub {
358 my $new_event = shift;
359 if ($new_event) {
360 $writer->write($new_event->as_json . "\n");
361 # Or:
362 # $writer->poll_cb(sub { $_[0]->write($new_event->as_json . "\n") });
363 } else {
364 $writer->close;
365 }
366 });
367 };
368 };
369 Delayed response and streaming should be useful if you want to
371 implement non-blocking I/O based server streaming or long-poll Comet
372 push technology. IO::Handle-like object is pull, while this streaming
373 response implements push.
374 This interface is optional: An applciation SHOULD check if the server
376 supports streaming. Servers MAY decide to not accept this streaming
377 response and throws an exception. Servers MUST set "psgi.streaming" to
378 true if this interface is supported. Servers MUST return a writer
379 object if the third argument (response body) is omitted or not defined
380 in the response starter callback arguments.
381 Middleware
383 Middleware is itself a PSGI application but it takes an existing PSGI
384 application and runs it like a server, mostly to do pre-processing on
385 $env or post-processing on the response objects.
386 Here's a simple example that appends special HTTP header X-PSGI-Used to
388 any PSGI application.
389 # $app is a simple PSGI application
391 my $app = sub {
392 my $env = shift;
393 return [ '200', [ 'Content-Type' => 'text/plain' ], [ "Hello World" ] ];
394 };
395 # $xheader is a middleware to wrap $app
397 my $xheader = sub {
398 my $env = shift;
399 my $res = $app->($env);
400 push @{$res->[1]}, 'X-PSGI-Used' => 1;
401 return $res;
402 };
403 Middleware itself MUST behave exactly like a PSGI application: take
405 $env and return $res. Middleware MAY decide not to support the
406 streaming interface (see above) but SHOULD pass through the response
407 types that it doesn't understand.
408
410 Some parts of this specification are adopted from the following
411 specifications.
412 · PEP333 Python Web Server Gateway Interface
414 http://www.python.org/dev/peps/pep-0333
415 <http://www.python.org/dev/peps/pep-0333>
416 · Rack <http://rack.rubyforge.org/doc/SPEC.html>
418 · JSGI Specification http://jackjs.org/jsgi-spec.html
420 <http://jackjs.org/jsgi-spec.html>
421 I'd like to thank authors of these great documents.
423
425 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
426
428 The following people have contributed to the PSGI specification and
429 Plack implementation by commiting their code, sending patches,
430 reporting bugs, asking questions, suggesting useful advices,
431 nitpicking, chatting on IRC or commenting on my blog (in no particular
432 order):
433 Tokuhiro Matsuno
435 Kazuhiro Osawa
436 Yuval Kogman
437 Kazuho Oku
438 Alexis Sukrieh
439 Takatoshi Kitano
440 Stevan Little
441 Daisuke Murase
442 mala
443 Pedro Melo
444 Jesse Luehrs
445 John Beppu
446 Shawn M Moore
447 Mark Stosberg
448 Matt S Trout
449 Jesse Vincent
450 Chia-liang Kao
451 Dave Rolsky
452 Hans Dieter Pearcey
453 Randy J Ray
454 Benjamin Trott
455 Max Maischein
456 Slaven ReziX
457 Marcel Gruenauer
458 Masayoshi Sekimura
459 Brock Wilcox
460 Piers Cawley
461 Daisuke Maki
462 Kang-min Liu
463 Yasuhiro Matsumoto
464 Ash Berlin
465 Artur Bergman
466 Simon Cozens
467 Scott McWhirter
468 Jiro Nishiguchi
469 Masahiro Chiba
470 Patrick Donelan
471 Paul Driver
472
474 Copyright Tatsuhiko Miyagawa, 2009.
475 This document is licensed under the Creative Commons license by-sa.
477perl v5.12.0 2009-10-22 PSGI(3)