Skip to content
This repository
Newer
Older
100644 622 lines (433 sloc) 19.184 kb
30917ff2 »
2009-09-30 POD fixes
1 =encoding utf-8
2
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
3 =head1 NAME
4
5 PSGI - Perl Web Server Gateway Interface Specification
6
7 =head1 ABSTRACT
8
ff0e6def »
2009-09-07 paragraphized
9 This document specifies a standard interface between web servers and
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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
ff0e6def »
2009-09-07 paragraphized
12 framework developers.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
13
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
14 Please keep in mind that PSGI is not Yet Another web application
0f6003f5 »
2009-09-07 Added a note that PSGI is not an API for end users
15 framework. PSGI is a specification to decouple web server environments
38d724bf »
2010-01-18 Promote psgi.streaming, nonblocking and run_once keys to be MUST.
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.
0f6003f5 »
2009-09-07 Added a note that PSGI is not an API for end users
20
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
21 =head1 TERMINOLOGY
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
22
23 =over 4
24
25 =item Servers
26
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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
a19c5bac »
2009-09-16 minor grammer fixes
30 inside an HTTP server (e.g. mod_perl in Apache), a daemon process
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
31 called from a web server (e.g. FastCGI daemon) or a pure perl HTTP
32 server.
33
34 =item Applications
35
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
38
39 =item Middleware
40
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
45
46 =item Framework developers
47
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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>.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
51
52 =item Web application developers
53
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
57
30917ff2 »
2009-09-30 POD fixes
58 =back
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
59
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
60 =head1 SPECIFICATION
61
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
62 =head2 Application
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
63
ff0e6def »
2009-09-07 paragraphized
64 A PSGI application is a Perl code reference. It takes exactly one
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
65 argument, the environment, and returns an array reference containing exactly
ff0e6def »
2009-09-07 paragraphized
66 three values.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
67
e0431ced »
2009-11-08 make PSGI app a code ref
68 my $app = sub {
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
69 my $env = shift;
70 return [
71 '200',
72 [ 'Content-Type' => 'text/plain' ],
31bd78b4 »
2009-09-07 s/objects/object/ because it sounded like an array of IO::Handle objects
73 [ "Hello World" ], # or IO::Handle-like object
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
74 ];
e0431ced »
2009-11-08 make PSGI app a code ref
75 };
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
76
77 =head3 The Environment
78
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
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
1d6c6fe9 »
2009-10-28 changed how to treat when boolean key doesn't exist
90 application B<MAY> treat this as a false value.
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
91
92 The values for all CGI keys (named without a period) B<MUST> be a scalar
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
93 string.
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
94
95 See below for details.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
96
97 =over 4
98
99 =item *
100
ff0e6def »
2009-09-07 paragraphized
101 C<REQUEST_METHOD>: The HTTP request method, such as "GET" or
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
102 "POST". This B<MUST NOT> be an empty string, and so is always
ff0e6def »
2009-09-07 paragraphized
103 required.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
104
105 =item *
106
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
107 C<SCRIPT_NAME>: The initial portion of the request URL's I<path>,
108 corresponding to the application. This tells the application its
65afea5d »
2009-09-08 apply grammer fixes from hanekomu
109 virtual "location". This may be an empty string if the application
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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</>).
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
113
114 =item *
115
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
116 C<PATH_INFO>: The remainder of the request URL's I<path>, designating
ff0e6def »
2009-09-07 paragraphized
117 the virtual "location" of the request's target within the
65afea5d »
2009-09-08 apply grammer fixes from hanekomu
118 application. This may be an empty string if the request URL targets
ff0e6def »
2009-09-07 paragraphized
119 the application root and does not have a trailing slash. This value
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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</>).
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
123
124 =item *
125
c6d7946f »
2009-10-09 added REQUEST_URI to the PSGI spec
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
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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>.
c6d7946f »
2009-10-09 added REQUEST_URI to the PSGI spec
133
134 =item *
135
ff0e6def »
2009-09-07 paragraphized
136 C<QUERY_STRING>: The portion of the request URL that follows the C<?>,
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
137 if any. This key B<MAY> be empty, but B<MUST> always be present, even if empty.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
138
139 =item *
140
ff0e6def »
2009-09-07 paragraphized
141 C<SERVER_NAME>, C<SERVER_PORT>: When combined with C<SCRIPT_NAME> and
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
142 C<PATH_INFO>, these keys can be used to complete the URL. Note,
ff0e6def »
2009-09-07 paragraphized
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>
9170aac1 »
2010-01-06 lint pod
145 and C<SERVER_PORT> B<MUST NOT> be empty strings, and are always
ff0e6def »
2009-09-07 paragraphized
146 required.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
147
148 =item *
149
ff0e6def »
2009-09-07 paragraphized
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.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
154
155 =item *
156
575189dd »
2009-10-28 update CONTENT_LENGTH/CONTENT_TYPE existence
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.
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
160
161 =item *
162
575189dd »
2009-10-28 update CONTENT_LENGTH/CONTENT_TYPE existence
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.
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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
65afea5d »
2009-09-08 apply grammer fixes from hanekomu
171 correspond to the presence or absence of the appropriate HTTP header
ff0e6def »
2009-09-07 paragraphized
172 in the request.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
173
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
174 If there are multiple header lines sent with the same key, the server
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
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>.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
177
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
178 =back
179
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
180 In addition to the keys above, the PSGI environment B<MUST> also include these
181 PSGI-specific keys:
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
182
183 =over 4
184
185 =item *
186
1dc8a402 »
2010-01-18 upped psgi.version to [1,1]
187 C<psgi.version>: An array reference [1,1] representing this version of
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
188 PSGI. The first number is the major version and the second it the minor
189 version.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
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
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
197 C<psgi.input>: the input stream. See below for details.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
198
199 =item *
200
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
201 C<psgi.errors>: the error stream. See below for details.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
202
eee76555 »
2009-09-09 Added psgi.multithread and psgi.multiprocess per discussion on about …
203 =item *
204
9170aac1 »
2010-01-06 lint pod
205 C<psgi.multithread>: This is a boolean value, which B<MUST> be true if the
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
206 application may be simultaneously invoked by another thread in the same
207 process, false otherwise.
eee76555 »
2009-09-09 Added psgi.multithread and psgi.multiprocess per discussion on about …
208
209 =item *
210
9170aac1 »
2010-01-06 lint pod
211 C<psgi.multiprocess>: This is a boolean value, which B<MUST> be true if an
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
212 equivalent application object may be simultaneously invoked by another
213 process, false otherwise.
eee76555 »
2009-09-09 Added psgi.multithread and psgi.multiprocess per discussion on about …
214
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
215 =item *
216
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
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
ff0e6def »
2009-09-07 paragraphized
220 server based on CGI (or something similar).
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
221
222 =item *
223
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
224 C<psgi.nonblocking>: A boolean which is true if the server is calling the
225 application in an non-blocking event loop.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
226
667bda22 »
2009-10-21 Draft streaming response
227 =item *
228
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
229 C<psgi.streaming>: A boolean which is true if the server supports callback
230 style delayed response and streaming writer object.
667bda22 »
2009-10-21 Draft streaming response
231
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
232 =back
233
f43792eb »
2010-01-18 added psgix.logger and psgix.session
234 The server or the application can store its own data in the
235 environment as well. These keys B<MUST> contain at least one dot, and
236 B<SHOULD> be prefixed uniquely.
237
238 The C<psgi.> prefix is reserved for use with the PSGI core
239 specification, and C<psgix.> prefix is reserved for officially blessed
240 extensions. These prefixes B<MUST NOT> be used by other servers or
f9641b1f »
2011-06-16 move extensions to PSGI::Extentions
241 application. See L<psgi-extensions|PSGI::Extentions> for the list of
242 officially approved extentions.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
243
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
244 The environment B<MUST NOT> contain keys named C<HTTP_CONTENT_TYPE> or
245 C<HTTP_CONTENT_LENGTH>.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
246
4bf74c0b »
2010-01-28 "PATH_INFO should be '/' when SCRIPT_NAME is empty" is only valid when
247 One of C<SCRIPT_NAME> or C<PATH_INFO> B<MUST> be set. When
248 C<REQUEST_URI> is C</>, C<PATH_INFO> should be C</> and C<SCRIPT_NAME>
249 should be empty. C<SCRIPT_NAME> B<MUST NOT> be C</>, but B<MAY> be
250 empty.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
251
252 =head3 The Input Stream
253
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
254 The input stream in C<psgi.input> is an L<IO::Handle>-like object which
ff0e6def »
2009-09-07 paragraphized
255 streams the raw HTTP POST or PUT data. If it is a file handle then it
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
256 B<MUST> be opened in binary mode. The input stream B<MUST> respond to
257 C<read> and B<MAY> implement C<seek>.
258
259 Perl's built-in filehandles or L<IO::Handle> based objects should work as-is
260 in a PSGI server. Application developers B<SHOULD NOT> inspect the type or
261 class of the stream. Instead, they B<SHOULD> simply call C<read> on the object.
262
263 Application developers B<SHOULD NOT> use Perl's built-in C<read> or iterator
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
264 (C<< <$fh> >>) to read from the input stream. Instead, application
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
265 developers should call C<read> as a method (C<< $fh->read >>) to allow for
266 duck typing.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
267
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
268 Framework developers, if they know the input stream will be used with the
269 built-in read() in any upstream code they can't touch, B<SHOULD> use PerlIO or
270 a tied handle to work around with this problem.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
271
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
272 The input stream objet is expected to provide a C<read> method:
e764e4f8 »
2009-09-07 Added a note about read() built-in
273
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
274 =over 4
275
276 =item read
277
278 $input->read($buf, $len [, $offset ]);
279
a87c2634 »
2009-10-04 mentions return value of psgi.input and psgi.errors methods
280 Returns the number of characters actually read, 0 at end of file, or
281 undef if there was an error.
282
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
283 =back
284
dc1543ba »
2011-05-01 psgi.input MUST have seek() when psgix.input.buffered is true
285 It may also implement an optional C<seek> method. If
286 C<psgix.input.buffered> environment is true, it <MUST> implement the
287 C<seek> method.
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
288
289 =over 4
290
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
291 =item seek
292
293 $input->seek($pos, $whence);
294
a87c2634 »
2009-10-04 mentions return value of psgi.input and psgi.errors methods
295 Returns 1 on success, 0 otherwise.
296
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
297 =back
298
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
299 See the L<IO::Handle> documentation for more details on exactly how these
300 methods should work.
301
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
302 =head3 The Error Stream
303
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
304 The error stream in C<psgi.errors> is an L<IO::Handle>-like object to
305 print errors. The error stream must implement a C<print> method.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
306
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
307 As with the input stream, Perl's built-in filehandles or L<IO::Handle> based
308 objects should work as-is in a PSGI server. Application developers B<SHOULD
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
309 NOT> inspect the type or class of the stream. Instead, they B<SHOULD> simply
310 call C<print> on the object.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
311
312 =over 4
313
314 =item print
315
316 $errors->print($error);
317
a87c2634 »
2009-10-04 mentions return value of psgi.input and psgi.errors methods
318 Returns true if successful.
319
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
320 =back
321
322 =head3 The Response
323
f745e834 »
2010-01-06 array or code ref. That is MUST per PSGI spec POV. If you return some…
324 Applications B<MUST> return a response as either a three element array
325 reference, or a code reference for a delayed/streaming response.
0d57abbf »
2009-10-21 some wording fixes
326
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
327 The response array reference consists of the following elements:
667bda22 »
2009-10-21 Draft streaming response
328
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
329 =head4 Status
330
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
331 An HTTP status code. This B<MUST> be an integer greater than or equal to 100,
332 and B<SHOULD> be an HTTP status code as documented in L<RFC
333 2616|http://www.w3.org/Protocols/rfc2616>.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
334
335 =head4 Headers
336
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
337 The headers B<MUST> be an array reference (B<not> a hash reference)
338 of key/value pairs. This means it B<MUST> contain an even number of elements.
339
1641d76c »
2010-05-12 typo
340 The header B<MUST NOT> contain a key named C<Status>, nor any keys with C<:>
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
341 or newlines in their name. It B<MUST NOT> contain any keys that end in C<-> or
342 C<_>.
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
343
ee917ff6 »
2011-06-07 Fixed a stupid mistake where I copied "Characterd below 037" from Rac…
344 All keys B<MUST> consist only of letters, digits, C<_> or C<->. All
345 keys B<MUST> start with a letter. The value of the header must be a
346 scalar string. The value string B<MUST NOT> contain characters below
ff2bb214 »
2011-06-07 cleanup
347 octal 037 i.e. chr(31).
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
348
ff0e6def »
2009-09-07 paragraphized
349 If the same key name appears multiple times in an array ref, those
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
350 header lines B<MUST> be sent to the client separately (e.g. multiple
ff0e6def »
2009-09-07 paragraphized
351 C<Set-Cookie> lines).
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
352
353 =head4 Content-Type
354
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
355 There B<MUST> be a C<Content-Type> except when the C<Status> is 1xx, 204
356 or 304, in which case there B<MUST NOT> be a content type.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
357
358 =head4 Content-Length
359
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
360 There B<MUST NOT> be a C<Content-Length> header when the C<Status> is
ff0e6def »
2009-09-07 paragraphized
361 1xx, 204 or 304.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
362
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
363 If the Status is not 1xx, 204 or 304 and there is no C<Content-Length> header,
364 a PSGI server B<MAY> calculate the content length by looking at the Body. This
365 value can then be appended to the list of headers returned by the application.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
366
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
367 =head4 Body
368
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
369 The response body B<MUST> be returned from the application as either an array
370 reference or a handle.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
371
372 =over 4
373
374 =item *
375
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
376 If the body is an array reference, it is expected to contain an array of lines
377 which make up the body.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
378
379 my $body = [ "Hello\n", "World\n" ];
380
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
381 Note that the elements in an array reference are B<NOT REQUIRED> to end
382 in a newline. A server B<SHOULD> write each elements as-is to the
383 client, and B<SHOULD NOT> care if the line ends with newline or not.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
384
6342aa0b »
2009-10-28 change the variable name to be less confusing
385 An array reference with a single value is valid. So C<[ $html ]> is a valid
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
386 response body.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
387
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
388 =item *
389
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
390 The body can instead be a handle, either a Perl built-in filehandle or an
391 L<IO::Handle>-like object.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
392
393 open my $body, "</path/to/file";
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
394 open my $body, "<:via(SomePerlIO)", ...;
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
395 my $body = IO::File->new("/path/to/file");
396
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
397 my $body = SomeClass->new(); # mock class that implements getline() and close()
398
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
399 Servers B<SHOULD NOT> check the type or class of the body. Instead, they should
400 simply call C<getline> to iterate over the body, and
0e5b33e0 »
2009-10-07 Updated spec: body can respond ->path.
401 call C<close> when done.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
402
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
403 Servers B<MAY> check if the body is a real filehandle using C<fileno> and
404 C<Scalar::Util::reftype>. If the body is real filehandle, the server B<MAY>
405 optimize using techniques like I<sendfile(2)>.
406
407 The body object B<MAY> also respond to a C<path> method. This method is
408 expected to return the path to a file accessible by the server. This allows
409 the server to use this information instead of a file descriptor number to
e0431ced »
2009-11-08 make PSGI app a code ref
410 serve the file.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
411
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
412 Servers B<SHOULD> set the C<$/> special variable to the buffer size when
413 reading content from C<$body> using the C<getline> method. This is done by
414 setting C<$/> with a reference to an integer (C<$/ = \8192>).
0e5b33e0 »
2009-10-07 Updated spec: body can respond ->path.
415
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
416 If the body filehandle is a Perl built-in filehandle L<IO::Handle> object,
417 they will respect this value. Similarly, an object which provides the same API
418 B<MAY> also respect this special variable, but are not required to do so.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
419
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
420 =back
421
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
422 =head2 Delayed Response and Streaming Body
667bda22 »
2009-10-21 Draft streaming response
423
c5aa24f2 »
2010-01-06 psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
424 The PSGI interface allows applications and servers to provide a
425 callback-style response instead of the three-element array
426 reference. This allows for a delayed response and a streaming body
427 (server push).
428
429 This interface B<SHOULD> be implemented by PSGI servers, and
430 C<psgi.streaming> environment B<MUST> be set to true in such servers.
667bda22 »
2009-10-21 Draft streaming response
431
c5aa24f2 »
2010-01-06 psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
432 To enable a delayed response, the application B<SHOULD> return a
5589b649 »
2010-01-06 Some linting, and fixed wrong FAQ explanation about streaming/nonbloc…
433 callback as its response. An application B<MAY> check if the
c5aa24f2 »
2010-01-06 psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
434 C<psgi.streaming> environment is true and falls back to the direct
435 response if it isn't.
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
436
437 This callback will be called with I<another> subroutine reference (referred to
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
438 as the I<responder> from now on) as its only argument. The I<responder>
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
439 should in turn be called with the standard three element array reference
440 response. This is best illustrated with an example:
667bda22 »
2009-10-21 Draft streaming response
441
442 my $app = sub {
443 my $env = shift;
444
445 # Delays response until it fetches content from the network
446 return sub {
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
447 my $responder = shift;
448
c5aa24f2 »
2010-01-06 psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
449 fetch_content_from_server(sub {
450 my $content = shift;
451 $responder->([ 200, $headers, [ $content ] ]);
452 });
667bda22 »
2009-10-21 Draft streaming response
453 };
454 };
455
c5aa24f2 »
2010-01-06 psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.
456 An application B<MAY> omit the third element (the body) when calling
457 the I<responder>. If the body is omitted, the I<responder> B<MUST>
458 return I<yet another> object which implements C<write> and C<close>
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
459 methods. Again, an example illustrates this best.
667bda22 »
2009-10-21 Draft streaming response
460
461 my $app = sub {
462 my $env = shift;
463
464 # immediately starts the response and stream the content
465 return sub {
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
466 my $responder = shift;
467 my $writer = $responder->([ 200, [ 'Content-Type', 'application/json' ]]);
667bda22 »
2009-10-21 Draft streaming response
468
469 wait_for_events(sub {
470 my $new_event = shift;
471 if ($new_event) {
472 $writer->write($new_event->as_json . "\n");
473 } else {
474 $writer->close;
475 }
476 });
477 };
478 };
479
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
480 This delayed response and streaming API is useful if you want to
481 implement a non-blocking I/O based server streaming or long-poll Comet
5589b649 »
2010-01-06 Some linting, and fixed wrong FAQ explanation about streaming/nonbloc…
482 push technology, but could also be used to implement unbuffered writes
483 in a blocking server.
667bda22 »
2009-10-21 Draft streaming response
484
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
485 =head2 Middleware
486
b4d5be27 »
2009-10-27 Various tweaks from discussion with miyagawa in #psgi, and line-wrapp…
487 A I<middleware> component takes another PSGI application and runs it. From the
488 perspective of a server, a middleware component is a PSGI application. From
489 the perspective of the application being run by the middleware component, the
490 middleware is the server. Generally, this will be done in order to implement
491 some sort of pre-processing on the PSGI environment hash or post-processing on
492 the response.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
493
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
494 Here's a simple example that appends a special HTTP header
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
495 I<X-PSGI-Used> to any PSGI application.
496
497 # $app is a simple PSGI application
498 my $app = sub {
499 my $env = shift;
500 return [ '200', [ 'Content-Type' => 'text/plain' ], [ "Hello World" ] ];
501 };
502
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
503 # $xheader is a piece of middleware that wraps $app
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
504 my $xheader = sub {
505 my $env = shift;
506 my $res = $app->($env);
507 push @{$res->[1]}, 'X-PSGI-Used' => 1;
508 return $res;
509 };
510
3e2dde3c »
2009-10-27 English cleanup, rewriting parts for clarity, adding links, and small…
511 Middleware B<MUST> behave exactly like a PSGI application from the perspective
512 of a server. Middleware B<MAY> decide not to support the streaming interface
513 discussed earlier, but B<SHOULD> pass through the response types that it doesn't
514 understand.
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
515
38d724bf »
2010-01-18 Promote psgi.streaming, nonblocking and run_once keys to be MUST.
516 =head1 CHANGELOGS
517
518 1.1: 2010.02.xx
519
520 =over 4
521
522 =item *
523
f43792eb »
2010-01-18 added psgix.logger and psgix.session
524 Added optional PSGI keys as extensions: C<psgix.logger> and C<psgix.session>.
525
526 =item *
527
38d724bf »
2010-01-18 Promote psgi.streaming, nonblocking and run_once keys to be MUST.
528 C<psgi.streaming> B<SHOULD> be implemented by PSGI servers, rather than B<MAY>.
529
530 =item *
531
532 PSGI keys C<psgi.run_once>, C<psgi.nonblocking> and C<psgi.streaming>
533 B<MUST> be set by PSGI servers.
534
535 =item *
536
537 Removed C<poll_cb> from writer methods.
538
539 =back
540
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
541 =head1 ACKNOWLEDGEMENTS
542
543 Some parts of this specification are adopted from the following specifications.
544
545 =over 4
546
547 =item *
548
549 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
550
551 =item *
552
553 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
554
555 =item *
556
557 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
558
559 =back
560
561 I'd like to thank authors of these great documents.
562
563 =head1 AUTHOR
564
565 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
566
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
567 =head1 CONTRIBUTORS
568
569 The following people have contributed to the PSGI specification and
570 Plack implementation by commiting their code, sending patches,
571 reporting bugs, asking questions, suggesting useful advices,
572 nitpicking, chatting on IRC or commenting on my blog (in no particular
573 order):
574
575 Tokuhiro Matsuno
576 Kazuhiro Osawa
577 Yuval Kogman
578 Kazuho Oku
579 Alexis Sukrieh
048f9a3f »
2009-09-30 update Dann's name. README links to the site
580 Takatoshi Kitano
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
581 Stevan Little
582 Daisuke Murase
583 mala
584 Pedro Melo
585 Jesse Luehrs
586 John Beppu
587 Shawn M Moore
588 Mark Stosberg
589 Matt S Trout
590 Jesse Vincent
591 Chia-liang Kao
592 Dave Rolsky
593 Hans Dieter Pearcey
594 Randy J Ray
595 Benjamin Trott
596 Max Maischein
597 Slaven Rezić
598 Marcel Grünauer
599 Masayoshi Sekimura
600 Brock Wilcox
601 Piers Cawley
ecdb6c01 »
2009-09-16 added some HTTP::Engine contributors
602 Daisuke Maki
603 Kang-min Liu
2b08fe38 »
2009-10-07 oops
604 Yasuhiro Matsumoto
5623139b »
2009-09-23 changed the Content-Length from SHOULD to MAY
605 Ash Berlin
31284b9c »
2009-09-29 Added Artur for his advice around gearman/schwartz
606 Artur Bergman
ba2001a8 »
2009-10-01 more questions around HTTP::Engine confusions
607 Simon Cozens
608 Scott McWhirter
a87c2634 »
2009-10-04 mentions return value of psgi.input and psgi.errors methods
609 Jiro Nishiguchi
01b3c476 »
2009-10-07 Sorry!
610 Masahiro Chiba
1ef1c9c2 »
2009-10-12 Added patspam for his webgui work
611 Patrick Donelan
d7fc7bbe »
2009-10-15 Added frodwith for helping us sort out the non-blocking from POE deve…
612 Paul Driver
93432fb2 »
2010-01-11 Added rafl
613 Florian Ragwitz
1173dc05 »
2009-09-16 New spec: feedbacks got merged.
614
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
615 =head1 COPYRIGHT AND LICENSE
616
f9641b1f »
2011-06-16 move extensions to PSGI::Extentions
617 Copyright Tatsuhiko Miyagawa, 2009-2011.
e85dbb3b »
2009-09-07 First draft of the PSGI spec and FAQ.
618
619 This document is licensed under the Creative Commons license by-sa.
620
621 =cut
Something went wrong with that request. Please try again.