Skip to content

HTTPS clone URL

Subversion checkout URL

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