FastCGI implementation in OCaml
anil.recoil.org
1(** FastCGI request handling with functional state management and Eio flows.
2
3 This module provides a functional approach to FastCGI request processing,
4 using immutable data structures and higher-order functions. Input and output
5 are handled through Eio flows for efficient streaming I/O. *)
6
7(** {1 Request Roles} *)
8
9(** FastCGI application roles defining request processing behavior *)
10type role =
11 | Responder (** Standard CGI-like request/response processing *)
12 | Authorizer (** Authorization decision with optional variables *)
13 | Filter (** Content filtering with additional data stream *)
14
15(** [pp_role ppf role] pretty-prints a FastCGI role *)
16val pp_role : Format.formatter -> role -> unit
17
18(** [role_of_begin_request record] extracts role from BEGIN_REQUEST record *)
19val role_of_begin_request : Fastcgi_record.t -> (role, string) result
20
21(** {1 Request Context} *)
22
23(** Immutable request context containing all request data *)
24type t = private {
25 request_id : Fastcgi_record.request_id; (** Request identifier *)
26 role : role; (** Application role *)
27 keep_conn : bool; (** Connection keep-alive flag *)
28 params : Fastcgi_record.KV.t; (** Environment parameters *)
29 stdin_data : string; (** Complete STDIN content *)
30 data_stream : string option; (** DATA stream for Filter role *)
31}
32
33(** [pp ppf request] pretty-prints a request context *)
34val pp : Format.formatter -> t -> unit
35
36(** [create record] creates request context from BEGIN_REQUEST record *)
37val create : Fastcgi_record.t -> (t, string) result
38
39(** {1 Stream Processing} *)
40
41(** [read_params buf_read] reads PARAMS stream from buf_read until empty record.
42 Returns the accumulated parameters. *)
43val read_params : Eio.Buf_read.t -> (Fastcgi_record.KV.t, string) result
44
45(** [read_stdin buf_read] reads STDIN stream from buf_read until empty record.
46 Returns the accumulated data. *)
47val read_stdin : Eio.Buf_read.t -> (string, string) result
48
49(** [read_data buf_read] reads DATA stream from buf_read until empty record.
50 Returns the accumulated data for Filter role. *)
51val read_data : Eio.Buf_read.t -> (string, string) result
52
53(** [read_request buf_read] reads a complete FastCGI request from buf_read.
54 Processes BEGIN_REQUEST, PARAMS, STDIN, and DATA records until complete.
55 Returns the populated request context. *)
56val read_request : Eio.Buf_read.t -> (t, string) result
57
58(** {1 Response Generation} *)
59
60(** Response status codes *)
61type app_status = int
62type protocol_status =
63 | Request_complete
64 | Cant_mpx_conn
65 | Overloaded
66 | Unknown_role
67
68(** [pp_protocol_status ppf status] pretty-prints protocol status *)
69val pp_protocol_status : Format.formatter -> protocol_status -> unit
70
71(** [write_stdout_records buf_write request_id content] writes STDOUT stream records.
72 Splits content into chunks and writes with terminator. *)
73val write_stdout_records : Eio.Buf_write.t -> Fastcgi_record.request_id -> string -> unit
74
75(** [write_stderr_records buf_write request_id content] writes STDERR stream records.
76 Splits content into chunks and writes with terminator. *)
77val write_stderr_records : Eio.Buf_write.t -> Fastcgi_record.request_id -> string -> unit
78
79(** [write_end_request buf_write request_id app_status protocol_status] writes END_REQUEST record. *)
80val write_end_request : Eio.Buf_write.t -> Fastcgi_record.request_id -> app_status -> protocol_status -> unit
81
82
83(** {1 Utilities} *)
84
85(** [is_stream_terminator record] returns true if record terminates a stream *)
86val is_stream_terminator : Fastcgi_record.t -> bool
87
88(** [stream_records_to_string records] concatenates content from stream records *)
89val stream_records_to_string : Fastcgi_record.t list -> string
90
91(** [string_to_stream_records ~request_id ~record_type content] converts string to stream records *)
92val string_to_stream_records :
93 request_id:Fastcgi_record.request_id ->
94 record_type:Fastcgi_record.record ->
95 string -> Fastcgi_record.t list
96
97