Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 330 lines (209 sloc) 8.912 kB
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
1 =head1 NAME
2
3 PSGI - Perl Web Server Gateway Interface Specification
4
5 =head1 ABSTRACT
6
ff0e6de @miyagawa paragraphized
miyagawa authored
7 This document specifies a standard interface between web servers and
8 Perl web applications or frameworks, to promote web application
9 portability and reduce the duplicated efforts by web application
10 framework developers.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
11
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored
12 Keep in mind that PSGI is not Yet Another web application
13 framework. PSGI is a specification to decouple web server environments
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
14 from web application framework code. PSGI is also not the web
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored
15 application API. Web application developers (end users) are not
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
16 supposed to run their web applications directly using the PSGI
17 interface, but instead are encouraged to use frameworks that
18 support PSGI, or use the helper implementations like Plack (more on
19 that later).
0f6003f @miyagawa Added a note that PSGI is not an API for end users
miyagawa authored
20
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
21 =head1 SPECIFICATION
22
23 =head2 Applications
24
ff0e6de @miyagawa paragraphized
miyagawa authored
25 A PSGI application is a Perl code reference. It takes exactly one
26 argument, the environment and returns an array reference of exactly
27 three values.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
28
29 sub app {
30 my $env = shift;
31 return [
32 '200',
33 [ 'Content-Type' => 'text/plain' ],
31bd78b @miyagawa s/objects/object/ because it sounded like an array of IO::Handle objects
miyagawa authored
34 [ "Hello World" ], # or IO::Handle-like object
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
35 ];
36 }
37
38 =head3 The Environment
39
ff0e6de @miyagawa paragraphized
miyagawa authored
40 The environment MUST be a hash reference that includes CGI-like
41 headers. The application is free to modify the environment. The
42 environment is required to include these variables (adopted from
43 PEP333, Rack and JSGI) except when they'd be empty, but see below:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
44
45 =over 4
46
47 =item *
48
ff0e6de @miyagawa paragraphized
miyagawa authored
49 C<REQUEST_METHOD>: The HTTP request method, such as "GET" or
50 "POST". This cannot ever be an empty string, and so is always
51 required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
52
53 =item *
54
ff0e6de @miyagawa paragraphized
miyagawa authored
55 C<SCRIPT_NAME>: The initial portion of the request URL's I<path> that
56 corresponds to the application, so that the application knows its
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
57 virtual "location". This may be an empty string if the application
ff0e6de @miyagawa paragraphized
miyagawa authored
58 corresponds to the "root" of the server.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
59
60 =item *
61
ff0e6de @miyagawa paragraphized
miyagawa authored
62 C<PATH_INFO>: The remainder of the request URL's "path", designating
63 the virtual "location" of the request's target within the
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
64 application. This may be an empty string if the request URL targets
ff0e6de @miyagawa paragraphized
miyagawa authored
65 the application root and does not have a trailing slash. This value
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
66 may be percent-encoded when it originates from a URL.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
67
68 =item *
69
ff0e6de @miyagawa paragraphized
miyagawa authored
70 C<QUERY_STRING>: The portion of the request URL that follows the C<?>,
71 if any. May be empty, but is always required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
72
73 =item *
74
ff0e6de @miyagawa paragraphized
miyagawa authored
75 C<SERVER_NAME>, C<SERVER_PORT>: When combined with C<SCRIPT_NAME> and
76 C<PATH_INFO>, these variables can be used to complete the URL. Note,
77 however, that C<HTTP_HOST>, if present, should be used in preference
78 to C<SERVER_NAME> for reconstructing the request URL. C<SERVER_NAME>
79 and C<SERVER_PORT> can never be empty strings, and so are always
80 required.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
81
82 =item *
83
ff0e6de @miyagawa paragraphized
miyagawa authored
84 C<SERVER_PROTOCOL>: The version of the protocol the client used to
85 send the request. Typically this will be something like "HTTP/1.0" or
86 "HTTP/1.1" and may be used by the application to determine how to
87 treat any HTTP request headers.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
88
89 =item *
90
ff0e6de @miyagawa paragraphized
miyagawa authored
91 C<HTTP_> Variables: Variables corresponding to the client-supplied
92 HTTP request headers (i.e., variables whose names begin with
93 C<HTTP_>). The presence or absence of these variables should
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
94 correspond to the presence or absence of the appropriate HTTP header
ff0e6de @miyagawa paragraphized
miyagawa authored
95 in the request.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
96
97 =back
98
ff0e6de @miyagawa paragraphized
miyagawa authored
99 In addition to this, the PSGI environment MUST include these
100 PSGI-specific variables:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
101
102 =over 4
103
104 =item *
105
106 C<psgi.version>: An array ref [1,0] representing this version of PSGI.
107
108 =item *
109
110 C<psgi.url_scheme>: A string C<http> or C<https>, depending on the request URL.
111
112 =item *
113
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
114 C<psgi.input>: the input stream. See below.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
115
116 =item *
117
118 C<psgi.errors>: the error stream. See below.
119
120 =back
121
122 The PSGI environment MAY include these optional PSGI variables:
123
124 =over 4
125
126 =item *
127
ff0e6de @miyagawa paragraphized
miyagawa authored
128 C<psgi.run_once>: true if the server expects (but does not guarantee!)
129 that the application will only be invoked this one time during the
130 life of its containing process. Normally, this will only be true for a
131 server based on CGI (or something similar).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
132
133 =item *
134
ff0e6de @miyagawa paragraphized
miyagawa authored
135 C<psgi.async>: true if the server is calling the application in an
136 asynchronous event loop. See L<PSGI Async extension|PSGI::Async>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
137
138 =back
139
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
140 The server or the application can store its own data in the
ff0e6de @miyagawa paragraphized
miyagawa authored
141 environment, too. The keys MUST contain at least one dot, and should
142 be prefixed uniquely. The prefix C<psgi.> is reserved for use with the
143 PSGI core implementation and other accepted extensions and MUST NOT be
144 used otherwise. The environment MUST NOT contain the keys
145 C<HTTP_CONTENT_TYPE> or C<HTTP_CONTENT_LENGTH> (use the versions
146 without C<HTTP_>). The CGI keys (named without a period) MUST have a
147 scalar variable containing strings. There are the following
148 restrictions:
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
149
150 =over 4
151
152 =item *
153
154 C<psgi.version> MUST be an array of integers.
155
156 =item *
157
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
158 C<psgi.url_scheme> MUST be a scalar variable containing either the
ff0e6de @miyagawa paragraphized
miyagawa authored
159 string C<http> or C<https>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
160
161 =item *
162
163 There MUST be a valid input stream in C<psgi.input>.
164
165 =item *
166
167 There MUST be a valid error stream in C<psgi.errors>.
168
169 =item *
170
171 The C<REQUEST_METHOD> MUST be a valid token.
172
173 =item *
174
175 The C<SCRIPT_NAME>, if non-empty, MUST start with C</>
176
177 =item *
178
179 The C<PATH_INFO>, if non-empty, MUST start with C</>
180
181 =item *
182
183 The C<CONTENT_LENGTH>, if given, MUST consist of digits only.
184
185 =item *
186
ff0e6de @miyagawa paragraphized
miyagawa authored
187 One of C<SCRIPT_NAME> or C<PATH_INFO> MUST be set. C<PATH_INFO> should
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
188 be C</> if C<SCRIPT_NAME> is empty. C<SCRIPT_NAME> should never be C</>,
189 but should instead be empty.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
190
191 =back
192
193 =head3 The Input Stream
194
ff0e6de @miyagawa paragraphized
miyagawa authored
195 The input stream in C<psgi.input> is an IO::Handle-like object which
196 streams the raw HTTP POST or PUT data. If it is a file handle then it
197 MUST be opened in binary mode. The input stream MUST respond to
198 C<read> and MAY implement C<seek>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
199
ff0e6de @miyagawa paragraphized
miyagawa authored
200 The built-in filehandle or IO::Handle based objects should work fine
201 everywhere. Application developers SHOULD NOT inspect the type or
202 class of the stream, but instead just call C<read> to duck type.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
203
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored
204 Application developers SHOULD NOT use the built-in C<read> function to
205 read from the input stream, because C<read> function only works with
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
206 the real IO object (a glob ref based file handle or PerlIO) and makes
207 duck typing difficult. Web application framework developers, if
208 they know the input stream will be used with the built-in read() in any
d36f900 @miyagawa web framework should deal with this IO thing
miyagawa authored
209 upstream code they can't touch, SHOULD use PerlIO or tie handle to
210 work around with this problem.
e764e4f @miyagawa Added a note about read() built-in
miyagawa authored
211
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
212 =over 4
213
214 =item read
215
216 $input->read($buf, $len [, $offset ]);
217
218 =item seek
219
220 $input->seek($pos, $whence);
221
222 =back
223
224 =head3 The Error Stream
225
ff0e6de @miyagawa paragraphized
miyagawa authored
226 The error stream in C<psgi.errors> is an IO::Handle-like object to
227 print errors. The error stream must implement C<print>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
228
ff0e6de @miyagawa paragraphized
miyagawa authored
229 The built-in filehandle or IO::Handle based objects should work fine
230 everywhere. Application developers SHOULD NOT inspect the type or
231 class of the stream, but instead just call C<print> to duck type.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
232
233 =over 4
234
235 =item print
236
237 $errors->print($error);
238
239 =back
240
241 =head3 The Response
242
243 =head4 Status
244
245 HTTP status code, is an integer and MUST be greater than or equal to 100.
246
247 =head4 Headers
248
79b722f @miyagawa clarified it's not a hash ref
miyagawa authored
249 The headers must be an array reference (and NOT a hash reference!)
250 containing key and value pairs. Its number of elements MUST be
251 even. The header MUST NOT contain a C<Status> key, contain keys with
252 C<:> or newlines in their name, contain keys that end in C<-> or C<_>
253 but only contain keys that consist of letters, digits, C<_> or C<->
254 and start with a letter. The value of the header must be a scalar
255 value that contain a string. The value string MUST NOT contain
256 characters below chr(37).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
257
ff0e6de @miyagawa paragraphized
miyagawa authored
258 If the same key name appears multiple times in an array ref, those
259 header lines MUST be sent to the client separately (e.g. multiple
260 C<Set-Cookie> lines).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
261
262 =head4 Content-Type
263
ff0e6de @miyagawa paragraphized
miyagawa authored
264 There MUST be a C<Content-Type> except when the C<Status> is 1xx, 204
265 or 304, in which case there MUST be none given.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
266
267 =head4 Content-Length
268
ff0e6de @miyagawa paragraphized
miyagawa authored
269 There MUST NOT be a C<Content-Length> header when the C<Status> is
270 1xx, 204 or 304.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
271
272 =head4 Body
273
ff0e6de @miyagawa paragraphized
miyagawa authored
274 The response body is returned from the application in one of following
275 two types of scalar variable.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
276
277 =over 4
278
279 =item *
280
281 An array reference containing body as lines.
282
283 my $body = [ "Hello\n", "World\n" ];
284
285 =item *
286
287 An IO::Handle-like object or a built-in filehandle.
288
289 open my $body, "</path/to/file";
290 my $body = IO::File->new("/path/to/file");
291
65afea5 @miyagawa apply grammer fixes from hanekomu
miyagawa authored
292 Implementors SHOULD NOT check the type or class of the body but instead
293 just call C<getline> to iterate over the body and call C<close> when done.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
294
295 =back
296
297 =head1 ACKNOWLEDGEMENTS
298
299 Some parts of this specification are adopted from the following specifications.
300
301 =over 4
302
303 =item *
304
305 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
306
307 =item *
308
309 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
310
311 =item *
312
313 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
314
315 =back
316
317 I'd like to thank authors of these great documents.
318
319 =head1 AUTHOR
320
321 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
322
323 =head1 COPYRIGHT AND LICENSE
324
325 Copyright Tatsuhiko Miyagawa, 2009.
326
327 This document is licensed under the Creative Commons license by-sa.
328
329 =cut
Something went wrong with that request. Please try again.