Skip to content

HTTPS clone URL

Subversion checkout URL

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