Skip to content
Newer
Older
100644 476 lines (319 sloc) 13 KB
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
1 =head1 NAME
2
3 PSGI - Perl Web Server Gateway Interface Specification
4
5 =head1 ABSTRACT
6
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
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 Sep 7, 2009
11
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored Sep 7, 2009
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 Sep 8, 2009
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 Sep 7, 2009
15 application API. Web application developers (end users) are not
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
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 Sep 7, 2009
20
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored Sep 16, 2009
21 =head1 TERMINOLOGIES
22
23 =over 4
24
25 =item Servers
26
27 Servers are web servers that accepts HTTP requests, dispatch the
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
30 inside an HTTP server (e.g. mod_perl in Apache) or a daemon process
31 called from a web server (e.g. FastCGI daemon) or a pure perl HTTP
32 server.
33
34 Servers are often called I<PSGI implementations> as well as
35 I<Backends>.
36
37 =item Applications
38
39 Applications are a web application that actually gets HTTP requests
40 and returns HTTP response. In PSGI it's a code reference: see below.
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
50 Framework developers are an authors of web application
51 frameworks. They need to write adapters (or engines) to read PSGI
52 input, then run the application logic and returns PSGI response to the
53 server.
54
55 =item Web application developers
56
57 Web application developers are developers who write code that uses one
58 of the web application framework that uses PSGI interface. They
59 usually don't need to deal with PSGI protocol at all.
60
61 =cut
62
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
63 =head1 SPECIFICATION
64
65 =head2 Applications
66
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
67 A PSGI application is a Perl code reference. It takes exactly one
68 argument, the environment and returns an array reference of exactly
69 three values.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
70
71 sub app {
72 my $env = shift;
73 return [
74 '200',
75 [ 'Content-Type' => 'text/plain' ],
31bd78b @miyagawa s/objects/object/ because it sounded like an array of IO::Handle objects
miyagawa authored Sep 7, 2009
76 [ "Hello World" ], # or IO::Handle-like object
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
77 ];
78 }
79
80 =head3 The Environment
81
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
82 The environment MUST be a hash reference that includes CGI-like
83 headers. The application is free to modify the environment. The
84 environment is required to include these variables (adopted from
85 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 Sep 7, 2009
86
87 =over 4
88
89 =item *
90
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
91 C<REQUEST_METHOD>: The HTTP request method, such as "GET" or
92 "POST". This cannot ever be an empty string, and so is always
93 required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
94
95 =item *
96
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
97 C<SCRIPT_NAME>: The initial portion of the request URL's I<path> that
98 corresponds to the application, so that the application knows its
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
99 virtual "location". This may be an empty string if the application
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
100 corresponds to the "root" of the server.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
101
102 =item *
103
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
104 C<PATH_INFO>: The remainder of the request URL's "path", designating
105 the virtual "location" of the request's target within the
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
106 application. This may be an empty string if the request URL targets
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
107 the application root and does not have a trailing slash. This value
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
108 may be percent-encoded when it originates from a URL.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
109
110 =item *
111
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
112 C<QUERY_STRING>: The portion of the request URL that follows the C<?>,
113 if any. May be empty, but is always required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
114
115 =item *
116
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
117 C<SERVER_NAME>, C<SERVER_PORT>: When combined with C<SCRIPT_NAME> and
118 C<PATH_INFO>, these variables can be used to complete the URL. Note,
119 however, that C<HTTP_HOST>, if present, should be used in preference
120 to C<SERVER_NAME> for reconstructing the request URL. C<SERVER_NAME>
121 and C<SERVER_PORT> can never be empty strings, and so are always
122 required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
123
124 =item *
125
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
126 C<SERVER_PROTOCOL>: The version of the protocol the client used to
127 send the request. Typically this will be something like "HTTP/1.0" or
128 "HTTP/1.1" and may be used by the application to determine how to
129 treat any HTTP request headers.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
130
131 =item *
132
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
133 C<HTTP_> Variables: Variables corresponding to the client-supplied
134 HTTP request headers (i.e., variables whose names begin with
135 C<HTTP_>). The presence or absence of these variables should
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
136 correspond to the presence or absence of the appropriate HTTP header
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
137 in the request.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
138
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored Sep 16, 2009
139 If there are multiple header lines sent with the same key, the server
140 should treat them as if they're sent in one line, i.e. combine them
141 with C<, > as in RFC 2616.
142
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
143 =back
144
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
145 In addition to this, the PSGI environment MUST include these
146 PSGI-specific variables:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
147
148 =over 4
149
150 =item *
151
152 C<psgi.version>: An array ref [1,0] representing this version of PSGI.
153
154 =item *
155
156 C<psgi.url_scheme>: A string C<http> or C<https>, depending on the request URL.
157
158 =item *
159
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
160 C<psgi.input>: the input stream. See below.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
161
162 =item *
163
164 C<psgi.errors>: the error stream. See below.
165
eee7655 @miyagawa Added psgi.multithread and psgi.multiprocess per discussion on about …
miyagawa authored Sep 9, 2009
166 =item *
167
168 C<psgi.multithread>: true if the application may be simultaneously
169 invoked by another thread in the same process, false otherwise.
170
171 =item *
172
173 C<psgi.multiprocess>: true if an equivalent application object may be
174 simultaneously invoked by another process, false otherwise.
175
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
176 =back
177
178 The PSGI environment MAY include these optional PSGI variables:
179
180 =over 4
181
182 =item *
183
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
184 C<psgi.run_once>: true if the server expects (but does not guarantee!)
185 that the application will only be invoked this one time during the
186 life of its containing process. Normally, this will only be true for a
187 server based on CGI (or something similar).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
188
189 =item *
190
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored Sep 16, 2009
191 C<psgi.async>: true if the server is calling the application in an
192 asynchronous event loop. See L<PSGI Async extension|PSGI::Async>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
193
194 =back
195
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
196 The server or the application can store its own data in the
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
197 environment, too. The keys MUST contain at least one dot, and should
198 be prefixed uniquely. The prefix C<psgi.> is reserved for use with the
199 PSGI core implementation and other accepted extensions and MUST NOT be
200 used otherwise. The environment MUST NOT contain the keys
201 C<HTTP_CONTENT_TYPE> or C<HTTP_CONTENT_LENGTH> (use the versions
202 without C<HTTP_>). The CGI keys (named without a period) MUST have a
203 scalar variable containing strings. There are the following
204 restrictions:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
205
206 =over 4
207
208 =item *
209
210 C<psgi.version> MUST be an array of integers.
211
212 =item *
213
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
214 C<psgi.url_scheme> MUST be a scalar variable containing either the
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
215 string C<http> or C<https>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
216
217 =item *
218
219 There MUST be a valid input stream in C<psgi.input>.
220
221 =item *
222
223 There MUST be a valid error stream in C<psgi.errors>.
224
225 =item *
226
227 The C<REQUEST_METHOD> MUST be a valid token.
228
229 =item *
230
231 The C<SCRIPT_NAME>, if non-empty, MUST start with C</>
232
233 =item *
234
235 The C<PATH_INFO>, if non-empty, MUST start with C</>
236
237 =item *
238
239 The C<CONTENT_LENGTH>, if given, MUST consist of digits only.
240
241 =item *
242
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
243 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 Sep 7, 2009
244 be C</> if C<SCRIPT_NAME> is empty. C<SCRIPT_NAME> should never be C</>,
245 but should instead be empty.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
246
247 =back
248
249 =head3 The Input Stream
250
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
251 The input stream in C<psgi.input> is an IO::Handle-like object which
252 streams the raw HTTP POST or PUT data. If it is a file handle then it
253 MUST be opened in binary mode. The input stream MUST respond to
254 C<read> and MAY implement C<seek>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
255
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
256 The built-in filehandle or IO::Handle based objects should work fine
257 everywhere. Application developers SHOULD NOT inspect the type or
258 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 Sep 7, 2009
259
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored Sep 7, 2009
260 Application developers SHOULD NOT use the built-in C<read> function to
261 read from the input stream, because C<read> function only works with
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
262 the real IO object (a glob ref based file handle or PerlIO) and makes
263 duck typing difficult. Web application framework developers, if
264 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 Sep 7, 2009
265 upstream code they can't touch, SHOULD use PerlIO or tie handle to
266 work around with this problem.
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored Sep 7, 2009
267
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
268 =over 4
269
270 =item read
271
272 $input->read($buf, $len [, $offset ]);
273
274 =item seek
275
276 $input->seek($pos, $whence);
277
278 =back
279
280 =head3 The Error Stream
281
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
282 The error stream in C<psgi.errors> is an IO::Handle-like object to
283 print errors. The error stream must implement C<print>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
284
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
285 The built-in filehandle or IO::Handle based objects should work fine
286 everywhere. Application developers SHOULD NOT inspect the type or
287 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 Sep 7, 2009
288
289 =over 4
290
291 =item print
292
293 $errors->print($error);
294
295 =back
296
297 =head3 The Response
298
299 =head4 Status
300
301 HTTP status code, is an integer and MUST be greater than or equal to 100.
302
303 =head4 Headers
304
79b722f @miyagawa clarified it's not a hash ref
miyagawa authored Sep 8, 2009
305 The headers must be an array reference (and NOT a hash reference!)
306 containing key and value pairs. Its number of elements MUST be
307 even. The header MUST NOT contain a C<Status> key, contain keys with
308 C<:> or newlines in their name, contain keys that end in C<-> or C<_>
309 but only contain keys that consist of letters, digits, C<_> or C<->
310 and start with a letter. The value of the header must be a scalar
311 value that contain a string. The value string MUST NOT contain
312 characters below chr(37).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
313
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
314 If the same key name appears multiple times in an array ref, those
315 header lines MUST be sent to the client separately (e.g. multiple
316 C<Set-Cookie> lines).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
317
318 =head4 Content-Type
319
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
320 There MUST be a C<Content-Type> except when the C<Status> is 1xx, 204
321 or 304, in which case there MUST be none given.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
322
323 =head4 Content-Length
324
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
325 There MUST NOT be a C<Content-Length> header when the C<Status> is
326 1xx, 204 or 304.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
327
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored Sep 16, 2009
328 If the Status is not 1xx, 204 or 304 and there is no C<Content-Length>
329 header, servers SHOULD calculate the content length by looking at
330 Body, in case it can be calculated, and append to the outgoing headers.
331
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
332 =head4 Body
333
ff0e6de @miyagawa paragraphized
miyagawa authored Sep 7, 2009
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 Sep 7, 2009
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 Sep 16, 2009
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 Sep 7, 2009
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 Sep 16, 2009
360 open my $body, "<:via(SomePerlIO)", ...;
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
361 my $body = IO::File->new("/path/to/file");
362
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored Sep 16, 2009
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 Sep 9, 2009
365 Servers SHOULD NOT check the type or class of the body but instead
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored Sep 7, 2009
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 Sep 7, 2009
367
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored Sep 16, 2009
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 Sep 7, 2009
379 =back
380
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored Sep 16, 2009
381 =head2 Middleware
382
383 Middleware is itself a PSGI application but it takes an existent PSGI
384 application and run it like a server, mostly to do pre-processing on
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 Sep 7, 2009
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 Sep 16, 2009
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
468
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored Sep 7, 2009
469 =head1 COPYRIGHT AND LICENSE
470
471 Copyright Tatsuhiko Miyagawa, 2009.
472
473 This document is licensed under the Creative Commons license by-sa.
474
475 =cut
Something went wrong with that request. Please try again.