···
1
+
(** FastCGI record handling for parsing and creating protocol messages.
3
+
This module provides the core functionality for handling FastCGI records,
4
+
which are the fundamental units of communication in the FastCGI protocol.
5
+
Records multiplex multiple requests over a single connection and provide
6
+
independent data streams within each request. *)
8
+
(** {1 Record Structure} *)
10
+
(** FastCGI protocol version *)
13
+
(** Record types define the purpose and interpretation of record content *)
15
+
| Begin_request (** Start a new FastCGI request *)
16
+
| Abort_request (** Abort an existing request *)
17
+
| End_request (** Terminate a request *)
18
+
| Params (** Name-value pairs (environment variables) *)
19
+
| Stdin (** Standard input data stream *)
20
+
| Stdout (** Standard output data stream *)
21
+
| Stderr (** Standard error data stream *)
22
+
| Data (** Additional data stream for Filter role *)
23
+
| Get_values (** Query application capabilities *)
24
+
| Get_values_result (** Response to capability query *)
25
+
| Unknown_type (** Unknown record type response *)
27
+
(** [record_type_to_int rt] converts record type to its protocol integer value *)
28
+
val record_to_int : record -> int
30
+
(** [record_type_of_int i] converts protocol integer to record type.
31
+
Raises Invalid_argument for unknown values. *)
32
+
val record_of_int : int -> record
34
+
(** [pp_record ppf rt] pretty-prints a record type *)
35
+
val pp_record : Format.formatter -> record -> unit
37
+
(** Request identifier for multiplexing multiple requests over one connection.
38
+
Request ID 0 is reserved for management records. *)
39
+
type request_id = int
41
+
(** A complete FastCGI record containing header and content.
42
+
Records consist of an 8-byte fixed header followed by variable-length
43
+
content and optional padding for alignment. *)
45
+
version : version; (** Protocol version (always 1) *)
46
+
record_type : record; (** Type of this record *)
47
+
request_id : request_id; (** Request identifier *)
48
+
content : string; (** Record content data *)
51
+
(** [pp ppf record] pretty-prints a FastCGI record *)
52
+
val pp : Format.formatter -> t -> unit
54
+
(** {1 Record Operations} *)
56
+
(** [read buf_read] reads a complete FastCGI record from the input buffer.
57
+
Returns the parsed record or raises an exception if the record is malformed
58
+
or if there's insufficient data. The padding is automatically handled and
59
+
discarded during parsing. *)
60
+
val read : Eio.Buf_read.t -> t
62
+
(** [write buf_write record] writes a FastCGI record to the output buffer.
63
+
The record header is automatically constructed from the record fields,
64
+
and appropriate padding is added to align the record on 8-byte boundaries
65
+
for optimal performance. *)
66
+
val write : Eio.Buf_write.t -> t -> unit
68
+
(** [create ~version ~record ~request_id ~content] creates a new record
69
+
with the specified parameters. The content length is automatically
70
+
calculated from the content string. *)
71
+
val create : version:version -> record:record ->
72
+
request_id:request_id -> content:string -> t
74
+
(** {1 Key-Value Pairs} *)
76
+
(** Key-value pairs are used to transmit environment variables and other
77
+
key-value data in FCGI_PARAMS and other record types. The FastCGI protocol
78
+
uses a specific encoding where lengths are variable-width (1 or 4 bytes). *)
81
+
(** Type for key-value pair collections *)
84
+
(** [empty] creates an empty key-value pair collection *)
87
+
(** [add name value pairs] adds a key-value pair to the collection *)
88
+
val add : string -> string -> t -> t
90
+
(** [remove name pairs] removes all pairs with the given key *)
91
+
val remove : string -> t -> t
93
+
(** [find name pairs] returns the value associated with the given key.
94
+
Raises Not_found if the key is not present. *)
95
+
val find : string -> t -> string
97
+
(** [find_opt name pairs] returns Some value or None if not found *)
98
+
val find_opt : string -> t -> string option
100
+
(** [to_seq pairs] converts to a sequence of (key, value) tuples *)
101
+
val to_seq : t -> (string * string) Seq.t
103
+
(** [of_seq pairs] creates from a sequence of (key, value) tuples *)
104
+
val of_seq : (string * string) Seq.t -> t
106
+
(** [read buf_read] reads key-value pairs from a buffer.
107
+
Handles the FastCGI variable-length encoding where lengths ≤ 127 bytes
108
+
use 1 byte, longer lengths use 4 bytes with the high bit set. *)
109
+
val read : Eio.Buf_read.t -> t
111
+
(** [write buf_write pairs] writes key-value pairs to a buffer using
112
+
the FastCGI encoding format *)
113
+
val write : Eio.Buf_write.t -> t -> unit
115
+
(** [encode pairs] returns the encoded byte string representation *)
116
+
val encode : t -> string
118
+
(** [decode content] parses encoded key-value pairs from a string *)
119
+
val decode : string -> t
121
+
(** [pp ppf pairs] pretty-prints key-value pairs *)
122
+
val pp : Format.formatter -> t -> unit
anil.recoil.org