fcgi-spec.html

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

            cache without reading the file data. The application reads at most <TT>FCGI_DATA_LENGTH</TT> bytes from
            this stream before receiving the end-of-stream indication.
            <P>
            </P>
         </LI>
         <LI>
            The Filter 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_STDIN</TT> before it begins writing
            <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT>, but it needn&#39;t finish reading from <TT>FCGI_DATA</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 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 a similar CGI
            program would have returned via the <TT>exit</TT> system call.<BR>
            <BR>
         </LI>
      </UL>
      <P>
         A Filter should compare the number of bytes received on <TT>FCGI_STDIN</TT> with <TT>CONTENT_LENGTH</TT> and
         on <TT>FCGI_DATA</TT> with <TT>FCGI_DATA_LENGTH</TT>. If the numbers don&#39;t match and the Filter is a
         query, the Filter response should provide an indication that data is missing. If the numbers don&#39;t match
         and the Filter is an update, the Filter should abort the update.
      </P>
      <P>
      </P>
      <H3>
         <A NAME="S7">7. Errors</A>
      </H3>
      <P>
         A FastCGI application exits with zero status to indicate that it terminated on purpose, e.g. in order to
         perform a crude form of garbage collection. A FastCGI application that exits with nonzero status is assumed to
         have crashed. How a Web server or other application manager responds to applications that exit with zero or
         nonzero status is outside the scope of this specification.
      </P>
      <P>
         A Web server can request that a FastCGI application exit by sending it <TT>SIGTERM</TT>. If the application
         ignores <TT>SIGTERM</TT> the Web server can resort to <TT>SIGKILL</TT>.
      </P>
      <P>
         FastCGI applications report application-level errors with the <TT>FCGI_STDERR</TT> stream and the
         <TT>appStatus</TT> component of the <TT>FCGI_END_REQUEST</TT> record. In many cases an error will be reported
         directly to the user via the <TT>FCGI_STDOUT</TT> stream.
      </P>
      <P>
         On Unix, applications report lower-level errors, including FastCGI protocol errors and syntax errors in
         FastCGI environment variables, to <TT>syslog</TT>. Depending upon the severity of the error, the application
         may either continue or exit with nonzero status.
      </P>
      <P>
      </P>
      <H3>
         <A NAME="S8">8. Types and Constants</A>
      </H3>
<PRE>
/*
 * Listening socket file number
 */
#define FCGI_LISTENSOCK_FILENO 0

typedef struct {
    unsigned char version;
    unsigned char type;
    unsigned char requestIdB1;
    unsigned char requestIdB0;
    unsigned char contentLengthB1;
    unsigned char contentLengthB0;
    unsigned char paddingLength;
    unsigned char reserved;
} FCGI_Header;

/*
 * Number of bytes in a FCGI_Header.  Future versions of the protocol
 * will not reduce this number.
 */
#define FCGI_HEADER_LEN  8

/*
 * Value for version component of FCGI_Header
 */
#define FCGI_VERSION_1           1

/*
 * Values for type component of FCGI_Header
 */
#define FCGI_BEGIN_REQUEST       1
#define FCGI_ABORT_REQUEST       2
#define FCGI_END_REQUEST         3
#define FCGI_PARAMS              4
#define FCGI_STDIN               5
#define FCGI_STDOUT              6
#define FCGI_STDERR              7
#define FCGI_DATA                8
#define FCGI_GET_VALUES          9
#define FCGI_GET_VALUES_RESULT  10
#define FCGI_UNKNOWN_TYPE       11
#define FCGI_MAXTYPE (FCGI_UNKNOWN_TYPE)

/*
 * Value for requestId component of FCGI_Header
 */
#define FCGI_NULL_REQUEST_ID     0

typedef struct {
    unsigned char roleB1;
    unsigned char roleB0;
    unsigned char flags;
    unsigned char reserved[5];
} FCGI_BeginRequestBody;

typedef struct {
    FCGI_Header header;
    FCGI_BeginRequestBody body;
} FCGI_BeginRequestRecord;

/*
 * Mask for flags component of FCGI_BeginRequestBody
 */
