@@ -7,28 +7,27 @@ PSGI - Perl Web Server Gateway Interface Specification =head1 ABSTRACT This document specifies a standard interface between web servers and -Perl web applications or frameworks, to promote web application -portability and reduce the duplicated efforts by web application +Perl web applications or frameworks. This interface is designed to promote web application +portability and reduce the duplication of effort by web application framework developers. -Keep in mind that PSGI is not Yet Another web application +Please keep in mind that PSGI is not Yet Another web application framework. PSGI is a specification to decouple web server environments -from web application framework code. PSGI is also not the web -application API. Web application developers (end users) are not -supposed to run their web applications directly using the PSGI +from web application framework code. Nor is PSGI is a web +application API. Web application developers (end users) will not +run their web applications directly using the PSGI interface, but instead are encouraged to use frameworks that -support PSGI, or use the helper implementations like Plack (more on -that later). +support PSGI. There is also a reference PSGI implementation called Plack. -=head1 TERMINOLOGIES +=head1 TERMINOLOGY =over 4 =item Servers -Servers are web servers that accept HTTP requests, dispatch the -requests to the web applications and return the HTTP response to the -clients. In PSGI specification it's a Perl process that's running +A I<Server> is a web server that accepts HTTP requests, dispatches the +request to web applications, and returns the HTTP response to the +client. In the context of PSGI the server could be a Perl process running inside an HTTP server (e.g. mod_perl in Apache), a daemon process called from a web server (e.g. FastCGI daemon) or a pure perl HTTP server. @@ -38,35 +37,36 @@ I<Backends>. =item Applications -Applications are web applications that actually get HTTP requests -and return HTTP response. In PSGI it's a code reference: see below. +I<Applications> are web applications that accept an HTTP request +and return an HTTP response. In PSGI an application is a code reference. =item Middleware -Middleware is a PSGI application, which is a code reference, but also -runs like a server to run other applications. It can be thought of a -I<plugin> to extend PSGI application: see below. +I<Middleware> is a PSGI application (a code reference) I<and> a +I<Server>. I<Middleware> looks like an I<application> when called from a +I<server>, and it in turn can call other I<applications>. It can be thought of +a I<plugin> to extend a PSGI application. =item Framework developers -Framework developers are authors of web application frameworks. They -need to write adapters (or engines) to read PSGI input, then run the -application logic and returns PSGI response to the server. +I<Framework developers> are the authors of web application frameworks. They +write adapters (or engines) which accept PSGI input, run a web +application, and return a PSGI response to the I<server>. =item Web application developers -Web application developers are developers who write code that uses one -of the web application framework that uses PSGI interface. They -usually don't need to deal with nor care about PSGI protocol at all. +I<Web application developers> are developers who write code on top of a web +application framework. These developers should never have to deal with PSGI +directly. =back =head1 SPECIFICATION -=head2 Applications +=head2 Application A PSGI application is a Perl code reference. It takes exactly one -argument, the environment and returns an array reference of exactly +argument, the environment, and returns an array reference containing exactly three values. sub app { @@ -80,33 +80,50 @@ three values. =head3 The Environment -The environment MUST be a hash reference that includes CGI-like -headers. The application is free to modify the environment. The -environment is required to include these variables (adopted from -PEP333, Rack and JSGI) except when they'd be empty, but see below: +The environment B<MUST> be a hash reference that includes CGI-like headers, as +detailed below. The application is free to modify the environment. The +environment B<MUST> include these keys (adopted from L<PEP +333|http://www.python.org/dev/peps/pep-0333/>, +L<Rack|http://rack.rubyforge.org/doc/files/SPEC.html> and +L<JSGI|http://jackjs.org/jsgi-spec.html>) except when they would normally be +empty. + +When an environment key is described as a boolean, itss value B<MUST> conform +to Perl's notion of boolean-ness. These variables B<SHOULD> contain a C<0> or +C<1>. An empty value or the absence of a key B<MAY> also be used to indicate a +false value. + +The values for all CGI keys (named without a period) B<MUST> be a scalar +string except where otherwise specified. + +See below for details. =over 4 =item * C<REQUEST_METHOD>: The HTTP request method, such as "GET" or -"POST". This cannot ever be an empty string, and so is always +"POST". This B<MUST NOT> be an empty string, and so is always required. =item * -C<SCRIPT_NAME>: The initial portion of the request URL's I<path> that -corresponds to the application, so that the application knows its +C<SCRIPT_NAME>: The initial portion of the request URL's I<path>, +corresponding to the application. This tells the application its virtual "location". This may be an empty string if the application -corresponds to the "root" of the server. +corresponds to the server's root URI. + +If this key is not empty, it B<MUST> start with a forward slash (C</>). =item * -C<PATH_INFO>: The remainder of the request URL's "path", designating +C<PATH_INFO>: The remainder of the request URL's I<path>, designating the virtual "location" of the request's target within the application. This may be an empty string if the request URL targets the application root and does not have a trailing slash. This value -should be URI decoded by servers to be compatible to RFC 3875. +should be URI decoded by servers in order to be compatible with L<RFC 3875|http://www.ietf.org/rfc/rfc3875>. + +If this key is not empty, it B<MUST> start with a forward slash (C</>). =item * @@ -114,23 +131,22 @@ C<REQUEST_URI>: The undecoded, raw request URL line. It is the raw URI path and query part that appears in the HTTP C<GET /... HTTP/1.x> line and doesn't contain URI scheme and host names. -Unlike C<PATH_INFO>, this value SHOULD NOT be decoded by servers and -hence it is an application's responsibility to properly decode paths -to map URL to application handlers, when using C<REQUEST_URI> over -C<PATH_INFO>. +Unlike C<PATH_INFO>, this value B<SHOULD NOT> be decoded by servers. It is an +application's responsibility to properly decode paths in order to map URLs to +application handlers if they choose to use this key instead of C<PATH_INFO>. =item * C<QUERY_STRING>: The portion of the request URL that follows the C<?>, -if any. May be empty, but is always required. +if any. This key B<MAY> be empty, but B<MUST> always be present, even if empty. =item * C<SERVER_NAME>, C<SERVER_PORT>: When combined with C<SCRIPT_NAME> and -C<PATH_INFO>, these variables can be used to complete the URL. Note, +C<PATH_INFO>, these keys can be used to complete the URL. Note, however, that C<HTTP_HOST>, if present, should be used in preference to C<SERVER_NAME> for reconstructing the request URL. C<SERVER_NAME> -and C<SERVER_PORT> can never be empty strings, and so are always +and C<SERVER_PORT> I<MUST NOT> be empty strings, and are always required. =item * @@ -142,26 +158,35 @@ treat any HTTP request headers. =item * -C<HTTP_> Variables: Variables corresponding to the client-supplied -HTTP request headers (i.e., variables whose names begin with -C<HTTP_>). The presence or absence of these variables should +C<CONTENT_LENGTH>: The length of the content in bytes, as an integer. This key +B<MAY> be omitted. + +=item * + +C<CONTENT_TYPE>: The request's MIME type, as specified by the client. This key +B<MAY> be omitted. + +=item * + +C<HTTP_*> Keys: These keys correspond to the client-supplied +HTTP request headers. The presence or absence of these keys should correspond to the presence or absence of the appropriate HTTP header in the request. If there are multiple header lines sent with the same key, the server -should treat them as if they're sent in one line, i.e. combine them -with C<, > as in RFC 2616. +should treat them as if they were sent in one line and combine them +with C<, >, as in L<RFC 2616|http://www.ietf.org/rfc/rfc2616>. =back -In addition to this, the PSGI environment MUST include these -PSGI-specific variables: +In addition to the keys above, the PSGI environment B<MUST> also include these +PSGI-specific keys: =over 4 =item * -C<psgi.version>: An array ref [1,0] representing this version of PSGI. +C<psgi.version>: An array reference [1,0] representing this version of PSGI. The first number is the major version and the second it the minor version. =item * @@ -169,118 +194,83 @@ C<psgi.url_scheme>: A string C<http> or C<https>, depending on the request URL. =item * -C<psgi.input>: the input stream. See below. +C<psgi.input>: the input stream. See below for details. =item * -C<psgi.errors>: the error stream. See below. +C<psgi.errors>: the error stream. See below for details. =item * -C<psgi.multithread>: true if the application may be simultaneously +C<psgi.multithread>: This is a boolean value, which I<MUST> be true if the application may be simultaneously invoked by another thread in the same process, false otherwise. =item * -C<psgi.multiprocess>: true if an equivalent application object may be +C<psgi.multiprocess>: This is a boolean value, which I<MUST> be true if an equivalent application object may be simultaneously invoked by another process, false otherwise. =back -The PSGI environment MAY include these optional PSGI variables: +The PSGI environment B<MAY> also include these optional PSGI keys: =over 4 =item * -C<psgi.run_once>: true if the server expects (but does not guarantee!) +C<psgi.run_once>: A boolean which is true if the server expects (but does not guarantee!) that the application will only be invoked this one time during the life of its containing process. Normally, this will only be true for a server based on CGI (or something similar). =item * -C<psgi.nonblocking>: true if the server is calling the application in an +C<psgi.nonblocking>: A boolean which is true if the server is calling the application in an non-blocking event loop. =item * -C<psgi.streaming>: true if the server supports callback style delayed +C<psgi.streaming>: A boolean which is true if the server supports callback style delayed response and streaming writer object. =back The server or the application can store its own data in the -environment, too. The keys MUST contain at least one dot, and should -be prefixed uniquely. The prefix C<psgi.> is reserved for use with the -PSGI core implementation and other accepted extensions and MUST NOT be -used otherwise. The environment MUST NOT contain the keys -C<HTTP_CONTENT_TYPE> or C<HTTP_CONTENT_LENGTH> (use the versions -without C<HTTP_>). The CGI keys (named without a period) MUST have a -scalar variable containing strings. There are the following -restrictions: - -=over 4 - -=item * +environment as well. These keys B<MUST> contain at least one dot, and B<SHOULD> +be prefixed uniquely. The C<psgi.> prefix is reserved for use with the +PSGI core implementation and officially blessed extensions. This prefix B<MUST NOT> be +used by other servers or application. -C<psgi.version> MUST be an array of integers. - -=item * - -C<psgi.url_scheme> MUST be a scalar variable containing either the -string C<http> or C<https>. - -=item * - -There MUST be a valid input stream in C<psgi.input>. - -=item * - -There MUST be a valid error stream in C<psgi.errors>. - -=item * - -The C<REQUEST_METHOD> MUST be a valid token. - -=item * +The environment B<MUST NOT> contain keys named C<HTTP_CONTENT_TYPE> or +C<HTTP_CONTENT_LENGTH>. -The C<SCRIPT_NAME>, if non-empty, MUST start with C</> - -=item * - -The C<PATH_INFO>, if non-empty, MUST start with C</> - -=item * - -The C<CONTENT_LENGTH>, if given, MUST consist of digits only. - -=item * - -One of C<SCRIPT_NAME> or C<PATH_INFO> MUST be set. C<PATH_INFO> should -be C</> if C<SCRIPT_NAME> is empty. C<SCRIPT_NAME> should never be C</>, -but should instead be empty. +One of C<SCRIPT_NAME> or C<PATH_INFO> B<MUST> be set. C<PATH_INFO> should be +C</> if C<SCRIPT_NAME> is empty. C<SCRIPT_NAME> B<MUST NOT> be C</>, but +B<MAY> be empty. =back =head3 The Input Stream -The input stream in C<psgi.input> is an IO::Handle-like object which +The input stream in C<psgi.input> is an L<IO::Handle>-like object which streams the raw HTTP POST or PUT data. If it is a file handle then it -MUST be opened in binary mode. The input stream MUST respond to -C<read> and MAY implement C<seek>. +B<MUST> be opened in binary mode. The input stream B<MUST> respond to +C<read> and B<MAY> implement C<seek>. + +Perl's built-in filehandles or L<IO::Handle> based objects should work as-is +in a PSGI server. Application developers B<SHOULD NOT> inspect the type or +class of the stream. Instead, they B<SHOULD> simply call C<read> on the object. + +Application developers B<SHOULD NOT> use Perl's built-in C<read> or iterator +(C<< <$fh> >>) to read from the input stream, because. Instead, application +developers should call C<read> as a method (C<< $fh->read >>) to allow for +duck typing. -The built-in filehandle or IO::Handle based objects should work fine -everywhere. Application developers SHOULD NOT inspect the type or -class of the stream, but instead just call C<read> to duck type. +Framework developers, if they know the input stream will be used with the +built-in read() in any upstream code they can't touch, B<SHOULD> use PerlIO or +a tied handle to work around with this problem. -Application developers SHOULD NOT use the built-in C<read> function to -read from the input stream, because C<read> function only works with -the real IO object (a glob ref based file handle or PerlIO) and makes -duck typing difficult. Web application framework developers, if -they know the input stream will be used with the built-in read() in any -upstream code they can't touch, SHOULD use PerlIO or tie handle to -work around with this problem. +The input stream objet is expected to provide a C<read> method: =over 4 @@ -291,6 +281,12 @@ work around with this problem. Returns the number of characters actually read, 0 at end of file, or undef if there was an error. +=back + +It may also implement an optional C<seek> method. + +=over 4 + =item seek $input->seek($pos, $whence); @@ -299,14 +295,18 @@ Returns 1 on success, 0 otherwise. =back +See the L<IO::Handle> documentation for more details on exactly how these +methods should work. + =head3 The Error Stream -The error stream in C<psgi.errors> is an IO::Handle-like object to -print errors. The error stream must implement C<print>. +The error stream in C<psgi.errors> is an L<IO::Handle>-like object to +print errors. The error stream must implement a C<print> method. -The built-in filehandle or IO::Handle based objects should work fine -everywhere. Application developers SHOULD NOT inspect the type or -class of the stream, but instead just call C<print> to duck type. +As with the input stream, Perl's built-in filehandles or L<IO::Handle> based +objects should work as-is in a PSGI server. Application developers B<SHOULD +NOT> inspect the type or class of the stream. Instead, they B<SHOULD> simply call C<print> +on the object. =over 4 @@ -320,73 +320,74 @@ Returns true if successful. =head3 The Response -The response MUST be a three element array reference if the -application wants to directly return the HTTP response. +Applications B<MUST> return a response as a three element array reference. + +B<IF> the server supports the streaming (see below), an application B<MAY> +choose to return other type of responses such as a code reference to delay the +response. -An application MAY choose to return other type of responses such as a -code reference, to delay the response only if the server supports the -streaming (See below). +The response array reference consists of the following elements: =head4 Status -HTTP status code, is an integer and MUST be greater than or equal to 100. +An HTTP status code. This B<MUST> be an integer greater than or equal to 100, +and B<SHOULD> be an HTTP status code as documented in L<RFC +2616|http://www.w3.org/Protocols/rfc2616>. =head4 Headers -The headers must be an array reference (and NOT a hash reference!) -containing key and value pairs. Its number of elements MUST be -even. The header MUST NOT contain a C<Status> key, contain keys with -C<:> or newlines in their name, contain keys that end in C<-> or C<_> -but only contain keys that consist of letters, digits, C<_> or C<-> -and start with a letter. The value of the header must be a scalar -value that contain a string. The value string MUST NOT contain -characters below chr(37) except chr(32) (whitespace). +The headers B<MUST> be an array reference (B<not> a hash reference) +of key/value pairs. This means it B<MUST> contain an even number of elements. + +The header B<MUST NOT> contain a key named C<Status>, onr any keys with +C<:> or newlines in their name. It B<MUST NOT> contain any keys that end in C<-> or C<_>. + +All keys B<MUST> consist only of letters, digits, C<_> or C<->. All keys +B<MUST> start with a letter. The value of the header must be a scalar +string. The value string B<MUST NOT> contain characters below ASCII chr(37) except for +chr(32) (whitespace). If the same key name appears multiple times in an array ref, those -header lines MUST be sent to the client separately (e.g. multiple +header lines B<MUST> be sent to the client separately (e.g. multiple C<Set-Cookie> lines). =head4 Content-Type -There MUST be a C<Content-Type> except when the C<Status> is 1xx, 204 -or 304, in which case there MUST be none given. +There B<MUST> be a C<Content-Type> except when the C<Status> is 1xx, 204 +or 304, in which case there B<MUST NOT> be a content type. =head4 Content-Length -There MUST NOT be a C<Content-Length> header when the C<Status> is +There B<MUST NOT> be a C<Content-Length> header when the C<Status> is 1xx, 204 or 304. If the Status is not 1xx, 204 or 304 and there is no C<Content-Length> -header, servers MAY calculate the content length by looking at Body, -in case it can be calculated (i.e. if it's an array ref of body chunk -or a real file handle), and append to the outgoing headers. +header, a PSGI server B<MAY> calculate the content length by looking at the Body. This value can then be appended to the list of headers returned by the application. =head4 Body -The response body is returned from the application in one of following -two types of scalar variable. +The response body B<MUST> be returned from the application as either an array +reference or a handle. =over 4 =item * -An array reference containing body as lines. +If it an array reference, it is expected to contain an array of lines which make up the body. my $body = [ "Hello\n", "World\n" ]; -Note that the elements in an array reference are NOT REQUIRED to end -in a newline. The servers SHOULD just write each elements as is to the -client, and SHOULD NOT care if the line ends with newline or not. - -So, when you have a big chunk of HTML in a single scalar C<$body>, +Note that the elements in an array reference are B<NOT REQUIRED> to end +in a newline. A server B<SHOULD> write each elements as-is to the +client, and B<SHOULD NOT> care if the line ends with newline or not. - [ $body ] - -is a valid response body. +An array reference with a single value is valid. So C<[ $body ]> is a valid +response body. =item * -An IO::Handle-like object or a built-in filehandle. +The body can instead be a handle, either a Perl built-in filehandle or an +L<IO::Handle>-like object. open my $body, "</path/to/file"; open my $body, "<:via(SomePerlIO)", ...; @@ -394,64 +395,68 @@ An IO::Handle-like object or a built-in filehandle. my $body = SomeClass->new(); # mock class that implements getline() and close() -Servers SHOULD NOT check the type or class of the body but instead -just call C<getline> (i.e. duck type) to iterate over the body and +Servers B<SHOULD NOT> check the type or class of the body. Instead, they should +simply call C<getline> to iterate over the body, and call C<close> when done. -Servers MAY check if the body is a real filehandle using C<fileno> and -C<Scalar::Util::reftype> and if it's a real filehandle that has a file -descriptor, it MAY optimize the file serving using techniques like -I<sendfile(2)>. +Servers B<MAY> check if the body is a real filehandle using C<fileno> and +C<Scalar::Util::reftype>. If the body is real filehandle, the server B<MAY> +optimize using techniques like I<sendfile(2)>. + +The body object B<MAY> also respond to a C<path> method. This method is +expected to return the path to a file accessible by the server. This allows +the server to use this information instead of a file descriptor number to +server the file. -The body object MAY respond to C<path> method to return the local file -system path, which MAY be used by some servers to switch to more -efficient file serving method using the file path instead of a file -descriptor. +Servers B<SHOULD> set the C<$/> special variable to the buffer size when +reading content from C<$body> using the C<getline> method. This is done by +setting C<$/> with a reference to an integer (C<$/ = \8192>). -Servers are RECOMMENDED to set C<$/> special variable to the buffer -size when reading content from C<$body> using C<getline> method, in -case it's a binary filehandle. Applications, when it returns a mock -object that implements C<getline> are NOT REQUIRED to respect the -C<$/> value. +If the body filehandle is a Perl built-in filehandle L<IO::Handle> object, +they will respect this value. Similarly, an object which provides the same API +B<MAY> also respect this special variable, but are not required to do so. =back -=head2 Delayed Reponse and Streaming Body +=head2 Delayed Response and Streaming Body -PSGI interface allows applications and servers optionally handle -callback-style response (instead of three-element array reference) to -delay the HTTP response and stream content (server push). +The PSGI interface allows applications and servers to provide a callback-style +response instead of the three-element array reference. This allows for a +delayed response and a streaming body (server push). -To enable delayed response, an application SHOULD check if -C<psgi.streaming> environment is true, and in that case, MAY return a -callback that is passed another callback (response starter) as its -first argument, and pass the three element response to the callback. +To enable a delayed response, an application B<SHOULD> check if +the C<psgi.streaming> environment is true. If it is, the application B<MAY> return a +callback as its response. + +This callback will be called with I<another> subroutine reference (referred to +as the I<responder> from now on) as it's only argument. The I<responder> +should in turn be called with the standard three element array reference +response. This is best illustrated with an example: my $app = sub { my $env = shift; # Delays response until it fetches content from the network return sub { - my $respond = shift; - fetch_content_from_server(sub { - my $content = shift; - # ... - $respond->([ 200, $headers, [ $content ] ]); - }); + my $responder = shift; + + my $content = fetch_content_from_server(); + $responder->([ 200, $headers, [ $content ] ]); }; }; -Similarly, an application MAY omit the third element (the body) in the -callback to get a response writer object, that implements C<write>, -C<poll_cb> and C<close> method to push the response body. +An application B<MAY> omit the third element (the body) when calling the +I<responder>. If the body is omitted, the I<responder> will return I<yet +another> an object which implements C<write>, C<poll_cb> and C<close> +methods. Again, an example illustrates this best. my $app = sub { my $env = shift; # immediately starts the response and stream the content return sub { - my $respond = shift; - my $writer = $respond->([ 200, [ 'Content-Type', 'application/json' ]]); + my $responder = shift; + my $writer = $responder->([ 200, [ 'Content-Type', 'application/json' ]]); wait_for_events(sub { my $new_event = shift; @@ -466,25 +471,26 @@ C<poll_cb> and C<close> method to push the response body. }; }; -Delayed response and streaming should be useful if you want to -implement non-blocking I/O based server streaming or long-poll Comet -push technology. IO::Handle-like object is I<pull>, while this -streaming response implements I<push>. +B<XXX: still need detalis on write, poll_cb, and close API methods.> + +This delayed response and streaming API is useful if you want to +implement a non-blocking I/O based server streaming or long-poll Comet +push technology. + +This interface is optional: An application B<SHOULD> check if the server +supports streaming before attempting to use it. Servers B<MAY> throw an +exception if they do not support streaming a response. -This interface is optional: An applciation SHOULD check if the server -supports streaming. Servers MAY decide to not accept this streaming -response and throws an exception. Servers MUST set C<psgi.streaming> -to true if this interface is supported. Servers MUST return a writer -object if the third argument (response body) is omitted or not -defined in the response starter callback arguments. +Servers B<MUST> set C<psgi.streaming> to true if this interface is +supported, and if it is supported, servers B<MUST> return a writer object when the third argument +(response body) to the I<responder> is omitted. =head2 Middleware -Middleware is itself a PSGI application but it takes an existing PSGI -application and runs it like a server, mostly to do pre-processing on -C<$env> or post-processing on the response objects. +A piece of I<middleware> is itself a PSGI application, one which takes an existing PSGI +application and runs it like a server. Generally, this will be done in order to implement some sort of pre-processing on the PSGI environment has or post-processing on the response. -Here's a simple example that appends special HTTP header +Here's a simple example that appends a special HTTP header I<X-PSGI-Used> to any PSGI application. # $app is a simple PSGI application @@ -493,7 +499,7 @@ I<X-PSGI-Used> to any PSGI application. return [ '200', [ 'Content-Type' => 'text/plain' ], [ "Hello World" ] ]; }; - # $xheader is a middleware to wrap $app + # $xheader is a piece of middleware that wraps $app my $xheader = sub { my $env = shift; my $res = $app->($env); @@ -501,10 +507,10 @@ I<X-PSGI-Used> to any PSGI application. return $res; }; -Middleware itself MUST behave exactly like a PSGI application: take -C<$env> and return C<$res>. Middleware MAY decide not to support the -streaming interface (see above) but SHOULD pass through the response -types that it doesn't understand. +Middleware B<MUST> behave exactly like a PSGI application from the perspective +of a server. Middleware B<MAY> decide not to support the streaming interface +discussed earlier, but B<SHOULD> pass through the response types that it doesn't +understand. =head1 ACKNOWLEDGEMENTS PSGI.pod fc80fb98dc932a7cbac25d5591988f5796cc83e9 Dave Rolsky autarch@urth.org http://github.com/autarch/psgi-specs/commit/3e2dde3c19cb9d2c308ce815997199835333ca80 3e2dde3c19cb9d2c308ce815997199835333ca80 2009-10-27T16:28:00-07:00 2009-10-27T16:28:00-07:00 English cleanup, rewriting parts for clarity, adding links, and small bits of re-org. 5beef78f23bc756e5aab8eb2d148395235f6c558 Dave Rolsky autarch@urth.org