Skip to content
Newer
Older
100644 589 lines (409 sloc) 16.8 KB
30917ff @miyagawa POD fixes
miyagawa authored
1 =encoding utf-8
2
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
3 =head1 NAME
4
5 PSGI - Perl Web Server Gateway Interface Specification
6
7 =head1 ABSTRACT
8
ff0e6de @miyagawa paragraphized
miyagawa authored
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.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
13
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored
14 Keep in mind that PSGI is not Yet Another web application
15 framework. PSGI is a specification to decouple web server environments
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
16 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
17 application API. Web application developers (end users) are not
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
18 supposed to run their web applications directly using the PSGI
19 interface, but instead are encouraged to use frameworks that
20 support PSGI, or use the helper implementations like Plack (more on
21 that later).
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored
22
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
23 =head1 TERMINOLOGIES
24
25 =over 4
26
27 =item Servers
28
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
29 Servers are web servers that accept HTTP requests, dispatch the
4cb936b @miyagawa fixed typo thanks to yann
miyagawa authored
30 requests to the web applications and return the HTTP response to the
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
31 clients. In PSGI specification it's a Perl process that's running
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
32 inside an HTTP server (e.g. mod_perl in Apache), a daemon process
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
33 called from a web server (e.g. FastCGI daemon) or a pure perl HTTP
34 server.
35
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
36 Servers are also called I<PSGI implementations> as well as
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
37 I<Backends>.
38
39 =item Applications
40
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
41 Applications are web applications that actually get HTTP requests
42 and return HTTP response. In PSGI it's a code reference: see below.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
43
44 =item Middleware
45
46 Middleware is a PSGI application, which is a code reference, but also
47 runs like a server to run other applications. It can be thought of a
48 I<plugin> to extend PSGI application: see below.
49
50 =item Framework developers
51
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
52 Framework developers are authors of web application frameworks. They
53 need to write adapters (or engines) to read PSGI input, then run the
54 application logic and returns PSGI response to the server.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
55
56 =item Web application developers
57
58 Web application developers are developers who write code that uses one
59 of the web application framework that uses PSGI interface. They
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
60 usually don't need to deal with nor care about PSGI protocol at all.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
61
30917ff @miyagawa POD fixes
miyagawa authored
62 =back
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
63
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
64 =head1 SPECIFICATION
65
66 =head2 Applications
67
ff0e6de @miyagawa paragraphized
miyagawa authored
68 A PSGI application is a Perl code reference. It takes exactly one
69 argument, the environment and returns an array reference of exactly
70 three values.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
71
72 sub app {
73 my $env = shift;
74 return [
75 '200',
76 [ 'Content-Type' => 'text/plain' ],
31bd78b @miyagawa s/objects/object/ because it sounded like an array of IO::Handle objects
miyagawa authored
77 [ "Hello World" ], # or IO::Handle-like object
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
78 ];
79 }
80
81 =head3 The Environment
82
ff0e6de @miyagawa paragraphized
miyagawa authored
83 The environment MUST be a hash reference that includes CGI-like
84 headers. The application is free to modify the environment. The
85 environment is required to include these variables (adopted from
86 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
87
88 =over 4
89
90 =item *
91
ff0e6de @miyagawa paragraphized
miyagawa authored
92 C<REQUEST_METHOD>: The HTTP request method, such as "GET" or
93 "POST". This cannot ever be an empty string, and so is always
94 required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
95
96 =item *
97
ff0e6de @miyagawa paragraphized
miyagawa authored
98 C<SCRIPT_NAME>: The initial portion of the request URL's I<path> that
99 corresponds to the application, so that the application knows its
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
100 virtual "location". This may be an empty string if the application
ff0e6de @miyagawa paragraphized
miyagawa authored
101 corresponds to the "root" of the server.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
102
103 =item *
104
ff0e6de @miyagawa paragraphized
miyagawa authored
105 C<PATH_INFO>: The remainder of the request URL's "path", designating
106 the virtual "location" of the request's target within the
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
107 application. This may be an empty string if the request URL targets
ff0e6de @miyagawa paragraphized
miyagawa authored
108 the application root and does not have a trailing slash. This value
b2f90a3 @miyagawa PATH_INFO should be decoded by servers
miyagawa authored
109 should be URI decoded by servers to be compatible to RFC 3875.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
110
111 =item *
112
c6d7946 @miyagawa added REQUEST_URI to the PSGI spec
miyagawa authored
113 C<REQUEST_URI>: The undecoded, raw request URL line. It is the raw URI
114 path and query part that appears in the HTTP C<GET /... HTTP/1.x> line
115 and doesn't contain URI scheme and host names.
116
117 Unlike C<PATH_INFO>, this value SHOULD NOT be decoded by servers and
118 hence it is an application's responsibility to properly decode paths
119 to map URL to application handlers, when using C<REQUEST_URI> over
120 C<PATH_INFO>.
121
122 =item *
123
ff0e6de @miyagawa paragraphized
miyagawa authored
124 C<QUERY_STRING>: The portion of the request URL that follows the C<?>,
125 if any. May be empty, but is always required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
126
127 =item *
128
ff0e6de @miyagawa paragraphized
miyagawa authored
129 C<SERVER_NAME>, C<SERVER_PORT>: When combined with C<SCRIPT_NAME> and
130 C<PATH_INFO>, these variables can be used to complete the URL. Note,
131 however, that C<HTTP_HOST>, if present, should be used in preference
132 to C<SERVER_NAME> for reconstructing the request URL. C<SERVER_NAME>
133 and C<SERVER_PORT> can never be empty strings, and so are always
134 required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
135
136 =item *
137
ff0e6de @miyagawa paragraphized
miyagawa authored
138 C<SERVER_PROTOCOL>: The version of the protocol the client used to
139 send the request. Typically this will be something like "HTTP/1.0" or
140 "HTTP/1.1" and may be used by the application to determine how to
141 treat any HTTP request headers.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
142
143 =item *
144
ff0e6de @miyagawa paragraphized
miyagawa authored
145 C<HTTP_> Variables: Variables corresponding to the client-supplied
146 HTTP request headers (i.e., variables whose names begin with
147 C<HTTP_>). The presence or absence of these variables should
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
148 correspond to the presence or absence of the appropriate HTTP header
ff0e6de @miyagawa paragraphized
miyagawa authored
149 in the request.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
150
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
151 If there are multiple header lines sent with the same key, the server
152 should treat them as if they're sent in one line, i.e. combine them
153 with C<, > as in RFC 2616.
154
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
155 =back
156
ff0e6de @miyagawa paragraphized
miyagawa authored
157 In addition to this, the PSGI environment MUST include these
158 PSGI-specific variables:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
159
160 =over 4
161
162 =item *
163
164 C<psgi.version>: An array ref [1,0] representing this version of PSGI.
165
166 =item *
167
168 C<psgi.url_scheme>: A string C<http> or C<https>, depending on the request URL.
169
170 =item *
171
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
172 C<psgi.input>: the input stream. See below.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
173
174 =item *
175
176 C<psgi.errors>: the error stream. See below.
177
eee7655 @miyagawa Added psgi.multithread and psgi.multiprocess per discussion on about …
miyagawa authored
178 =item *
179
180 C<psgi.multithread>: true if the application may be simultaneously
181 invoked by another thread in the same process, false otherwise.
182
183 =item *
184
185 C<psgi.multiprocess>: true if an equivalent application object may be
186 simultaneously invoked by another process, false otherwise.
187
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
188 =back
189
190 The PSGI environment MAY include these optional PSGI variables:
191
192 =over 4
193
194 =item *
195
ff0e6de @miyagawa paragraphized
miyagawa authored
196 C<psgi.run_once>: true if the server expects (but does not guarantee!)
197 that the application will only be invoked this one time during the
198 life of its containing process. Normally, this will only be true for a
199 server based on CGI (or something similar).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
200
201 =item *
202
e21be68 @miyagawa s/.async/.nonblocking/ per discussions with nothingmuch++
miyagawa authored
203 C<psgi.nonblocking>: true if the server is calling the application in an
204 non-blocking event loop.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
205
667bda2 @miyagawa Draft streaming response
miyagawa authored
206 =item *
207
208 C<psgi.streaming>: true if the server supports callback style delayed
209 response and streaming writer object.
210
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
211 =back
212
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
213 The server or the application can store its own data in the
ff0e6de @miyagawa paragraphized
miyagawa authored
214 environment, too. The keys MUST contain at least one dot, and should
215 be prefixed uniquely. The prefix C<psgi.> is reserved for use with the
216 PSGI core implementation and other accepted extensions and MUST NOT be
217 used otherwise. The environment MUST NOT contain the keys
218 C<HTTP_CONTENT_TYPE> or C<HTTP_CONTENT_LENGTH> (use the versions
219 without C<HTTP_>). The CGI keys (named without a period) MUST have a
220 scalar variable containing strings. There are the following
221 restrictions:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
222
223 =over 4
224
225 =item *
226
227 C<psgi.version> MUST be an array of integers.
228
229 =item *
230
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
231 C<psgi.url_scheme> MUST be a scalar variable containing either the
ff0e6de @miyagawa paragraphized
miyagawa authored
232 string C<http> or C<https>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
233
234 =item *
235
236 There MUST be a valid input stream in C<psgi.input>.
237
238 =item *
239
240 There MUST be a valid error stream in C<psgi.errors>.
241
242 =item *
243
244 The C<REQUEST_METHOD> MUST be a valid token.
245
246 =item *
247
248 The C<SCRIPT_NAME>, if non-empty, MUST start with C</>
249
250 =item *
251
252 The C<PATH_INFO>, if non-empty, MUST start with C</>
253
254 =item *
255
256 The C<CONTENT_LENGTH>, if given, MUST consist of digits only.
257
258 =item *
259
ff0e6de @miyagawa paragraphized
miyagawa authored
260 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
261 be C</> if C<SCRIPT_NAME> is empty. C<SCRIPT_NAME> should never be C</>,
262 but should instead be empty.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
263
264 =back
265
266 =head3 The Input Stream
267
ff0e6de @miyagawa paragraphized
miyagawa authored
268 The input stream in C<psgi.input> is an IO::Handle-like object which
269 streams the raw HTTP POST or PUT data. If it is a file handle then it
270 MUST be opened in binary mode. The input stream MUST respond to
271 C<read> and MAY implement C<seek>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
272
ff0e6de @miyagawa paragraphized
miyagawa authored
273 The built-in filehandle or IO::Handle based objects should work fine
274 everywhere. Application developers SHOULD NOT inspect the type or
275 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
276
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored
277 Application developers SHOULD NOT use the built-in C<read> function to
278 read from the input stream, because C<read> function only works with
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
279 the real IO object (a glob ref based file handle or PerlIO) and makes
280 duck typing difficult. Web application framework developers, if
281 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
282 upstream code they can't touch, SHOULD use PerlIO or tie handle to
283 work around with this problem.
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored
284
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
285 =over 4
286
287 =item read
288
289 $input->read($buf, $len [, $offset ]);
290
a87c263 @miyagawa mentions return value of psgi.input and psgi.errors methods
miyagawa authored
291 Returns the number of characters actually read, 0 at end of file, or
292 undef if there was an error.
293
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
294 =item seek
295
296 $input->seek($pos, $whence);
297
a87c263 @miyagawa mentions return value of psgi.input and psgi.errors methods
miyagawa authored
298 Returns 1 on success, 0 otherwise.
299
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
300 =back
301
302 =head3 The Error Stream
303
ff0e6de @miyagawa paragraphized
miyagawa authored
304 The error stream in C<psgi.errors> is an IO::Handle-like object to
305 print errors. The error stream must implement C<print>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
306
ff0e6de @miyagawa paragraphized
miyagawa authored
307 The built-in filehandle or IO::Handle based objects should work fine
308 everywhere. Application developers SHOULD NOT inspect the type or
309 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
310
311 =over 4
312
313 =item print
314
315 $errors->print($error);
316
a87c263 @miyagawa mentions return value of psgi.input and psgi.errors methods
miyagawa authored
317 Returns true if successful.
318
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
319 =back
320
321 =head3 The Response
322
667bda2 @miyagawa Draft streaming response
miyagawa authored
323 The response MUST be a three element array reference if the
0d57abb @miyagawa some wording fixes
miyagawa authored
324 application wants to directly return the HTTP response.
325
326 An application MAY choose to return other type of responses such as a
327 code reference, to delay the response only if the server supports the
328 streaming (See below).
667bda2 @miyagawa Draft streaming response
miyagawa authored
329
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
330 =head4 Status
331
332 HTTP status code, is an integer and MUST be greater than or equal to 100.
333
334 =head4 Headers
335
79b722f @miyagawa clarified it's not a hash ref
miyagawa authored
336 The headers must be an array reference (and NOT a hash reference!)
337 containing key and value pairs. Its number of elements MUST be
338 even. The header MUST NOT contain a C<Status> key, contain keys with
339 C<:> or newlines in their name, contain keys that end in C<-> or C<_>
340 but only contain keys that consist of letters, digits, C<_> or C<->
341 and start with a letter. The value of the header must be a scalar
342 value that contain a string. The value string MUST NOT contain
0dd2975 @miyagawa header value can contain whitespace
miyagawa authored
343 characters below chr(37) except chr(32) (whitespace).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
344
ff0e6de @miyagawa paragraphized
miyagawa authored
345 If the same key name appears multiple times in an array ref, those
346 header lines MUST be sent to the client separately (e.g. multiple
347 C<Set-Cookie> lines).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
348
349 =head4 Content-Type
350
ff0e6de @miyagawa paragraphized
miyagawa authored
351 There MUST be a C<Content-Type> except when the C<Status> is 1xx, 204
352 or 304, in which case there MUST be none given.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
353
354 =head4 Content-Length
355
ff0e6de @miyagawa paragraphized
miyagawa authored
356 There MUST NOT be a C<Content-Length> header when the C<Status> is
357 1xx, 204 or 304.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
358
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
359 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
360 header, servers MAY calculate the content length by looking at Body,
361 in case it can be calculated (i.e. if it's an array ref of body chunk
362 or a real file handle), and append to the outgoing headers.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
363
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
364 =head4 Body
365
ff0e6de @miyagawa paragraphized
miyagawa authored
366 The response body is returned from the application in one of following
367 two types of scalar variable.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
368
369 =over 4
370
371 =item *
372
373 An array reference containing body as lines.
374
375 my $body = [ "Hello\n", "World\n" ];
376
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
377 Note that the elements in an array reference are NOT REQUIRED to end
378 in a newline. The servers SHOULD just write each elements as is to the
379 client, and SHOULD NOT care if the line ends with newline or not.
380
381 So, when you have a big chunk of HTML in a single scalar C<$body>,
382
383 [ $body ]
384
0d05bb1 @miyagawa another typo
miyagawa authored
385 is a valid response body.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
386
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
387 =item *
388
389 An IO::Handle-like object or a built-in filehandle.
390
391 open my $body, "</path/to/file";
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
392 open my $body, "<:via(SomePerlIO)", ...;
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
393 my $body = IO::File->new("/path/to/file");
394
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
395 my $body = SomeClass->new(); # mock class that implements getline() and close()
396
0e5a284 @miyagawa more clarifications about what is Plack and what is Adapter. s/implem…
miyagawa authored
397 Servers SHOULD NOT check the type or class of the body but instead
0e5b33e @miyagawa Updated spec: body can respond ->path.
miyagawa authored
398 just call C<getline> (i.e. duck type) to iterate over the body and
399 call C<close> when done.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
400
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
401 Servers MAY check if the body is a real filehandle using C<fileno> and
402 C<Scalar::Util::reftype> and if it's a real filehandle that has a file
403 descriptor, it MAY optimize the file serving using techniques like
404 I<sendfile(2)>.
405
0e5b33e @miyagawa Updated spec: body can respond ->path.
miyagawa authored
406 The body object MAY respond to C<path> method to return the local file
407 system path, which MAY be used by some servers to switch to more
408 efficient file serving method using the file path instead of a file
409 descriptor.
410
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
411 Servers are RECOMMENDED to set C<$/> special variable to the buffer
412 size when reading content from C<$body> using C<getline> method, in
413 case it's a binary filehandle. Applications, when it returns a mock
414 object that implements C<getline> are NOT REQUIRED to respect the
415 C<$/> value.
416
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
417 =back
418
667bda2 @miyagawa Draft streaming response
miyagawa authored
419 =head2 Delayed Reponse and Streaming Body
420
421 PSGI interface allows applications and servers optionally handle
422 callback-style response (instead of three-element array reference) to
423 delay the HTTP response and stream content (server push).
424
425 To enable delayed response, an application SHOULD check if
426 C<psgi.streaming> environment is true, and in that case, MAY return a
427 callback that is passed another callback (response starter) as its
428 first argument, and pass the three element response to the callback.
429
430 my $app = sub {
431 my $env = shift;
432
433 # Delays response until it fetches content from the network
434 return sub {
435 my $respond = shift;
436 fetch_content_from_server(sub {
437 my $content = shift;
438 # ...
439 $respond->([ 200, $headers, [ $content ] ]);
440 });
441 };
442 };
443
444 Similarly, an application MAY omit the third element (the body) in the
445 callback to get a response writer object, that implements C<write>,
0d57abb @miyagawa some wording fixes
miyagawa authored
446 C<poll_cb> and C<close> method to push the response body.
667bda2 @miyagawa Draft streaming response
miyagawa authored
447
448 my $app = sub {
449 my $env = shift;
450
451 # immediately starts the response and stream the content
452 return sub {
453 my $respond = shift;
454 my $writer = $respond->([ 200, [ 'Content-Type', 'application/json' ]]);
455
456 wait_for_events(sub {
457 my $new_event = shift;
458 if ($new_event) {
459 $writer->write($new_event->as_json . "\n");
460 # Or:
461 # $writer->poll_cb(sub { $_[0]->write($new_event->as_json . "\n") });
462 } else {
463 $writer->close;
464 }
465 });
466 };
467 };
468
469 Delayed response and streaming should be useful if you want to
470 implement non-blocking I/O based server streaming or long-poll Comet
0d57abb @miyagawa some wording fixes
miyagawa authored
471 push technology. IO::Handle-like object is I<pull>, while this
472 streaming response implements I<push>.
667bda2 @miyagawa Draft streaming response
miyagawa authored
473
474 This interface is optional: An applciation SHOULD check if the server
475 supports streaming. Servers MAY decide to not accept this streaming
476 response and throws an exception. Servers MUST set C<psgi.streaming>
477 to true if this interface is supported. Servers MUST return a writer
478 object if the third argument (response body) is omitted or not
479 defined in the response starter callback arguments.
480
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
481 =head2 Middleware
482
5d680fe @miyagawa s/existent/existing/
miyagawa authored
483 Middleware is itself a PSGI application but it takes an existing PSGI
a19c5ba @miyagawa minor grammer fixes
miyagawa authored
484 application and runs it like a server, mostly to do pre-processing on
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
485 C<$env> or post-processing on the response objects.
486
487 Here's a simple example that appends special HTTP header
488 I<X-PSGI-Used> to any PSGI application.
489
490 # $app is a simple PSGI application
491 my $app = sub {
492 my $env = shift;
493 return [ '200', [ 'Content-Type' => 'text/plain' ], [ "Hello World" ] ];
494 };
495
496 # $xheader is a middleware to wrap $app
497 my $xheader = sub {
498 my $env = shift;
499 my $res = $app->($env);
500 push @{$res->[1]}, 'X-PSGI-Used' => 1;
501 return $res;
502 };
503
504 Middleware itself MUST behave exactly like a PSGI application: take
0d57abb @miyagawa some wording fixes
miyagawa authored
505 C<$env> and return C<$res>. Middleware MAY decide not to support the
667bda2 @miyagawa Draft streaming response
miyagawa authored
506 streaming interface (see above) but SHOULD pass through the response
507 types that it doesn't understand.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
508
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
509 =head1 ACKNOWLEDGEMENTS
510
511 Some parts of this specification are adopted from the following specifications.
512
513 =over 4
514
515 =item *
516
517 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
518
519 =item *
520
521 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
522
523 =item *
524
525 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
526
527 =back
528
529 I'd like to thank authors of these great documents.
530
531 =head1 AUTHOR
532
533 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
534
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
535 =head1 CONTRIBUTORS
536
537 The following people have contributed to the PSGI specification and
538 Plack implementation by commiting their code, sending patches,
539 reporting bugs, asking questions, suggesting useful advices,
540 nitpicking, chatting on IRC or commenting on my blog (in no particular
541 order):
542
543 Tokuhiro Matsuno
544 Kazuhiro Osawa
545 Yuval Kogman
546 Kazuho Oku
547 Alexis Sukrieh
048f9a3 @miyagawa update Dann's name. README links to the site
miyagawa authored
548 Takatoshi Kitano
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
549 Stevan Little
550 Daisuke Murase
551 mala
552 Pedro Melo
553 Jesse Luehrs
554 John Beppu
555 Shawn M Moore
556 Mark Stosberg
557 Matt S Trout
558 Jesse Vincent
559 Chia-liang Kao
560 Dave Rolsky
561 Hans Dieter Pearcey
562 Randy J Ray
563 Benjamin Trott
564 Max Maischein
565 Slaven Rezić
566 Marcel Grünauer
567 Masayoshi Sekimura
568 Brock Wilcox
569 Piers Cawley
ecdb6c0 @miyagawa added some HTTP::Engine contributors
miyagawa authored
570 Daisuke Maki
571 Kang-min Liu
2b08fe3 @miyagawa oops
miyagawa authored
572 Yasuhiro Matsumoto
5623139 @miyagawa changed the Content-Length from SHOULD to MAY
miyagawa authored
573 Ash Berlin
31284b9 @miyagawa Added Artur for his advice around gearman/schwartz
miyagawa authored
574 Artur Bergman
ba2001a @miyagawa more questions around HTTP::Engine confusions
miyagawa authored
575 Simon Cozens
576 Scott McWhirter
a87c263 @miyagawa mentions return value of psgi.input and psgi.errors methods
miyagawa authored
577 Jiro Nishiguchi
01b3c47 @miyagawa Sorry!
miyagawa authored
578 Masahiro Chiba
1ef1c9c @miyagawa Added patspam for his webgui work
miyagawa authored
579 Patrick Donelan
d7fc7bb @miyagawa Added frodwith for helping us sort out the non-blocking from POE deve…
miyagawa authored
580 Paul Driver
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
581
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
582 =head1 COPYRIGHT AND LICENSE
583
584 Copyright Tatsuhiko Miyagawa, 2009.
585
586 This document is licensed under the Creative Commons license by-sa.
587
588 =cut
Something went wrong with that request. Please try again.