Skip to content

HTTPS clone URL

Subversion checkout URL

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