Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 312 lines (193 sloc) 7.965 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
195 =over 4
196
197 =item read
198
199 $input->read($buf, $len [, $offset ]);
200
201 =item seek
202
203 $input->seek($pos, $whence);
204
205 =back
206
207 =head3 The Error Stream
208
ff0e6de @miyagawa paragraphized
miyagawa authored
209 The error stream in C<psgi.errors> is an IO::Handle-like object to
210 print errors. The error stream must implement C<print>.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
211
ff0e6de @miyagawa paragraphized
miyagawa authored
212 The built-in filehandle or IO::Handle based objects should work fine
213 everywhere. Application developers SHOULD NOT inspect the type or
214 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
215
216 =over 4
217
218 =item print
219
220 $errors->print($error);
221
222 =back
223
224 =head3 The Response
225
226 =head4 Status
227
228 HTTP status code, is an integer and MUST be greater than or equal to 100.
229
230 =head4 Headers
231
ff0e6de @miyagawa paragraphized
miyagawa authored
232 The header must be an array reference containing a pair of key and
233 value. Its number of elements MUST be even. The header MUST NOT
234 contain a C<Status> key, contain keys with C<:> or newlines in their
235 name, contain keys that end in C<-> or C<_> but only contain keys that
236 consist of letters, digits, C<_> or C<-> and start with a letter. The
237 value of the header must be a scalar value that contains strings. The
238 value string MUST NOT contain characters below chr(37).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
239
ff0e6de @miyagawa paragraphized
miyagawa authored
240 If the same key name appears multiple times in an array ref, those
241 header lines MUST be sent to the client separately (e.g. multiple
242 C<Set-Cookie> lines).
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
243
244 =head4 Content-Type
245
ff0e6de @miyagawa paragraphized
miyagawa authored
246 There MUST be a C<Content-Type> except when the C<Status> is 1xx, 204
247 or 304, in which case there MUST be none given.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
248
249 =head4 Content-Length
250
ff0e6de @miyagawa paragraphized
miyagawa authored
251 There MUST NOT be a C<Content-Length> header when the C<Status> is
252 1xx, 204 or 304.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
253
254 =head4 Body
255
ff0e6de @miyagawa paragraphized
miyagawa authored
256 The response body is returned from the application in one of following
257 two types of scalar variable.
e85dbb3 @miyagawa First draft of the PSGI spec and FAQ.
miyagawa authored
258
259 =over 4
260
261 =item *
262
263 An array reference containing body as lines.
264
265 my $body = [ "Hello\n", "World\n" ];
266
267 =item *
268
269 An IO::Handle-like object or a built-in filehandle.
270
271 open my $body, "</path/to/file";
272 my $body = IO::File->new("/path/to/file");
273
ff0e6de @miyagawa paragraphized
miyagawa authored
274 Implementors SHOULD NOT check if the type or class of body but instead
275 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
276
277 =back
278
279 =head1 ACKNOWLEDGEMENTS
280
281 Some parts of this specification are adopted from the following specifications.
282
283 =over 4
284
285 =item *
286
287 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
288
289 =item *
290
291 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
292
293 =item *
294
295 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
296
297 =back
298
299 I'd like to thank authors of these great documents.
300
301 =head1 AUTHOR
302
303 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
304
305 =head1 COPYRIGHT AND LICENSE
306
307 Copyright Tatsuhiko Miyagawa, 2009.
308
309 This document is licensed under the Creative Commons license by-sa.
310
311 =cut
Something went wrong with that request. Please try again.