···
+
(** Core FastCGI types and constants.
+
This module defines the fundamental types used throughout the
+
FastCGI protocol implementation.
+
FastCGI is an open extension to CGI that provides high performance for
+
all Internet applications without the penalties of Web server APIs.
+
Unlike traditional CGI programs that are started for each request,
+
FastCGI applications are long-lived processes that can handle multiple
+
requests over persistent connections. *)
+
(** FastCGI protocol version.
+
The current protocol uses version 1. Future versions of the
+
protocol may increment this value. Applications should check the version
+
field in incoming records and reject unsupported versions.
+
Version 1 is represented by the value [1]. *)
+
(** FastCGI record types.
+
All data transmitted over a FastCGI connection is packaged in records.
+
Each record has a type that determines how the record's content should
+
be interpreted. The protocol defines both management records (for
+
protocol-level communication) and application records (for request
+
Management records contain information that is not specific to any web
+
server request, such as capability queries and unknown type responses.
+
Application records contain information about a particular request,
+
identified by a non-zero request ID. *)
+
| Begin_request (** Starts a new request. Sent by the web server to begin
+
processing. Contains the role and connection flags. *)
+
| Abort_request (** Aborts an existing request. Sent by the web server
+
when an HTTP client closes its connection while the
+
request is still being processed. *)
+
| End_request (** Completes a request. Sent by the application to
+
terminate processing, either normally or due to
+
| Params (** Parameter name-value pairs. Used to transmit CGI-style
+
environment variables from the web server to the
+
application. Sent as a stream. *)
+
| Stdin (** Standard input data. Contains the request body data
+
that would normally be available on stdin in CGI.
+
| Stdout (** Standard output data. Response data from the application
+
to the web server. This becomes the HTTP response.
+
| Stderr (** Standard error data. Error messages from the application.
+
Used for logging and debugging. Sent as a stream. *)
+
| Data (** Additional data stream. Used only in the Filter role
+
to transmit file data that needs to be filtered.
+
| Get_values (** Management record to query application variables.
+
Allows the web server to discover application
+
capabilities like max connections and multiplexing. *)
+
| Get_values_result (** Management record response to Get_values. Contains
+
the requested variable values. *)
+
| Unknown_type (** Management record for unknown type handling. Sent by
+
the application when it receives a record type it
+
(** FastCGI application roles.
+
A FastCGI application can play one of several well-defined roles.
+
The role determines what information the application receives and
+
what it's expected to produce.
+
A FastCGI application plays one of several well-defined roles. The most
+
familiar is the Responder role, in which the application receives all
+
the information associated with an HTTP request and generates an HTTP
+
| Responder (** The most common role, equivalent to traditional CGI.
+
The application receives all information associated with
+
an HTTP request and generates an HTTP response. This
+
includes environment variables, request headers, and
+
| Authorizer (** Performs access control decisions. The application
+
receives HTTP request information and generates an
+
authorized/unauthorized decision. In case of authorization,
+
it can associate additional variables with the request.
+
For unauthorized requests, it provides a complete HTTP
+
| Filter (** Processes data streams with filtering. The application
+
receives HTTP request information plus an additional
+
data stream from a file stored on the web server, and
+
generates a "filtered" version of the data as an HTTP
+
response. Both the file and the filter can be access
+
(** Request ID for multiplexing multiple requests over a single connection.
+
FastCGI supports multiplexing, allowing multiple concurrent requests
+
to be processed over a single transport connection. Each request is
+
identified by a unique request ID within the scope of that connection.
+
The Web server re-uses FastCGI request IDs; the application keeps track
+
of the current state of each request ID on a given transport connection.
+
Request IDs should be small integers to allow efficient tracking using
+
arrays rather than hash tables.
+
The value [0] is reserved for management records and is called the
+
(** Application-level status code.
+
When an application completes a request, it provides an application
+
status code similar to the exit status of a traditional CGI program.
+
A value of [0] indicates success, while non-zero values indicate
+
various error conditions.
+
The application sets the appStatus component to the status code that
+
the CGI program would have returned via the exit system call. *)
+
(** Protocol-level status codes.
+
In addition to application status, each request completion includes
+
a protocol-level status that indicates whether the request was
+
processed normally or rejected for protocol-related reasons.
+
These status codes allow the web server to understand why a request
+
was not processed and take appropriate action. *)
+
| Request_complete (** Normal end of request. The application successfully
+
processed the request and the appStatus field
+
indicates the application-level result. *)
+
| Cant_mpx_conn (** Rejecting a new request because the application
+
cannot multiplex connections. This happens when
+
a web server sends concurrent requests over one
+
connection to an application that processes only
+
one request at a time per connection. *)
+
| Overloaded (** Rejecting a new request because the application
+
is overloaded. This occurs when the application
+
runs out of some resource, such as database
+
connections or memory. *)
+
| Unknown_role (** Rejecting a new request because the requested
+
role is unknown to the application. This happens
+
when the web server specifies a role that the
+
application doesn't implement. *)
+
(** Connection flags for controlling connection behavior.
+
These flags are sent in Begin_request records to control how the
+
connection should be managed after the request completes. *)
+
type connection_flags = {
+
keep_conn : bool; (** Keep connection open after request completion.
+
If false, the application closes the connection after
+
responding to this request. If true, the application
+
does not close the connection after responding to this
+
request; the Web server retains responsibility for the
+
This flag enables connection reuse for better performance,
+
especially important for high-traffic applications. *)
+
(** {1 Record Types} *)
+
(** FastCGI record header.
+
Every FastCGI record begins with an 8-byte header that identifies
+
the record type, request ID, and content length. This fixed-length
+
prefix allows efficient parsing and proper demultiplexing of records.
+
A FastCGI record consists of a fixed-length prefix followed by a
+
variable number of content and padding bytes.
+
The header format is platform-independent and uses network byte order
+
for multi-byte integers. *)
+
version : int; (** Protocol version. Must be [1] for this specification.
+
Future versions may increment this value. *)
+
record_type : record_type; (** Type of this record, determining how to interpret
+
request_id : request_id; (** Request ID this record belongs to. Value [0] is
+
reserved for management records. *)
+
content_length : int; (** Number of bytes in the content data. Must be
+
between [0] and [65535]. *)
+
padding_length : int; (** Number of padding bytes following content.
+
Must be between [0] and [255]. Used for alignment. *)
+
(** Begin request record body.
+
This record marks the start of a new request and specifies the role
+
the application should play and connection management flags.
+
The Web server sends a FCGI_BEGIN_REQUEST record to start a request.
+
The record body contains the role and flags that control request
+
type begin_request_body = {
+
role : role; (** The role the web server expects the application
+
to play for this request. *)
+
flags : connection_flags; (** Flags controlling connection behavior after
+
(** End request record body.
+
This record marks the completion of a request and provides both
+
application-level and protocol-level status information.
+
The application sends a FCGI_END_REQUEST record to terminate a request,
+
either because the application has processed the request or because the
+
application has rejected the request. *)
+
type end_request_body = {
+
app_status : app_status; (** Application-level status code, similar to
+
a CGI program's exit status. *)
+
protocol_status : protocol_status; (** Protocol-level status indicating normal
+
completion or rejection reason. *)
+
(** Complete FastCGI record.
+
A complete record consists of the header, content data, and optional
+
padding. The content interpretation depends on the record type.
+
Records support padding to allow senders to keep data aligned for more
+
efficient processing. Experience with the X window system protocols shows
+
the performance benefit of such alignment. *)
+
header : record_header; (** Fixed 8-byte header with record metadata. *)
+
content : bytes; (** Variable-length content data. Length must match
+
header.content_length. *)
+
padding : bytes option; (** Optional padding data for alignment. Length must
+
match header.padding_length if present. *)
+
(** Name-value pair for parameters.
+
FastCGI uses a compact binary encoding for transmitting name-value pairs
+
such as CGI environment variables. This encoding supports both short
+
and long names/values efficiently.
+
FastCGI transmits a name-value pair as the length of the name, followed
+
by the length of the value, followed by the name, followed by the value.
+
Lengths of 127 bytes and less can be encoded in one byte, while longer
+
lengths are always encoded in four bytes. *)
+
type name_value_pair = {
+
name : string; (** Parameter name. For CGI compatibility, these are typically
+
uppercase environment variable names like "REQUEST_METHOD". *)
+
value : string; (** Parameter value. The value does not include a terminating
+
null byte in the FastCGI encoding. *)
+
(** {1 Request/Response Model} *)
+
(** Request context containing all information for a FastCGI request.
+
This high-level type aggregates all the information needed to process
+
a FastCGI request. It combines the protocol-level details (request ID,
+
role, flags) with the application data (parameters and input streams).
+
The request follows a two-level processing model: First, the protocol
+
multiplexes a single transport connection between several independent
+
FastCGI requests. Second, within each request the protocol provides
+
several independent data streams in each direction. *)
+
request_id : request_id; (** Unique identifier for this request within
+
the connection scope. Used for multiplexing. *)
+
role : role; (** The role this application should play for
+
this request (Responder, Authorizer, or Filter). *)
+
flags : connection_flags; (** Connection management flags from the web server. *)
+
params : (string * string) list; (** CGI-style environment variables transmitted
+
via FCGI_PARAMS records. These provide request
+
context like HTTP headers, server info, etc. *)
+
stdin : 'a Eio.Flow.source; (** Standard input stream, containing request body
+
data (equivalent to CGI stdin). For HTTP POST
+
requests, this contains the form data or payload. *)
+
data : 'a Eio.Flow.source option; (** Additional data stream, used only in Filter
+
role. Contains file data that needs to be
+
filtered. [None] for Responder and Authorizer. *)
+
(** Response builder for constructing FastCGI responses.
+
This type provides the output streams for sending response data back
+
to the web server. Following CGI conventions, it separates normal
+
output from error output.
+
Both stdout and stderr data pass over a single transport connection from
+
the application to the Web server, rather than requiring separate pipes
+
stdout : 'a Eio.Flow.sink; (** Standard output stream for response data.
+
In Responder role, this contains the HTTP
+
response including headers and body. *)
+
stderr : 'a Eio.Flow.sink; (** Standard error stream for logging and debugging.
+
All role protocols use the FCGI_STDERR stream
+
just the way stderr is used in conventional
+
applications programming: to report application-level
+
errors in an intelligible way. *)
+
(** Complete response with status.
+
When an application finishes processing a request, it must provide
+
both application-level and protocol-level status information. This
+
allows the web server to understand the outcome and take appropriate
+
This corresponds to the FCGI_END_REQUEST record sent by the application. *)
+
type response_result = {
+
app_status : app_status; (** Application exit status, equivalent to what
+
a CGI program would return via exit(). *)
+
protocol_status : protocol_status; (** Protocol-level completion status, indicating
+
normal completion or various rejection reasons. *)
+
(** {1 Protocol Constants} *)
+
(** Protocol version constant.
+
This constant represents FCGI_VERSION_1. This value should be used in
+
the version field of all record headers. *)
+
(** Standard file descriptor for FastCGI listening socket.
+
The Web server leaves a single file descriptor, FCGI_LISTENSOCK_FILENO,
+
open when the application begins execution. This descriptor refers to a
+
listening socket created by the Web server.
+
The value equals STDIN_FILENO (0). Applications can distinguish between
+
CGI and FastCGI invocation by calling getpeername() on this descriptor. *)
+
val listensock_fileno : int
+
(** {2 Record Type Constants}
+
These integer constants correspond to the record_type variants and are
+
used in the binary protocol encoding. These are the values transmitted
+
in the type field of record headers. *)
+
(** Value [1]. Starts a new request. *)
+
val fcgi_begin_request : int
+
(** Value [2]. Aborts an existing request. *)
+
val fcgi_abort_request : int
+
(** Value [3]. Completes a request. *)
+
val fcgi_end_request : int
+
(** Value [4]. Parameter name-value pairs. *)
+
(** Value [5]. Standard input data. *)
+
(** Value [6]. Standard output data. *)
+
(** Value [7]. Standard error data. *)
+
(** Value [8]. Additional data stream (Filter). *)
+
(** Value [9]. Query application variables. *)
+
val fcgi_get_values : int
+
(** Value [10]. Response to Get_values. *)
+
val fcgi_get_values_result : int
+
(** Value [11]. Unknown record type response. *)
+
val fcgi_unknown_type : int
+
These integer constants correspond to the role variants and are used
+
in Begin_request record bodies. These identify the role the web server
+
expects the application to play. *)
+
(** Value [1]. Handle HTTP requests and generate responses. *)
+
val fcgi_responder : int
+
(** Value [2]. Perform authorization decisions. *)
+
val fcgi_authorizer : int
+
(** Value [3]. Process data streams with filtering. *)
+
These constants are used in the flags field of Begin_request records
+
to control connection behavior. *)
+
(** Value [1]. Keep connection open after request.
+
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
+
val fcgi_keep_conn : int
+
(** {2 Protocol Limits}
+
These constants define the maximum sizes for various protocol elements,
+
ensuring compatibility and preventing buffer overflows. *)
+
(** Value [65535]. Maximum bytes in record content.
+
Between 0 and 65535 bytes of data, interpreted
+
according to the record type. *)
+
val max_content_length : int
+
(** Value [255]. Maximum bytes in record padding.
+
Between 0 and 255 bytes of data, which are ignored. *)
+
val max_padding_length : int
+
(** Value [8]. Fixed size of record headers.
+
Number of bytes in a FCGI_Header. Future versions
+
of the protocol will not reduce this number. *)
+
val header_length : int
+
(** {2 Management Record Variables}
+
These string constants identify the standard management variables that
+
can be queried using FCGI_GET_VALUES records. They allow the web server
+
to discover application capabilities.
+
The initial set provides information to help the server perform application
+
and connection management. *)
+
(** Variable name "FCGI_MAX_CONNS". The maximum number
+
of concurrent transport connections this application
+
will accept, e.g. "1" or "10". *)
+
val fcgi_max_conns : string
+
(** Variable name "FCGI_MAX_REQS". The maximum number
+
of concurrent requests this application will accept,
+
val fcgi_max_reqs : string
+
(** Variable name "FCGI_MPXS_CONNS". "0" if this
+
application does not multiplex connections (i.e.
+
handle concurrent requests over each connection),
+
val fcgi_mpxs_conns : string
anil.recoil.org