fcgi-spec.html

FastCGI,语言无关的、可伸缩架构的CGI开放扩展

            unsigned char reserved[5];
        } FCGI_BeginRequestBody;
</PRE>
      <P>
         The <TT>role</TT> component sets the role the Web server expects the application to play. The
         currently-defined roles are:
      </P>
      <P>
      </P>
      <UL TYPE="square">
         <LI>
            <TT>FCGI_RESPONDER</TT>
         </LI>
         <LI>
            <TT>FCGI_AUTHORIZER</TT>
         </LI>
         <LI>
            <TT>FCGI_FILTER</TT>
         </LI>
      </UL>
      <P>
         Roles are described in more detail in <A HREF="#S6">Section 6</A> below.
      </P>
      <P>
         The <TT>flags</TT> component contains a bit that controls connection shutdown:
      </P>
      <P>
      </P>
      <UL TYPE="square">
         <LI>
            <TT>flags &amp; FCGI_KEEP_CONN</TT>: If zero, the application closes the connection after responding to
            this request. If not zero, the application does not close the connection after responding to this request;
            the Web server retains responsibility for the connection.<BR>
            <BR>
         </LI>
      </UL>
      <H4>
         <A NAME="S5.2">5.2 Name-Value Pair Stream: <TT>FCGI_PARAMS</TT></A>
      </H4>
      <TT>FCGI_PARAMS</TT>
      <P>
         is a stream record type used in sending name-value pairs from the Web server to the application. The
         name-value pairs are sent down the stream one after the other, in no specified order.
      </P>
      <P>
      </P>
      <H4>
         <A NAME="S5.3">5.3 Byte Streams: <TT>FCGI_STDIN</TT>, <TT>FCGI_DATA</TT>, <TT>FCGI_STDOUT</TT>,
         <TT>FCGI_STDERR</TT></A>
      </H4>
      <TT>FCGI_STDIN</TT>
      <P>
         is a stream record type used in sending arbitrary data from the Web server to the application.
         <TT>FCGI_DATA</TT> is a second stream record type used to send additional data to the application.
      </P>
      <P>
         <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT> are stream record types for sending arbitrary data and error
         data respectively from the application to the Web server.
      </P>
      <P>
      </P>
      <H4>
         <A NAME="S5.4">5.4 <TT>FCGI_ABORT_REQUEST</TT></A>
      </H4>
      <P>
         The Web server sends a <TT>FCGI_ABORT_REQUEST</TT> record to abort a request. After receiving
         <TT>{FCGI_ABORT_REQUEST, R}</TT>, the application responds as soon as possible with <TT>{FCGI_END_REQUEST, R,
         {FCGI_REQUEST_COMPLETE, appStatus}}</TT>. This is truly a response from the application, not a low-level
         acknowledgement from the FastCGI library.
      </P>
      <P>
         A Web server aborts a FastCGI request when an HTTP client closes its transport connection while the FastCGI
         request is running on behalf of that client. The situation may seem unlikely; most FastCGI requests will have
         short response times, with the Web server providing output buffering if the client is slow. But the FastCGI
         application may be delayed communicating with another system, or performing a server push.
      </P>
      <P>
         When a Web server is not multiplexing requests over a transport connection, the Web server can abort a request
         by closing the request&#39;s transport connection. But with multiplexed requests, closing the transport
         connection has the unfortunate effect of aborting <I>all</I> the requests on the connection.
      </P>
      <P>
      </P>
      <H4>
         <A NAME="S5.5">5.5 <TT>FCGI_END_REQUEST</TT></A>
      </H4>
      <P>
         The application sends a <TT>FCGI_END_REQUEST</TT> record to terminate a request, either because the
         application has processed the request or because the application has rejected the request.
      </P>
      <P>
         The <TT>contentData</TT> component of a <TT>FCGI_END_REQUEST</TT> record has the form:
      </P>
<PRE>
        typedef struct {
            unsigned char appStatusB3;
            unsigned char appStatusB2;
            unsigned char appStatusB1;
            unsigned char appStatusB0;
            unsigned char protocolStatus;
            unsigned char reserved[3];
        } FCGI_EndRequestBody;
