📄 fcgi-spec.html
字号:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"><HTML> <!--Copyright (c) 1996 Open Market, Inc. --> <!--See the file "LICENSE.TERMS" for information on usage and redistribution--> <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. --> <HEAD> <TITLE> FastCGI Specification </TITLE><STYLE TYPE="text/css"> h5.c2 {text-align: center} div.c1 {text-align: center}</STYLE> </HEAD> <BODY> <DIV CLASS="c1"> <H2> FastCGI Specification </H2> </DIV> <DIV CLASS="c1"> Mark R. Brown<BR> Open Market, Inc.<BR> <P> Document Version: 1.0<BR> 29 April 1996<BR> </P> </DIV> <P> </P> <H5 CLASS="c2"> Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR> Tel: 617-621-9500 Fax: 617-621-1703 URL: <A HREF= "http://www.openmarket.com/">http://www.openmarket.com/</A><BR> <BR> $Id: fcgi-spec.html,v 1.4 2002/02/25 00:42:59 robs Exp $ </H5> <HR> <UL TYPE="square"> <LI> <A HREF="#S1">1. Introduction</A> </LI> <LI> <A HREF="#S2">2. Initial Process State</A> <UL TYPE="square"> <LI> <A HREF="#S2.1">2.1 Argument list</A> </LI> <LI> <A HREF="#S2.2">2.2 File descriptors</A> </LI> <LI> <A HREF="#S2.3">2.3 Environment variables</A> </LI> <LI> <A HREF="#S2.4">2.4 Other state</A> </LI> </UL> </LI> <LI> <A HREF="#S3">3. Protocol Basics</A> <UL TYPE="square"> <LI> <A HREF="#S3.1">3.1 Notation</A> </LI> <LI> <A HREF="#S3.2">3.2 Accepting Transport Connections</A> </LI> <LI> <A HREF="#S3.3">3.3 Records</A> </LI> <LI> <A HREF="#S3.4">3.4 Name-Value Pairs</A> </LI> <LI> <A HREF="#S3.5">3.5 Closing Transport Connections</A> </LI> </UL> </LI> <LI> <A HREF="#S4">4. Management Record Types</A> <UL TYPE="square"> <LI> <A HREF="#S4.1">4.1 <TT>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</TT></A> </LI> <LI> <A HREF="#S4.2">4.2 <TT>FCGI_UNKNOWN_TYPE</TT></A> </LI> </UL> </LI> <LI> <A HREF="#S5">5. Application Record Types</A> <UL TYPE="square"> <LI> <A HREF="#S5.1">5.1 <TT>FCGI_BEGIN_REQUEST</TT></A> </LI> <LI> <A HREF="#S5.2">5.2 Name-Value Pair Streams: <TT>FCGI_PARAMS</TT>, <TT>FCGI_RESULTS</TT></A> </LI> <LI> <A HREF="#S5.3">5.3 Byte Streams: <TT>FCGI_STDIN</TT>, <TT>FCGI_DATA</TT>, <TT>FCGI_STDOUT</TT>, <TT>FCGI_STDERR</TT></A> </LI> <LI> <A HREF="#S5.4">5.4 <TT>FCGI_ABORT_REQUEST</TT></A> </LI> <LI> <A HREF="#S5.5">5.5 <TT>FCGI_END_REQUEST</TT></A> </LI> </UL> </LI> <LI> <A HREF="#S6">6. Roles</A> <UL TYPE="square"> <LI> <A HREF="#S6.1">6.1 Role Protocols</A> </LI> <LI> <A HREF="#S6.2">6.2 Responder</A> </LI> <LI> <A HREF="#S6.3">6.3 Authorizer</A> </LI> <LI> <A HREF="#S6.4">6.4 Filter</A> </LI> </UL> </LI> <LI> <A HREF="#S7">7. Errors</A> </LI> <LI> <A HREF="#S8">8. Types and Constants</A> </LI> <LI> <A HREF="#S9">9. References</A> </LI> <LI> <A HREF="#SA">A. Table: Properties of the record types</A> </LI> <LI> <A HREF="#SB">B. Typical Protocol Message Flow</A> </LI> </UL> <P> </P> <HR> <H3> <A NAME="S1">1. Introduction</A> </H3> <P> FastCGI is an open extension to CGI that provides high performance for all Internet applications without the penalties of Web server APIs. </P> <P> This specification has narrow goal: to specify, from an application perspective, the interface between a FastCGI application and a Web server that supports FastCGI. Many Web server features related to FastCGI, e.g. application management facilities, have nothing to do with the application to Web server interface, and are not described here. </P> <P> This specification is for Unix (more precisely, for POSIX systems that support Berkeley Sockets). The bulk of the specification is a simple communications protocol that is independent of byte ordering and will extend to other systems. </P> <P> We'll introduce FastCGI by comparing it with conventional Unix implementations of CGI/1.1. FastCGI is designed to support long-lived application processes, i.e. <I>application servers</I>. That's a major difference compared with conventional Unix implementations of CGI/1.1, which construct an application process, use it respond to one request, and have it exit. </P> <P> The initial state of a FastCGI process is more spartan than the initial state of a CGI/1.1 process, because the FastCGI process doesn't begin life connected to anything. It doesn't have the conventional open files <TT>stdin</TT>, <TT>stdout</TT>, and <TT>stderr</TT>, and it doesn't receive much information through environment variables. The key piece of initial state in a FastCGI process is a listening socket, through which it accepts connections from a Web server. </P> <P> After a FastCGI process accepts a connection on its listening socket, the process executes a simple protocol to receive and send data. The protocol serves two purposes. First, the protocol multiplexes a single transport connection between several independent FastCGI requests. This supports applications that are able to process concurrent requests using event-driven or multi-threaded programming techniques. Second, within each request the protocol provides several independent data streams in each direction. This way, for instance, both <TT>stdout</TT> and <TT>stderr</TT> data pass over a single transport connection from the application to the Web server, rather than requiring separate pipes as with CGI/1.1. </P> <P> A FastCGI application plays one of several well-defined <I>roles</I>. The most familiar is the <I>Responder</I> role, in which the application receives all the information associated with an HTTP request and generates an HTTP response; that's the role CGI/1.1 programs play. A second role is <I>Authorizer</I>, in which the application receives all the information associated with an HTTP request and generates an authorized/unauthorized decision. A third role is <I>Filter</I>, in which the 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 "filtered" version of the data stream as an HTTP response. The framework is extensible so that more FastCGI can be defined later. </P> <P> In the remainder of this specification the terms "FastCGI application," "application process," or "application server" are abbreviated to "application" whenever that won't cause confusion. </P> <P> </P> <H3> <A NAME="S2">2. Initial Process State</A> </H3> <H4> <A NAME="S2.1">2.1 Argument list</A> </H4> <P> By default the Web server creates an argument list containing a single element, the name of the application, taken to be the last component of the executable's path name. The Web server may provide a way to specify a different application name, or a more elaborate argument list. </P> <P> Note that the file executed by the Web server might be an interpreter file (a text file that starts with the characters <TT>#!</TT>), in which case the application's argument list is constructed as described in the <TT>execve</TT> manpage. </P> <P> </P> <H4> <A NAME="S2.2">2.2 File descriptors</A> </H4> <P> The Web server leaves a single file descriptor, <TT>FCGI_LISTENSOCK_FILENO</TT>, open when the application begins execution. This descriptor refers to a listening socket created by the Web server. </P> <P> <TT>FCGI_LISTENSOCK_FILENO</TT> equals <TT>STDIN_FILENO</TT>. The standard descriptors <TT>STDOUT_FILENO</TT> and <TT>STDERR_FILENO</TT> are closed when the application begins execution. A reliable method for an application to determine whether it was invoked using CGI or FastCGI is to call <TT>getpeername(FCGI_LISTENSOCK_FILENO)</TT>, which returns -1 with <TT>errno</TT> set to <TT>ENOTCONN</TT> for a FastCGI application. </P> <P> The Web server's choice of reliable transport, Unix stream pipes (<TT>AF_UNIX</TT>) or TCP/IP (<TT>AF_INET</TT>), is implicit in the internal state of the <TT>FCGI_LISTENSOCK_FILENO</TT> socket. </P> <P> </P> <H4> <A NAME="S2.3">2.3 Environment variables</A> </H4> <P> The Web server may use environment variables to pass parameters to the application. This specification defines one such variable, <TT>FCGI_WEB_SERVER_ADDRS</TT>; we expect more to be defined as the specification evolves. The Web server may provide a way to bind other environment variables, such as the <TT>PATH</TT> variable. </P> <P> </P> <H4> <A NAME="S2.4">2.4 Other state</A> </H4> <P> The Web server may provide a way to specify other components of an application's initial process state, such as the priority, user ID, group ID, root directory, and working directory of the process. </P> <P> </P> <H3> <A NAME="S3">3. Protocol Basics</A> </H3> <H4> <A NAME="S3.1">3.1 Notation</A> </H4> <P> We use C language notation to define protocol message formats. All structure elements are defined in terms of the <TT>unsigned char</TT> type, and are arranged so that an ISO C compiler lays them out in the obvious manner, with no padding. The first byte defined in the structure is transmitted first, the second byte second, etc. </P> <P> We use two conventions to abbreviate our definitions. </P> <P> First, when two adjacent structure components are named identically except for the suffixes "<TT>B1</TT>" and "<TT>B0</TT>," it means that the two components may be viewed as a single number, computed as <TT>B1<<8 + B0</TT>. The name of this single number is the name of the components, minus the suffixes. This convention generalizes in an obvious way to handle numbers represented in more than two bytes. </P> <P> Second, we extend C <TT>struct</TT>s to allow the form </P><PRE> struct { unsigned char mumbleLengthB1; unsigned char mumbleLengthB0; ... /* other stuff */ unsigned char mumbleData[mumbleLength]; };</PRE> <P> meaning a structure of varying length, where the length of a component is determined by the values of the indicated earlier component or components. </P> <P> </P> <H4> <A NAME="S3.2">3.2 Accepting Transport Connections</A> </H4> <P> A FastCGI application calls <TT>accept()</TT> on the socket referred to by file descriptor <TT>FCGI_LISTENSOCK_FILENO</TT> to accept a new transport connection. If the <TT>accept()</TT> succeeds, and the <TT>FCGI_WEB_SERVER_ADDRS</TT> environment variable is bound, the application application immediately performs the following special processing: </P> <P> </P> <UL TYPE="square"> <LI> <TT>FCGI_WEB_SERVER_ADDRS</TT>: The value is a list of valid IP addresses for the Web server. <P> If <TT>FCGI_WEB_SERVER_ADDRS</TT> was bound, the application checks the peer IP address of the new connection for membership in the list. If the check fails (including the possibility that the connection didn't use TCP/IP transport), the application responds by closing the connection. </P> <P> <TT>FCGI_WEB_SERVER_ADDRS</TT> is expressed as a comma-separated list of IP addresses. Each IP address is written as four decimal numbers in the range [0..255] separated by decimal points. So one legal binding for this variable is <TT>FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71</TT>. </P> <BR> <BR> </LI> </UL> <P> An application may accept several concurrent transport connections, but it need not do so. </P> <P> </P> <H4> <A NAME="S3.3">3.3 Records</A> </H4>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -