Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 651 lines (453 sloc) 20.237 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
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
279 One of C<SCRIPT_NAME> or C<PATH_INFO> B<MUST> be set. C<PATH_INFO> should be
280 C</> if C<SCRIPT_NAME> is empty. C<SCRIPT_NAME> B<MUST NOT> be C</>, but
281 B<MAY> be empty.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
282
283 =head3 The Input Stream
284
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
285 The input stream in C<psgi.input> is an L<IO::Handle>-like object which
ff0e6de @miyagawa paragraphized
miyagawa authored
286 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
287 B<MUST> be opened in binary mode. The input stream B<MUST> respond to
288 C<read> and B<MAY> implement C<seek>.
289
290 Perl's built-in filehandles or L<IO::Handle> based objects should work as-is
291 in a PSGI server. Application developers B<SHOULD NOT> inspect the type or
292 class of the stream. Instead, they B<SHOULD> simply call C<read> on the object.
293
294 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
295 (C<< <$fh> >>) to read from the input stream. Instead, application
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
296 developers should call C<read> as a method (C<< $fh->read >>) to allow for
297 duck typing.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
298
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
299 Framework developers, if they know the input stream will be used with the
300 built-in read() in any upstream code they can't touch, B<SHOULD> use PerlIO or
301 a tied handle to work around with this problem.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
302
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
303 The input stream objet is expected to provide a C<read> method:
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored
304
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
305 =over 4
306
307 =item read
308
309 $input->read($buf, $len [, $offset ]);
310
a87c263 @miyagawa mentions return value of psgi.input and psgi.errors methods
miyagawa authored
311 Returns the number of characters actually read, 0 at end of file, or
312 undef if there was an error.
313
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
314 =back
315
316 It may also implement an optional C<seek> method.
317
318 =over 4
319
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
320 =item seek
321
322 $input->seek($pos, $whence);
323
a87c263 @miyagawa mentions return value of psgi.input and psgi.errors methods
miyagawa authored
324 Returns 1 on success, 0 otherwise.
325
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
326 =back
327
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
328 See the L<IO::Handle> documentation for more details on exactly how these
329 methods should work.
330
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
331 =head3 The Error Stream
332
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
333 The error stream in C<psgi.errors> is an L<IO::Handle>-like object to
334 print errors. The error stream must implement a C<print> method.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
335
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
336 As with the input stream, Perl's built-in filehandles or L<IO::Handle> based
337 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
338 NOT> inspect the type or class of the stream. Instead, they B<SHOULD> simply
339 call C<print> on the object.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
340
341 =over 4
342
343 =item print
344
345 $errors->print($error);
346
a87c263 @miyagawa mentions return value of psgi.input and psgi.errors methods
miyagawa authored
347 Returns true if successful.
348
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
349 =back
350
351 =head3 The Response
352
f745e83 @miyagawa array or code ref. That is MUST per PSGI spec POV. If you return some…
miyagawa authored
353 Applications B<MUST> return a response as either a three element array
354 reference, or a code reference for a delayed/streaming response.
0d57abb @miyagawa some wording fixes
miyagawa authored
355
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
356 The response array reference consists of the following elements:
667bda2 @miyagawa Draft streaming response
miyagawa authored
357
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
358 =head4 Status
359
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
360 An HTTP status code. This B<MUST> be an integer greater than or equal to 100,
361 and B<SHOULD> be an HTTP status code as documented in L<RFC
362 2616|http://www.w3.org/Protocols/rfc2616>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
363
364 =head4 Headers
365
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
366 The headers B<MUST> be an array reference (B<not> a hash reference)
367 of key/value pairs. This means it B<MUST> contain an even number of elements.
368
b4d5be2 @autarch Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
autarch authored
369 The header B<MUST NOT> contain a key named C<Status>, onr any keys with C<:>
370 or newlines in their name. It B<MUST NOT> contain any keys that end in C<-> or
371 C<_>.
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
372
373 All keys B<MUST> consist only of letters, digits, C<_> or C<->. All keys
374 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
375 string. The value string B<MUST NOT> contain characters below ASCII chr(37)
376 except for chr(32) (whitespace).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
377
ff0e6de @miyagawa paragraphized
miyagawa authored
378 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
379 header lines B<MUST> be sent to the client separately (e.g. multiple
ff0e6de @miyagawa paragraphized
miyagawa authored
380 C<Set-Cookie> lines).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
381
382 =head4 Content-Type
383
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
384 There B<MUST> be a C<Content-Type> except when the C<Status> is 1xx, 204
385 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
386
387 =head4 Content-Length
388
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
389 There B<MUST NOT> be a C<Content-Length> header when the C<Status> is
ff0e6de @miyagawa paragraphized
miyagawa authored
390 1xx, 204 or 304.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
391
b4d5be2 @autarch Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
autarch authored
392 If the Status is not 1xx, 204 or 304 and there is no C<Content-Length> header,
393 a PSGI server B<MAY> calculate the content length by looking at the Body. This
394 value can then be appended to the list of headers returned by the application.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
395
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
396 =head4 Body
397
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
398 The response body B<MUST> be returned from the application as either an array
399 reference or a handle.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
400
401 =over 4
402
403 =item *
404
b4d5be2 @autarch Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
autarch authored
405 If the body is an array reference, it is expected to contain an array of lines
406 which make up the body.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
407
408 my $body = [ "Hello\n", "World\n" ];
409
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
410 Note that the elements in an array reference are B<NOT REQUIRED> to end
411 in a newline. A server B<SHOULD> write each elements as-is to the
412 client, and B<SHOULD NOT> care if the line ends with newline or not.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
413
6342aa0 @miyagawa change the variable name to be less confusing
miyagawa authored
414 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
415 response body.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
416
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
417 =item *
418
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
419 The body can instead be a handle, either a Perl built-in filehandle or an
420 L<IO::Handle>-like object.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
421
422 open my $body, "</path/to/file";
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
423 open my $body, "<:via(SomePerlIO)", ...;
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
424 my $body = IO::File->new("/path/to/file");
425
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
426 my $body = SomeClass->new(); # mock class that implements getline() and close()
427
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
428 Servers B<SHOULD NOT> check the type or class of the body. Instead, they should
429 simply call C<getline> to iterate over the body, and
0e5b33e @miyagawa Updated spec: body can respond ->path.
miyagawa authored
430 call C<close> when done.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
431
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
432 Servers B<MAY> check if the body is a real filehandle using C<fileno> and
433 C<Scalar::Util::reftype>. If the body is real filehandle, the server B<MAY>
434 optimize using techniques like I<sendfile(2)>.
435
436 The body object B<MAY> also respond to a C<path> method. This method is
437 expected to return the path to a file accessible by the server. This allows
438 the server to use this information instead of a file descriptor number to
e0431ce @miyagawa make PSGI app a code ref
miyagawa authored
439 serve the file.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
440
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
441 Servers B<SHOULD> set the C<$/> special variable to the buffer size when
442 reading content from C<$body> using the C<getline> method. This is done by
443 setting C<$/> with a reference to an integer (C<$/ = \8192>).
0e5b33e @miyagawa Updated spec: body can respond ->path.
miyagawa authored
444
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
445 If the body filehandle is a Perl built-in filehandle L<IO::Handle> object,
446 they will respect this value. Similarly, an object which provides the same API
447 B<MAY> also respect this special variable, but are not required to do so.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
448
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
449 =back
450
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
451 =head2 Delayed Response and Streaming Body
667bda2 @miyagawa Draft streaming response
miyagawa authored
452
c5aa24f @miyagawa psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
miyagawa authored
453 The PSGI interface allows applications and servers to provide a
454 callback-style response instead of the three-element array
455 reference. This allows for a delayed response and a streaming body
456 (server push).
457
458 This interface B<SHOULD> be implemented by PSGI servers, and
459 C<psgi.streaming> environment B<MUST> be set to true in such servers.
667bda2 @miyagawa Draft streaming response
miyagawa authored
460
c5aa24f @miyagawa psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
miyagawa authored
461 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
462 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
463 C<psgi.streaming> environment is true and falls back to the direct
464 response if it isn't.
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
465
466 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
467 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
468 should in turn be called with the standard three element array reference
469 response. This is best illustrated with an example:
667bda2 @miyagawa Draft streaming response
miyagawa authored
470
471 my $app = sub {
472 my $env = shift;
473
474 # Delays response until it fetches content from the network
475 return sub {
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
476 my $responder = shift;
477
c5aa24f @miyagawa psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
miyagawa authored
478 fetch_content_from_server(sub {
479 my $content = shift;
480 $responder->([ 200, $headers, [ $content ] ]);
481 });
667bda2 @miyagawa Draft streaming response
miyagawa authored
482 };
483 };
484
c5aa24f @miyagawa psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
miyagawa authored
485 An application B<MAY> omit the third element (the body) when calling
486 the I<responder>. If the body is omitted, the I<responder> B<MUST>
487 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
488 methods. Again, an example illustrates this best.
667bda2 @miyagawa Draft streaming response
miyagawa authored
489
490 my $app = sub {
491 my $env = shift;
492
493 # immediately starts the response and stream the content
494 return sub {
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
495 my $responder = shift;
496 my $writer = $responder->([ 200, [ 'Content-Type', 'application/json' ]]);
667bda2 @miyagawa Draft streaming response
miyagawa authored
497
498 wait_for_events(sub {
499 my $new_event = shift;
500 if ($new_event) {
501 $writer->write($new_event->as_json . "\n");
502 } else {
503 $writer->close;
504 }
505 });
506 };
507 };
508
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
509 This delayed response and streaming API is useful if you want to
510 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
511 push technology, but could also be used to implement unbuffered writes
512 in a blocking server.
667bda2 @miyagawa Draft streaming response
miyagawa authored
513
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
514 =head2 Middleware
515
b4d5be2 @autarch Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
autarch authored
516 A I<middleware> component takes another PSGI application and runs it. From the
517 perspective of a server, a middleware component is a PSGI application. From
518 the perspective of the application being run by the middleware component, the
519 middleware is the server. Generally, this will be done in order to implement
520 some sort of pre-processing on the PSGI environment hash or post-processing on
521 the response.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
522
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
523 Here's a simple example that appends a special HTTP header
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
524 I<X-PSGI-Used> to any PSGI application.
525
526 # $app is a simple PSGI application
527 my $app = sub {
528 my $env = shift;
529 return [ '200', [ 'Content-Type' => 'text/plain' ], [ "Hello World" ] ];
530 };
531
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
532 # $xheader is a piece of middleware that wraps $app
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
533 my $xheader = sub {
534 my $env = shift;
535 my $res = $app->($env);
536 push @{$res->[1]}, 'X-PSGI-Used' => 1;
537 return $res;
538 };
539
3e2dde3 @autarch English cleanup, rewriting parts for clarity, adding links, and small…
autarch authored
540 Middleware B<MUST> behave exactly like a PSGI application from the perspective
541 of a server. Middleware B<MAY> decide not to support the streaming interface
542 discussed earlier, but B<SHOULD> pass through the response types that it doesn't
543 understand.
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
544
38d724b @miyagawa Promote psgi.streaming, nonblocking and run_once keys to be MUST.
miyagawa authored
545 =head1 CHANGELOGS
546
547 1.1: 2010.02.xx
548
549 =over 4
550
551 =item *
552
f43792e @miyagawa added psgix.logger and psgix.session
miyagawa authored
553 Added optional PSGI keys as extensions: C<psgix.logger> and C<psgix.session>.
554
555 =item *
556
38d724b @miyagawa Promote psgi.streaming, nonblocking and run_once keys to be MUST.
miyagawa authored
557 C<psgi.streaming> B<SHOULD> be implemented by PSGI servers, rather than B<MAY>.
558
559 =item *
560
561 PSGI keys C<psgi.run_once>, C<psgi.nonblocking> and C<psgi.streaming>
562 B<MUST> be set by PSGI servers.
563
564 =item *
565
566 Removed C<poll_cb> from writer methods.
567
568 =back
569
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
570 =head1 ACKNOWLEDGEMENTS
571
572 Some parts of this specification are adopted from the following specifications.
573
574 =over 4
575
576 =item *
577
578 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
579
580 =item *
581
582 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
583
584 =item *
585
586 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
587
588 =back
589
590 I'd like to thank authors of these great documents.
591
592 =head1 AUTHOR
593
594 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
595
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
596 =head1 CONTRIBUTORS
597
598 The following people have contributed to the PSGI specification and
599 Plack implementation by commiting their code, sending patches,
600 reporting bugs, asking questions, suggesting useful advices,
601 nitpicking, chatting on IRC or commenting on my blog (in no particular
602 order):
603
604 Tokuhiro Matsuno
605 Kazuhiro Osawa
606 Yuval Kogman
607 Kazuho Oku
608 Alexis Sukrieh
048f9a3 @miyagawa update Dann's name. README links to the site
miyagawa authored
609 Takatoshi Kitano
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
610 Stevan Little
611 Daisuke Murase
612 mala
613 Pedro Melo
614 Jesse Luehrs
615 John Beppu
616 Shawn M Moore
617 Mark Stosberg
618 Matt S Trout
619 Jesse Vincent
620 Chia-liang Kao
621 Dave Rolsky
622 Hans Dieter Pearcey
623 Randy J Ray
624 Benjamin Trott
625 Max Maischein
626 Slaven Rezić
627 Marcel Grünauer
628 Masayoshi Sekimura
629 Brock Wilcox
630 Piers Cawley
ecdb6c0 @miyagawa added some HTTP::Engine contributors
miyagawa authored
631 Daisuke Maki
632 Kang-min Liu
2b08fe3 @miyagawa oops
miyagawa authored
633 Yasuhiro Matsumoto
5623139 @miyagawa changed the Content-Length from SHOULD to MAY
miyagawa authored
634 Ash Berlin
31284b9 @miyagawa Added Artur for his advice around gearman/schwartz
miyagawa authored
635 Artur Bergman
ba2001a @miyagawa more questions around HTTP::Engine confusions
miyagawa authored
636 Simon Cozens
637 Scott McWhirter
a87c263 @miyagawa mentions return value of psgi.input and psgi.errors methods
miyagawa authored
638 Jiro Nishiguchi
01b3c47 @miyagawa Sorry!
miyagawa authored
639 Masahiro Chiba
1ef1c9c @miyagawa Added patspam for his webgui work
miyagawa authored
640 Patrick Donelan
d7fc7bb @miyagawa Added frodwith for helping us sort out the non-blocking from POE deve…
miyagawa authored
641 Paul Driver
93432fb @miyagawa Added rafl
miyagawa authored
642 Florian Ragwitz
1173dc0 @miyagawa New spec: feedbacks got merged.
miyagawa authored
643
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
644 =head1 COPYRIGHT AND LICENSE
645
646 Copyright Tatsuhiko Miyagawa, 2009.
647
648 This document is licensed under the Creative Commons license by-sa.
649
650 =cut
Something went wrong with that request. Please try again.