</PRE>
      <P>
         The <TT>appStatus</TT> component is an application-level status code. Each role documents its usage of
         <TT>appStatus</TT>.
      </P>
      <P>
         The <TT>protocolStatus</TT> component is a protocol-level status code; the possible <TT>protocolStatus</TT>
         values are:
      </P>
      <P>
      </P>
      <UL TYPE="square">
         <LI>
            <TT>FCGI_REQUEST_COMPLETE</TT>: normal end of request.
            <P>
            </P>
         </LI>
         <LI>
            <TT>FCGI_CANT_MPX_CONN</TT>: rejecting a new request. This happens when a Web server sends concurrent
            requests over one connection to an application that is designed to process one request at a time per
            connection.
            <P>
            </P>
         </LI>
         <LI>
            <TT>FCGI_OVERLOADED</TT>: rejecting a new request. This happens when the application runs out of some
            resource, e.g. database connections.
            <P>
            </P>
         </LI>
         <LI>
            <TT>FCGI_UNKNOWN_ROLE</TT>: rejecting a new request. This happens when the Web server has specified a role
            that is unknown to the application.<BR>
            <BR>
         </LI>
      </UL>
      <H3>
         <A NAME="S6">6. Roles</A>
      </H3>
      <H4>
         <A NAME="S6.1">6.1 Role Protocols</A>
      </H4>
      <P>
         Role protocols only include records with application record types. They transfer essentially all data using
         streams.
      </P>
      <P>
         To make the protocols reliable and to simplify application programming, role protocols are designed to use
         <I>nearly sequential marshalling</I>. In a protocol with strictly sequential marshalling, the application
         receives its first input, then its second, etc. until it has received them all. Similarly, the application
         sends its first output, then its second, etc. until it has sent them all. Inputs are not interleaved with each
         other, and outputs are not interleaved with each other.
      </P>
      <P>
         The sequential marshalling rule is too restrictive for some FastCGI roles, because CGI programs can write to
         both <TT>stdout</TT> and <TT>stderr</TT> without timing restrictions. So role protocols that use both
         <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT> allow these two streams to be interleaved.
      </P>
      <P>
         All role protocols use the <TT>FCGI_STDERR</TT> stream just the way <TT>stderr</TT> is used in conventional
         applications programming: to report application-level errors in an intelligible way. Use of the
         <TT>FCGI_STDERR</TT> stream is always optional. If an application has no errors to report, it sends either no
         <TT>FCGI_STDERR</TT> records or one zero-length <TT>FCGI_STDERR</TT> record.
      </P>
      <P>
         When a role protocol calls for transmitting a stream other than <TT>FCGI_STDERR</TT>, at least one record of
         the stream type is always transmitted, even if the stream is empty.
      </P>
      <P>
         Again in the interests of reliable protocols and simplified application programming, role protocols are
         designed to be <I>nearly request-response</I>. In a truly request-response protocol, the application receives
         all of its input records before sending its first output record. Request-response protocols don&#39;t allow
         pipelining.
      </P>
      <P>
         The request-response rule is too restrictive for some FastCGI roles; after all, CGI programs aren&#39;t
         restricted to read all of <TT>stdin</TT> before starting to write <TT>stdout</TT>. So some role protocols
         allow that specific possibility. First the application receives all of its inputs except for a final stream
         input. As the application begins to receive the final stream input, it can begin writing its output.
      </P>
      <P>
         When a role protocol uses <TT>FCGI_PARAMS</TT> to transmit textual values, such as the values that CGI
         programs obtain from environment variables, the length of the value does not include the terminating null
         byte, and the value itself does not include a null byte. An application that needs to provide
         <TT>environ(7)</TT> format name-value pairs must insert an equal sign between the name and value and append a
         null byte after the value.
      </P>
      <P>
         Role protocols do not support the non-parsed header feature of CGI. FastCGI applications set response status
         using the <TT>Status</TT> and <TT>Location</TT> CGI headers.
      </P>
      <P>
      </P>
      <H4>
         <A NAME="S6.2">6.2 Responder</A>
      </H4>
      <P>
         A Responder FastCGI application has the same purpose as a CGI/1.1 program: It receives all the information
         associated with an HTTP request and generates an HTTP response.
      </P>
      <P>
         It suffices to explain how each element of CGI/1.1 is emulated by a Responder:
      </P>
      <BR>
      <BR>
      <UL TYPE="square">
         <LI>
            The Responder application receives CGI/1.1 environment variables from the Web server over
            <TT>FCGI_PARAMS</TT>.
            <P>
            </P>
         </LI>
         <LI>
            Next the Responder application receives CGI/1.1 <TT>stdin</TT> data from the Web server over
            <TT>FCGI_STDIN</TT>. The application receives at most <TT>CONTENT_LENGTH</TT> bytes from this stream before
            receiving the end-of-stream indication. (The application receives less than <TT>CONTENT_LENGTH</TT> bytes
            only if the HTTP client fails to provide them, e.g. because the client crashed.)
            <P>
            </P>
         </LI>
         <LI>
            The Responder application sends CGI/1.1 <TT>stdout</TT> data to the Web server over <TT>FCGI_STDOUT</TT>,
            and CGI/1.1 <TT>stderr</TT> data over <TT>FCGI_STDERR</TT>. The application sends these concurrently, not
            one after the other. The application must wait to finish reading <TT>FCGI_PARAMS</TT> before it begins
            writing <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT>, but it needn&#39;t finish reading from
            <TT>FCGI_STDIN</TT> before it begins writing these two streams.
            <P>
            </P>
         </LI>
         <LI>
            After sending all its <TT>stdout</TT> and <TT>stderr</TT> data, the Responder application sends a
            <TT>FCGI_END_REQUEST</TT> record. The application sets the <TT>protocolStatus</TT> component to
            <TT>FCGI_REQUEST_COMPLETE</TT> and the <TT>appStatus</TT> component to the status code that the CGI program
            would have returned via the <TT>exit</TT> system call.<BR>
            <BR>
         </LI>
      </UL>
      <P>
         A Responder performing an update, e.g. implementing a <TT>POST</TT> method, should compare the number of bytes
         received on <TT>FCGI_STDIN</TT> with <TT>CONTENT_LENGTH</TT> and abort the update if the two numbers are not
         equal.
      </P>
      <P>
      </P>
      <H4>
         <A NAME="S6.3">6.3 Authorizer</A>
      </H4>
      <P>
         An Authorizer FastCGI application receives all the information associated with an HTTP request and generates
         an authorized/unauthorized decision. In case of an authorized decision the Authorizer can also associate
         name-value pairs with the HTTP request; when giving an unauthorized decision the Authorizer sends a complete
         response to the HTTP client.
      </P>
      <P>
         Since CGI/1.1 defines a perfectly good way to represent the information associated with an HTTP request,
         Authorizers use the same representation:
      </P>
      <P>
      </P>
      <UL TYPE="square">
         <LI>
            The Authorizer application receives HTTP request information from the Web server on the
            <TT>FCGI_PARAMS</TT> stream, in the same format as a Responder. The Web server does not send
            <TT>CONTENT_LENGTH</TT>, <TT>PATH_INFO</TT>, <TT>PATH_TRANSLATED</TT>, and <TT>SCRIPT_NAME</TT> headers.
            <P>
            </P>
         </LI>
         <LI>
            The Authorizer application sends <TT>stdout</TT> and <TT>stderr</TT> data in the same manner as a
            Responder. The CGI/1.1 response status specifies the disposition of the request. If the application sends
            status 200 (OK), the Web server allows access. Depending upon its configuration the Web server may proceed
            with other access checks, including requests to other Authorizers.
            <P>
               An Authorizer application&#39;s 200 response may include headers whose names are prefixed with
               <TT>Variable-</TT>. These headers communicate name-value pairs from the application to the Web server.
               For instance, the response header
            </P>