#define FCGI_KEEP_CONN  1

/*
 * Values for role component of FCGI_BeginRequestBody
 */
#define FCGI_RESPONDER  1
#define FCGI_AUTHORIZER 2
#define FCGI_FILTER     3

typedef struct {
    unsigned char appStatusB3;
    unsigned char appStatusB2;
    unsigned char appStatusB1;
    unsigned char appStatusB0;
    unsigned char protocolStatus;
    unsigned char reserved[3];
} FCGI_EndRequestBody;

typedef struct {
    FCGI_Header header;
    FCGI_EndRequestBody body;
} FCGI_EndRequestRecord;

/*
 * Values for protocolStatus component of FCGI_EndRequestBody
 */
#define FCGI_REQUEST_COMPLETE 0
#define FCGI_CANT_MPX_CONN    1
#define FCGI_OVERLOADED       2
#define FCGI_UNKNOWN_ROLE     3

/*
 * Variable names for FCGI_GET_VALUES / FCGI_GET_VALUES_RESULT records
 */
#define FCGI_MAX_CONNS  &quot;FCGI_MAX_CONNS&quot;
#define FCGI_MAX_REQS   &quot;FCGI_MAX_REQS&quot;
#define FCGI_MPXS_CONNS &quot;FCGI_MPXS_CONNS&quot;

typedef struct {
    unsigned char type;    
    unsigned char reserved[7];
} FCGI_UnknownTypeBody;

typedef struct {
    FCGI_Header header;
    FCGI_UnknownTypeBody body;
} FCGI_UnknownTypeRecord;
</PRE>
      <P>
      </P>
      <H3>
         <A NAME="S9">9. References</A>
      </H3>
      <P>
         National Center for Supercomputer Applications, <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">The Common Gateway
         Interface</A>, version CGI/1.1.
      </P>
      <P>
         D.R.T. Robinson, <A HREF="http://cgi-spec.golux.com/">The WWW
         Common Gateway Interface Version 1.1</A>, Internet-Draft, 15 February 1996.
      </P>
      <P>
      </P>
      <H3>
         <A NAME="SA">A. Table: Properties of the record types</A>
      </H3>
      <P>
         The following chart lists all of the record types and indicates these properties of each:
      </P>
      <P>
      </P>
      <UL TYPE="square">
         <LI>
            <TT>WS-&gt;App</TT>: records of this type can only be sent by the Web server to the application. Records of
            other types can only be sent by the application to the Web server.
            <P>
            </P>
         </LI>
         <LI>
            <TT>management</TT>: records of this type contain information that is not specific to a Web server request,
            and use the null request ID. Records of other types contain request-specific information, and cannot use
            the null request ID.
            <P>
            </P>
         </LI>
         <LI>
            <TT>stream</TT>: records of this type form a stream, terminated by a record with empty
            <TT>contentData</TT>. Records of other types are discrete; each carries a meaningful unit of data.<BR>
            <BR>
         </LI>
      </UL>
<PRE>
                               WS-&gt;App   management  stream

        FCGI_GET_VALUES           x          x
        FCGI_GET_VALUES_RESULT               x
        FCGI_UNKNOWN_TYPE                    x

        FCGI_BEGIN_REQUEST        x
        FCGI_ABORT_REQUEST        x
        FCGI_END_REQUEST
        FCGI_PARAMS               x                    x
        FCGI_STDIN                x                    x
        FCGI_DATA                 x                    x
        FCGI_STDOUT                                    x 
        FCGI_STDERR                                    x     


</PRE>
      <P>
      </P>
      <H3>
         <A NAME="SB">B. Typical Protocol Message Flow</A>
      </H3>
      <P>
         Additional notational conventions for the examples:
      </P>
      <UL>
         <LI>
            The <TT>contentData</TT> of stream records (<TT>FCGI_PARAMS</TT>, <TT>FCGI_STDIN</TT>,
            <TT>FCGI_STDOUT</TT>, and <TT>FCGI_STDERR</TT>) is represented as a character string. A string ending in
            <TT>&quot; ... &quot;</TT> is too long to display, so only a prefix is shown.
         </LI>
         <LI>
            Messages sent to the Web server are indented with respect to messages received from the Web server.
         </LI>
         <LI>
            Messages are shown in the time sequence experienced by the application.
         </LI>
      </UL>
      <P>
         1. A simple request with no data on <TT>stdin</TT>, and a successful response:
      </P>
