1PSGI(3)               User Contributed Perl Documentation              PSGI(3)
2
3
4

NAME

6       PSGI - Perl Web Server Gateway Interface Specification
7

ABSTRACT

9       This document specifies a standard interface between web servers and
10       Perl web applications or frameworks. This interface is designed to
11       promote web application portability and reduce the duplication of
12       effort by web application framework developers.
13
14       Please keep in mind that PSGI is not Yet Another web application
15       framework. PSGI is a specification to decouple web server environments
16       from web application framework code. Nor is PSGI a web application API.
17       Web application developers (end users) will not run their web
18       applications directly using the PSGI interface, but instead are
19       encouraged to use frameworks that support PSGI.
20

TERMINOLOGY

22       Web Servers
23           Web servers accept HTTP requests issued by web clients, dispatching
24           those requests to web applications if configured to do so, and
25           return HTTP responses to the request-initiating clients.
26
27       PSGI Server
28           A PSGI Server is a Perl program providing an environment for a PSGI
29           application to run in.
30
31           PSGI specifying an interface for web applications and the main
32           purpose of web applications being to be served to the Internet, a
33           PSGI Server will most likely be either: part of a web server (like
34           Apache mod_perl), connected to a web server (with FastCGI, SCGI),
35           invoked by a web server (as in plain old CGI), or be a standalone
36           web server itself, written entirely or partly in Perl.
37
38           There is, however, no requirement for a PSGI Server to actually be
39           a web server or part of one, as PSGI only defines an interface
40           between the server and the application, not between the server and
41           the world.
42
43           A PSGI Server is often also called PSGI Application Container
44           because it is similar to a Java Servlet container, which is Java
45           process providing an environment for Java Servlets.
46
47       Applications
48           Web applications accept HTTP requests and return HTTP responses.
49
50           PSGI applications are web applications conforming to the PSGI
51           interface, prescribing they take the form of a code reference with
52           defined input and output.
53
54           For simplicity, PSGI Applications will also be referred to as
55           Applications for the remainder of this document.
56
57       Middleware
58           Middleware is a PSGI application (a code reference) and a Server.
59           Middleware looks like an application when called from a server, and
60           it in turn can call other applications. It can be thought of a
61           plugin to extend a PSGI application.
62
63       Framework developers
64           Framework developers are the authors of web application frameworks.
65           They write adapters (or engines) which accept PSGI input, run a web
66           application, and return a PSGI response to the server.
67
68       Web application developers
69           Web application developers are developers who write code on top of
70           a web application framework. These developers should never have to
71           deal with PSGI directly.
72

SPECIFICATION