<PRE>
        Variable-AUTH_METHOD: database lookup
</PRE>
            transmits the value <TT>&quot;database lookup&quot;</TT> with name <TT>AUTH-METHOD</TT>. The server
            associates such name-value pairs with the HTTP request and includes them in subsequent CGI or FastCGI
            requests performed in processing the HTTP request. When the application gives a 200 response, the server
            ignores response headers whose names aren&#39;t prefixed with <TT>Variable-</TT> prefix, and ignores any
            response content.
            <P>
               For Authorizer response status values other than &quot;200&quot; (OK), the Web server denies access and
               sends the response status, headers, and content back to the HTTP client.
            </P>
            <BR>
            <BR>
         </LI>
      </UL>
      <H4>
         <A NAME="S6.4">6.4 Filter</A>
      </H4>
      <P>
         A Filter FastCGI application receives all the information associated with an HTTP request, plus an extra
         stream of data from a file stored on the Web server, and generates a &quot;filtered&quot; version of the data
         stream as an HTTP response.
      </P>
      <P>
         A Filter is similar in functionality to a Responder that takes a data file as a parameter. The difference is
         that with a Filter, both the data file and the Filter itself can be access controlled using the Web
         server&#39;s access control mechanisms, while a Responder that takes the name of a data file as a parameter
         must perform its own access control checks on the data file.
      </P>
      <P>
         The steps taken by a Filter are similar to those of a Responder. The server presents the Filter with
         environment variables first, then standard input (normally form <TT>POST</TT> data), finally the data file
         input:
      </P>
      <BR>
      <BR>
      <UL TYPE="square">
         <LI>
            Like a Responder, the Filter application receives name-value pairs from the Web server over
            <TT>FCGI_PARAMS</TT>. Filter applications receive two Filter-specific variables:
            <TT>FCGI_DATA_LAST_MOD</TT> and <TT>FCGI_DATA_LENGTH</TT>.
            <P>
            </P>
         </LI>
         <LI>
            Next the Filter application receives CGI/1.1 <TT>stdin</TT> data from the Web server over
            <TT>FCGI_STDIN</TT>. The application receives at most <TT>CONTENT_LENGTH</TT> bytes from this stream before
            receiving the end-of-stream indication. (The application receives less than <TT>CONTENT_LENGTH</TT> bytes
            only if the HTTP client fails to provide them, e.g. because the client crashed.)
            <P>
            </P>
         </LI>
         <LI>
            Next the Filter application receives the file data from the Web server over <TT>FCGI_DATA</TT>. This
            file&#39;s last modification time (expressed as an integer number of seconds since the epoch January 1,
            1970 UTC) is <TT>FCGI_DATA_LAST_MOD</TT>; the application may consult this variable and respond from a