<PRE>
{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
{FCGI_PARAMS,          1, &quot;\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... &quot;}
{FCGI_PARAMS,          1, &quot;&quot;}
{FCGI_STDIN,           1, &quot;&quot;}

    {FCGI_STDOUT,      1, &quot;Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... &quot;}
    {FCGI_STDOUT,      1, &quot;&quot;}
    {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
</PRE>
      <P>
         2. Similar to example 1, but this time with data on <TT>stdin</TT>. The Web server chooses to send the
         parameters using more <TT>FCGI_PARAMS</TT> records than before:
      </P>
<PRE>
{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
{FCGI_PARAMS,          1, &quot;\013\002SERVER_PORT80\013\016SER&quot;}
{FCGI_PARAMS,          1, &quot;VER_ADDR199.170.183.42 ... &quot;}
{FCGI_PARAMS,          1, &quot;&quot;}
{FCGI_STDIN,           1, &quot;quantity=100&amp;item=3047936&quot;}
{FCGI_STDIN,           1, &quot;&quot;}

    {FCGI_STDOUT,      1, &quot;Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... &quot;}
    {FCGI_STDOUT,      1, &quot;&quot;}
    {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
</PRE>
      <P>
         3. Similar to example 1, but this time the application detects an error. The application logs a message to
         <TT>stderr</TT>, returns a page to the client, and returns non-zero exit status to the Web server. The
         application chooses to send the page using more <TT>FCGI_STDOUT</TT> records:
      </P>
<PRE>
{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
{FCGI_PARAMS,          1, &quot;\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... &quot;}
{FCGI_PARAMS,          1, &quot;&quot;}
{FCGI_STDIN,           1, &quot;&quot;}

    {FCGI_STDOUT,      1, &quot;Content-type: text/html\r\n\r\n&lt;ht&quot;}
    {FCGI_STDERR,      1, &quot;config error: missing SI_UID\n&quot;}
    {FCGI_STDOUT,      1, &quot;ml&gt;\n&lt;head&gt; ... &quot;}
    {FCGI_STDOUT,      1, &quot;&quot;}
    {FCGI_STDERR,      1, &quot;&quot;}
    {FCGI_END_REQUEST, 1, {938, FCGI_REQUEST_COMPLETE}}
</PRE>
      <P>
         4. Two instances of example 1, multiplexed onto a single connection. The first request is more difficult than
         the second, so the application finishes the requests out of order:
      </P>
<PRE>
{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, FCGI_KEEP_CONN}}
{FCGI_PARAMS,          1, &quot;\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... &quot;}
{FCGI_PARAMS,          1, &quot;&quot;}
{FCGI_BEGIN_REQUEST,   2, {FCGI_RESPONDER, FCGI_KEEP_CONN}}
{FCGI_PARAMS,          2, &quot;\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... &quot;}
{FCGI_STDIN,           1, &quot;&quot;}

    {FCGI_STDOUT,      1, &quot;Content-type: text/html\r\n\r\n&quot;}

{FCGI_PARAMS,          2, &quot;&quot;}
{FCGI_STDIN,           2, &quot;&quot;}

    {FCGI_STDOUT,      2, &quot;Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... &quot;}
    {FCGI_STDOUT,      2, &quot;&quot;}
    {FCGI_END_REQUEST, 2, {0, FCGI_REQUEST_COMPLETE}}
    {FCGI_STDOUT,      1, &quot;&lt;html&gt;\n&lt;head&gt; ... &quot;}
    {FCGI_STDOUT,      1, &quot;&quot;}
    {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
</PRE>
      <P>
      </P>
      <HR>
      <ADDRESS>
         &copy; 1995, 1996 Open Market, Inc. / [e-mail]
      </ADDRESS>
   </BODY>
</HTML>