74   Application
75       A PSGI application is a Perl code reference. It takes exactly one
76       argument, the environment, and returns an array reference containing
77       exactly three values.
78
79         my $app = sub {
80             my $env = shift;
81             return [
82                 '200',
83                 [ 'Content-Type' => 'text/plain' ],
84                 [ "Hello World" ], # or IO::Handle-like object
85             ];
86         };
87
88       The Environment
89
90       The environment MUST be a hash reference that includes CGI-like
91       headers, as detailed below. The application is free to modify the
92       environment. The environment MUST include these keys (adopted from PEP
93       333 <http://www.python.org/dev/peps/pep-0333/>, Rack
94       <http://rack.rubyforge.org/doc/files/SPEC.html> and JSGI
95       <http://jackjs.org/jsgi-spec.html>) except when they would normally be
96       empty.
97
98       When an environment key is described as a boolean, its value MUST
99       conform to Perl's notion of boolean-ness. This means that an empty
100       string or an explicit 0 are both valid false values. If a boolean key
101       is not present, an application MAY treat this as a false value.
102
103       The values for all CGI keys (named without a period) MUST be a scalar
104       string.
105
106       See below for details.
107
108       •   "REQUEST_METHOD": The HTTP request method, such as "GET" or "POST".
109           This MUST NOT be an empty string, and so is always required.
110
111       •   "SCRIPT_NAME": The initial portion of the request URL's path,
112           corresponding to the application. This tells the application its
113           virtual "location". This may be an empty string if the application
114           corresponds to the server's root URI.
115
116           If this key is not empty, it MUST start with a forward slash ("/").
117
118       •   "PATH_INFO": The remainder of the request URL's path, designating
119           the virtual "location" of the request's target within the
120           application. This may be an empty string if the request URL targets
121           the application root and does not have a trailing slash. This value
122           should be URI decoded by servers in order to be compatible with RFC
123           3875 <http://www.ietf.org/rfc/rfc3875>.
124
125           If this key is not empty, it MUST start with a forward slash ("/").
126
127       •   "REQUEST_URI": The undecoded, raw request URL line. It is the raw
128           URI path and query part that appears in the HTTP "GET /...
129           HTTP/1.x" line and doesn't contain URI scheme and host names.
130
131           Unlike "PATH_INFO", this value SHOULD NOT be decoded by servers. It
132           is an application's responsibility to properly decode paths in
133           order to map URLs to application handlers if they choose to use
134           this key instead of "PATH_INFO".
135
136       •   "QUERY_STRING": The portion of the request URL that follows the
137           "?", if any. This key MAY be empty, but MUST always be present,
138           even if empty.
139
140       •   "SERVER_NAME", "SERVER_PORT": When combined with "SCRIPT_NAME" and
141           "PATH_INFO", these keys can be used to complete the URL. Note,
142           however, that "HTTP_HOST", if present, should be used in preference
143           to "SERVER_NAME" for reconstructing the request URL. "SERVER_NAME"
144           and "SERVER_PORT" MUST NOT be empty strings, and are always
145           required.
146
147       •   "SERVER_PROTOCOL": The version of the protocol the client used to
148           send the request. Typically this will be something like "HTTP/1.0"
149           or "HTTP/1.1" and may be used by the application to determine how
150           to treat any HTTP request headers.
151
152       •   "CONTENT_LENGTH": The length of the content in bytes, as an
153           integer. The presence or absence of this key should correspond to
154           the presence or absence of HTTP Content-Length header in the
155           request.
156
157       •   "CONTENT_TYPE": The request's MIME type, as specified by the
158           client.  The presence or absence of this key should correspond to
159           the presence or absence of HTTP Content-Type header in the request.
160
161       •   "HTTP_*" Keys: These keys correspond to the client-supplied HTTP
162           request headers. The presence or absence of these keys should
163           correspond to the presence or absence of the appropriate HTTP
164           header in the request.
165
166           The key is obtained converting the HTTP header field name to upper
167           case, replacing all occurrences of hyphens "-" with underscores "_"
168           and prepending "HTTP_", as in RFC 3875
169           <http://www.ietf.org/rfc/rfc3875>.
170
171           If there are multiple header lines sent with the same key, the
172           server should treat them as if they were sent in one line and
173           combine them with ", ", as in RFC 2616
174           <http://www.ietf.org/rfc/rfc2616>.
175
176       A server should attempt to provide as many other CGI variables as are
177       applicable.  Note, however, that an application that uses any CGI
178       variables other than the ones listed above are necessarily non-portable
179       to web servers that do not support the relevant extensions.
180
181       In addition to the keys above, the PSGI environment MUST also include
182       these PSGI-specific keys:
183
184       •   "psgi.version": An array reference [1,1] representing this version
185           of PSGI. The first number is the major version and the second it
186           the minor version.
187
188       •   "psgi.url_scheme": A string "http" or "https", depending on the
189           request URL.
190
191       •   "psgi.input": the input stream. See below for details.
192
193       •   "psgi.errors": the error stream. See below for details.
194
195       •   "psgi.multithread": This is a boolean value, which MUST be true if
196           the application may be simultaneously invoked by another thread in
197           the same process, false otherwise.
198
199       •   "psgi.multiprocess": This is a boolean value, which MUST be true if
200           an equivalent application object may be simultaneously invoked by
201           another process, false otherwise.
202
203       •   "psgi.run_once": A boolean which is true if the server expects (but
204           does not guarantee!)  that the application will only be invoked
205           this one time during the life of its containing process. Normally,
206           this will only be true for a server based on CGI (or something
207           similar).
208
209       •   "psgi.nonblocking": A boolean which is true if the server is
210           calling the application in an non-blocking event loop.
211
212       •   "psgi.streaming": A boolean which is true if the server supports
213           callback style delayed response and streaming writer object.
214
215       The server or the application can store its own data in the environment
216       as well. These keys MUST contain at least one dot, and SHOULD be
217       prefixed uniquely.
218
219       The "psgi." prefix is reserved for use with the PSGI core
220       specification, and "psgix." prefix is reserved for officially blessed
221       extensions. These prefixes MUST NOT be used by other servers or
222       application. See psgi-extensions for the list of officially approved
223       extensions.
224
225       The environment MUST NOT contain keys named "HTTP_CONTENT_TYPE" or
226       "HTTP_CONTENT_LENGTH".
227
228       One of "SCRIPT_NAME" or "PATH_INFO" MUST be set. When "REQUEST_URI" is
229       "/", "PATH_INFO" should be "/" and "SCRIPT_NAME" should be empty.
230       "SCRIPT_NAME" MUST NOT be "/", but MAY be empty.
231
232       The Input Stream
233
234       The input stream in "psgi.input" is an IO::Handle-like object which
235       streams the raw HTTP POST or PUT data. If it is a file handle then it
236       MUST be opened in binary mode. The input stream MUST respond to "read"
237       and MAY implement "seek".
238
239       Perl's built-in filehandles or IO::Handle based objects should work as-
240       is in a PSGI server. Application developers SHOULD NOT inspect the type
241       or class of the stream. Instead, they SHOULD simply call "read" on the
242       object.
243
244       Application developers SHOULD NOT use Perl's built-in "read" or
245       iterator ("<$fh>") to read from the input stream. Instead, application
246       developers should call "read" as a method ("$fh->read") to allow for
247       duck typing.
248
249       Framework developers, if they know the input stream will be used with
250       the built-in read() in any upstream code they can't touch, SHOULD use
251       PerlIO or a tied handle to work around with this problem.
252
253       The input stream object is expected to provide a "read" method:
254
255       read
256             $input->read($buf, $len [, $offset ]);
257
258           Returns the number of characters actually read, 0 at end of file,
259           or undef if there was an error.
260
261       It may also implement an optional "seek" method. If
262       "psgix.input.buffered" environment is true, it MUST implement the
263       "seek" method.
264
265       seek
266             $input->seek($pos, $whence);
267
268           Returns 1 on success, 0 otherwise.
269
270       See the IO::Handle documentation for more details on exactly how these
271       methods should work.
272
273       The Error Stream
274
275       The error stream in "psgi.errors" is an IO::Handle-like object to print
276       errors. The error stream must implement a "print" method.
277
278       As with the input stream, Perl's built-in filehandles or IO::Handle
279       based objects should work as-is in a PSGI server. Application
280       developers SHOULD NOT inspect the type or class of the stream. Instead,
281       they SHOULD simply call "print" on the object.
282
283       print
284             $errors->print($error);
285
286           Returns true if successful.
287
288       The Response
289
290       Applications MUST return a response as either a three element array
291       reference, or a code reference for a delayed/streaming response.
292
293       The response array reference consists of the following elements:
294
295       Status
296
297       An HTTP status code. This MUST be an integer greater than or equal to
298       100, and SHOULD be an HTTP status code as documented in RFC 2616
299       <http://www.w3.org/Protocols/rfc2616>.
300
301       Headers
302
303       The headers MUST be an array reference (not a hash reference) of
304       key/value pairs. This means it MUST contain an even number of elements.
305
306       The header MUST NOT contain a key named "Status", nor any keys with ":"
307       or newlines in their name. It MUST NOT contain any keys that end in "-"
308       or "_".
309
310       All keys MUST consist only of letters, digits, "_" or "-". All keys
311       MUST start with a letter. The value of the header MUST be a scalar
312       string and defined. The value string MUST NOT contain characters below
313       octal 037 i.e. chr(31).
314
315       If the same key name appears multiple times in an array ref, those
316       header lines MUST be sent to the client separately (e.g. multiple
317       "Set-Cookie" lines).
318
319       Content-Type
320
321       There MUST be a "Content-Type" except when the "Status" is 1xx, 204 or
322       304, in which case there MUST NOT be a content type.
323
324       Content-Length
325
326       There MUST NOT be a "Content-Length" header when the "Status" is 1xx,
327       204 or 304.
328
329       If the Status is not 1xx, 204 or 304 and there is no "Content-Length"
330       header, a PSGI server MAY calculate the content length by looking at
331       the Body. This value can then be appended to the list of headers
332       returned by the application.
333
334       Body
335
336       The response body MUST be returned from the application as either an
337       array reference or a handle containing the response body as byte
338       strings. The body MUST be encoded into appropriate encodings and MUST
339       NOT contain wide characters (> 255).
340
341       •   If the body is an array reference, it is expected to contain an
342           array of lines which make up the body.
343
344             my $body = [ "Hello\n", "World\n" ];
345
346           Note that the elements in an array reference are NOT REQUIRED to
347           end in a newline. A server SHOULD write each elements as-is to the
348           client, and SHOULD NOT care if the line ends with newline or not.
349
350           An array reference with a single value is valid. So "[ $html ]" is
351           a valid response body.
352
353       •   The body can instead be a handle, either a Perl built-in filehandle
354           or an IO::Handle-like object.
355
356             open my $body, "</path/to/file";
357             open my $body, "<:via(SomePerlIO)", ...;
358             my $body = IO::File->new("/path/to/file");
359
360             # mock class that implements getline() and close()
361             my $body = SomeClass->new();
362
363           Servers SHOULD NOT check the type or class of the body. Instead,
364           they should simply call "getline" to iterate over the body, and
365           call "close" when done.
366
367           Servers MAY check if the body is a real filehandle using "fileno"
368           and "Scalar::Util::reftype". If the body is real filehandle, the
369           server MAY optimize using techniques like sendfile(2).
370
371           The body object MAY also respond to a "path" method. This method is
372           expected to return the path to a file accessible by the server.
373           This allows the server to use this information instead of a file
374           descriptor number to serve the file.
375
376           Servers SHOULD set the $/ special variable to the buffer size when
377           reading content from $body using the "getline" method. This is done
378           by setting $/ with a reference to an integer ("$/ = \8192").
379
380           If the body filehandle is a Perl built-in filehandle IO::Handle
381           object, they will respect this value. Similarly, an object which
382           provides the same API MAY also respect this special variable, but
383           are not required to do so.
384
385   Delayed Response and Streaming Body
386       The PSGI interface allows applications and servers to provide a
387       callback-style response instead of the three-element array reference.
388       This allows for a delayed response and a streaming body (server push).
389
390       This interface SHOULD be implemented by PSGI servers, and
391       "psgi.streaming" environment MUST be set to true in such servers.
392
393       To enable a delayed response, the application SHOULD return a callback
394       as its response. An application MAY check if the "psgi.streaming"
395       environment is true and falls back to the direct response if it isn't.
396
397       This callback will be called with another subroutine reference
398       (referred to as the responder from now on) as its only argument. The
399       responder should in turn be called with the standard three element
400       array reference response. This is best illustrated with an example:
401
402         my $app = sub {
403             my $env = shift;
404
405             # Delays response until it fetches content from the network
406             return sub {
407                 my $responder = shift;
408
409                 fetch_content_from_server(sub {
410                     my $content = shift;
411                     $responder->([ 200, $headers, [ $content ] ]);
412                 });
413             };
414         };
415
416       An application MAY omit the third element (the body) when calling the
417       responder. If the body is omitted, the responder MUST return yet
418       another object which implements "write" and "close" methods. Again, an
419       example illustrates this best.
420
421         my $app = sub {
422             my $env = shift;
423
424             # immediately starts the response and stream the content
425             return sub {
426                 my $responder = shift;
427                 my $writer = $responder->(
428                     [ 200, [ 'Content-Type', 'application/json' ]]);
429
430                 wait_for_events(sub {
431                     my $new_event = shift;
432                     if ($new_event) {
433                         $writer->write($new_event->as_json . "\n");
434                     } else {
435                         $writer->close;
436                     }
437                 });
438             };
439         };
440
441       This delayed response and streaming API is useful if you want to
442       implement a non-blocking I/O based server streaming or long-poll Comet
443       push technology, but could also be used to implement unbuffered writes
444       in a blocking server.
445
446   Middleware
447       A middleware component takes another PSGI application and runs it. From
448       the perspective of a server, a middleware component is a PSGI
449       application. From the perspective of the application being run by the
450       middleware component, the middleware is the server. Generally, this
451       will be done in order to implement some sort of pre-processing on the
452       PSGI environment hash or post-processing on the response.
453
454       Here's a simple example that appends a special HTTP header X-PSGI-Used
455       to any PSGI application.
456
457         # $app is a simple PSGI application
458         my $app = sub {
459             my $env = shift;
460             return [ '200',
461                      [ 'Content-Type' => 'text/plain' ],
462                      [ "Hello World" ] ];
463         };
464
465         # $xheader is a piece of middleware that wraps $app
466         my $xheader = sub {
467             my $env = shift;
468             my $res = $app->($env);
469             push @{$res->[1]}, 'X-PSGI-Used' => 1;
470             return $res;
471         };
472
473       Middleware MUST behave exactly like a PSGI application from the
474       perspective of a server. Middleware MAY decide not to support the
475       streaming interface discussed earlier, but SHOULD pass through the
476       response types that it doesn't understand.
477

CHANGELOGS

479       1.1: 2010.02.xx
480
481       •   Added optional PSGI keys as extensions: "psgix.logger" and
482           "psgix.session".
483
484       •   "psgi.streaming" SHOULD be implemented by PSGI servers, rather than
485           MAY.
486
487       •   PSGI keys "psgi.run_once", "psgi.nonblocking" and "psgi.streaming"
488           MUST be set by PSGI servers.
489
490       •   Removed "poll_cb" from writer methods.
491

ACKNOWLEDGEMENTS

493       Some parts of this specification are adopted from the following
494       specifications.
495
496       •   PEP333 Python Web Server Gateway Interface
497           <http://www.python.org/dev/peps/pep-0333>
498
499       •   Rack <http://rack.rubyforge.org/doc/SPEC.html>
500
501       •   JSGI Specification <http://jackjs.org/jsgi-spec.html>
502
503       I'd like to thank authors of these great documents.
504

AUTHOR

506       Tatsuhiko Miyagawa <miyagawa@bulknews.net>
507

CONTRIBUTORS

509       The following people have contributed to the PSGI specification and
510       Plack implementation by commiting their code, sending patches,
511       reporting bugs, asking questions, suggesting useful advices,
512       nitpicking, chatting on IRC or commenting on my blog (in no particular
513       order):
514
515         Tokuhiro Matsuno
516         Kazuhiro Osawa
517         Yuval Kogman
518         Kazuho Oku
519         Alexis Sukrieh
520         Takatoshi Kitano
521         Stevan Little
522         Daisuke Murase
523         mala
524         Pedro Melo
525         Jesse Luehrs
526         John Beppu
527         Shawn M Moore
528         Mark Stosberg
529         Matt S Trout
530         Jesse Vincent
531         Chia-liang Kao
532         Dave Rolsky
533         Hans Dieter Pearcey
534         Randy J Ray
535         Benjamin Trott
536         Max Maischein
537         Slaven Rezić
538         Marcel Grünauer
539         Masayoshi Sekimura
540         Brock Wilcox
541         Piers Cawley
542         Daisuke Maki
543         Kang-min Liu
544         Yasuhiro Matsumoto
545         Ash Berlin
546         Artur Bergman
547         Simon Cozens
548         Scott McWhirter
549         Jiro Nishiguchi
550         Masahiro Chiba
551         Patrick Donelan
552         Paul Driver
553         Florian Ragwitz
554
556       Copyright Tatsuhiko Miyagawa, 2009-2011.
557
558       This document is licensed under the Creative Commons license by-sa.
559
560
561
562perl v5.38.0                      2023-07-21                           PSGI(3)
Impressum