Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 480 lines (323 sloc) 13.377 kB
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
1 =head1 NAME
2
3 PSGI - Perl Web Server Gateway Interface Specification
4
5 =head1 ABSTRACT
6
ff0e6de @miyagawa paragraphized
miyagawa authored
7 This document specifies a standard interface between web servers and
8 Perl web applications or frameworks, to promote web application
9 portability and reduce the duplicated efforts by web application
10 framework developers.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
11
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored
12 Keep in mind that PSGI is not Yet Another web application
13 framework. PSGI is a specification to decouple web server environments
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
14 from web application framework code. PSGI is also not the web
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored
15 application API. Web application developers (end users) are not
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
16 supposed to run their web applications directly using the PSGI
17 interface, but instead are encouraged to use frameworks that
18 support PSGI, or use the helper implementations like Plack (more on
19 that later).
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored
20
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
21 =head1 TERMINOLOGIES
22
23 =over 4
24
25 =item Servers
26
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
27 Servers are web servers that accept HTTP requests, dispatch the
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
28 requests to the web appilcations and return the HTTP response to the
29 clients. In PSGI specification it's a Perl process that's running
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
30 inside an HTTP server (e.g. mod_perl in Apache), a daemon process
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
31 called from a web server (e.g. FastCGI daemon) or a pure perl HTTP
32 server.
33
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
34 Servers are also called I<PSGI implementations> as well as
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
35 I<Backends>.
36
37 =item Applications
38
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
39 Applications are web applications that actually get HTTP requests
40 and return HTTP response. In PSGI it's a code reference: see below.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
41
42 =item Middleware
43
44 Middleware is a PSGI application, which is a code reference, but also
45 runs like a server to run other applications. It can be thought of a
46 I<plugin> to extend PSGI application: see below.
47
48 =item Framework developers
49
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
50 Framework developers are authors of web application frameworks. They
51 need to write adapters (or engines) to read PSGI input, then run the
52 application logic and returns PSGI response to the server.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
53
54 =item Web application developers
55
56 Web application developers are developers who write code that uses one
57 of the web application framework that uses PSGI interface. They
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
58 usually don't need to deal with nor care about PSGI protocol at all.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
59
60 =cut
61
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
62 =head1 SPECIFICATION
63
64 =head2 Applications
65
ff0e6de @miyagawa paragraphized
miyagawa authored
66 A PSGI application is a Perl code reference. It takes exactly one
67 argument, the environment and returns an array reference of exactly
68 three values.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
69
70 sub app {
71 my $env = shift;
72 return [
73 '200',
74 [ 'Content-Type' => 'text/plain' ],
31bd78b @miyagawa s/objects/object/ because it sounded like an array of IO::Handle objects
miyagawa authored
75 [ "Hello World" ], # or IO::Handle-like object
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
76 ];
77 }
78
79 =head3 The Environment
80
ff0e6de @miyagawa paragraphized
miyagawa authored
81 The environment MUST be a hash reference that includes CGI-like
82 headers. The application is free to modify the environment. The
83 environment is required to include these variables (adopted from
84 PEP333, Rack and JSGI) except when they'd be empty, but see below:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
85
86 =over 4
87
88 =item *
89
ff0e6de @miyagawa paragraphized
miyagawa authored
90 C<REQUEST_METHOD>: The HTTP request method, such as "GET" or
91 "POST". This cannot ever be an empty string, and so is always
92 required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
93
94 =item *
95
ff0e6de @miyagawa paragraphized
miyagawa authored
96 C<SCRIPT_NAME>: The initial portion of the request URL's I<path> that
97 corresponds to the application, so that the application knows its
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
98 virtual "location". This may be an empty string if the application
ff0e6de @miyagawa paragraphized
miyagawa authored
99 corresponds to the "root" of the server.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
100
101 =item *
102
ff0e6de @miyagawa paragraphized
miyagawa authored
103 C<PATH_INFO>: The remainder of the request URL's "path", designating
104 the virtual "location" of the request's target within the
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
105 application. This may be an empty string if the request URL targets
ff0e6de @miyagawa paragraphized
miyagawa authored
106 the application root and does not have a trailing slash. This value
b2f90a3 @miyagawa PATH_INFO should be decoded by servers
miyagawa authored
107 should be URI decoded by servers to be compatible to RFC 3875.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
108
109 =item *
110
ff0e6de @miyagawa paragraphized
miyagawa authored
111 C<QUERY_STRING>: The portion of the request URL that follows the C<?>,
112 if any. May be empty, but is always required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
113
114 =item *
115
ff0e6de @miyagawa paragraphized
miyagawa authored
116 C<SERVER_NAME>, C<SERVER_PORT>: When combined with C<SCRIPT_NAME> and
117 C<PATH_INFO>, these variables can be used to complete the URL. Note,
118 however, that C<HTTP_HOST>, if present, should be used in preference
119 to C<SERVER_NAME> for reconstructing the request URL. C<SERVER_NAME>
120 and C<SERVER_PORT> can never be empty strings, and so are always
121 required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
122
123 =item *
124
ff0e6de @miyagawa paragraphized
miyagawa authored
125 C<SERVER_PROTOCOL>: The version of the protocol the client used to
126 send the request. Typically this will be something like "HTTP/1.0" or
127 "HTTP/1.1" and may be used by the application to determine how to
128 treat any HTTP request headers.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
129
130 =item *
131
ff0e6de @miyagawa paragraphized
miyagawa authored
132 C<HTTP_> Variables: Variables corresponding to the client-supplied
133 HTTP request headers (i.e., variables whose names begin with
134 C<HTTP_>). The presence or absence of these variables should
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
135 correspond to the presence or absence of the appropriate HTTP header
ff0e6de @miyagawa paragraphized
miyagawa authored
136 in the request.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
137
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
138 If there are multiple header lines sent with the same key, the server
139 should treat them as if they're sent in one line, i.e. combine them
140 with C<, > as in RFC 2616.
141
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
142 =back
143
ff0e6de @miyagawa paragraphized
miyagawa authored
144 In addition to this, the PSGI environment MUST include these
145 PSGI-specific variables:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
146
147 =over 4
148
149 =item *
150
151 C<psgi.version>: An array ref [1,0] representing this version of PSGI.
152
153 =item *
154
155 C<psgi.url_scheme>: A string C<http> or C<https>, depending on the request URL.
156
157 =item *
158
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
159 C<psgi.input>: the input stream. See below.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
160
161 =item *
162
163 C<psgi.errors>: the error stream. See below.
164
eee7655 @miyagawa Added psgi.multithread and psgi.multiprocess per discussion on about …
miyagawa authored
165 =item *
166
167 C<psgi.multithread>: true if the application may be simultaneously
168 invoked by another thread in the same process, false otherwise.
169
170 =item *
171
172 C<psgi.multiprocess>: true if an equivalent application object may be
173 simultaneously invoked by another process, false otherwise.
174
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
175 =back
176
177 The PSGI environment MAY include these optional PSGI variables:
178
179 =over 4
180
181 =item *
182
ff0e6de @miyagawa paragraphized
miyagawa authored
183 C<psgi.run_once>: true if the server expects (but does not guarantee!)
184 that the application will only be invoked this one time during the
185 life of its containing process. Normally, this will only be true for a
186 server based on CGI (or something similar).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
187
188 =item *
189
e21be68 @miyagawa s/.async/.nonblocking/ per discussions with nothingmuch++
miyagawa authored
190 C<psgi.nonblocking>: true if the server is calling the application in an
191 non-blocking event loop.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
192
193 =back
194
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
195 The server or the application can store its own data in the
ff0e6de @miyagawa paragraphized
miyagawa authored
196 environment, too. The keys MUST contain at least one dot, and should
197 be prefixed uniquely. The prefix C<psgi.> is reserved for use with the
198 PSGI core implementation and other accepted extensions and MUST NOT be
199 used otherwise. The environment MUST NOT contain the keys
200 C<HTTP_CONTENT_TYPE> or C<HTTP_CONTENT_LENGTH> (use the versions
201 without C<HTTP_>). The CGI keys (named without a period) MUST have a
202 scalar variable containing strings. There are the following
203 restrictions:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
204
205 =over 4
206
207 =item *
208
209 C<psgi.version> MUST be an array of integers.
210
211 =item *
212
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
213 C<psgi.url_scheme> MUST be a scalar variable containing either the
ff0e6de @miyagawa paragraphized
miyagawa authored
214 string C<http> or C<https>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
215
216 =item *
217
218 There MUST be a valid input stream in C<psgi.input>.
219
220 =item *
221
222 There MUST be a valid error stream in C<psgi.errors>.
223
224 =item *
225
226 The C<REQUEST_METHOD> MUST be a valid token.
227
228 =item *
229
230 The C<SCRIPT_NAME>, if non-empty, MUST start with C</>
231
232 =item *
233
234 The C<PATH_INFO>, if non-empty, MUST start with C</>
235
236 =item *
237
238 The C<CONTENT_LENGTH>, if given, MUST consist of digits only.
239
240 =item *
241
ff0e6de @miyagawa paragraphized
miyagawa authored
242 One of C<SCRIPT_NAME> or C<PATH_INFO> MUST be set. C<PATH_INFO> should
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
243 be C</> if C<SCRIPT_NAME> is empty. C<SCRIPT_NAME> should never be C</>,
244 but should instead be empty.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
245
246 =back
247
248 =head3 The Input Stream
249
ff0e6de @miyagawa paragraphized
miyagawa authored
250 The input stream in C<psgi.input> is an IO::Handle-like object which
251 streams the raw HTTP POST or PUT data. If it is a file handle then it
252 MUST be opened in binary mode. The input stream MUST respond to
253 C<read> and MAY implement C<seek>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
254
ff0e6de @miyagawa paragraphized
miyagawa authored
255 The built-in filehandle or IO::Handle based objects should work fine
256 everywhere. Application developers SHOULD NOT inspect the type or
257 class of the stream, but instead just call C<read> to duck type.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
258
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored
259 Application developers SHOULD NOT use the built-in C<read> function to
260 read from the input stream, because C<read> function only works with
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
261 the real IO object (a glob ref based file handle or PerlIO) and makes
262 duck typing difficult. Web application framework developers, if
263 they know the input stream will be used with the built-in read() in any
d36f900 @miyagawa web framework should deal with this IO thing
miyagawa authored
264 upstream code they can't touch, SHOULD use PerlIO or tie handle to
265 work around with this problem.
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored
266
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
267 =over 4
268
269 =item read
270
271 $input->read($buf, $len [, $offset ]);
272
273 =item seek
274
275 $input->seek($pos, $whence);
276
277 =back
278
279 =head3 The Error Stream
280
ff0e6de @miyagawa paragraphized
miyagawa authored
281 The error stream in C<psgi.errors> is an IO::Handle-like object to
282 print errors. The error stream must implement C<print>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
283
ff0e6de @miyagawa paragraphized
miyagawa authored
284 The built-in filehandle or IO::Handle based objects should work fine
285 everywhere. Application developers SHOULD NOT inspect the type or
286 class of the stream, but instead just call C<print> to duck type.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
287
288 =over 4
289
290 =item print
291
292 $errors->print($error);
293
294 =back
295
296 =head3 The Response
297
298 =head4 Status
299
300 HTTP status code, is an integer and MUST be greater than or equal to 100.
301
302 =head4 Headers
303
79b722f @miyagawa clarified it's not a hash ref
miyagawa authored
304 The headers must be an array reference (and NOT a hash reference!)
305 containing key and value pairs. Its number of elements MUST be
306 even. The header MUST NOT contain a C<Status> key, contain keys with
307 C<:> or newlines in their name, contain keys that end in C<-> or C<_>
308 but only contain keys that consist of letters, digits, C<_> or C<->
309 and start with a letter. The value of the header must be a scalar
310 value that contain a string. The value string MUST NOT contain
311 characters below chr(37).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
312
ff0e6de @miyagawa paragraphized
miyagawa authored
313 If the same key name appears multiple times in an array ref, those
314 header lines MUST be sent to the client separately (e.g. multiple
315 C<Set-Cookie> lines).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
316
317 =head4 Content-Type
318
ff0e6de @miyagawa paragraphized
miyagawa authored
319 There MUST be a C<Content-Type> except when the C<Status> is 1xx, 204
320 or 304, in which case there MUST be none given.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
321
322 =head4 Content-Length
323
ff0e6de @miyagawa paragraphized
miyagawa authored
324 There MUST NOT be a C<Content-Length> header when the C<Status> is
325 1xx, 204 or 304.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
326
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
327 If the Status is not 1xx, 204 or 304 and there is no C<Content-Length>
77b3dfe @miyagawa apps are not supposed to add Transfer-Encoding, remove it
miyagawa authored
328 header, servers MAY calculate the content length by looking at Body,
329 in case it can be calculated (i.e. if it's an array ref of body chunk
330 or a real file handle), and append to the outgoing headers.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
331
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
332 =head4 Body
333
ff0e6de @miyagawa paragraphized
miyagawa authored
334 The response body is returned from the application in one of following
335 two types of scalar variable.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
336
337 =over 4
338
339 =item *
340
341 An array reference containing body as lines.
342
343 my $body = [ "Hello\n", "World\n" ];
344
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
345 Note that the elements in an array reference are NOT REQUIRED to end
346 in a newline. The servers SHOULD just write each elements as is to the
347 client, and SHOULD NOT care if the line ends with newline or not.
348
349 So, when you have a big chunk of HTML in a single scalar C<$body>,
350
351 [ $body ]
352
353 is a valie response body.
354
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
355 =item *
356
357 An IO::Handle-like object or a built-in filehandle.
358
359 open my $body, "</path/to/file";
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
360 open my $body, "<:via(SomePerlIO)", ...;
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
361 my $body = IO::File->new("/path/to/file");
362
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
363 my $body = SomeClass->new(); # mock class that implements getline() and close()
364
0e5a284 @miyagawa more clarifications about what is Plack and what is Adapter. s/implem…
miyagawa authored
365 Servers SHOULD NOT check the type or class of the body but instead
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
366 just call C<getline> to iterate over the body and call C<close> when done.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
367
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
368 Servers MAY check if the body is a real filehandle using C<fileno> and
369 C<Scalar::Util::reftype> and if it's a real filehandle that has a file
370 descriptor, it MAY optimize the file serving using techniques like
371 I<sendfile(2)>.
372
373 Servers are RECOMMENDED to set C<$/> special variable to the buffer
374 size when reading content from C<$body> using C<getline> method, in
375 case it's a binary filehandle. Applications, when it returns a mock
376 object that implements C<getline> are NOT REQUIRED to respect the
377 C<$/> value.
378
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
379 =back
380
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
381 =head2 Middleware
382
383 Middleware is itself a PSGI application but it takes an existent PSGI
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
384 application and runs it like a server, mostly to do pre-processing on
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
385 C<$env> or post-processing on the response objects.
386
387 Here's a simple example that appends special HTTP header
388 I<X-PSGI-Used> to any PSGI application.
389
390 # $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
396 # $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
404 Middleware itself MUST behave exactly like a PSGI application: take
405 C<$env> and return C<$res>.
406
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
407 =head1 ACKNOWLEDGEMENTS
408
409 Some parts of this specification are adopted from the following specifications.
410
411 =over 4
412
413 =item *
414
415 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
416
417 =item *
418
419 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
420
421 =item *
422
423 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
424
425 =back
426
427 I'd like to thank authors of these great documents.
428
429 =head1 AUTHOR
430
431 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
432
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
433 =head1 CONTRIBUTORS
434
435 The following people have contributed to the PSGI specification and
436 Plack implementation by commiting their code, sending patches,
437 reporting bugs, asking questions, suggesting useful advices,
438 nitpicking, chatting on IRC or commenting on my blog (in no particular
439 order):
440
441 Tokuhiro Matsuno
442 Kazuhiro Osawa
443 Yuval Kogman
444 Kazuho Oku
445 Alexis Sukrieh
446 dann
447 Stevan Little
448 Daisuke Murase
449 mala
450 Pedro Melo
451 Jesse Luehrs
452 John Beppu
453 Shawn M Moore
454 Mark Stosberg
455 Matt S Trout
456 Jesse Vincent
457 Chia-liang Kao
458 Dave Rolsky
459 Hans Dieter Pearcey
460 Randy J Ray
461 Benjamin Trott
462 Max Maischein
463 Slaven Rezić
464 Marcel Grünauer
465 Masayoshi Sekimura
466 Brock Wilcox
467 Piers Cawley
ecdb6c0 @miyagawa added some HTTP::Engine contributors
miyagawa authored
468 Daisuke Maki
469 Kang-min Liu
470 Yukihiro Matsumoto
5623139 @miyagawa changed the Content-Length from SHOULD to MAY
miyagawa authored
471 Ash Berlin
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
472
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
473 =head1 COPYRIGHT AND LICENSE
474
475 Copyright Tatsuhiko Miyagawa, 2009.
476
477 This document is licensed under the Creative Commons license by-sa.
478
479 =cut
Something went wrong with that request. Please try again.