Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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