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