Skip to content

HTTPS clone URL

Subversion checkout URL

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