this repo has no description
more
+133
-1
+1
-1
CLAUDE.md
+1
-1
CLAUDE.md
···
94
94
95
95
# Software engineering
96
96
97
-
We will go through a multi step process to build this library. We are currently at STEP 2.
97
+
We will go through a multi step process to build this library.
98
98
99
99
1) we will generate OCaml interface files only, and no module implementations. The purpose here is to write and document the necessary type signatures. Once we generate these, we can check that they work with "dune build @check". Once that succeeds, we will build HTML documentation with "dune build @doc" in order to ensure the interfaces are reasonable.
100
100
+9
lib/fastcgi.mli
+9
lib/fastcgi.mli
···
1
+
(** FastCGI protocol implementation for OCaml using Eio.
2
+
3
+
This library provides a complete implementation of the FastCGI protocol
4
+
for building high-performance web applications in OCaml. *)
5
+
6
+
(** {1 Core Protocol Components} *)
7
+
8
+
(** Record-level protocol handling *)
9
+
module Record = Fastcgi_record
+123
lib/fastcgi_record.mli
+123
lib/fastcgi_record.mli
···
1
+
(** FastCGI record handling for parsing and creating protocol messages.
2
+
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. *)
7
+
8
+
(** {1 Record Structure} *)
9
+
10
+
(** FastCGI protocol version *)
11
+
type version = int
12
+
13
+
(** Record types define the purpose and interpretation of record content *)
14
+
type record =
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 *)
26
+
27
+
(** [record_type_to_int rt] converts record type to its protocol integer value *)
28
+
val record_to_int : record -> int
29
+
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
33
+
34
+
(** [pp_record ppf rt] pretty-prints a record type *)
35
+
val pp_record : Format.formatter -> record -> unit
36
+
37
+
(** Request identifier for multiplexing multiple requests over one connection.
38
+
Request ID 0 is reserved for management records. *)
39
+
type request_id = int
40
+
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. *)
44
+
type t = {
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 *)
49
+
}
50
+
51
+
(** [pp ppf record] pretty-prints a FastCGI record *)
52
+
val pp : Format.formatter -> t -> unit
53
+
54
+
(** {1 Record Operations} *)
55
+
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
61
+
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
67
+
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
73
+
74
+
(** {1 Key-Value Pairs} *)
75
+
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). *)
79
+
80
+
module KV : sig
81
+
(** Type for key-value pair collections *)
82
+
type t
83
+
84
+
(** [empty] creates an empty key-value pair collection *)
85
+
val empty : t
86
+
87
+
(** [add name value pairs] adds a key-value pair to the collection *)
88
+
val add : string -> string -> t -> t
89
+
90
+
(** [remove name pairs] removes all pairs with the given key *)
91
+
val remove : string -> t -> t
92
+
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
96
+
97
+
(** [find_opt name pairs] returns Some value or None if not found *)
98
+
val find_opt : string -> t -> string option
99
+
100
+
(** [to_seq pairs] converts to a sequence of (key, value) tuples *)
101
+
val to_seq : t -> (string * string) Seq.t
102
+
103
+
(** [of_seq pairs] creates from a sequence of (key, value) tuples *)
104
+
val of_seq : (string * string) Seq.t -> t
105
+
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
110
+
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
114
+
115
+
(** [encode pairs] returns the encoded byte string representation *)
116
+
val encode : t -> string
117
+
118
+
(** [decode content] parses encoded key-value pairs from a string *)
119
+
val decode : string -> t
120
+
121
+
(** [pp ppf pairs] pretty-prints key-value pairs *)
122
+
val pp : Format.formatter -> t -> unit
123
+
end