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. This interface is designed to
11 promote web application portability and reduce the duplication of
12 effort by web application framework developers.
13 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
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 PSGI Server
28 A PSGI Server is a Perl program providing an environment for a PSGI
29 application to run in.
30 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 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 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 Applications
48 Web applications accept HTTP requests and return HTTP responses.
49 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 For simplicity, PSGI Applications will also be referred to as
55 Applications for the remainder of this document.
56 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 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 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
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 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 The Environment
89 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 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 The values for all CGI keys (named without a period) MUST be a scalar
104 string.
105 See below for details.
107 • "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 • "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 If this key is not empty, it MUST start with a forward slash ("/").
117 • "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 If this key is not empty, it MUST start with a forward slash ("/").
126 • "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 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 • "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 • "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 • "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 • "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 • "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 • "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 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 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 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 In addition to the keys above, the PSGI environment MUST also include
182 these PSGI-specific keys:
183 • "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 • "psgi.url_scheme": A string "http" or "https", depending on the
189 request URL.
190 • "psgi.input": the input stream. See below for details.
192 • "psgi.errors": the error stream. See below for details.
194 • "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 • "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 • "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 • "psgi.nonblocking": A boolean which is true if the server is
210 calling the application in an non-blocking event loop.
211 • "psgi.streaming": A boolean which is true if the server supports
213 callback style delayed response and streaming writer object.
214 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 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 The environment MUST NOT contain keys named "HTTP_CONTENT_TYPE" or
226 "HTTP_CONTENT_LENGTH".
227 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 The Input Stream
233 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 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 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 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 The input stream object is expected to provide a "read" method:
254 read
256 $input->read($buf, $len [, $offset ]);
257 Returns the number of characters actually read, 0 at end of file,
259 or undef if there was an error.
260 It may also implement an optional "seek" method. If
262 "psgix.input.buffered" environment is true, it MUST implement the
263 "seek" method.
264 seek
266 $input->seek($pos, $whence);
267 Returns 1 on success, 0 otherwise.
269 See the IO::Handle documentation for more details on exactly how these
271 methods should work.
272 The Error Stream
274 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 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 print
284 $errors->print($error);
285 Returns true if successful.
287 The Response
289 Applications MUST return a response as either a three element array
291 reference, or a code reference for a delayed/streaming response.
292 The response array reference consists of the following elements:
294 Status
296 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 Headers
302 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 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 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 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 Content-Type
320 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 Content-Length
325 There MUST NOT be a "Content-Length" header when the "Status" is 1xx,
327 204 or 304.
328 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 Body
335 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 • If the body is an array reference, it is expected to contain an
342 array of lines which make up the body.
343 my $body = [ "Hello\n", "World\n" ];
345 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 An array reference with a single value is valid. So "[ $html ]" is
351 a valid response body.
352 • The body can instead be a handle, either a Perl built-in filehandle
354 or an IO::Handle-like object.
355 open my $body, "</path/to/file";
357 open my $body, "<:via(SomePerlIO)", ...;
358 my $body = IO::File->new("/path/to/file");
359 # mock class that implements getline() and close()
361 my $body = SomeClass->new();
362 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 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 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 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 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 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 This interface SHOULD be implemented by PSGI servers, and
391 "psgi.streaming" environment MUST be set to true in such servers.
392 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 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 my $app = sub {
403 my $env = shift;
404 # Delays response until it fetches content from the network
406 return sub {
407 my $responder = shift;
408 fetch_content_from_server(sub {
410 my $content = shift;
411 $responder->([ 200, $headers, [ $content ] ]);
412 });
413 };
414 };
415 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 my $app = sub {
422 my $env = shift;
423 # 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 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 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 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 Here's a simple example that appends a special HTTP header X-PSGI-Used
455 to any PSGI application.
456 # $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 # $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 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
479 1.1: 2010.02.xx
480 • Added optional PSGI keys as extensions: "psgix.logger" and
482 "psgix.session".
483 • "psgi.streaming" SHOULD be implemented by PSGI servers, rather than
485 MAY.
486 • PSGI keys "psgi.run_once", "psgi.nonblocking" and "psgi.streaming"
488 MUST be set by PSGI servers.
489 • Removed "poll_cb" from writer methods.
491
493 Some parts of this specification are adopted from the following
494 specifications.
495 • PEP333 Python Web Server Gateway Interface
497 <http://www.python.org/dev/peps/pep-0333>
498 • Rack <http://rack.rubyforge.org/doc/SPEC.html>
500 • JSGI Specification <http://jackjs.org/jsgi-spec.html>
502 I'd like to thank authors of these great documents.
504
506 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
507
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 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 This document is licensed under the Creative Commons license by-sa.
559perl v5.36.0 2023-01-20 PSGI(3)