···
+
(** FastCGI record handling for parsing and creating protocol messages.
+
This module provides the core functionality for handling FastCGI records,
+
which are the fundamental units of communication in the FastCGI protocol.
+
Records multiplex multiple requests over a single connection and provide
+
independent data streams within each request. *)
+
(** {1 Record Structure} *)
+
(** FastCGI protocol version *)
+
(** Record types define the purpose and interpretation of record content *)
+
| Begin_request (** Start a new FastCGI request *)
+
| Abort_request (** Abort an existing request *)
+
| End_request (** Terminate a request *)
+
| Params (** Name-value pairs (environment variables) *)
+
| Stdin (** Standard input data stream *)
+
| Stdout (** Standard output data stream *)
+
| Stderr (** Standard error data stream *)
+
| Data (** Additional data stream for Filter role *)
+
| Get_values (** Query application capabilities *)
+
| Get_values_result (** Response to capability query *)
+
| Unknown_type (** Unknown record type response *)
+
(** [record_type_to_int rt] converts record type to its protocol integer value *)
+
val record_to_int : record -> int
+
(** [record_type_of_int i] converts protocol integer to record type.
+
Raises Invalid_argument for unknown values. *)
+
val record_of_int : int -> record
+
(** [pp_record ppf rt] pretty-prints a record type *)
+
val pp_record : Format.formatter -> record -> unit
+
(** Request identifier for multiplexing multiple requests over one connection.
+
Request ID 0 is reserved for management records. *)
+
(** A complete FastCGI record containing header and content.
+
Records consist of an 8-byte fixed header followed by variable-length
+
content and optional padding for alignment. *)
+
version : version; (** Protocol version (always 1) *)
+
record_type : record; (** Type of this record *)
+
request_id : request_id; (** Request identifier *)
+
content : string; (** Record content data *)
+
(** [pp ppf record] pretty-prints a FastCGI record *)
+
val pp : Format.formatter -> t -> unit
+
(** {1 Record Operations} *)
+
(** [read buf_read] reads a complete FastCGI record from the input buffer.
+
Returns the parsed record or raises an exception if the record is malformed
+
or if there's insufficient data. The padding is automatically handled and
+
discarded during parsing. *)
+
val read : Eio.Buf_read.t -> t
+
(** [write buf_write record] writes a FastCGI record to the output buffer.
+
The record header is automatically constructed from the record fields,
+
and appropriate padding is added to align the record on 8-byte boundaries
+
for optimal performance. *)
+
val write : Eio.Buf_write.t -> t -> unit
+
(** [create ~version ~record ~request_id ~content] creates a new record
+
with the specified parameters. The content length is automatically
+
calculated from the content string. *)
+
val create : version:version -> record:record ->
+
request_id:request_id -> content:string -> t
+
(** {1 Key-Value Pairs} *)
+
(** Key-value pairs are used to transmit environment variables and other
+
key-value data in FCGI_PARAMS and other record types. The FastCGI protocol
+
uses a specific encoding where lengths are variable-width (1 or 4 bytes). *)
+
(** Type for key-value pair collections *)
+
(** [empty] creates an empty key-value pair collection *)
+
(** [add name value pairs] adds a key-value pair to the collection *)
+
val add : string -> string -> t -> t
+
(** [remove name pairs] removes all pairs with the given key *)
+
val remove : string -> t -> t
+
(** [find name pairs] returns the value associated with the given key.
+
Raises Not_found if the key is not present. *)
+
val find : string -> t -> string
+
(** [find_opt name pairs] returns Some value or None if not found *)
+
val find_opt : string -> t -> string option
+
(** [to_seq pairs] converts to a sequence of (key, value) tuples *)
+
val to_seq : t -> (string * string) Seq.t
+
(** [of_seq pairs] creates from a sequence of (key, value) tuples *)
+
val of_seq : (string * string) Seq.t -> t
+
(** [read buf_read] reads key-value pairs from a buffer.
+
Handles the FastCGI variable-length encoding where lengths ≤ 127 bytes
+
use 1 byte, longer lengths use 4 bytes with the high bit set. *)
+
val read : Eio.Buf_read.t -> t
+
(** [write buf_write pairs] writes key-value pairs to a buffer using
+
the FastCGI encoding format *)
+
val write : Eio.Buf_write.t -> t -> unit
+
(** [encode pairs] returns the encoded byte string representation *)
+
val encode : t -> string
+
(** [decode content] parses encoded key-value pairs from a string *)
+
val decode : string -> t
+
(** [pp ppf pairs] pretty-prints key-value pairs *)
+
val pp : Format.formatter -> t -> unit
anil.recoil.org