FastCGI Protocol Specification: A Comprehensive Guide

This comprehensive guide translates and explains the FastCGI protocol specification originally authored by Mark R. Brown. FastCGI is an open extension protocol that significantly improves CGI application performance by allowing persistent processes rather than creating new ones for each request.

The document begins with an introduction explaining FastCGI's purpose and how it differs from traditional CGI/1.1 applications. While CGI creates a new process for each request, FastCGI maintains a persistent process that listens on a socket for incoming requests, eliminating the overhead of process creation and destruction.

The protocol specification covers several key areas:

Application Initialization - FastCGI applications receive a parameter list and are bound to a special file descriptor (FCGI_LISTENSOCK_FILENO) that serves as the listening socket. The application can determine if it's running in FastCGI mode by checking if getpeername() returns ENOTCONN.

Protocol Basics - Communication between web servers and FastCGI applications uses a simple record-based protocol. Records are structured with a header containing version, type, request ID, content length, and padding information. This design allows multiple requests to share a single connection and supports multiplexing different data streams (stdout, stderr) over the same connection.

Record Structure - The FCGI_Record structure includes version, type, requestId, contentLength, paddingLength, and data fields. The protocol uses a simplified C language notation where multi-byte integers are represented by adjacent single-byte members (e.g., requestIdB1 and requestIdB0 represent a 16-bit requestId).

Key-Value Pair Encoding - FastCGI uses a specific encoding for transmitting key-value pairs where lengths are encoded in 1 or 4 bytes depending on size, followed by the key and value data. This allows efficient binary transmission without additional metadata.

Management Records - These records (FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT, FCGI_UNKNOWN_TYPE) handle server-to-application queries about application capabilities like maximum connections, requests, and multiplexing support.

Application Records - These include FCGI_BEGIN_REQUEST (starts a request with role and flags), FCGI_PARAMS (transmits key-value pairs), FCGI_STDIN/FCGI_DATA (transmits input data), FCGI_STDOUT/FCGI_STDERR (transmits output), FCGI_ABORT_REQUEST (terminates a request), and FCGI_END_REQUEST (signals request completion).

Roles - FastCGI defines three primary roles: Responder (handles HTTP requests like CGI), Authorizer (performs authentication and can add variables to requests), and Filter (processes files with additional input streams).

Error Handling - Applications report errors through FCGI_STDERR records or by setting appropriate status codes in FCGI_END_REQUEST records. System-level errors are logged to syslog.

The specification includes detailed data structure definitions, constant values, and examples of typical data flows showing how requests are processed. It also provides tables categorizing record types by their characteristics (WS-to-App direction, management vs application, stream vs non-stream).

This document serves as an essential reference for developers implementing FastCGI applications or working with PHP-FPM and web servers that use FastCGI modules, providing the foundational knowledge needed to understand and work with this high-performance web application protocol.