FastCGI 协议规范中文版

3.4、键值对

// name 长度不大于 127， value 长度不大于 127
typedef struct {
    unsigned char nameLengthB0;  /* nameLengthB0  >> 7 == 0 */
    unsigned char valueLengthB0; /* valueLengthB0 >> 7 == 0 */
    unsigned char nameData[nameLength];
    unsigned char valueData[valueLength];
} FCGI_NameValuePair11;
// name 长度不大于 127， value 长度大于 127
typedef struct {
    unsigned char nameLengthB0;  /* nameLengthB0  >> 7 == 0 */
    unsigned char valueLengthB3; /* valueLengthB3 >> 7 == 1 */
    unsigned char valueLengthB2;
    unsigned char valueLengthB1;
    unsigned char valueLengthB0;
    unsigned char nameData[nameLength];
    unsigned char valueData[valueLength
    ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 <> 7 == 1 */
    unsigned char nameLengthB2;
    unsigned char nameLengthB1;
    unsigned char nameLengthB0;
    unsigned char valueLengthB0; /* valueLengthB0 >> 7 == 0 */
    unsigned char nameData[nameLength
    ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 <> 7 == 1 */
    unsigned char nameLengthB2;
    unsigned char nameLengthB1;
    unsigned char nameLengthB0;
    unsigned char valueLengthB3; /* valueLengthB3 >> 7 == 1 */
    unsigned char valueLengthB2;
    unsigned char valueLengthB1;
    unsigned char valueLengthB0;
    unsigned char nameData[nameLength
    ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0];
    unsigned char valueData[valueLength
    ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0];
} FCGI_NameValuePair44; 

3.5、关闭连接

正常情况下，Web 服务器管理着连接的生命期。当没有待处理的请求时，Web 服务器就可以关闭此连接。Web 服务器也可以授权 FastCGI 应用代为关闭某个连接（见 FCGI_BEGIN_REQUEST 记录），在这种情况下，应用会在处理完成那个请求之后，自行关闭对应连接。

上述机制让应用在实现时可以选择不同的风格。一个简单的 FastCGI 的应用实现可能是，对同一个连接只处理一个请求，每个新请求都需要建立新连接传递过来。一种更加复杂的实现是，应用可以在同一个连接上并发处理多个请求，这样这个连接就会作为长连接存在。

应用在输出响应之后自行关闭连接，然后继续进行后续逻辑的处理，可以显著地降低响应时间。注意此时长连接的生命期只能由 Web 服务器自己管理。

当应用自行关闭了某个连接或者发现某连接已经被关闭了，在必要的时候，需要建立新连接来进行后续处理。

五、 应用类记录

5.1、FCGI_BEGIN_REQUEST

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

5.2、键值对数据记录：FCGI_PARAMS

FCGI_PARAMS 记录被 Web 服务器用来向应用传递键值对数据，键值对数据会被封装成若干这类记录，形成一个数据流，依次传递。键值对间不区分顺序。

5.3、字节流类记录

FCGI_STDIN，FCGI_DATA

FCGI_STDOUT FCGI_STDERR

FCGI_STDIN 记录被 Web 服务器用来向应用传输任意格式的数据，FCGI_DATA 记录是类似的用法。

FCGI_STDOUT 记录被应用当做标准输出，用来向 Web 服务器传输任意类型的数据。

FCGI_STDERR 记录被应用当做标准错误输出，用来向 Web 服务器传输任意类型的数据。

5.4、FCGI_ABORT_REQUET

Web 服务器通过向 FastCGI 应用发送一个 FCGI_ABORT_REQUEST 记录来终止一个请求的处理。当应用收到一个

{FCGI_ABORT_REQUEST, R} 记录时， 需要立即以

{FCGI_END_REQUEST, R, {FCGI_REQUEST_COMPLETE, appStatus}} 

记录进行回复， 这是一个应用实现级别的响应，并非 FastCGI 底层库自行发出的响应。

当一个请求经由 Web 服务器进入到 FastCGI 应用中，处理暂未结束时，如果此时 HTTP 客户端断开与 Web 服务器的连接，那么 Web 服务器就会触发此请求的终止操作。这种情况发生比例较低，因为大多数 FastCGI 请求在应用中都会在较短的时间内完成并返回，甚至在 HTTP 客户端传输速度较慢的时候，Web 服务器会把应用的响应数据缓存下来，慢慢的发送给客户端。在某些情况下，应用可能会因为外部依赖或者执行某个推送任务而耗时过长。

如果 Web 服务器和应用之间的通信没有复用连接，那么 Web 服务器可以通过关闭这个请求对应的连接来终止这个请求的处理。但是在连接复用的情况下，关闭这个连接会导致此连接上所有正在进行请求的执行终止。

5.5、FCGI_END_REQUEST

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

六、 角色

6.1、角色下的协议

八、 数据结构和常量定义

/*
 * 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  "FCGI_MAX_CONNS"
#define FCGI_MAX_REQS   "FCGI_MAX_REQS"
#define FCGI_MPXS_CONNS "FCGI_MPXS_CONNS"

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

typedef struct {
    FCGI_Header header;
    FCGI_UnknownTypeBody body;
} FCGI_UnknownTypeRecord;

九、 参考资料

The WWW Common Gateway Interface at W3C

（https://www.w3.org/CGI/ ）

附表A：各种类型记录的特性

下表列出了各类型记录所支持的特性情况（x表示勾选）

• WS->App ：这个特性勾选表示此类型记录只能被 Web 服务器发送给应用。非勾选类型的记录只能被应用发送给 Web 服务器。

• management ：这个特性勾选表示此类型记录是非关联到某个请求的记录，记录的 requestId 成员值为 null。非勾选类型的记录则有关联到某个请求，记录的 requestId 成员值不为 null。

• stream ：这个特性勾选表示此类型记录的内容被用来组成一个数据流，这个数据流会使用一个 contentData 成员长度为 0 的记录作为终止标志。这种类型的记录都是非自描述的，每个记录都是整个流数据中的一部分。

附表B：典型数据流示例

这里引入一些简化表达方式来描述数据流：

流数据式记录 (FCGI_PARAMS，FCGI_STDIN，FCGI_STDOUT， FCGI_STDERR) 中的 contentData 成员值使用字符串表示。一个以 “…” 结尾的字符串表示此值过长，需要截断显示。

为了区别显示 Web 服务器发送和接收的数据，Web 服务器接收的数据会缩进显示。 数据流会按照实际的处理时间顺序排列显示。

{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
{FCGI_PARAMS,          1, "\013\002SERVER_PORT80\013\016SERVER_ADDR ... "}
{FCGI_PARAMS,          1, ""}
{FCGI_STDIN,           1, ""}

    {FCGI_STDOUT,      1, "Content-type: text/html\r\n\r\n\n ... "}
    {FCGI_STDOUT,      1, ""}
    {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}

{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
{FCGI_PARAMS,          1, "\013\002SERVER_PORT80\013\016SER"}
{FCGI_PARAMS,          1, "VER_ADDR199.170.183.42 ... "}
{FCGI_PARAMS,          1, ""}
{FCGI_STDIN,           1, "quantity=100&item=3047936"}
{FCGI_STDIN,           1, ""}

    {FCGI_STDOUT,      1, "Content-type: text/html\r\n\r\n\n ... "}
    {FCGI_STDOUT,      1, ""}
    {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}

{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
{FCGI_PARAMS,          1, "\013\002SERVER_PORT80\013\016SERVER_ADDR ... "}
{FCGI_PARAMS,          1, ""}
{FCGI_STDIN,           1, ""}

    {FCGI_STDOUT,      1, "Content-type: text/html\r\n\r\n<ht"}
    {FCGI_STDERR,      1, "config error: missing SI_UID\n"}
    {FCGI_STDOUT,      1, "ml>\n ... "}
    {FCGI_STDOUT,      1, ""}
    {FCGI_STDERR,      1, ""}
    {FCGI_END_REQUEST, 1, {938, FCGI_REQUEST_COMPLETE}}

{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, FCGI_KEEP_CONN}}
{FCGI_PARAMS,          1, "\013\002SERVER_PORT80\013\016SERVER_ADDR ... "}
{FCGI_PARAMS,          1, ""}
{FCGI_BEGIN_REQUEST,   2, {FCGI_RESPONDER, FCGI_KEEP_CONN}}
{FCGI_PARAMS,          2, "\013\002SERVER_PORT80\013\016SERVER_ADDR ... "}
{FCGI_STDIN,           1, ""}

    {FCGI_STDOUT,      1, "Content-type: text/html\r\n\r\n"}

{FCGI_PARAMS,          2, ""}
{FCGI_STDIN,           2, ""}

    {FCGI_STDOUT,      2, "Content-type: text/html\r\n\r\n\n ... "}
    {FCGI_STDOUT,      2, ""}
    {FCGI_END_REQUEST, 2, {0, FCGI_REQUEST_COMPLETE}}
    {FCGI_STDOUT,      1, "\n ... "}
    {FCGI_STDOUT,      1, ""}
    {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}

附：原文地址和版权声明

———- END ———-