commit e47b5d15087a75cab5f3ca576c6d7bd83c8da174 · anil.recoil.org/ocaml-fastcgi

-43

examples/basic_filter.ml

···

       1
       1
       -
       (* Basic filter that uppercases text content *)

     

       2
       2
       -
       

     

       3
       3
       -
       open Fastcgi

     

       4
       4
       -
       

     

       5
       5
       -
       let uppercase_filter_logic filter_req response =

     

       6
       6
       -
         let input = filter_req.Filter.data_stream in

     

       7
       7
       -
         let output = response.stdout in

     

       8
       8
       -
         

     

       9
       9
       -
         (* Simple text transformation: read input and write uppercase output *)

     

       10
       10
       -
         let buffer = Cstruct.create 4096 in

     

       11
       11
       -
         let rec process () =

     

       12
       12
       -
           try

     

       13
       13
       -
             let n = Eio.Flow.single_read input buffer in

     

       14
       14
       -
             if n > 0 then begin

     

       15
       15
       -
               let text = Cstruct.to_string ~len:n buffer in

     

       16
       16
       -
               let uppercase_text = String.uppercase_ascii text in

     

       17
       17
       -
               Eio.Flow.copy_string uppercase_text output;

     

       18
       18
       -
               process ()

     

       19
       19
       -
             end

     

       20
       20
       -
           with

     

       21
       21
       -
           | End_of_file -> ()

     

       22
       22
       -
         in

     

       23
       23
       -
         process ()

     

       24
       24
       -
       

     

       25
       25
       -
       let filter_handler request response =

     

       26
       26
       -
         let filter_req = Filter.request_of_fastcgi request in

     

       27
       27
       -
         

     

       28
       28
       -
         (* Write HTTP headers *)

     

       29
       29
       -
         Eio.Flow.copy_string "Status: 200 OK\r\n" response.stdout;

     

       30
       30
       -
         Eio.Flow.copy_string "Content-Type: text/plain\r\n" response.stdout;

     

       31
       31
       -
         Eio.Flow.copy_string "\r\n" response.stdout;

     

       32
       32
       -
         

     

       33
       33
       -
         (* Process the data stream *)

     

       34
       34
       -
         uppercase_filter_logic filter_req response;

     

       35
       35
       -
         

     

       36
       36
       -
         { app_status = 0; protocol_status = Request_complete }

     

       37
       37
       -
       

     

       38
       38
       -
       let () = Eio_main.run @@ fun env ->

     

       39
       39
       -
         let net = Eio.Stdenv.net env in

     

       40
       40
       -
         Eio.Switch.run @@ fun sw ->

     

       41
       41
       -
         Server.run_default ~sw ~net

     

       42
       42
       -
           ~handler:(Handler.Filter filter_handler)

     

       43
       43
       -
           ~listen_address:(`Tcp ("127.0.0.1", 9003))

-4

examples/dune

···

       1
       1
       -
       (executables

     

       2
       2
       -
        (public_names hello_responder echo_responder simple_authorizer basic_filter)

     

       3
       3
       -
        (names hello_responder echo_responder simple_authorizer basic_filter)

     

       4
       4
       -
        (libraries fastcgi eio_main cstruct))

-40

examples/echo_responder.ml

···

       1
       1
       -
       (* Echo server that shows request information *)

     

       2
       2
       -
       

     

       3
       3
       -
       open Fastcgi

     

       4
       4
       -
       

     

       5
       5
       -
       let echo_handler request response =

     

       6
       6
       -
         let http_req = Responder.request_of_fastcgi request in

     

       7
       7
       -
         let http_resp = Responder.response_of_fastcgi response in

     

       8
       8
       -
         

     

       9
       9
       -
         http_resp.write_status 200;

     

       10
       10
       -
         http_resp.write_header "Content-Type" "text/html";

     

       11
       11
       -
         

     

       12
       12
       -
         http_resp.write_body "<h1>FastCGI Echo Server</h1>";

     

       13
       13
       -
         http_resp.write_body ("<p><strong>Method:</strong> " ^ http_req.method_ ^ "</p>");

     

       14
       14
       -
         http_resp.write_body ("<p><strong>URI:</strong> " ^ http_req.uri ^ "</p>");

     

       15
       15
       -
         http_resp.write_body ("<p><strong>Query String:</strong> " ^ http_req.query_string ^ "</p>");

     

       16
       16
       -
         

     

       17
       17
       -
         (match http_req.content_type with

     

       18
       18
       -
          | Some ct -> http_resp.write_body ("<p><strong>Content-Type:</strong> " ^ ct ^ "</p>")

     

       19
       19
       -
          | None -> ());

     

       20
       20
       -
          

     

       21
       21
       -
         (match http_req.content_length with

     

       22
       22
       -
          | Some cl -> http_resp.write_body ("<p><strong>Content-Length:</strong> " ^ string_of_int cl ^ "</p>")

     

       23
       23
       -
          | None -> ());

     

       24
       24
       -
         

     

       25
       25
       -
         http_resp.write_body "<h2>Headers:</h2><ul>";

     

       26
       26
       -
         List.iter (fun (name, value) ->

     

       27
       27
       -
           http_resp.write_body ("<li><strong>" ^ name ^ ":</strong> " ^ value ^ "</li>")

     

       28
       28
       -
         ) http_req.headers;

     

       29
       29
       -
         http_resp.write_body "</ul>";

     

       30
       30
       -
         

     

       31
       31
       -
         http_resp.finish ();

     

       32
       32
       -
         

     

       33
       33
       -
         { app_status = 0; protocol_status = Request_complete }

     

       34
       34
       -
       

     

       35
       35
       -
       let () = Eio_main.run @@ fun env ->

     

       36
       36
       -
         let net = Eio.Stdenv.net env in

     

       37
       37
       -
         Eio.Switch.run @@ fun sw ->

     

       38
       38
       -
         Server.run_default ~sw ~net

     

       39
       39
       -
           ~handler:(Handler.Responder echo_handler)

     

       40
       40
       -
           ~listen_address:(`Tcp ("127.0.0.1", 9001))

-22

examples/hello_responder.ml

···

       1
       1
       -
       (* Simple Hello World FastCGI Responder application *)

     

       2
       2
       -
       

     

       3
       3
       -
       open Fastcgi

     

       4
       4
       -
       

     

       5
       5
       -
       let hello_handler request response =

     

       6
       6
       -
         let _http_req = Responder.request_of_fastcgi request in

     

       7
       7
       -
         let http_resp = Responder.response_of_fastcgi response in

     

       8
       8
       -
         

     

       9
       9
       -
         http_resp.write_status 200;

     

       10
       10
       -
         http_resp.write_header "Content-Type" "text/html";

     

       11
       11
       -
         http_resp.write_body "<h1>Hello, FastCGI!</h1>";

     

       12
       12
       -
         http_resp.write_body "<p>This is a simple FastCGI responder application.</p>";

     

       13
       13
       -
         http_resp.finish ();

     

       14
       14
       -
         

     

       15
       15
       -
         { app_status = 0; protocol_status = Request_complete }

     

       16
       16
       -
       

     

       17
       17
       -
       let () = Eio_main.run @@ fun env ->

     

       18
       18
       -
         let net = Eio.Stdenv.net env in

     

       19
       19
       -
         Eio.Switch.run @@ fun sw ->

     

       20
       20
       -
         Server.run_default ~sw ~net

     

       21
       21
       -
           ~handler:(Handler.Responder hello_handler)

     

       22
       22
       -
           ~listen_address:(`Tcp ("127.0.0.1", 9000))

-29

examples/simple_authorizer.ml

···

       1
       1
       -
       (* Simple authorization server *)

     

       2
       2
       -
       

     

       3
       3
       -
       open Fastcgi

     

       4
       4
       -
       

     

       5
       5
       -
       let auth_logic auth_req =

     

       6
       6
       -
         (* Simple authorization: allow only GET requests to /public/* paths *)

     

       7
       7
       -
         match auth_req.Authorizer.method_, auth_req.uri with

     

       8
       8
       -
         | "GET", uri when String.starts_with ~prefix:"/public/" uri ->

     

       9
       9
       -
             Authorizer.Authorized [("USER_AUTHORIZED", "true"); ("ACCESS_LEVEL", "public")]

     

       10
       10
       -
         | "GET", "/login" ->

     

       11
       11
       -
             Authorizer.Authorized [("LOGIN_PAGE", "true")]

     

       12
       12
       -
         | _ ->

     

       13
       13
       -
             Authorizer.Unauthorized {

     

       14
       14
       -
               status = 403;

     

       15
       15
       -
               headers = [("Content-Type", "text/html")];

     

       16
       16
       -
               body = "<h1>403 Forbidden</h1><p>Access denied. Only GET requests to /public/* are allowed.</p>";

     

       17
       17
       -
             }

     

       18
       18
       -
       

     

       19
       19
       -
       let auth_handler request response =

     

       20
       20
       -
         let auth_req = Authorizer.request_of_fastcgi request in

     

       21
       21
       -
         let result = auth_logic auth_req in

     

       22
       22
       -
         Authorizer.response_of_result result response

     

       23
       23
       -
       

     

       24
       24
       -
       let () = Eio_main.run @@ fun env ->

     

       25
       25
       -
         let net = Eio.Stdenv.net env in

     

       26
       26
       -
         Eio.Switch.run @@ fun sw ->

     

       27
       27
       -
         Server.run_default ~sw ~net

     

       28
       28
       -
           ~handler:(Handler.Authorizer auth_handler)

     

       29
       29
       -
           ~listen_address:(`Tcp ("127.0.0.1", 9002))

+3 -10

lib/dune

···

       3
       3
        
        (name fastcgi)

     

       4
       4
        
        (libraries eio)

     

       5
       5
        
        (modules

     

       6
       6
       -
         fastcgi_types

     

       7
       6
        
         fastcgi

     

       8
       8
       -
         fastcgi_protocol

     

       9
       9
       -
         fastcgi_responder

     

       10
       10
       -
         fastcgi_authorizer

     

       11
       11
       -
         fastcgi_filter)

     

       7
       7
       +
        )

     

       12
       8
        
        (modules_without_implementation

     

       13
       13
       -
         fastcgi_types

     

       14
       9
        
         fastcgi

     

       15
       15
       -
         fastcgi_protocol

     

       16
       16
       -
         fastcgi_responder

     

       17
       17
       -
         fastcgi_authorizer

     

       18
       18
       -
         fastcgi_filter))
     

       10
       10
       +
        )

     

       11
       11
       +
       )

-389

lib/fastcgi.mli

···

       1
       1
       -
       (** FastCGI protocol implementation for OCaml using Eio.

     

       2
       2
       -
       

     

       3
       3
       -
           This library provides a type-safe, high-performance implementation of the

     

       4
       4
       -
           FastCGI protocol using OCaml's Eio effects-based IO library. It supports

     

       5
       5
       -
           all three FastCGI roles: Responder, Authorizer, and Filter.

     

       6
       6
       -
       

     

       7
       7
       -
           FastCGI is an open extension to CGI that provides high performance for all

     

       8
       8
       -
           Internet applications without the penalties of Web server APIs. Unlike

     

       9
       9
       -
           traditional CGI programs that are started for each request, FastCGI

     

       10
       10
       -
           applications are long-lived processes that can handle multiple requests

     

       11
       11
       -
           over persistent connections.

     

       12
       12
       -
       

     

       13
       13
       -
           The library follows Eio conventions for structured concurrency,

     

       14
       14
       -
           capability-based security, and resource management. All network I/O is

     

       15
       15
       -
           performed using Eio's effects system, enabling high-performance concurrent

     

       16
       16
       -
           request processing.

     

       17
       17
       -
       

     

       18
       18
       -
           {2 Key Features}

     

       19
       19
       -
           

     

       20
       20
       -
           - {b Type Safety}: Leverages OCaml's type system to prevent protocol errors

     

       21
       21
       -
           - {b High Performance}: Connection multiplexing and keep-alive for efficiency  

     

       22
       22
       -
           - {b Structured Concurrency}: Automatic resource cleanup using Eio switches

     

       23
       23
       -
           - {b All FastCGI Roles}: Complete support for Responder, Authorizer, and Filter

     

       24
       24
       -
           - {b Standards Compliant}: Full implementation of FastCGI Protocol 1.0

     

       25
       25
       -
       

     

       26
       26
       -
           {2 Usage Example}

     

       27
       27
       -
       

     

       28
       28
       -
           {[

     

       29
       29
       -
             let hello_handler request response =

     

       30
       30
       -
               let http_req = Responder.request_of_fastcgi request in

     

       31
       31
       -
               let http_resp = Responder.response_of_fastcgi response in

     

       32
       32
       -
               

     

       33
       33
       -
               http_resp.write_status 200;

     

       34
       34
       -
               http_resp.write_header "Content-Type" "text/html";

     

       35
       35
       -
               http_resp.write_body "<h1>Hello, FastCGI!</h1>";

     

       36
       36
       -
               http_resp.finish ();

     

       37
       37
       -
               

     

       38
       38
       -
               { app_status = 0; protocol_status = Request_complete }

     

       39
       39
       -
       

     

       40
       40
       -
             let () = Eio_main.run @@ fun env ->

     

       41
       41
       -
               let net = Eio.Stdenv.net env in

     

       42
       42
       -
               Switch.run @@ fun sw ->

     

       43
       43
       -
               Server.run_default ~sw ~net 

     

       44
       44
       -
                 ~handler:(Handler.Responder hello_handler)

     

       45
       45
       -
                 ~listen_address:(`Tcp (Eio.Net.Sockaddr.stream, 9000))

     

       46
       46
       -
           ]}

     

       47
       47
       -
       

     

       48
       48
       -
           {2 References}

     

       49
       49
       -
           

     

       50
       50
       -
           - {{:https://github.com/ocaml-multicore/eio} Eio Documentation} *)

     

       51
       51
       -
       

     

       52
       52
       -
       (** {1 Core Types} *)

     

       53
       53
       -
       

     

       54
       54
       -
       (** Re-export core types from Fastcgi_types.

     

       55
       55
       -
           

     

       56
       56
       -
           This includes all the fundamental FastCGI protocol types such as

     

       57
       57
       -
           [record_type], [role], [request], [response], and protocol constants.

     

       58
       58
       -
           This includes all the fundamental FastCGI protocol types. *)

     

       59
       59
       -
       include module type of Fastcgi_types

     

       60
       60
       -
       

     

       61
       61
       -
       (** {1 Protocol Implementation} *)

     

       62
       62
       -
       

     

       63
       63
       -
       (** Wire protocol parsing and serialization. *)

     

       64
       64
       -
       module Protocol = Fastcgi_protocol

     

       65
       65
       -
       

     

       66
       66
       -
       (** {1 Role-Specific Implementations} *)

     

       67
       67
       -
       

     

       68
       68
       -
       (** Responder role implementation. *)

     

       69
       69
       -
       module Responder = Fastcgi_responder

     

       70
       70
       -
       

     

       71
       71
       -
       (** Authorizer role implementation. *)

     

       72
       72
       -
       module Authorizer = Fastcgi_authorizer

     

       73
       73
       -
       

     

       74
       74
       -
       (** Filter role implementation. *)

     

       75
       75
       -
       module Filter = Fastcgi_filter

     

       76
       76
       -
       

     

       77
       77
       -
       (** {1 Application Interface} *)

     

       78
       78
       -
       

     

       79
       79
       -
       (** Application handler signatures.

     

       80
       80
       -
           

     

       81
       81
       -
           This module defines the core handler types that applications implement

     

       82
       82
       -
           to process FastCGI requests. Each handler type corresponds to one of

     

       83
       83
       -
           the three FastCGI roles: Responder, Authorizer, and Filter. *)

     

       84
       84
       -
       module Handler : sig

     

       85
       85
       -
         (** Responder handler: process HTTP request and generate response.

     

       86
       86
       -
             

     

       87
       87
       -
             This is the most common handler type, equivalent to traditional CGI.

     

       88
       88
       -
             A Responder FastCGI application has the same purpose as a CGI/1.1 program:

     

       89
       89
       -
             it receives all the information associated with an HTTP request and generates

     

       90
       90
       -
             an HTTP response.

     

       91
       91
       -
             

     

       92
       92
       -
             @param request Complete FastCGI request with parameters and input streams

     

       93
       93
       -
             @param response Output streams for writing response data

     

       94
       94
       -
             @return Response result with application and protocol status *)

     

       95
       95
       -
         type 'a responder = 'a request -> 'a response -> response_result

     

       96
       96
       -
       

     

       97
       97
       -
         (** Authorizer handler: make authorization decision.

     

       98
       98
       -
             

     

       99
       99
       -
             An Authorizer FastCGI application receives all the information associated

     

       100
       100
       -
             with an HTTP request and generates an authorized/unauthorized decision.

     

       101
       101
       -
             In case of an authorized decision, the Authorizer can also associate

     

       102
       102
       -
             name-value pairs with the HTTP request.

     

       103
       103
       -
             

     

       104
       104
       -
             @param request FastCGI request with authentication context

     

       105
       105
       -
             @param response Output streams for authorization response

     

       106
       106
       -
             @return Response result indicating authorization decision *)

     

       107
       107
       -
         type 'a authorizer = 'a request -> 'a response -> response_result

     

       108
       108
       -
       

     

       109
       109
       -
         (** Filter handler: process data stream with filtering.

     

       110
       110
       -
             

     

       111
       111
       -
             A Filter FastCGI application receives all the information associated

     

       112
       112
       -
             with an HTTP request, plus an extra stream of data from a file stored

     

       113
       113
       -
             on the Web server, and generates a 'filtered' version of the data stream

     

       114
       114
       -
             as an HTTP response.

     

       115
       115
       -
             

     

       116
       116
       -
             @param request FastCGI request including both HTTP context and file data

     

       117
       117
       -
             @param response Output streams for filtered response

     

       118
       118
       -
             @return Response result with filtered content status *)

     

       119
       119
       -
         type 'a filter = 'a request -> 'a response -> response_result

     

       120
       120
       -
       

     

       121
       121
       -
         (** Generic handler that can handle any role.

     

       122
       122
       -
             

     

       123
       123
       -
             This variant type allows applications to support multiple roles or

     

       124
       124
       -
             to be configured at runtime for different roles. The web server

     

       125
       125
       -
             specifies the desired role in each Begin_request record. *)

     

       126
       126
       -
         type 'a handler =

     

       127
       127
       -
           | Responder of 'a responder   (** Handle HTTP requests and responses *)

     

       128
       128
       -
           | Authorizer of 'a authorizer (** Handle authorization decisions *)

     

       129
       129
       -
           | Filter of 'a filter         (** Handle data filtering *)

     

       130
       130
       -
       end

     

       131
       131
       -
       

     

       132
       132
       -
       (** Application configuration.

     

       133
       133
       -
           

     

       134
       134
       -
           This type encapsulates all the settings needed to configure a FastCGI

     

       135
       135
       -
           application's behavior. It includes both resource limits and the

     

       136
       136
       -
           application logic (handler function).

     

       137
       137
       -
           

     

       138
       138
       -
           The configuration values affect how the application responds to

     

       139
       139
       -
           FCGI_GET_VALUES management queries from the web server. *)

     

       140
       140
       -
       type 'a app_config = {

     

       141
       141
       -
         max_connections : int;        (** Maximum concurrent transport connections

     

       142
       142
       -
                                           this application will accept. Corresponds to

     

       143
       143
       -
                                           FCGI_MAX_CONNS management variable. *)

     

       144
       144
       -
         max_requests : int;          (** Maximum concurrent requests this application

     

       145
       145
       -
                                          will accept across all connections. Corresponds

     

       146
       146
       -
                                          to FCGI_MAX_REQS management variable. *)

     

       147
       147
       -
         multiplex_connections : bool; (** Whether this application can multiplex

     

       148
       148
       -
                                           connections (handle concurrent requests over

     

       149
       149
       -
                                           each connection). Corresponds to FCGI_MPXS_CONNS

     

       150
       150
       -
                                           management variable. *)

     

       151
       151
       -
         handler : 'a Handler.handler; (** Application request handler that implements

     

       152
       152
       -
                                           the core application logic. *)

     

       153
       153
       -
       }

     

       154
       154
       -
       

     

       155
       155
       -
       (** {1 Connection Management} *)

     

       156
       156
       -
       

     

       157
       157
       -
       (** Connection manager for handling FastCGI protocol.

     

       158
       158
       -
           

     

       159
       159
       -
           This module provides low-level connection management for FastCGI applications.

     

       160
       160
       -
           It handles the binary protocol details, record parsing/serialization, and

     

       161
       161
       -
           request multiplexing over individual transport connections.

     

       162
       162
       -
           

     

       163
       163
       -
           After a FastCGI process accepts a connection on its listening socket, the

     

       164
       164
       -
           process executes a simple protocol to receive and send data. The protocol

     

       165
       165
       -
           serves two purposes: First, it multiplexes a single transport connection

     

       166
       166
       -
           between several independent FastCGI requests. Second, within each request

     

       167
       167
       -
           the protocol provides several independent data streams in each direction. *)

     

       168
       168
       -
       module Connection : sig

     

       169
       169
       -
         (** Opaque connection type.

     

       170
       170
       -
             

     

       171
       171
       -
             Represents a single transport connection from a web server. The connection

     

       172
       172
       -
             handles protocol parsing, request demultiplexing, and stream management.

     

       173
       173
       -
             Each connection can handle multiple concurrent requests if the application

     

       174
       174
       -
             supports multiplexing. *)

     

       175
       175
       -
         type 'a t

     

       176
       176
       -
       

     

       177
       177
       -
         (** Connection statistics.

     

       178
       178
       -
             

     

       179
       179
       -
             Provides runtime metrics about connection usage for monitoring and

     

       180
       180
       -
             debugging purposes. These statistics can help tune application

     

       181
       181
       -
             performance and detect potential issues. *)

     

       182
       182
       -
         type stats = {

     

       183
       183
       -
           active_requests : int;   (** Number of requests currently being processed

     

       184
       184
       -
                                        on this connection. *)

     

       185
       185
       -
           total_requests : int;    (** Total number of requests processed since

     

       186
       186
       -
                                        connection establishment. *)

     

       187
       187
       -
           bytes_sent : int;        (** Total bytes sent to the web server (responses). *)

     

       188
       188
       -
           bytes_received : int;    (** Total bytes received from the web server (requests). *)

     

       189
       189
       -
         }

     

       190
       190
       -
       

     

       191
       191
       -
         (** Create a connection from a network flow.

     

       192
       192
       -
             

     

       193
       193
       -
             Initializes a new FastCGI connection over an established transport.

     

       194
       194
       -
             The connection will parse incoming records and manage request state

     

       195
       195
       -
             according to the FastCGI protocol.

     

       196
       196
       -
             

     

       197
       197
       -
             The connection handles a simple protocol to receive and send data,

     

       198
       198
       -
             including record headers, content data, and proper multiplexing.

     

       199
       199
       -
             

     

       200
       200
       -
             @param sw Switch for managing connection lifetime and automatic cleanup

     

       201
       201
       -
             @param flow Two-way network flow for bidirectional communication

     

       202
       202
       -
             @return New connection ready to process FastCGI requests

     

       203
       203
       -
             @raise Invalid_argument if the flow is already closed *)

     

       204
       204
       -
         val create : sw:Eio.Switch.t -> 'a Eio.Flow.two_way -> 'a t

     

       205
       205
       -
       

     

       206
       206
       -
         (** Accept and process a single request on the connection.

     

       207
       207
       -
             

     

       208
       208
       -
             Waits for the next FastCGI request to arrive on this connection,

     

       209
       209
       -
             then processes it using the provided handler. This function handles

     

       210
       210
       -
             all protocol details including record parsing, stream management,

     

       211
       211
       -
             and response generation.

     

       212
       212
       -
             

     

       213
       213
       -
             The function is concurrent-safe and can be called multiple times

     

       214
       214
       -
             if the application supports request multiplexing.

     

       215
       215
       -
             

     

       216
       216
       -
             @param conn Connection to process request on

     

       217
       217
       -
             @param handler Application handler for the request

     

       218
       218
       -
             @return Promise that resolves to the response result when processing completes

     

       219
       219
       -
             @raise Fastcgi.Error.Fastcgi_error on protocol violations *)

     

       220
       220
       -
         val process_request : 'a t -> 'a Handler.handler -> response_result Eio.Promise.t

     

       221
       221
       -
       

     

       222
       222
       -
         (** Get connection statistics.

     

       223
       223
       -
             

     

       224
       224
       -
             Returns current runtime statistics for this connection. This information

     

       225
       225
       -
             can be used for monitoring, load balancing decisions, and performance

     

       226
       226
       -
             tuning.

     

       227
       227
       -
             

     

       228
       228
       -
             @param conn Connection to query

     

       229
       229
       -
             @return Current statistics snapshot *)

     

       230
       230
       -
         val stats : 'a t -> stats

     

       231
       231
       -
       

     

       232
       232
       -
         (** Close the connection gracefully.

     

       233
       233
       -
             

     

       234
       234
       -
             Closes the transport connection after completing any active requests.

     

       235
       235
       -
             The Web server controls the lifetime of transport connections and can

     

       236
       236
       -
             close a connection when no requests are active.

     

       237
       237
       -
             

     

       238
       238
       -
             @param conn Connection to close *)

     

       239
       239
       -
         val close : 'a t -> unit

     

       240
       240
       -
       end

     

       241
       241
       -
       

     

       242
       242
       -
       (** FastCGI server for accepting and managing connections.

     

       243
       243
       -
           

     

       244
       244
       -
           This module provides a high-level server that listens for incoming

     

       245
       245
       -
           connections and manages them according to FastCGI protocol requirements.

     

       246
       246
       -
           It handles connection acceptance, lifecycle management, and graceful

     

       247
       247
       -
           shutdown.

     

       248
       248
       -
           

     

       249
       249
       -
           The server supports both Unix domain sockets and TCP sockets, as

     

       250
       250
       -
           commonly used by web servers like nginx, Apache, and lighttpd. *)

     

       251
       251
       -
       module Server : sig

     

       252
       252
       -
         (** Server configuration.

     

       253
       253
       -
             

     

       254
       254
       -
             Complete configuration for a FastCGI server, including application

     

       255
       255
       -
             settings, network binding, and resource limits. *)

     

       256
       256
       -
         type 'a config = {

     

       257
       257
       -
           app : 'a app_config;        (** Application configuration including handlers

     

       258
       258
       -
                                            and capability limits. *)

     

       259
       259
       -
           listen_address : [

     

       260
       260
       -
             | `Unix of string          (** Unix domain socket path. Common for local

     

       261
       261
       -
                                            communication with web servers. *)

     

       262
       262
       -
             | `Tcp of string * int  (** TCP socket address (host) and port.

     

       263
       263
       -
                                                          Used for remote FastCGI servers. *)

     

       264
       264
       -
           ];

     

       265
       265
       -
           backlog : int;               (** Listen socket backlog size. Controls how

     

       266
       266
       -
                                            many pending connections can be queued. *)

     

       267
       267
       -
           max_connections : int;       (** Maximum concurrent connections to accept.

     

       268
       268
       -
                                            Should align with app.max_connections. *)

     

       269
       269
       -
         }

     

       270
       270
       -
       

     

       271
       271
       -
         (** Run a FastCGI server.

     

       272
       272
       -
             

     

       273
       273
       -
             Starts a FastCGI server with the specified configuration. The server

     

       274
       274
       -
             will listen for connections, accept them within the configured limits,

     

       275
       275
       -
             and process requests using the application handler.

     

       276
       276
       -
             

     

       277
       277
       -
             The server implements the standard FastCGI application lifecycle:

     

       278
       278
       -
             a FastCGI application calls accept() on the socket referred to by file

     

       279
       279
       -
             descriptor FCGI_LISTENSOCK_FILENO to accept a new transport connection.

     

       280
       280
       -
             

     

       281
       281
       -
             This function blocks until the switch is cancelled or an error occurs.

     

       282
       282
       -
             

     

       283
       283
       -
             @param sw Switch for managing server lifetime and automatic cleanup

     

       284
       284
       -
             @param net Network capability for creating listening sockets

     

       285
       285
       -
             @param config Complete server configuration

     

       286
       286
       -
             @raise Sys_error if unable to bind to the specified address *)

     

       287
       287
       -
         val run :

     

       288
       288
       -
           sw:Eio.Switch.t ->

     

       289
       289
       -
           net:[< `Generic | `Unix ] Eio.Net.ty Eio.Resource.t ->

     

       290
       290
       -
           _ config ->

     

       291
       291
       -
           unit

     

       292
       292
       -
       

     

       293
       293
       -
         (** Run server with default configuration.

     

       294
       294
       -
             

     

       295
       295
       -
             Convenience function to start a FastCGI server with sensible defaults.

     

       296
       296
       -
             Useful for simple applications that don't need custom configuration.

     

       297
       297
       -
             

     

       298
       298
       -
             Default settings:

     

       299
       299
       -
             - max_connections: 10

     

       300
       300
       -
             - max_requests: 50

     

       301
       301
       -
             - multiplex_connections: true

     

       302
       302
       -
             - backlog: 5

     

       303
       303
       -
             

     

       304
       304
       -
             @param sw Switch for managing server lifetime

     

       305
       305
       -
             @param net Network capability for creating sockets

     

       306
       306
       -
             @param handler Application handler function

     

       307
       307
       -
             @param listen_address Address to listen on (Unix socket or TCP)

     

       308
       308
       -
             @raise Sys_error if unable to bind to the specified address *)

     

       309
       309
       -
         val run_default :

     

       310
       310
       -
           sw:Eio.Switch.t ->

     

       311
       311
       -
           net:[< `Generic | `Unix ] Eio.Net.ty Eio.Resource.t ->

     

       312
       312
       -
           handler:_ Handler.handler ->

     

       313
       313
       -
           listen_address:[`Unix of string | `Tcp of string * int] ->

     

       314
       314
       -
           unit

     

       315
       315
       -
       end

     

       316
       316
       -
       

     

       317
       317
       -
       (** {1 Error Handling} *)

     

       318
       318
       -
       

     

       319
       319
       -
       (** FastCGI specific errors. *)

     

       320
       320
       -
       module Error : sig

     

       321
       321
       -
         (** Error types. *)

     

       322
       322
       -
         type t =

     

       323
       323
       -
           | Protocol_error of string         (** Protocol violation *)

     

       324
       324
       -
           | Invalid_record of string         (** Malformed record *)

     

       325
       325
       -
           | Unsupported_version of int       (** Unsupported protocol version *)

     

       326
       326
       -
           | Unknown_record_type of int       (** Unknown record type *)

     

       327
       327
       -
           | Request_id_conflict of request_id (** Duplicate request ID *)

     

       328
       328
       -
           | Connection_closed                (** Connection unexpectedly closed *)

     

       329
       329
       -
           | Application_error of string      (** Application-specific error *)

     

       330
       330
       -
       

     

       331
       331
       -
         (** FastCGI exception. *)

     

       332
       332
       -
         exception Fastcgi_error of t

     

       333
       333
       -
       

     

       334
       334
       -
         (** Convert error to string description. *)

     

       335
       335
       -
         val to_string : t -> string

     

       336
       336
       -
       

     

       337
       337
       -
         (** Raise a FastCGI error. *)

     

       338
       338
       -
         val raise : t -> 'a

     

       339
       339
       -
       end

     

       340
       340
       -
       

     

       341
       341
       -
       (** {1 Resource Management} *)

     

       342
       342
       -
       

     

       343
       343
       -
       (** Resource management utilities. *)

     

       344
       344
       -
       module Resource : sig

     

       345
       345
       -
         (** Request context with automatic cleanup. *)

     

       346
       346
       -
         type 'a request_context = {

     

       347
       347
       -
           request : 'a request;

     

       348
       348
       -
           response : 'a response;

     

       349
       349
       -
           switch : Eio.Switch.t;  (** Switch for request-scoped resources *)

     

       350
       350
       -
         }

     

       351
       351
       -
       

     

       352
       352
       -
         (** Create a request context with automatic resource management.

     

       353
       353
       -
             

     

       354
       354
       -
             @param sw Parent switch

     

       355
       355
       -
             @param request FastCGI request

     

       356
       356
       -
             @param f Function to execute with request context

     

       357
       357
       -
             @return Result of function execution *)

     

       358
       358
       -
         val with_request_context :

     

       359
       359
       -
           sw:Eio.Switch.t ->

     

       360
       360
       -
           'a request ->

     

       361
       361
       -
           ('a request_context -> 'b) ->

     

       362
       362
       -
           'b

     

       363
       363
       -
       

     

       364
       364
       -
         (** Buffer management for efficient I/O. *)

     

       365
       365
       -
         module Buffer : sig

     

       366
       366
       -
           (** Buffer type. *)

     

       367
       367
       -
           type t

     

       368
       368
       -
       

     

       369
       369
       -
           (** Create a buffer with specified size. *)

     

       370
       370
       -
           val create : size:int -> t

     

       371
       371
       -
       

     

       372
       372
       -
           (** Read data into buffer from source.

     

       373
       373
       -
               

     

       374
       374
       -
               @param buffer Buffer to read into

     

       375
       375
       -
               @param source Source to read from

     

       376
       376
       -
               @return Number of bytes read *)

     

       377
       377
       -
           val read_into : t -> 'a Eio.Flow.source -> int

     

       378
       378
       -
       

     

       379
       379
       -
           (** Write data from buffer to sink.

     

       380
       380
       -
               

     

       381
       381
       -
               @param buffer Buffer to write from

     

       382
       382
       -
               @param sink Sink to write to

     

       383
       383
       -
               @param length Number of bytes to write *)

     

       384
       384
       -
           val write_from : t -> 'a Eio.Flow.sink -> int -> unit

     

       385
       385
       -
       

     

       386
       386
       -
           (** Clear buffer contents. *)

     

       387
       387
       -
           val clear : t -> unit

     

       388
       388
       -
         end

     

       389
       389
       -
       end

-229

lib/fastcgi_authorizer.mli

···

       1
       1
       -
       (** Authorizer role implementation for FastCGI.

     

       2
       2
       -
       

     

       3
       3
       -
           The Authorizer role performs access control decisions for web requests.

     

       4
       4
       -
           An Authorizer FastCGI application receives all the information associated

     

       5
       5
       -
           with an HTTP request and generates an authorized/unauthorized decision.

     

       6
       6
       -
           

     

       7
       7
       -
           In case of an authorized decision, the Authorizer can associate name-value

     

       8
       8
       -
           pairs with the HTTP request for use by subsequent processing stages. When

     

       9
       9
       -
           giving an unauthorized decision, the Authorizer sends a complete response

     

       10
       10
       -
           to the HTTP client with appropriate error information.

     

       11
       11
       -
           

     

       12
       12
       -
           This role is commonly used for:

     

       13
       13
       -
           - Authentication and authorization checks

     

       14
       14
       -
           - Access control based on IP addresses, user roles, or request attributes

     

       15
       15
       -
           - Rate limiting and quota enforcement

     

       16
       16
       -
           - Custom security policies

     

       17
       17
       -
           

     

       18
       18
       -
           The web server may proceed with additional access checks after a successful

     

       19
       19
       -
           authorization, including requests to other Authorizers, depending on its

     

       20
       20
       -
           configuration. *)

     

       21
       21
       -
       

     

       22
       22
       -
       (** {1 Authorization Types} *)

     

       23
       23
       -
       

     

       24
       24
       -
       (** Authorization result.

     

       25
       25
       -
           

     

       26
       26
       -
           Represents the outcome of an authorization decision. The Authorizer can

     

       27
       27
       -
           either grant access (possibly with additional variables) or deny access

     

       28
       28
       -
           with a complete error response. *)

     

       29
       29
       -
       type auth_result =

     

       30
       30
       -
         | Authorized of (string * string) list  (** Request is authorized. The list contains

     

       31
       31
       -
                                                      variable bindings that will be added to

     

       32
       32
       -
                                                      the request environment for subsequent

     

       33
       33
       -
                                                      processing stages. *)

     

       34
       34
       -
         | Unauthorized of {

     

       35
       35
       -
             status : int;                        (** HTTP status code for the error response

     

       36
       36
       -
                                                      (typically 401, 403, or 429). *)

     

       37
       37
       -
             headers : (string * string) list;   (** HTTP headers for the error response.

     

       38
       38
       -
                                                      May include WWW-Authenticate, etc. *)

     

       39
       39
       -
             body : string;                       (** Error response body content sent to the client. *)

     

       40
       40
       -
           } (** Request is denied. The web server will send this error

     

       41
       41
       -
                  response directly to the client without further processing. *)

     

       42
       42
       -
       

     

       43
       43
       -
       (** Authorization request information.

     

       44
       44
       -
           

     

       45
       45
       -
           Contains the relevant information from an HTTP request needed to make

     

       46
       46
       -
           authorization decisions. This is extracted from the CGI environment

     

       47
       47
       -
           variables provided by the web server. *)

     

       48
       48
       -
       type auth_request = {

     

       49
       49
       -
         method_ : string;              (** HTTP method (GET, POST, etc.). *)

     

       50
       50
       -
         uri : string;                  (** Request URI being accessed. *)

     

       51
       51
       -
         remote_addr : string option;   (** Client IP address, if available.

     

       52
       52
       -
                                            Useful for IP-based access control. *)

     

       53
       53
       -
         remote_user : string option;   (** Authenticated username, if any.

     

       54
       54
       -
                                            Set by prior authentication stages. *)

     

       55
       55
       -
         auth_type : string option;     (** Authentication method used (Basic, Bearer, etc.).

     

       56
       56
       -
                                            Indicates how the user was authenticated. *)

     

       57
       57
       -
         headers : (string * string) list; (** HTTP headers from the request.

     

       58
       58
       -
                                                May contain authorization headers, user agents, etc. *)

     

       59
       59
       -
       }

     

       60
       60
       -
       

     

       61
       61
       -
       (** {1 Conversion Functions} *)

     

       62
       62
       -
       

     

       63
       63
       -
       (** Convert FastCGI request to authorization request.

     

       64
       64
       -
           

     

       65
       65
       -
           Extracts authorization-relevant information from FastCGI

     

       66
       66
       -
           parameters and creates an auth request object.

     

       67
       67
       -
           

     

       68
       68
       -
           @param request FastCGI request

     

       69
       69
       -
           @return Authorization request *)

     

       70
       70
       -
       val request_of_fastcgi : 'a Fastcgi_types.request -> auth_request

     

       71
       71
       -
       

     

       72
       72
       -
       (** Convert authorization result to FastCGI response.

     

       73
       73
       -
           

     

       74
       74
       -
           Writes the authorization decision to the FastCGI response

     

       75
       75
       -
           streams in the correct format.

     

       76
       76
       -
           

     

       77
       77
       -
           @param result Authorization decision

     

       78
       78
       -
           @param response FastCGI response

     

       79
       79
       -
           @return Response result *)

     

       80
       80
       -
       val response_of_result : auth_result -> 'a Fastcgi_types.response -> Fastcgi_types.response_result

     

       81
       81
       -
       

     

       82
       82
       -
       (** {1 Handler Utilities} *)

     

       83
       83
       -
       

     

       84
       84
       -
       (** Authorizer handler type. *)

     

       85
       85
       -
       type 'a authorizer_handler = 'a Fastcgi_types.request -> 'a Fastcgi_types.response -> Fastcgi_types.response_result

     

       86
       86
       -
       

     

       87
       87
       -
       (** Convenience handler wrapper for authorization handlers.

     

       88
       88
       -
           

     

       89
       89
       -
           Converts an authorization handler function into a FastCGI handler.

     

       90
       90
       -
           This allows writing handlers that work with auth request/result

     

       91
       91
       -
           types instead of raw FastCGI types.

     

       92
       92
       -
           

     

       93
       93
       -
           @param handler Authorization handler function

     

       94
       94
       -
           @return FastCGI authorizer handler *)

     

       95
       95
       -
       val auth_handler :

     

       96
       96
       -
         (auth_request -> auth_result) ->

     

       97
       97
       -
         'a authorizer_handler

     

       98
       98
       -
       

     

       99
       99
       -
       (** {1 Common Authorization Patterns} *)

     

       100
       100
       -
       

     

       101
       101
       -
       (** Create a simple allow/deny authorizer.

     

       102
       102
       -
           

     

       103
       103
       -
           @param predicate Function that returns true for authorized requests

     

       104
       104
       -
           @return Authorization result *)

     

       105
       105
       -
       val simple_authorizer : (auth_request -> bool) -> (auth_request -> auth_result)

     

       106
       106
       -
       

     

       107
       107
       -
       (** IP-based authorization.

     

       108
       108
       -
           

     

       109
       109
       -
           @param allowed_ips List of allowed IP addresses/ranges

     

       110
       110
       -
           @param request Authorization request

     

       111
       111
       -
           @return Authorization result *)

     

       112
       112
       -
       val ip_authorizer : string list -> auth_request -> auth_result

     

       113
       113
       -
       

     

       114
       114
       -
       (** User-based authorization.

     

       115
       115
       -
           

     

       116
       116
       -
           @param allowed_users List of allowed usernames

     

       117
       117
       -
           @param request Authorization request

     

       118
       118
       -
           @return Authorization result *)

     

       119
       119
       -
       val user_authorizer : string list -> auth_request -> auth_result

     

       120
       120
       -
       

     

       121
       121
       -
       (** Role-based authorization.

     

       122
       122
       -
           

     

       123
       123
       -
           @param get_user_roles Function to get roles for a user

     

       124
       124
       -
           @param required_roles Roles required for access

     

       125
       125
       -
           @param request Authorization request

     

       126
       126
       -
           @return Authorization result *)

     

       127
       127
       -
       val role_authorizer :

     

       128
       128
       -
         get_user_roles:(string -> string list) ->

     

       129
       129
       -
         required_roles:string list ->

     

       130
       130
       -
         auth_request ->

     

       131
       131
       -
         auth_result

     

       132
       132
       -
       

     

       133
       133
       -
       (** Time-based authorization.

     

       134
       134
       -
           

     

       135
       135
       -
           @param allowed_hours List of allowed hours (0-23)

     

       136
       136
       -
           @param request Authorization request

     

       137
       137
       -
           @return Authorization result *)

     

       138
       138
       -
       val time_authorizer : int list -> auth_request -> auth_result

     

       139
       139
       -
       

     

       140
       140
       -
       (** {1 Authentication Integration} *)

     

       141
       141
       -
       

     

       142
       142
       -
       (** Basic authentication handler.

     

       143
       143
       -
           

     

       144
       144
       -
           @param realm Authentication realm

     

       145
       145
       -
           @param verify_credentials Function to verify username/password

     

       146
       146
       -
           @param request Authorization request

     

       147
       147
       -
           @return Authorization result *)

     

       148
       148
       -
       val basic_auth :

     

       149
       149
       -
         realm:string ->

     

       150
       150
       -
         verify_credentials:(string -> string -> bool) ->

     

       151
       151
       -
         auth_request ->

     

       152
       152
       -
         auth_result

     

       153
       153
       -
       

     

       154
       154
       -
       (** Bearer token authentication.

     

       155
       155
       -
           

     

       156
       156
       -
           @param verify_token Function to verify and decode token

     

       157
       157
       -
           @param request Authorization request

     

       158
       158
       -
           @return Authorization result *)

     

       159
       159
       -
       val bearer_auth :

     

       160
       160
       -
         verify_token:(string -> (string * (string * string) list) option) ->

     

       161
       161
       -
         auth_request ->

     

       162
       162
       -
         auth_result

     

       163
       163
       -
       

     

       164
       164
       -
       (** API key authentication.

     

       165
       165
       -
           

     

       166
       166
       -
           @param header_name Header containing API key

     

       167
       167
       -
           @param verify_key Function to verify API key

     

       168
       168
       -
           @param request Authorization request

     

       169
       169
       -
           @return Authorization result *)

     

       170
       170
       -
       val api_key_auth :

     

       171
       171
       -
         header_name:string ->

     

       172
       172
       -
         verify_key:(string -> (string * (string * string) list) option) ->

     

       173
       173
       -
         auth_request ->

     

       174
       174
       -
         auth_result

     

       175
       175
       -
       

     

       176
       176
       -
       (** {1 Response Helpers} *)

     

       177
       177
       -
       

     

       178
       178
       -
       (** Create a standard 401 Unauthorized response.

     

       179
       179
       -
           

     

       180
       180
       -
           @param realm Authentication realm

     

       181
       181
       -
           @param message Error message

     

       182
       182
       -
           @return Unauthorized result *)

     

       183
       183
       -
       val unauthorized_response :

     

       184
       184
       -
         realm:string ->

     

       185
       185
       -
         message:string ->

     

       186
       186
       -
         auth_result

     

       187
       187
       -
       

     

       188
       188
       -
       (** Create a standard 403 Forbidden response.

     

       189
       189
       -
           

     

       190
       190
       -
           @param message Error message

     

       191
       191
       -
           @return Unauthorized result *)

     

       192
       192
       -
       val forbidden_response :

     

       193
       193
       -
         message:string ->

     

       194
       194
       -
         auth_result

     

       195
       195
       -
       

     

       196
       196
       -
       (** Create a custom error response.

     

       197
       197
       -
           

     

       198
       198
       -
           @param status HTTP status code

     

       199
       199
       -
           @param headers Additional headers

     

       200
       200
       -
           @param body Response body

     

       201
       201
       -
           @return Unauthorized result *)

     

       202
       202
       -
       val error_response :

     

       203
       203
       -
         status:int ->

     

       204
       204
       -
         headers:(string * string) list ->

     

       205
       205
       -
         body:string ->

     

       206
       206
       -
         auth_result

     

       207
       207
       -
       

     

       208
       208
       -
       (** {1 Variable Binding} *)

     

       209
       209
       -
       

     

       210
       210
       -
       (** Create authorized response with variables.

     

       211
       211
       -
           

     

       212
       212
       -
           Variables are passed to subsequent FastCGI applications

     

       213
       213
       -
           as environment variables with "Variable-" prefix.

     

       214
       214
       -
           

     

       215
       215
       -
           @param variables Name-value pairs to bind

     

       216
       216
       -
           @return Authorized result *)

     

       217
       217
       -
       val authorized_with_variables : (string * string) list -> auth_result

     

       218
       218
       -
       

     

       219
       219
       -
       (** Add authentication information as variables.

     

       220
       220
       -
           

     

       221
       221
       -
           @param user Authenticated username

     

       222
       222
       -
           @param auth_type Authentication method

     

       223
       223
       -
           @param additional Additional variables

     

       224
       224
       -
           @return Variable bindings *)

     

       225
       225
       -
       val auth_variables :

     

       226
       226
       -
         user:string ->

     

       227
       227
       -
         auth_type:string ->

     

       228
       228
       -
         additional:(string * string) list ->

     

       229
       229
       -
         (string * string) list

-329

lib/fastcgi_filter.mli

···

       1
       1
       -
       (** Filter role implementation for FastCGI.

     

       2
       2
       -
       

     

       3
       3
       -
           The Filter role processes data streams with filtering capabilities.

     

       4
       4
       -
           A Filter FastCGI application receives all the information associated with

     

       5
       5
       -
           an HTTP request, plus an extra stream of data from a file stored on the

     

       6
       6
       -
           web server, and generates a "filtered" version of the data stream as an

     

       7
       7
       -
           HTTP response.

     

       8
       8
       -
           

     

       9
       9
       -
           This role is useful for:

     

       10
       10
       -
           - Dynamic content transformation (e.g., server-side includes, templating)

     

       11
       11
       -
           - Format conversion (e.g., Markdown to HTML, image resizing)

     

       12
       12
       -
           - Content compression and optimization

     

       13
       13
       -
           - Real-time content modification based on request context

     

       14
       14
       -
           

     

       15
       15
       -
           A Filter is similar in functionality to a Responder that takes a data file

     

       16
       16
       -
           as a parameter. The key difference is that with a Filter, both the data file

     

       17
       17
       -
           and the Filter itself can be access controlled using the web server's access

     

       18
       18
       -
           control mechanisms, while a Responder that takes the name of a data file as

     

       19
       19
       -
           a parameter must perform its own access control checks on the data file.

     

       20
       20
       -
           

     

       21
       21
       -
           The web server presents the Filter with environment variables first, then

     

       22
       22
       -
           standard input (normally form POST data), and finally the data file input

     

       23
       23
       -
           that needs to be processed. *)

     

       24
       24
       -
       

     

       25
       25
       -
       (** {1 Filter Types} *)

     

       26
       26
       -
       

     

       27
       27
       -
       (** Filter request with data stream.

     

       28
       28
       -
           

     

       29
       29
       -
           Represents a complete Filter request including both the HTTP request

     

       30
       30
       -
           context and the data stream that needs to be processed. *)

     

       31
       31
       -
       type 'a filter_request = {

     

       32
       32
       -
         request : 'a Fastcgi_types.request;       (** Base FastCGI request containing HTTP context,

     

       33
       33
       -
                                                        parameters, and form data. *)

     

       34
       34
       -
         data_stream : 'a Eio.Flow.source;         (** File data stream to be filtered.

     

       35
       35
       -
                                                        This is the content that needs processing. *)

     

       36
       36
       -
         data_last_modified : float option;        (** File modification time as seconds since epoch.

     

       37
       37
       -
                                                        Useful for caching and conditional requests. *)

     

       38
       38
       -
         data_length : int option;                 (** Expected length of the data stream in bytes.

     

       39
       39
       -
                                                        May be None if length is unknown. *)

     

       40
       40
       -
       }

     

       41
       41
       -
       

     

       42
       42
       -
       (** Filter metadata about the data being processed. *)

     

       43
       43
       -
       type filter_metadata = {

     

       44
       44
       -
         filename : string option;                  (** Original filename *)

     

       45
       45
       -
         mime_type : string option;                (** MIME type of data *)

     

       46
       46
       -
         last_modified : float option;             (** Last modification time *)

     

       47
       47
       -
         size : int option;                        (** Data size in bytes *)

     

       48
       48
       -
         etag : string option;                     (** Entity tag for caching *)

     

       49
       49
       -
       }

     

       50
       50
       -
       

     

       51
       51
       -
       (** Filter context with additional processing information. *)

     

       52
       52
       -
       type 'a filter_context = {

     

       53
       53
       -
         filter_request : 'a filter_request;       (** Request and data *)

     

       54
       54
       -
         metadata : filter_metadata;              (** File metadata *)

     

       55
       55
       -
         cache_control : cache_policy;             (** Caching policy *)

     

       56
       56
       -
       }

     

       57
       57
       -
       

     

       58
       58
       -
       (** Cache policy for filtered content. *)

     

       59
       59
       -
       and cache_policy =

     

       60
       60
       -
         | No_cache                                (** No caching *)

     

       61
       61
       -
         | Cache_for of int                        (** Cache for N seconds *)

     

       62
       62
       -
         | Cache_until of float                    (** Cache until timestamp *)

     

       63
       63
       -
         | Conditional_cache of (filter_metadata -> bool) (** Conditional caching *)

     

       64
       64
       -
       

     

       65
       65
       -
       (** {1 Conversion Functions} *)

     

       66
       66
       -
       

     

       67
       67
       -
       (** Convert FastCGI request to filter request.

     

       68
       68
       -
           

     

       69
       69
       -
           Extracts filter-specific information from FastCGI streams

     

       70
       70
       -
           and creates a filter request object.

     

       71
       71
       -
           

     

       72
       72
       -
           @param request FastCGI request

     

       73
       73
       -
           @return Filter request with data stream *)

     

       74
       74
       -
       val request_of_fastcgi : 'a Fastcgi_types.request -> 'a filter_request

     

       75
       75
       -
       

     

       76
       76
       -
       (** Create filter context with metadata.

     

       77
       77
       -
           

     

       78
       78
       -
           @param filter_request Filter request

     

       79
       79
       -
           @param metadata File metadata

     

       80
       80
       -
           @param cache_control Caching policy

     

       81
       81
       -
           @return Filter context *)

     

       82
       82
       -
       val context_of_request :

     

       83
       83
       -
         'a filter_request ->

     

       84
       84
       -
         metadata:filter_metadata ->

     

       85
       85
       -
         cache_control:cache_policy ->

     

       86
       86
       -
         'a filter_context

     

       87
       87
       -
       

     

       88
       88
       -
       (** {1 Handler Utilities} *)

     

       89
       89
       -
       

     

       90
       90
       -
       (** Filter handler type. *)

     

       91
       91
       -
       type 'a filter_handler = 'a Fastcgi_types.request -> 'a Fastcgi_types.response -> Fastcgi_types.response_result

     

       92
       92
       -
       

     

       93
       93
       -
       (** Convenience handler wrapper for filter handlers.

     

       94
       94
       -
           

     

       95
       95
       -
           Converts a filter handler function into a FastCGI handler.

     

       96
       96
       -
           This allows writing handlers that work with filter request/response

     

       97
       97
       -
           types instead of raw FastCGI types.

     

       98
       98
       -
           

     

       99
       99
       -
           @param handler Filter handler function

     

       100
       100
       -
           @return FastCGI filter handler *)

     

       101
       101
       -
       

     

       102
       102
       -
       val filter_handler :

     

       103
       103
       -
         ('a filter_request -> 'a Fastcgi_types.response -> unit) ->

     

       104
       104
       -
         'a filter_handler

     

       105
       105
       -
       

     

       106
       106
       -
       (** Context-aware filter handler.

     

       107
       107
       -
           

     

       108
       108
       -
           Similar to filter_handler but provides additional context

     

       109
       109
       -
           including metadata and caching information.

     

       110
       110
       -
           

     

       111
       111
       -
           @param handler Context-aware filter handler

     

       112
       112
       -
           @return FastCGI filter handler *)

     

       113
       113
       -
       val context_filter_handler :

     

       114
       114
       -
         ('a filter_context -> 'a Fastcgi_types.response -> unit) ->

     

       115
       115
       -
         'a filter_handler

     

       116
       116
       -
       

     

       117
       117
       -
       (** {1 Common Filter Operations} *)

     

       118
       118
       -
       

     

       119
       119
       -
       (** Text processing filters. *)

     

       120
       120
       -
       module Text : sig

     

       121
       121
       -
         (** Convert text encoding.

     

       122
       122
       -
             

     

       123
       123
       -
             @param from_encoding Source encoding

     

       124
       124
       -
             @param to_encoding Target encoding

     

       125
       125
       -
             @param input Text stream

     

       126
       126
       -
             @param output Filtered stream *)

     

       127
       127
       -
         val convert_encoding :

     

       128
       128
       -
           from_encoding:string ->

     

       129
       129
       -
           to_encoding:string ->

     

       130
       130
       -
           input:'a Eio.Flow.source ->

     

       131
       131
       -
           output:'a Eio.Flow.sink ->

     

       132
       132
       -
           unit

     

       133
       133
       -
       

     

       134
       134
       -
         (** Find and replace text patterns.

     

       135
       135
       -
             

     

       136
       136
       -
             @param pattern Regular expression pattern

     

       137
       137
       -
             @param replacement Replacement text

     

       138
       138
       -
             @param input Text stream

     

       139
       139
       -
             @param output Filtered stream *)

     

       140
       140
       -
         val find_replace :

     

       141
       141
       -
           pattern:string ->

     

       142
       142
       -
           replacement:string ->

     

       143
       143
       -
           input:'a Eio.Flow.source ->

     

       144
       144
       -
           output:'a Eio.Flow.sink ->

     

       145
       145
       -
           unit

     

       146
       146
       -
       

     

       147
       147
       -
         (** Template substitution.

     

       148
       148
       -
             

     

       149
       149
       -
             @param variables Variable substitutions

     

       150
       150
       -
             @param input Template stream

     

       151
       151
       -
             @param output Processed stream *)

     

       152
       152
       -
         val template_substitute :

     

       153
       153
       -
           variables:(string * string) list ->

     

       154
       154
       -
           input:'a Eio.Flow.source ->

     

       155
       155
       -
           output:'a Eio.Flow.sink ->

     

       156
       156
       -
           unit

     

       157
       157
       -
       

     

       158
       158
       -
         (** Markdown to HTML conversion.

     

       159
       159
       -
             

     

       160
       160
       -
             @param options Markdown processing options

     

       161
       161
       -
             @param input Markdown stream

     

       162
       162
       -
             @param output HTML stream *)

     

       163
       163
       -
         val markdown_to_html :

     

       164
       164
       -
           options:string list ->

     

       165
       165
       -
           input:'a Eio.Flow.source ->

     

       166
       166
       -
           output:'a Eio.Flow.sink ->

     

       167
       167
       -
           unit

     

       168
       168
       -
       end

     

       169
       169
       -
       

     

       170
       170
       -
       (** Image processing filters. *)

     

       171
       171
       -
       module Image : sig

     

       172
       172
       -
         (** Image resize operation.

     

       173
       173
       -
             

     

       174
       174
       -
             @param width Target width

     

       175
       175
       -
             @param height Target height

     

       176
       176
       -
             @param input Image stream

     

       177
       177
       -
             @param output Resized stream *)

     

       178
       178
       -
         val resize :

     

       179
       179
       -
           width:int ->

     

       180
       180
       -
           height:int ->

     

       181
       181
       -
           input:'a Eio.Flow.source ->

     

       182
       182
       -
           output:'a Eio.Flow.sink ->

     

       183
       183
       -
           unit

     

       184
       184
       -
       

     

       185
       185
       -
         (** Image format conversion.

     

       186
       186
       -
             

     

       187
       187
       -
             @param format Target format (jpeg, png, etc.)

     

       188
       188
       -
             @param quality Quality setting (for lossy formats)

     

       189
       189
       -
             @param input Image stream

     

       190
       190
       -
             @param output Converted stream *)

     

       191
       191
       -
         val convert_format :

     

       192
       192
       -
           format:string ->

     

       193
       193
       -
           quality:int option ->

     

       194
       194
       -
           input:'a Eio.Flow.source ->

     

       195
       195
       -
           output:'a Eio.Flow.sink ->

     

       196
       196
       -
           unit

     

       197
       197
       -
       

     

       198
       198
       -
         (** Image compression.

     

       199
       199
       -
             

     

       200
       200
       -
             @param level Compression level

     

       201
       201
       -
             @param input Image stream

     

       202
       202
       -
             @param output Compressed stream *)

     

       203
       203
       -
         val compress :

     

       204
       204
       -
           level:int ->

     

       205
       205
       -
           input:'a Eio.Flow.source ->

     

       206
       206
       -
           output:'a Eio.Flow.sink ->

     

       207
       207
       -
           unit

     

       208
       208
       -
       end

     

       209
       209
       -
       

     

       210
       210
       -
       (** Data compression filters. *)

     

       211
       211
       -
       module Compression : sig

     

       212
       212
       -
         (** Gzip compression.

     

       213
       213
       -
             

     

       214
       214
       -
             @param level Compression level (1-9)

     

       215
       215
       -
             @param input Data stream

     

       216
       216
       -
             @param output Compressed stream *)

     

       217
       217
       -
         val gzip :

     

       218
       218
       -
           level:int ->

     

       219
       219
       -
           input:'a Eio.Flow.source ->

     

       220
       220
       -
           output:'a Eio.Flow.sink ->

     

       221
       221
       -
           unit

     

       222
       222
       -
       

     

       223
       223
       -
         (** Brotli compression.

     

       224
       224
       -
             

     

       225
       225
       -
             @param level Compression level

     

       226
       226
       -
             @param input Data stream

     

       227
       227
       -
             @param output Compressed stream *)

     

       228
       228
       -
         val brotli :

     

       229
       229
       -
           level:int ->

     

       230
       230
       -
           input:'a Eio.Flow.source ->

     

       231
       231
       -
           output:'a Eio.Flow.sink ->

     

       232
       232
       -
           unit

     

       233
       233
       -
       

     

       234
       234
       -
         (** Auto-detect and compress.

     

       235
       235
       -
             

     

       236
       236
       -
             @param preferred_formats Preferred compression formats

     

       237
       237
       -
             @param accept_encoding Client Accept-Encoding header

     

       238
       238
       -
             @param input Data stream

     

       239
       239
       -
             @param output Compressed stream *)

     

       240
       240
       -
         val auto_compress :

     

       241
       241
       -
           preferred_formats:string list ->

     

       242
       242
       -
           accept_encoding:string option ->

     

       243
       243
       -
           input:'a Eio.Flow.source ->

     

       244
       244
       -
           output:'a Eio.Flow.sink ->

     

       245
       245
       -
           string option  (** Returns content-encoding used *)

     

       246
       246
       -
       end

     

       247
       247
       -
       

     

       248
       248
       -
       (** {1 Caching and Optimization} *)

     

       249
       249
       -
       

     

       250
       250
       -
       (** Check if content should be served from cache.

     

       251
       251
       -
           

     

       252
       252
       -
           @param metadata File metadata

     

       253
       253
       -
           @param if_modified_since Client If-Modified-Since header

     

       254
       254
       -
           @param if_none_match Client If-None-Match header

     

       255
       255
       -
           @return True if content is not modified *)

     

       256
       256
       -
       val check_not_modified :

     

       257
       257
       -
         metadata:filter_metadata ->

     

       258
       258
       -
         if_modified_since:string option ->

     

       259
       259
       -
         if_none_match:string option ->

     

       260
       260
       -
         bool

     

       261
       261
       -
       

     

       262
       262
       -
       (** Generate appropriate cache headers.

     

       263
       263
       -
           

     

       264
       264
       -
           @param metadata File metadata

     

       265
       265
       -
           @param cache_policy Caching policy

     

       266
       266
       -
           @return List of cache-related headers *)

     

       267
       267
       -
       val generate_cache_headers :

     

       268
       268
       -
         metadata:filter_metadata ->

     

       269
       269
       -
         cache_policy:cache_policy ->

     

       270
       270
       -
         (string * string) list

     

       271
       271
       -
       

     

       272
       272
       -
       (** {1 Streaming Operations} *)

     

       273
       273
       -
       

     

       274
       274
       -
       (** Stream processor for chunk-by-chunk filtering. *)

     

       275
       275
       -
       type 'a stream_processor = {

     

       276
       276
       -
         process_chunk : bytes -> bytes option;    (** Process a data chunk *)

     

       277
       277
       -
         finalize : unit -> bytes option;          (** Finalize and get remaining data *)

     

       278
       278
       -
         reset : unit -> unit;                     (** Reset processor state *)

     

       279
       279
       -
       }

     

       280
       280
       -
       

     

       281
       281
       -
       (** Create a streaming filter.

     

       282
       282
       -
           

     

       283
       283
       -
           @param processor Stream processor

     

       284
       284
       -
           @param input Source stream

     

       285
       285
       -
           @param output Target stream *)

     

       286
       286
       -
       val streaming_filter :

     

       287
       287
       -
         processor:'a stream_processor ->

     

       288
       288
       -
         input:'a Eio.Flow.source ->

     

       289
       289
       -
         output:'a Eio.Flow.sink ->

     

       290
       290
       -
         unit

     

       291
       291
       -
       

     

       292
       292
       -
       (** Chain multiple filters together.

     

       293
       293
       -
           

     

       294
       294
       -
           @param filters List of filter functions

     

       295
       295
       -
           @param input Source stream

     

       296
       296
       -
           @param output Target stream *)

     

       297
       297
       -
       val chain_filters :

     

       298
       298
       -
         filters:(('a Eio.Flow.source -> 'a Eio.Flow.sink -> unit) list) ->

     

       299
       299
       -
         input:'a Eio.Flow.source ->

     

       300
       300
       -
         output:'a Eio.Flow.sink ->

     

       301
       301
       -
         unit

     

       302
       302
       -
       

     

       303
       303
       -
       (** {1 Error Handling} *)

     

       304
       304
       -
       

     

       305
       305
       -
       (** Filter-specific errors. *)

     

       306
       306
       -
       type filter_error =

     

       307
       307
       -
         | Data_corruption of string              (** Data corruption detected *)

     

       308
       308
       -
         | Unsupported_format of string           (** Unsupported file format *)

     

       309
       309
       -
         | Processing_failed of string            (** Filter processing failed *)

     

       310
       310
       -
         | Resource_exhausted of string           (** Out of memory/disk space *)

     

       311
       311
       -
       

     

       312
       312
       -
       (** Filter exception. *)

     

       313
       313
       -
       exception Filter_error of filter_error

     

       314
       314
       -
       

     

       315
       315
       -
       (** Convert filter error to string. *)

     

       316
       316
       -
       val filter_error_to_string : filter_error -> string

     

       317
       317
       -
       

     

       318
       318
       -
       (** Safe filter wrapper that handles errors gracefully.

     

       319
       319
       -
           

     

       320
       320
       -
           @param fallback Fallback function if filter fails

     

       321
       321
       -
           @param filter Primary filter function

     

       322
       322
       -
           @param input Source stream

     

       323
       323
       -
           @param output Target stream *)

     

       324
       324
       -
       val safe_filter :

     

       325
       325
       -
         fallback:('a Eio.Flow.source -> 'a Eio.Flow.sink -> unit) ->

     

       326
       326
       -
         filter:('a Eio.Flow.source -> 'a Eio.Flow.sink -> unit) ->

     

       327
       327
       -
         input:'a Eio.Flow.source ->

     

       328
       328
       -
         output:'a Eio.Flow.sink ->

     

       329
       329
       -
         unit

-414

lib/fastcgi_protocol.mli

···

       1
       1
       -
       (** FastCGI wire protocol parsing and serialization.

     

       2
       2
       -
       

     

       3
       3
       -
           This module handles the low-level FastCGI protocol details including

     

       4
       4
       -
           record parsing, name-value pair encoding, and binary data serialization

     

       5
       5
       -
           using Eio's Buf_read and Buf_write modules.

     

       6
       6
       -
           

     

       7
       7
       -
           The FastCGI protocol uses a binary record format where all data is

     

       8
       8
       -
           transmitted as 8-byte fixed headers followed by variable-length content

     

       9
       9
       -
           and optional padding. Multi-byte integers use network byte order for

     

       10
       10
       -
           platform independence.

     

       11
       11
       -
           

     

       12
       12
       -
           The protocol supports several key features:

     

       13
       13
       -
           - Request multiplexing over single connections

     

       14
       14
       -
           - Variable-length encoding for efficient name-value pairs

     

       15
       15
       -
           - Stream-based data transmission with proper termination

     

       16
       16
       -
           - Alignment padding for optimal performance

     

       17
       17
       -
           

     

       18
       18
       -
           This module provides the low-level primitives for encoding and decoding

     

       19
       19
       -
           these protocol elements, allowing higher-level modules to focus on

     

       20
       20
       -
           application logic rather than binary protocol details. *)

     

       21
       21
       -
       

     

       22
       22
       -
       (** Protocol parsing error.

     

       23
       23
       -
           

     

       24
       24
       -
           Raised when invalid or malformed protocol data is encountered during

     

       25
       25
       -
           parsing operations. This includes version mismatches, invalid record

     

       26
       26
       -
           structures, malformed length encodings, and other protocol violations. *)

     

       27
       27
       -
       exception Protocol_error of string

     

       28
       28
       -
       

     

       29
       29
       -
       (** {1 Protocol Parsing}

     

       30
       30
       -
           

     

       31
       31
       -
           These functions parse incoming FastCGI records and protocol elements

     

       32
       32
       -
           from binary data streams. They validate protocol compliance and convert

     

       33
       33
       -
           binary data into OCaml types for processing. *)

     

       34
       34
       -
       

     

       35
       35
       -
       (** Parse a FastCGI record header from a buffer.

     

       36
       36
       -
           

     

       37
       37
       -
           Reads exactly 8 bytes from the buffer to construct a record header.

     

       38
       38
       -
           The header contains version, record type, request ID, content length,

     

       39
       39
       -
           and padding length fields using network byte order.

     

       40
       40
       -
           

     

       41
       41
       -
           The function validates that the version is supported (currently only

     

       42
       42
       -
           version 1) and that the record type is recognized.

     

       43
       43
       -
           

     

       44
       44
       -
           @param buf Input buffer positioned at the start of a record header

     

       45
       45
       -
           @return Parsed record header with validated fields

     

       46
       46
       -
           @raise Protocol_error if version is unsupported or data is malformed *)

     

       47
       47
       -
       val parse_record_header : Eio.Buf_read.t -> Fastcgi_types.record_header

     

       48
       48
       -
       

     

       49
       49
       -
       (** Parse a complete FastCGI record from a buffer.

     

       50
       50
       -
           

     

       51
       51
       -
           Reads a record header followed by the specified amount of content data

     

       52
       52
       -
           and padding. This is the primary function for reading FastCGI records

     

       53
       53
       -
           from network streams.

     

       54
       54
       -
           

     

       55
       55
       -
           The function ensures that exactly the number of content and padding

     

       56
       56
       -
           bytes specified in the header are read, maintaining proper stream

     

       57
       57
       -
           alignment for subsequent records.

     

       58
       58
       -
           

     

       59
       59
       -
           @param buf Input buffer positioned at the start of a complete record

     

       60
       60
       -
           @return Complete parsed record with header, content, and optional padding

     

       61
       61
       -
           @raise Protocol_error if the record structure is invalid *)

     

       62
       62
       -
       val parse_record : Eio.Buf_read.t -> Fastcgi_types.record

     

       63
       63
       -
       

     

       64
       64
       -
       (** Parse begin request body from record content.

     

       65
       65
       -
           

     

       66
       66
       -
           Extracts role and connection flags from the 8-byte Begin_request record

     

       67
       67
       -
           body. The role indicates whether the application should act as a

     

       68
       68
       -
           Responder, Authorizer, or Filter. The flags control connection lifetime

     

       69
       69
       -
           management.

     

       70
       70
       -
           

     

       71
       71
       -
           @param content Record content bytes (must be exactly 8 bytes)

     

       72
       72
       -
           @return Begin request body with role and flags

     

       73
       73
       -
           @raise Protocol_error if content length is wrong or role is unknown *)

     

       74
       74
       -
       val parse_begin_request : bytes -> Fastcgi_types.begin_request_body

     

       75
       75
       -
       

     

       76
       76
       -
       (** Parse end request body from record content.

     

       77
       77
       -
           

     

       78
       78
       -
           Extracts application status and protocol status from the 8-byte

     

       79
       79
       -
           End_request record body. The application status is similar to a

     

       80
       80
       -
           program exit code, while protocol status indicates completion

     

       81
       81
       -
           or rejection reasons.

     

       82
       82
       -
           

     

       83
       83
       -
           @param content Record content bytes (must be exactly 8 bytes)

     

       84
       84
       -
           @return End request body with status codes

     

       85
       85
       -
           @raise Protocol_error if content length is wrong or status is invalid *)

     

       86
       86
       -
       val parse_end_request : bytes -> Fastcgi_types.end_request_body

     

       87
       87
       -
       

     

       88
       88
       -
       (** Parse name-value pairs from record content.

     

       89
       89
       -
           

     

       90
       90
       -
           Decodes the compact binary encoding used for parameter transmission.

     

       91
       91
       -
           Names and values can be up to 127 bytes (1-byte length) or longer

     

       92
       92
       -
           (4-byte length with high bit set). This encoding allows efficient

     

       93
       93
       -
           transmission of CGI environment variables and other parameters.

     

       94
       94
       -
           

     

       95
       95
       -
           @param content Record content bytes containing encoded name-value pairs

     

       96
       96
       -
           @return List of decoded name-value pairs

     

       97
       97
       -
           @raise Protocol_error if the encoding is malformed *)

     

       98
       98
       -
       val parse_name_value_pairs : bytes -> Fastcgi_types.name_value_pair list

     

       99
       99
       -
       

     

       100
       100
       -
       (** {1 Protocol Serialization}

     

       101
       101
       -
           

     

       102
       102
       -
           These functions serialize OCaml types into the binary FastCGI protocol

     

       103
       103
       -
           format for transmission to web servers. All multi-byte integers are

     

       104
       104
       -
           written in network byte order for platform independence. *)

     

       105
       105
       -
       

     

       106
       106
       -
       (** Write a FastCGI record header to a buffer.

     

       107
       107
       -
           

     

       108
       108
       -
           Serializes a record header into exactly 8 bytes using network byte order.

     

       109
       109
       -
           The header format is: version (1 byte), type (1 byte), request ID (2 bytes),

     

       110
       110
       -
           content length (2 bytes), padding length (1 byte), reserved (1 byte).

     

       111
       111
       -
           

     

       112
       112
       -
           @param buf Output buffer to write the header to

     

       113
       113
       -
           @param header Record header to serialize *)

     

       114
       114
       -
       val write_record_header : Eio.Buf_write.t -> Fastcgi_types.record_header -> unit

     

       115
       115
       -
       

     

       116
       116
       -
       (** Write a complete FastCGI record to a buffer.

     

       117
       117
       -
           

     

       118
       118
       -
           Serializes a complete record including header, content data, and padding.

     

       119
       119
       -
           This is the primary function for sending FastCGI records over network

     

       120
       120
       -
           connections. The function ensures proper alignment by writing any

     

       121
       121
       -
           specified padding bytes.

     

       122
       122
       -
           

     

       123
       123
       -
           @param buf Output buffer to write the complete record to  

     

       124
       124
       -
           @param record Complete record with header, content, and optional padding *)

     

       125
       125
       -
       val write_record : Eio.Buf_write.t -> Fastcgi_types.record -> unit

     

       126
       126
       -
       

     

       127
       127
       -
       (** Write begin request body to bytes.

     

       128
       128
       -
           

     

       129
       129
       -
           Serializes role and connection flags into the 8-byte Begin_request record

     

       130
       130
       -
           body format. The first 2 bytes contain the role, the next byte contains

     

       131
       131
       -
           flags, and the remaining 5 bytes are reserved (set to zero).

     

       132
       132
       -
           

     

       133
       133
       -
           @param body Begin request body with role and flags

     

       134
       134
       -
           @return 8-byte serialized record body *)

     

       135
       135
       -
       val write_begin_request : Fastcgi_types.begin_request_body -> bytes

     

       136
       136
       -
       

     

       137
       137
       -
       (** Write end request body to bytes.

     

       138
       138
       -
           

     

       139
       139
       -
           Serializes application and protocol status into the 8-byte End_request

     

       140
       140
       -
           record body format. The first 4 bytes contain the application status,

     

       141
       141
       -
           the next byte contains the protocol status, and the remaining 3 bytes

     

       142
       142
       -
           are reserved.

     

       143
       143
       -
           

     

       144
       144
       -
           @param body End request body with status codes

     

       145
       145
       -
           @return 8-byte serialized record body *)

     

       146
       146
       -
       val write_end_request : Fastcgi_types.end_request_body -> bytes

     

       147
       147
       -
       

     

       148
       148
       -
       (** Write name-value pairs to bytes.

     

       149
       149
       -
           

     

       150
       150
       -
           Serializes name-value pairs using the compact binary encoding where

     

       151
       151
       -
           each pair is encoded as: name length, value length, name data, value data.

     

       152
       152
       -
           Lengths up to 127 bytes use 1-byte encoding; longer lengths use 4-byte

     

       153
       153
       -
           encoding with the high bit set.

     

       154
       154
       -
           

     

       155
       155
       -
           @param pairs List of name-value pairs to encode

     

       156
       156
       -
           @return Serialized bytes containing all encoded pairs *)

     

       157
       157
       -
       val write_name_value_pairs : Fastcgi_types.name_value_pair list -> bytes

     

       158
       158
       -
       

     

       159
       159
       -
       (** {1 Type Conversions} *)

     

       160
       160
       -
       

     

       161
       161
       -
       (** Convert record type to integer. *)

     

       162
       162
       -
       val record_type_to_int : Fastcgi_types.record_type -> int

     

       163
       163
       -
       

     

       164
       164
       -
       (** Convert integer to record type.

     

       165
       165
       -
           

     

       166
       166
       -
           @param i Integer value

     

       167
       167
       -
           @return Record type

     

       168
       168
       -
           @raise Protocol_error if unknown *)

     

       169
       169
       -
       val record_type_of_int : int -> Fastcgi_types.record_type

     

       170
       170
       -
       

     

       171
       171
       -
       (** Convert role to integer. *)

     

       172
       172
       -
       val role_to_int : Fastcgi_types.role -> int

     

       173
       173
       -
       

     

       174
       174
       -
       (** Convert integer to role.

     

       175
       175
       -
           

     

       176
       176
       -
           @param i Integer value

     

       177
       177
       -
           @return Role

     

       178
       178
       -
           @raise Protocol_error if unknown *)

     

       179
       179
       -
       val role_of_int : int -> Fastcgi_types.role

     

       180
       180
       -
       

     

       181
       181
       -
       (** Convert protocol status to integer. *)

     

       182
       182
       -
       val protocol_status_to_int : Fastcgi_types.protocol_status -> int

     

       183
       183
       -
       

     

       184
       184
       -
       (** Convert integer to protocol status.

     

       185
       185
       -
           

     

       186
       186
       -
           @param i Integer value

     

       187
       187
       -
           @return Protocol status

     

       188
       188
       -
           @raise Protocol_error if unknown *)

     

       189
       189
       -
       val protocol_status_of_int : int -> Fastcgi_types.protocol_status

     

       190
       190
       -
       

     

       191
       191
       -
       (** {1 Length Encoding}

     

       192
       192
       -
           

     

       193
       193
       -
           FastCGI uses a variable-length encoding for efficient transmission of

     

       194
       194
       -
           length values in name-value pairs. This encoding minimizes overhead

     

       195
       195
       -
           for short strings while supporting arbitrarily long values. *)

     

       196
       196
       -
       

     

       197
       197
       -
       (** Encode a length value using FastCGI variable-length encoding.

     

       198
       198
       -
           

     

       199
       199
       -
           Short lengths (0-127) are encoded in a single byte with the high bit

     

       200
       200
       -
           clear. Longer lengths (128 and above) are encoded in 4 bytes with the

     

       201
       201
       -
           high bit of the first byte set to 1, and the remaining 31 bits containing

     

       202
       202
       -
           the actual length value.

     

       203
       203
       -
           

     

       204
       204
       -
           This encoding provides optimal space efficiency for typical use cases

     

       205
       205
       -
           where most parameter names and values are relatively short.

     

       206
       206
       -
           

     

       207
       207
       -
           @param length Length value to encode (must be non-negative)

     

       208
       208
       -
           @return 1-byte or 4-byte encoded length

     

       209
       209
       -
           @raise Invalid_argument if length is negative *)

     

       210
       210
       -
       val encode_length : int -> bytes

     

       211
       211
       -
       

     

       212
       212
       -
       (** Decode a length value from FastCGI variable-length encoding.

     

       213
       213
       -
           

     

       214
       214
       -
           Reads either 1 or 4 bytes from the buffer depending on the high bit

     

       215
       215
       -
           of the first byte. Returns both the decoded length and the number of

     

       216
       216
       -
           bytes consumed to allow proper buffer advancement.

     

       217
       217
       -
           

     

       218
       218
       -
           @param buf Input buffer positioned at the start of an encoded length

     

       219
       219
       -
           @return Tuple of (decoded length, bytes consumed)

     

       220
       220
       -
           @raise Protocol_error if the encoding is invalid or buffer is too short *)

     

       221
       221
       -
       val decode_length : Eio.Buf_read.t -> int * int

     

       222
       222
       -
       

     

       223
       223
       -
       (** {1 Record Construction}

     

       224
       224
       -
           

     

       225
       225
       -
           These convenience functions create properly formatted FastCGI records

     

       226
       226
       -
           with correct headers and content. They handle the binary encoding details

     

       227
       227
       -
           and ensure protocol compliance. *)

     

       228
       228
       -
       

     

       229
       229
       -
       (** Create a begin request record.

     

       230
       230
       -
           

     

       231
       231
       -
           Constructs a Begin_request record to initiate a new FastCGI request.

     

       232
       232
       -
           This record type is sent by web servers to start request processing

     

       233
       233
       -
           and specifies the role the application should play.

     

       234
       234
       -
           

     

       235
       235
       -
           The record contains the application role (Responder, Authorizer, or Filter)

     

       236
       236
       -
           and connection flags that control whether the connection should be kept

     

       237
       237
       -
           alive after the request completes.

     

       238
       238
       -
           

     

       239
       239
       -
           @param request_id Unique request identifier for multiplexing

     

       240
       240
       -
           @param role Role the application should play for this request

     

       241
       241
       -
           @param flags Connection management flags 

     

       242
       242
       -
           @return Complete Begin_request record ready for transmission *)

     

       243
       243
       -
       val make_begin_request :

     

       244
       244
       -
         request_id:Fastcgi_types.request_id ->

     

       245
       245
       -
         role:Fastcgi_types.role ->

     

       246
       246
       -
         flags:Fastcgi_types.connection_flags ->

     

       247
       247
       -
         Fastcgi_types.record

     

       248
       248
       -
       

     

       249
       249
       -
       (** Create an end request record.

     

       250
       250
       -
           

     

       251
       251
       -
           Constructs an End_request record to complete a FastCGI request.

     

       252
       252
       -
           This record is sent by applications to indicate request completion

     

       253
       253
       -
           and provide both application-level and protocol-level status information.

     

       254
       254
       -
           

     

       255
       255
       -
           The application status is similar to a program exit code, where 0

     

       256
       256
       -
           indicates success and non-zero values indicate errors. The protocol

     

       257
       257
       -
           status indicates whether the request was completed normally or rejected

     

       258
       258
       -
           for protocol-related reasons.

     

       259
       259
       -
           

     

       260
       260
       -
           @param request_id Request ID that is being completed

     

       261
       261
       -
           @param app_status Application exit status (0 for success)

     

       262
       262
       -
           @param protocol_status Protocol completion status

     

       263
       263
       -
           @return Complete End_request record ready for transmission *)

     

       264
       264
       -
       val make_end_request :

     

       265
       265
       -
         request_id:Fastcgi_types.request_id ->

     

       266
       266
       -
         app_status:Fastcgi_types.app_status ->

     

       267
       267
       -
         protocol_status:Fastcgi_types.protocol_status ->

     

       268
       268
       -
         Fastcgi_types.record

     

       269
       269
       -
       

     

       270
       270
       -
       (** Create a params record.

     

       271
       271
       -
           

     

       272
       272
       -
           @param request_id Request ID

     

       273
       273
       -
           @param params Parameter name-value pairs

     

       274
       274
       -
           @return Params record *)

     

       275
       275
       -
       val make_params_record :

     

       276
       276
       -
         request_id:Fastcgi_types.request_id ->

     

       277
       277
       -
         params:(string * string) list ->

     

       278
       278
       -
         Fastcgi_types.record

     

       279
       279
       -
       

     

       280
       280
       -
       (** Create a stream record (stdin, stdout, stderr, data).

     

       281
       281
       -
           

     

       282
       282
       -
           @param record_type Stream record type

     

       283
       283
       -
           @param request_id Request ID

     

       284
       284
       -
           @param data Stream data

     

       285
       285
       -
           @return Stream record *)

     

       286
       286
       -
       val make_stream_record :

     

       287
       287
       -
         record_type:Fastcgi_types.record_type ->

     

       288
       288
       -
         request_id:Fastcgi_types.request_id ->

     

       289
       289
       -
         data:bytes ->

     

       290
       290
       -
         Fastcgi_types.record

     

       291
       291
       -
       

     

       292
       292
       -
       (** Create an empty stream record (marks end of stream).

     

       293
       293
       -
           

     

       294
       294
       -
           @param record_type Stream record type

     

       295
       295
       -
           @param request_id Request ID

     

       296
       296
       -
           @return Empty stream record *)

     

       297
       297
       -
       val make_empty_stream_record :

     

       298
       298
       -
         record_type:Fastcgi_types.record_type ->

     

       299
       299
       -
         request_id:Fastcgi_types.request_id ->

     

       300
       300
       -
         Fastcgi_types.record

     

       301
       301
       -
       

     

       302
       302
       -
       (** Create a get values record.

     

       303
       303
       -
           

     

       304
       304
       -
           @param variables Variable names to query

     

       305
       305
       -
           @return Get values record *)

     

       306
       306
       -
       val make_get_values_record :

     

       307
       307
       -
         variables:string list ->

     

       308
       308
       -
         Fastcgi_types.record

     

       309
       309
       -
       

     

       310
       310
       -
       (** Create a get values result record.

     

       311
       311
       -
           

     

       312
       312
       -
           @param values Variable name-value pairs

     

       313
       313
       -
           @return Get values result record *)

     

       314
       314
       -
       val make_get_values_result_record :

     

       315
       315
       -
         values:(string * string) list ->

     

       316
       316
       -
         Fastcgi_types.record

     

       317
       317
       -
       

     

       318
       318
       -
       (** Create an unknown type record.

     

       319
       319
       -
           

     

       320
       320
       -
           @param unknown_type Unknown record type value

     

       321
       321
       -
           @return Unknown type record *)

     

       322
       322
       -
       val make_unknown_type_record :

     

       323
       323
       -
         unknown_type:int ->

     

       324
       324
       -
         Fastcgi_types.record

     

       325
       325
       -
       

     

       326
       326
       -
       (** Create an abort request record.

     

       327
       327
       -
           

     

       328
       328
       -
           @param request_id Request ID to abort

     

       329
       329
       -
           @return Abort request record *)

     

       330
       330
       -
       val make_abort_request_record :

     

       331
       331
       -
         request_id:Fastcgi_types.request_id ->

     

       332
       332
       -
         Fastcgi_types.record

     

       333
       333
       -
       

     

       334
       334
       -
       (** {1 Validation}

     

       335
       335
       -
           

     

       336
       336
       -
           These functions validate protocol elements for compliance with FastCGI

     

       337
       337
       -
           requirements. They help detect malformed data and ensure protocol

     

       338
       338
       -
           correctness during parsing and construction. *)

     

       339
       339
       -
       

     

       340
       340
       -
       (** Validate a record header.

     

       341
       341
       -
           

     

       342
       342
       -
           Checks that a record header contains valid values for all fields.

     

       343
       343
       -
           This includes verifying the protocol version, record type bounds,

     

       344
       344
       -
           content length limits, and padding length constraints.

     

       345
       345
       -
           

     

       346
       346
       -
           @param header Record header to validate

     

       347
       347
       -
           @return True if the header is valid and protocol-compliant

     

       348
       348
       -
           @raise Protocol_error if any field contains invalid values *)

     

       349
       349
       -
       val validate_record_header : Fastcgi_types.record_header -> bool

     

       350
       350
       -
       

     

       351
       351
       -
       (** Validate a complete record.

     

       352
       352
       -
           

     

       353
       353
       -
           Performs comprehensive validation of a complete record including

     

       354
       354
       -
           header validation and content/padding length consistency checks.

     

       355
       355
       -
           Ensures the record can be safely transmitted or processed.

     

       356
       356
       -
           

     

       357
       357
       -
           @param record Complete record to validate

     

       358
       358
       -
           @return True if the entire record is valid and well-formed

     

       359
       359
       -
           @raise Protocol_error if any part of the record is invalid *)

     

       360
       360
       -
       val validate_record : Fastcgi_types.record -> bool

     

       361
       361
       -
       

     

       362
       362
       -
       (** Check if a record type is a management record.

     

       363
       363
       -
           

     

       364
       364
       -
           Management records use request ID 0 and contain protocol-level information

     

       365
       365
       -
           such as capability queries (Get_values) and unknown type responses.

     

       366
       366
       -
           They are not associated with any specific request.

     

       367
       367
       -
           

     

       368
       368
       -
           @param record_type Record type to classify

     

       369
       369
       -
           @return True if this is a management record type *)

     

       370
       370
       -
       val is_management_record : Fastcgi_types.record_type -> bool

     

       371
       371
       -
       

     

       372
       372
       -
       (** Check if a record type is a stream record.

     

       373
       373
       -
           

     

       374
       374
       -
           Stream records (Params, Stdin, Stdout, Stderr, Data) can be sent in

     

       375
       375
       -
           multiple parts and are terminated with an empty record of the same type.

     

       376
       376
       -
           This allows streaming of arbitrarily large data without buffering.

     

       377
       377
       -
           

     

       378
       378
       -
           @param record_type Record type to classify

     

       379
       379
       -
           @return True if this is a stream record type *)

     

       380
       380
       -
       val is_stream_record : Fastcgi_types.record_type -> bool

     

       381
       381
       -
       

     

       382
       382
       -
       (** {1 Protocol Constants}

     

       383
       383
       -
           

     

       384
       384
       -
           Essential constants and utility functions for FastCGI protocol

     

       385
       385
       -
           implementation. These values are defined by the protocol specification. *)

     

       386
       386
       -
       

     

       387
       387
       -
       (** Null request ID for management records.

     

       388
       388
       -
           

     

       389
       389
       -
           Management records always use request ID 0 to indicate they are not

     

       390
       390
       -
           associated with any specific request. Applications must use non-zero

     

       391
       391
       -
           request IDs for all application records. *)

     

       392
       392
       -
       val null_request_id : Fastcgi_types.request_id

     

       393
       393
       -
       

     

       394
       394
       -
       (** Maximum content length for a single record.

     

       395
       395
       -
           

     

       396
       396
       -
           FastCGI records can contain at most 65535 bytes of content data.

     

       397
       397
       -
           Larger data must be split across multiple records of the same type. *)

     

       398
       398
       -
       val max_content_length : int

     

       399
       399
       -
       

     

       400
       400
       -
       (** Maximum padding length for a record.

     

       401
       401
       -
           

     

       402
       402
       -
           Records can have at most 255 bytes of padding for alignment purposes.

     

       403
       403
       -
           Padding bytes are ignored by the receiver. *)

     

       404
       404
       -
       val max_padding_length : int

     

       405
       405
       -
       

     

       406
       406
       -
       (** Calculate optimal padding for 8-byte alignment.

     

       407
       407
       -
           

     

       408
       408
       -
           Computes the number of padding bytes needed to align the total record

     

       409
       409
       -
           size to an 8-byte boundary. This provides optimal performance on most

     

       410
       410
       -
           architectures by ensuring proper memory alignment.

     

       411
       411
       -
           

     

       412
       412
       -
           @param content_length Length of the record content data

     

       413
       413
       -
           @return Number of padding bytes needed (0-7) *)

     

       414
       414
       -
       val calculate_padding : int -> int

-222

lib/fastcgi_responder.mli

···

       1
       1
       -
       (** Responder role implementation for FastCGI.

     

       2
       2
       -
       

     

       3
       3
       -
           The Responder role is the most common FastCGI role, equivalent to

     

       4
       4
       -
           traditional CGI applications. It handles HTTP requests and generates

     

       5
       5
       -
           HTTP responses.

     

       6
       6
       -
           

     

       7
       7
       -
           A Responder FastCGI application has the same purpose as a CGI/1.1 program:

     

       8
       8
       -
           it receives all the information associated with an HTTP request and generates

     

       9
       9
       -
           an HTTP response. This includes CGI environment variables, request headers,

     

       10
       10
       -
           request body data, and produces HTTP response headers and body content.

     

       11
       11
       -
           

     

       12
       12
       -
           The key difference from traditional CGI is that Responder applications are

     

       13
       13
       -
           long-lived processes that can handle multiple requests efficiently, avoiding

     

       14
       14
       -
           the overhead of process creation for each request.

     

       15
       15
       -
           

     

       16
       16
       -
           This module provides high-level abstractions for working with HTTP requests

     

       17
       17
       -
           and responses, automatically handling the conversion between FastCGI protocol

     

       18
       18
       -
           elements and familiar HTTP concepts. *)

     

       19
       19
       -
       

     

       20
       20
       -
       (** {1 HTTP Request/Response Types} *)

     

       21
       21
       -
       

     

       22
       22
       -
       (** CGI-style environment variables.

     

       23
       23
       -
           

     

       24
       24
       -
           A list of name-value pairs containing the CGI environment variables

     

       25
       25
       -
           passed from the web server. These typically include variables like

     

       26
       26
       -
           REQUEST_METHOD, REQUEST_URI, HTTP_HOST, CONTENT_TYPE, etc. *)

     

       27
       27
       -
       type cgi_env = (string * string) list

     

       28
       28
       -
       

     

       29
       29
       -
       (** HTTP request information extracted from FastCGI parameters.

     

       30
       30
       -
           

     

       31
       31
       -
           This type represents an HTTP request in a convenient form for application

     

       32
       32
       -
           processing. It extracts and parses the most commonly needed information

     

       33
       33
       -
           from the CGI environment variables provided by the web server. *)

     

       34
       34
       -
       type 'a http_request = {

     

       35
       35
       -
         method_ : string;              (** HTTP method (GET, POST, PUT, DELETE, etc.).

     

       36
       36
       -
                                            Extracted from REQUEST_METHOD CGI variable. *)

     

       37
       37
       -
         uri : string;                 (** Request URI path component, without query string.

     

       38
       38
       -
                                            Extracted from REQUEST_URI or SCRIPT_NAME + PATH_INFO. *)

     

       39
       39
       -
         query_string : string;        (** URL query string parameters (after the '?' in the URL).

     

       40
       40
       -
                                            Extracted from QUERY_STRING CGI variable. *)

     

       41
       41
       -
         content_type : string option; (** MIME type of the request body, if present.

     

       42
       42
       -
                                            Extracted from CONTENT_TYPE CGI variable. *)

     

       43
       43
       -
         content_length : int option;  (** Length of the request body in bytes, if known.

     

       44
       44
       -
                                            Extracted from CONTENT_LENGTH CGI variable. *)

     

       45
       45
       -
         headers : (string * string) list; (** HTTP headers sent by the client. Extracted from

     

       46
       46
       -
                                                CGI variables with HTTP_ prefix. *)

     

       47
       47
       -
         body : 'a Eio.Flow.source;   (** Request body data stream. For POST requests,

     

       48
       48
       -
                                            this contains form data or payload content. *)

     

       49
       49
       -
       }

     

       50
       50
       -
       

     

       51
       51
       -
       (** HTTP response builder for constructing responses.

     

       52
       52
       -
           

     

       53
       53
       -
           This type provides a streaming interface for generating HTTP responses.

     

       54
       54
       -
           It handles proper HTTP formatting including status line, headers, and

     

       55
       55
       -
           body content. The response is written incrementally to avoid buffering

     

       56
       56
       -
           large responses in memory. *)

     

       57
       57
       -
       type 'a http_response = {

     

       58
       58
       -
         write_status : int -> unit;                    (** Set the HTTP status code (200, 404, 500, etc.).

     

       59
       59
       -
                                                            Must be called before writing headers or body. *)

     

       60
       60
       -
         write_header : string -> string -> unit;      (** Add an HTTP response header.

     

       61
       61
       -
                                                            Common headers include Content-Type, Set-Cookie, etc. *)

     

       62
       62
       -
         write_body : string -> unit;                  (** Write string content to the response body.

     

       63
       63
       -
                                                            Handles encoding and streaming automatically. *)

     

       64
       64
       -
         write_body_chunk : bytes -> unit;             (** Write binary data to the response body.

     

       65
       65
       -
                                                            Useful for file downloads or binary content. *)

     

       66
       66
       -
         finish : unit -> unit;                        (** Complete the response and close the connection.

     

       67
       67
       -
                                                            Must be called to ensure proper termination. *)

     

       68
       68
       -
       }

     

       69
       69
       -
       

     

       70
       70
       -
       (** {1 Conversion Functions} *)

     

       71
       71
       -
       

     

       72
       72
       -
       (** Convert FastCGI request to HTTP request.

     

       73
       73
       -
           

     

       74
       74
       -
           Extracts HTTP-specific information from FastCGI parameters

     

       75
       75
       -
           and creates an HTTP request object.

     

       76
       76
       -
           

     

       77
       77
       -
           @param request FastCGI request

     

       78
       78
       -
           @return HTTP request with extracted information *)

     

       79
       79
       -
       val request_of_fastcgi : 'a Fastcgi_types.request -> 'a http_request

     

       80
       80
       -
       

     

       81
       81
       -
       (** Create HTTP response writer from FastCGI response.

     

       82
       82
       -
           

     

       83
       83
       -
           Wraps FastCGI response streams to provide HTTP-style

     

       84
       84
       -
           response writing interface.

     

       85
       85
       -
           

     

       86
       86
       -
           @param response FastCGI response

     

       87
       87
       -
           @return HTTP response writer *)

     

       88
       88
       -
       val response_of_fastcgi : 'a Fastcgi_types.response -> 'a http_response

     

       89
       89
       -
       

     

       90
       90
       -
       (** {1 Handler Utilities} *)

     

       91
       91
       -
       

     

       92
       92
       -
       (** Responder handler type. *)

     

       93
       93
       -
       type 'a responder_handler = 'a Fastcgi_types.request -> 'a Fastcgi_types.response -> Fastcgi_types.response_result

     

       94
       94
       -
       

     

       95
       95
       -
       (** Convenience handler wrapper for HTTP-style handlers.

     

       96
       96
       -
           

     

       97
       97
       -
           Converts an HTTP-style handler function into a FastCGI handler.

     

       98
       98
       -
           This allows writing handlers that work with HTTP request/response

     

       99
       99
       -
           objects instead of raw FastCGI types.

     

       100
       100
       -
           

     

       101
       101
       -
           @param handler HTTP handler function

     

       102
       102
       -
           @return FastCGI responder handler *)

     

       103
       103
       -
       val http_handler :

     

       104
       104
       -
         ('a http_request -> 'a http_response -> unit) ->

     

       105
       105
       -
         'a responder_handler

     

       106
       106
       -
       

     

       107
       107
       -
       (** {1 Common HTTP Operations} *)

     

       108
       108
       -
       

     

       109
       109
       -
       (** Send a simple text response.

     

       110
       110
       -
           

     

       111
       111
       -
           @param response HTTP response writer

     

       112
       112
       -
           @param status HTTP status code

     

       113
       113
       -
           @param content_type MIME type

     

       114
       114
       -
           @param body Response body text *)

     

       115
       115
       -
       val send_text_response :

     

       116
       116
       -
         'a http_response ->

     

       117
       117
       -
         status:int ->

     

       118
       118
       -
         content_type:string ->

     

       119
       119
       -
         body:string ->

     

       120
       120
       -
         unit

     

       121
       121
       -
       

     

       122
       122
       -
       (** Send a JSON response.

     

       123
       123
       -
           

     

       124
       124
       -
           @param response HTTP response writer

     

       125
       125
       -
           @param status HTTP status code

     

       126
       126
       -
           @param json JSON string *)

     

       127
       127
       -
       val send_json_response :

     

       128
       128
       -
         'a http_response ->

     

       129
       129
       -
         status:int ->

     

       130
       130
       -
         json:string ->

     

       131
       131
       -
         unit

     

       132
       132
       -
       

     

       133
       133
       -
       (** Send an HTML response.

     

       134
       134
       -
           

     

       135
       135
       -
           @param response HTTP response writer

     

       136
       136
       -
           @param status HTTP status code

     

       137
       137
       -
           @param html HTML content *)

     

       138
       138
       -
       val send_html_response :

     

       139
       139
       -
         'a http_response ->

     

       140
       140
       -
         status:int ->

     

       141
       141
       -
         html:string ->

     

       142
       142
       -
         unit

     

       143
       143
       -
       

     

       144
       144
       -
       (** Send an error response.

     

       145
       145
       -
           

     

       146
       146
       -
           @param response HTTP response writer

     

       147
       147
       -
           @param status HTTP error status code

     

       148
       148
       -
           @param message Error message *)

     

       149
       149
       -
       val send_error_response :

     

       150
       150
       -
         'a http_response ->

     

       151
       151
       -
         status:int ->

     

       152
       152
       -
         message:string ->

     

       153
       153
       -
         unit

     

       154
       154
       -
       

     

       155
       155
       -
       (** Send a redirect response.

     

       156
       156
       -
           

     

       157
       157
       -
           @param response HTTP response writer

     

       158
       158
       -
           @param status Redirect status code (301, 302, etc.)

     

       159
       159
       -
           @param location Target URL *)

     

       160
       160
       -
       val send_redirect_response :

     

       161
       161
       -
         'a http_response ->

     

       162
       162
       -
         status:int ->

     

       163
       163
       -
         location:string ->

     

       164
       164
       -
         unit

     

       165
       165
       -
       

     

       166
       166
       -
       (** {1 Request Parsing} *)

     

       167
       167
       -
       

     

       168
       168
       -
       (** Parse query string into parameter map.

     

       169
       169
       -
           

     

       170
       170
       -
           @param query_string URL-encoded query string

     

       171
       171
       -
           @return Association list of parameter name-value pairs *)

     

       172
       172
       -
       val parse_query_string : string -> (string * string) list

     

       173
       173
       -
       

     

       174
       174
       -
       (** Parse form data from request body.

     

       175
       175
       -
           

     

       176
       176
       -
           Supports both application/x-www-form-urlencoded and

     

       177
       177
       -
           multipart/form-data content types.

     

       178
       178
       -
           

     

       179
       179
       -
           @param request HTTP request

     

       180
       180
       -
           @return Association list of form field name-value pairs *)

     

       181
       181
       -
       val parse_form_data : 'a http_request -> (string * string) list

     

       182
       182
       -
       

     

       183
       183
       -
       (** Get request header value.

     

       184
       184
       -
           

     

       185
       185
       -
           @param request HTTP request

     

       186
       186
       -
           @param name Header name (case-insensitive)

     

       187
       187
       -
           @return Header value if present *)

     

       188
       188
       -
       val get_header : 'a http_request -> string -> string option

     

       189
       189
       -
       

     

       190
       190
       -
       (** Get request parameter from query string or form data.

     

       191
       191
       -
           

     

       192
       192
       -
           @param request HTTP request

     

       193
       193
       -
           @param name Parameter name

     

       194
       194
       -
           @return Parameter value if present *)

     

       195
       195
       -
       val get_param : 'a http_request -> string -> string option

     

       196
       196
       -
       

     

       197
       197
       -
       (** {1 File Operations} *)

     

       198
       198
       -
       

     

       199
       199
       -
       (** File upload information. *)

     

       200
       200
       -
       type 'a file_upload = {

     

       201
       201
       -
         filename : string option;     (** Original filename *)

     

       202
       202
       -
         content_type : string option; (** MIME type *)

     

       203
       203
       -
         size : int;                   (** File size in bytes *)

     

       204
       204
       -
         data : 'a Eio.Flow.source;   (** File content stream *)

     

       205
       205
       -
       }

     

       206
       206
       -
       

     

       207
       207
       -
       (** Parse file uploads from multipart form data.

     

       208
       208
       -
           

     

       209
       209
       -
           @param request HTTP request with multipart content

     

       210
       210
       -
           @return Association list of field name to file upload *)

     

       211
       211
       -
       val parse_file_uploads : 'a http_request -> (string * 'a file_upload) list

     

       212
       212
       -
       

     

       213
       213
       -
       (** Save uploaded file to filesystem.

     

       214
       214
       -
           

     

       215
       215
       -
           @param fs Filesystem capability

     

       216
       216
       -
           @param path Destination path

     

       217
       217
       -
           @param upload File upload to save *)

     

       218
       218
       -
       val save_upload :

     

       219
       219
       -
         fs:Eio.Fs.dir_ty Eio.Path.t ->

     

       220
       220
       -
         path:string ->

     

       221
       221
       -
         upload:'a file_upload ->

     

       222
       222
       -
         unit

-444

lib/fastcgi_types.mli

···

       1
       1
       -
       (** Core FastCGI types and constants.

     

       2
       2
       -
       

     

       3
       3
       -
           This module defines the fundamental types used throughout the

     

       4
       4
       -
           FastCGI protocol implementation.

     

       5
       5
       -
       

     

       6
       6
       -
           FastCGI is an open extension to CGI that provides high performance for

     

       7
       7
       -
           all Internet applications without the penalties of Web server APIs.

     

       8
       8
       -
           Unlike traditional CGI programs that are started for each request,

     

       9
       9
       -
           FastCGI applications are long-lived processes that can handle multiple

     

       10
       10
       -
           requests over persistent connections. *)

     

       11
       11
       -
       

     

       12
       12
       -
       (** {1 Core Types} *)

     

       13
       13
       -
       

     

       14
       14
       -
       (** FastCGI protocol version.

     

       15
       15
       -
           

     

       16
       16
       -
           The current protocol uses version 1. Future versions of the

     

       17
       17
       -
           protocol may increment this value. Applications should check the version

     

       18
       18
       -
           field in incoming records and reject unsupported versions.

     

       19
       19
       -
           

     

       20
       20
       -
           Version 1 is represented by the value [1]. *)

     

       21
       21
       -
       type version = int

     

       22
       22
       -
       

     

       23
       23
       -
       (** FastCGI record types.

     

       24
       24
       -
           

     

       25
       25
       -
           All data transmitted over a FastCGI connection is packaged in records.

     

       26
       26
       -
           Each record has a type that determines how the record's content should

     

       27
       27
       -
           be interpreted. The protocol defines both management records (for

     

       28
       28
       -
           protocol-level communication) and application records (for request

     

       29
       29
       -
           processing).

     

       30
       30
       -
           

     

       31
       31
       -
           Management records contain information that is not specific to any web

     

       32
       32
       -
           server request, such as capability queries and unknown type responses.

     

       33
       33
       -
           Application records contain information about a particular request,

     

       34
       34
       -
           identified by a non-zero request ID. *)

     

       35
       35
       -
       type record_type =

     

       36
       36
       -
         | Begin_request    (** Starts a new request. Sent by the web server to begin

     

       37
       37
       -
                                processing. Contains the role and connection flags. *)

     

       38
       38
       -
         | Abort_request    (** Aborts an existing request. Sent by the web server

     

       39
       39
       -
                                when an HTTP client closes its connection while the

     

       40
       40
       -
                                request is still being processed. *)

     

       41
       41
       -
         | End_request      (** Completes a request. Sent by the application to

     

       42
       42
       -
                                terminate processing, either normally or due to

     

       43
       43
       -
                                an error condition. *)

     

       44
       44
       -
         | Params           (** Parameter name-value pairs. Used to transmit CGI-style

     

       45
       45
       -
                                environment variables from the web server to the

     

       46
       46
       -
                                application. Sent as a stream. *)

     

       47
       47
       -
         | Stdin            (** Standard input data. Contains the request body data

     

       48
       48
       -
                                that would normally be available on stdin in CGI.

     

       49
       49
       -
                                Sent as a stream. *)

     

       50
       50
       -
         | Stdout           (** Standard output data. Response data from the application

     

       51
       51
       -
                                to the web server. This becomes the HTTP response.

     

       52
       52
       -
                                Sent as a stream. *)

     

       53
       53
       -
         | Stderr           (** Standard error data. Error messages from the application.

     

       54
       54
       -
                                Used for logging and debugging. Sent as a stream. *)

     

       55
       55
       -
         | Data             (** Additional data stream. Used only in the Filter role

     

       56
       56
       -
                                to transmit file data that needs to be filtered.

     

       57
       57
       -
                                Sent as a stream. *)

     

       58
       58
       -
         | Get_values       (** Management record to query application variables.

     

       59
       59
       -
                                Allows the web server to discover application

     

       60
       60
       -
                                capabilities like max connections and multiplexing. *)

     

       61
       61
       -
         | Get_values_result (** Management record response to Get_values. Contains

     

       62
       62
       -
                                the requested variable values. *)

     

       63
       63
       -
         | Unknown_type     (** Management record for unknown type handling. Sent by

     

       64
       64
       -
                                the application when it receives a record type it

     

       65
       65
       -
                                doesn't understand. *)

     

       66
       66
       -
       

     

       67
       67
       -
       (** FastCGI application roles.

     

       68
       68
       -
           

     

       69
       69
       -
           A FastCGI application can play one of several well-defined roles.

     

       70
       70
       -
           The role determines what information the application receives and

     

       71
       71
       -
           what it's expected to produce.

     

       72
       72
       -
           

     

       73
       73
       -
           A FastCGI application plays one of several well-defined roles. The most

     

       74
       74
       -
           familiar is the Responder role, in which the application receives all

     

       75
       75
       -
           the information associated with an HTTP request and generates an HTTP

     

       76
       76
       -
           response. *)

     

       77
       77
       -
       type role =

     

       78
       78
       -
         | Responder    (** The most common role, equivalent to traditional CGI.

     

       79
       79
       -
                            The application receives all information associated with

     

       80
       80
       -
                            an HTTP request and generates an HTTP response. This

     

       81
       81
       -
                            includes environment variables, request headers, and

     

       82
       82
       -
                            request body data. *)

     

       83
       83
       -
         | Authorizer   (** Performs access control decisions. The application

     

       84
       84
       -
                            receives HTTP request information and generates an

     

       85
       85
       -
                            authorized/unauthorized decision. In case of authorization,

     

       86
       86
       -
                            it can associate additional variables with the request.

     

       87
       87
       -
                            For unauthorized requests, it provides a complete HTTP

     

       88
       88
       -
                            error response. *)

     

       89
       89
       -
         | Filter       (** Processes data streams with filtering. The application

     

       90
       90
       -
                            receives HTTP request information plus an additional

     

       91
       91
       -
                            data stream from a file stored on the web server, and

     

       92
       92
       -
                            generates a "filtered" version of the data as an HTTP

     

       93
       93
       -
                            response. Both the file and the filter can be access

     

       94
       94
       -
                            controlled. *)

     

       95
       95
       -
       

     

       96
       96
       -
       (** Request ID for multiplexing multiple requests over a single connection.

     

       97
       97
       -
           

     

       98
       98
       -
           FastCGI supports multiplexing, allowing multiple concurrent requests

     

       99
       99
       -
           to be processed over a single transport connection. Each request is

     

       100
       100
       -
           identified by a unique request ID within the scope of that connection.

     

       101
       101
       -
           

     

       102
       102
       -
           The Web server re-uses FastCGI request IDs; the application keeps track

     

       103
       103
       -
           of the current state of each request ID on a given transport connection.

     

       104
       104
       -
           Request IDs should be small integers to allow efficient tracking using

     

       105
       105
       -
           arrays rather than hash tables.

     

       106
       106
       -
           

     

       107
       107
       -
           The value [0] is reserved for management records and is called the

     

       108
       108
       -
           "null request ID". *)

     

       109
       109
       -
       type request_id = int

     

       110
       110
       -
       

     

       111
       111
       -
       (** Application-level status code.

     

       112
       112
       -
           

     

       113
       113
       -
           When an application completes a request, it provides an application

     

       114
       114
       -
           status code similar to the exit status of a traditional CGI program.

     

       115
       115
       -
           A value of [0] indicates success, while non-zero values indicate

     

       116
       116
       -
           various error conditions.

     

       117
       117
       -
           

     

       118
       118
       -
           The application sets the appStatus component to the status code that

     

       119
       119
       -
           the CGI program would have returned via the exit system call. *)

     

       120
       120
       -
       type app_status = int

     

       121
       121
       -
       

     

       122
       122
       -
       (** Protocol-level status codes.

     

       123
       123
       -
           

     

       124
       124
       -
           In addition to application status, each request completion includes

     

       125
       125
       -
           a protocol-level status that indicates whether the request was

     

       126
       126
       -
           processed normally or rejected for protocol-related reasons.

     

       127
       127
       -
           

     

       128
       128
       -
           These status codes allow the web server to understand why a request

     

       129
       129
       -
           was not processed and take appropriate action. *)

     

       130
       130
       -
       type protocol_status =

     

       131
       131
       -
         | Request_complete      (** Normal end of request. The application successfully

     

       132
       132
       -
                                     processed the request and the appStatus field

     

       133
       133
       -
                                     indicates the application-level result. *)

     

       134
       134
       -
         | Cant_mpx_conn        (** Rejecting a new request because the application

     

       135
       135
       -
                                     cannot multiplex connections. This happens when

     

       136
       136
       -
                                     a web server sends concurrent requests over one

     

       137
       137
       -
                                     connection to an application that processes only

     

       138
       138
       -
                                     one request at a time per connection. *)

     

       139
       139
       -
         | Overloaded           (** Rejecting a new request because the application

     

       140
       140
       -
                                     is overloaded. This occurs when the application

     

       141
       141
       -
                                     runs out of some resource, such as database

     

       142
       142
       -
                                     connections or memory. *)

     

       143
       143
       -
         | Unknown_role         (** Rejecting a new request because the requested

     

       144
       144
       -
                                     role is unknown to the application. This happens

     

       145
       145
       -
                                     when the web server specifies a role that the

     

       146
       146
       -
                                     application doesn't implement. *)

     

       147
       147
       -
       

     

       148
       148
       -
       (** Connection flags for controlling connection behavior.

     

       149
       149
       -
           

     

       150
       150
       -
           These flags are sent in Begin_request records to control how the

     

       151
       151
       -
           connection should be managed after the request completes. *)

     

       152
       152
       -
       type connection_flags = {

     

       153
       153
       -
         keep_conn : bool;  (** Keep connection open after request completion.

     

       154
       154
       -
                                

     

       155
       155
       -
                                If false, the application closes the connection after

     

       156
       156
       -
                                responding to this request. If true, the application

     

       157
       157
       -
                                does not close the connection after responding to this

     

       158
       158
       -
                                request; the Web server retains responsibility for the

     

       159
       159
       -
                                connection.

     

       160
       160
       -
                                

     

       161
       161
       -
                                This flag enables connection reuse for better performance,

     

       162
       162
       -
                                especially important for high-traffic applications. *)

     

       163
       163
       -
       }

     

       164
       164
       -
       

     

       165
       165
       -
       (** {1 Record Types} *)

     

       166
       166
       -
       

     

       167
       167
       -
       (** FastCGI record header.

     

       168
       168
       -
           

     

       169
       169
       -
           Every FastCGI record begins with an 8-byte header that identifies

     

       170
       170
       -
           the record type, request ID, and content length. This fixed-length

     

       171
       171
       -
           prefix allows efficient parsing and proper demultiplexing of records.

     

       172
       172
       -
           

     

       173
       173
       -
           A FastCGI record consists of a fixed-length prefix followed by a

     

       174
       174
       -
           variable number of content and padding bytes.

     

       175
       175
       -
           

     

       176
       176
       -
           The header format is platform-independent and uses network byte order

     

       177
       177
       -
           for multi-byte integers. *)

     

       178
       178
       -
       type record_header = {

     

       179
       179
       -
         version : int;          (** Protocol version. Must be [1] for this specification.

     

       180
       180
       -
                                     Future versions may increment this value. *)

     

       181
       181
       -
         record_type : record_type; (** Type of this record, determining how to interpret

     

       182
       182
       -
                                        the content data. *)

     

       183
       183
       -
         request_id : request_id;   (** Request ID this record belongs to. Value [0] is

     

       184
       184
       -
                                        reserved for management records. *)

     

       185
       185
       -
         content_length : int;      (** Number of bytes in the content data. Must be

     

       186
       186
       -
                                        between [0] and [65535]. *)

     

       187
       187
       -
         padding_length : int;      (** Number of padding bytes following content.

     

       188
       188
       -
                                        Must be between [0] and [255]. Used for alignment. *)

     

       189
       189
       -
       }

     

       190
       190
       -
       

     

       191
       191
       -
       (** Begin request record body.

     

       192
       192
       -
           

     

       193
       193
       -
           This record marks the start of a new request and specifies the role

     

       194
       194
       -
           the application should play and connection management flags.

     

       195
       195
       -
           

     

       196
       196
       -
           The Web server sends a FCGI_BEGIN_REQUEST record to start a request.

     

       197
       197
       -
           The record body contains the role and flags that control request

     

       198
       198
       -
           processing. *)

     

       199
       199
       -
       type begin_request_body = {

     

       200
       200
       -
         role : role;              (** The role the web server expects the application

     

       201
       201
       -
                                       to play for this request. *)

     

       202
       202
       -
         flags : connection_flags; (** Flags controlling connection behavior after

     

       203
       203
       -
                                       request completion. *)

     

       204
       204
       -
       }

     

       205
       205
       -
       

     

       206
       206
       -
       (** End request record body.

     

       207
       207
       -
           

     

       208
       208
       -
           This record marks the completion of a request and provides both

     

       209
       209
       -
           application-level and protocol-level status information.

     

       210
       210
       -
           

     

       211
       211
       -
           The application sends a FCGI_END_REQUEST record to terminate a request,

     

       212
       212
       -
           either because the application has processed the request or because the

     

       213
       213
       -
           application has rejected the request. *)

     

       214
       214
       -
       type end_request_body = {

     

       215
       215
       -
         app_status : app_status;        (** Application-level status code, similar to

     

       216
       216
       -
                                             a CGI program's exit status. *)

     

       217
       217
       -
         protocol_status : protocol_status; (** Protocol-level status indicating normal

     

       218
       218
       -
                                                 completion or rejection reason. *)

     

       219
       219
       -
       }

     

       220
       220
       -
       

     

       221
       221
       -
       (** Complete FastCGI record.

     

       222
       222
       -
           

     

       223
       223
       -
           A complete record consists of the header, content data, and optional

     

       224
       224
       -
           padding. The content interpretation depends on the record type.

     

       225
       225
       -
           

     

       226
       226
       -
           Records support padding to allow senders to keep data aligned for more

     

       227
       227
       -
           efficient processing. Experience with the X window system protocols shows

     

       228
       228
       -
           the performance benefit of such alignment. *)

     

       229
       229
       -
       type record = {

     

       230
       230
       -
         header : record_header;  (** Fixed 8-byte header with record metadata. *)

     

       231
       231
       -
         content : bytes;         (** Variable-length content data. Length must match

     

       232
       232
       -
                                      header.content_length. *)

     

       233
       233
       -
         padding : bytes option;  (** Optional padding data for alignment. Length must

     

       234
       234
       -
                                      match header.padding_length if present. *)

     

       235
       235
       -
       }

     

       236
       236
       -
       

     

       237
       237
       -
       (** Name-value pair for parameters.

     

       238
       238
       -
           

     

       239
       239
       -
           FastCGI uses a compact binary encoding for transmitting name-value pairs

     

       240
       240
       -
           such as CGI environment variables. This encoding supports both short

     

       241
       241
       -
           and long names/values efficiently.

     

       242
       242
       -
           

     

       243
       243
       -
           FastCGI transmits a name-value pair as the length of the name, followed

     

       244
       244
       -
           by the length of the value, followed by the name, followed by the value.

     

       245
       245
       -
           Lengths of 127 bytes and less can be encoded in one byte, while longer

     

       246
       246
       -
           lengths are always encoded in four bytes. *)

     

       247
       247
       -
       type name_value_pair = {

     

       248
       248
       -
         name : string;   (** Parameter name. For CGI compatibility, these are typically

     

       249
       249
       -
                              uppercase environment variable names like "REQUEST_METHOD". *)

     

       250
       250
       -
         value : string;  (** Parameter value. The value does not include a terminating

     

       251
       251
       -
                              null byte in the FastCGI encoding. *)

     

       252
       252
       -
       }

     

       253
       253
       -
       

     

       254
       254
       -
       (** {1 Request/Response Model} *)

     

       255
       255
       -
       

     

       256
       256
       -
       (** Request context containing all information for a FastCGI request.

     

       257
       257
       -
           

     

       258
       258
       -
           This high-level type aggregates all the information needed to process

     

       259
       259
       -
           a FastCGI request. It combines the protocol-level details (request ID,

     

       260
       260
       -
           role, flags) with the application data (parameters and input streams).

     

       261
       261
       -
           

     

       262
       262
       -
           The request follows a two-level processing model: First, the protocol

     

       263
       263
       -
           multiplexes a single transport connection between several independent

     

       264
       264
       -
           FastCGI requests. Second, within each request the protocol provides

     

       265
       265
       -
           several independent data streams in each direction. *)

     

       266
       266
       -
       type 'a request = {

     

       267
       267
       -
         request_id : request_id;      (** Unique identifier for this request within

     

       268
       268
       -
                                           the connection scope. Used for multiplexing. *)

     

       269
       269
       -
         role : role;                  (** The role this application should play for

     

       270
       270
       -
                                           this request (Responder, Authorizer, or Filter). *)

     

       271
       271
       -
         flags : connection_flags;     (** Connection management flags from the web server. *)

     

       272
       272
       -
         params : (string * string) list; (** CGI-style environment variables transmitted

     

       273
       273
       -
                                               via FCGI_PARAMS records. These provide request

     

       274
       274
       -
                                               context like HTTP headers, server info, etc. *)

     

       275
       275
       -
         stdin : 'a Eio.Flow.source;  (** Standard input stream, containing request body

     

       276
       276
       -
                                           data (equivalent to CGI stdin). For HTTP POST

     

       277
       277
       -
                                           requests, this contains the form data or payload. *)

     

       278
       278
       -
         data : 'a Eio.Flow.source option; (** Additional data stream, used only in Filter

     

       279
       279
       -
                                                role. Contains file data that needs to be

     

       280
       280
       -
                                                filtered. [None] for Responder and Authorizer. *)

     

       281
       281
       -
       }

     

       282
       282
       -
       

     

       283
       283
       -
       (** Response builder for constructing FastCGI responses.

     

       284
       284
       -
           

     

       285
       285
       -
           This type provides the output streams for sending response data back

     

       286
       286
       -
           to the web server. Following CGI conventions, it separates normal

     

       287
       287
       -
           output from error output.

     

       288
       288
       -
           

     

       289
       289
       -
           Both stdout and stderr data pass over a single transport connection from

     

       290
       290
       -
           the application to the Web server, rather than requiring separate pipes

     

       291
       291
       -
           as with CGI/1.1. *)

     

       292
       292
       -
       type 'a response = {

     

       293
       293
       -
         stdout : 'a Eio.Flow.sink;   (** Standard output stream for response data.

     

       294
       294
       -
                                           In Responder role, this contains the HTTP

     

       295
       295
       -
                                           response including headers and body. *)

     

       296
       296
       -
         stderr : 'a Eio.Flow.sink;   (** Standard error stream for logging and debugging.

     

       297
       297
       -
                                           All role protocols use the FCGI_STDERR stream

     

       298
       298
       -
                                           just the way stderr is used in conventional

     

       299
       299
       -
                                           applications programming: to report application-level

     

       300
       300
       -
                                           errors in an intelligible way. *)

     

       301
       301
       -
       }

     

       302
       302
       -
       

     

       303
       303
       -
       (** Complete response with status.

     

       304
       304
       -
           

     

       305
       305
       -
           When an application finishes processing a request, it must provide

     

       306
       306
       -
           both application-level and protocol-level status information. This

     

       307
       307
       -
           allows the web server to understand the outcome and take appropriate

     

       308
       308
       -
           action.

     

       309
       309
       -
           

     

       310
       310
       -
           This corresponds to the FCGI_END_REQUEST record sent by the application. *)

     

       311
       311
       -
       type response_result = {

     

       312
       312
       -
         app_status : app_status;        (** Application exit status, equivalent to what

     

       313
       313
       -
                                             a CGI program would return via exit(). *)

     

       314
       314
       -
         protocol_status : protocol_status; (** Protocol-level completion status, indicating

     

       315
       315
       -
                                                 normal completion or various rejection reasons. *)

     

       316
       316
       -
       }

     

       317
       317
       -
       

     

       318
       318
       -
       (** {1 Protocol Constants} *)

     

       319
       319
       -
       

     

       320
       320
       -
       (** Protocol version constant.

     

       321
       321
       -
           

     

       322
       322
       -
           This constant represents FCGI_VERSION_1. This value should be used in

     

       323
       323
       -
           the version field of all record headers. *)

     

       324
       324
       -
       val version_1 : int

     

       325
       325
       -
       

     

       326
       326
       -
       (** Standard file descriptor for FastCGI listening socket.

     

       327
       327
       -
           

     

       328
       328
       -
           The Web server leaves a single file descriptor, FCGI_LISTENSOCK_FILENO,

     

       329
       329
       -
           open when the application begins execution. This descriptor refers to a

     

       330
       330
       -
           listening socket created by the Web server.

     

       331
       331
       -
           

     

       332
       332
       -
           The value equals STDIN_FILENO (0). Applications can distinguish between

     

       333
       333
       -
           CGI and FastCGI invocation by calling getpeername() on this descriptor. *)

     

       334
       334
       -
       val listensock_fileno : int

     

       335
       335
       -
       

     

       336
       336
       -
       (** {2 Record Type Constants}

     

       337
       337
       -
           

     

       338
       338
       -
           These integer constants correspond to the record_type variants and are

     

       339
       339
       -
           used in the binary protocol encoding. These are the values transmitted

     

       340
       340
       -
           in the type field of record headers. *)

     

       341
       341
       -
       

     

       342
       342
       -
       (** Value [1]. Starts a new request. *)

     

       343
       343
       -
       val fcgi_begin_request : int

     

       344
       344
       -
       

     

       345
       345
       -
       (** Value [2]. Aborts an existing request. *)

     

       346
       346
       -
       val fcgi_abort_request : int

     

       347
       347
       -
       

     

       348
       348
       -
       (** Value [3]. Completes a request. *)

     

       349
       349
       -
       val fcgi_end_request : int

     

       350
       350
       -
       

     

       351
       351
       -
       (** Value [4]. Parameter name-value pairs. *)

     

       352
       352
       -
       val fcgi_params : int

     

       353
       353
       -
       

     

       354
       354
       -
       (** Value [5]. Standard input data. *)

     

       355
       355
       -
       val fcgi_stdin : int

     

       356
       356
       -
       

     

       357
       357
       -
       (** Value [6]. Standard output data. *)

     

       358
       358
       -
       val fcgi_stdout : int

     

       359
       359
       -
       

     

       360
       360
       -
       (** Value [7]. Standard error data. *)

     

       361
       361
       -
       val fcgi_stderr : int

     

       362
       362
       -
       

     

       363
       363
       -
       (** Value [8]. Additional data stream (Filter). *)

     

       364
       364
       -
       val fcgi_data : int

     

       365
       365
       -
       

     

       366
       366
       -
       (** Value [9]. Query application variables. *)

     

       367
       367
       -
       val fcgi_get_values : int

     

       368
       368
       -
       

     

       369
       369
       -
       (** Value [10]. Response to Get_values. *)

     

       370
       370
       -
       val fcgi_get_values_result : int

     

       371
       371
       -
       

     

       372
       372
       -
       (** Value [11]. Unknown record type response. *)

     

       373
       373
       -
       val fcgi_unknown_type : int

     

       374
       374
       -
       

     

       375
       375
       -
       (** {2 Role Constants}

     

       376
       376
       -
           

     

       377
       377
       -
           These integer constants correspond to the role variants and are used

     

       378
       378
       -
           in Begin_request record bodies. These identify the role the web server

     

       379
       379
       -
           expects the application to play. *)

     

       380
       380
       -
       

     

       381
       381
       -
       (** Value [1]. Handle HTTP requests and generate responses. *)

     

       382
       382
       -
       val fcgi_responder : int

     

       383
       383
       -
       

     

       384
       384
       -
       (** Value [2]. Perform authorization decisions. *)

     

       385
       385
       -
       val fcgi_authorizer : int

     

       386
       386
       -
       

     

       387
       387
       -
       (** Value [3]. Process data streams with filtering. *)

     

       388
       388
       -
       val fcgi_filter : int

     

       389
       389
       -
       

     

       390
       390
       -
       (** {2 Flag Constants}

     

       391
       391
       -
           

     

       392
       392
       -
           These constants are used in the flags field of Begin_request records

     

       393
       393
       -
           to control connection behavior. *)

     

       394
       394
       -
       

     

       395
       395
       -
       (** Value [1]. Keep connection open after request.

     

       396
       396
       -
           If zero, the application closes the connection after

     

       397
       397
       -
           responding to this request. If not zero, the application

     

       398
       398
       -
           does not close the connection after responding to this

     

       399
       399
       -
           request. *)

     

       400
       400
       -
       val fcgi_keep_conn : int

     

       401
       401
       -
       

     

       402
       402
       -
       (** {2 Protocol Limits}

     

       403
       403
       -
           

     

       404
       404
       -
           These constants define the maximum sizes for various protocol elements,

     

       405
       405
       -
           ensuring compatibility and preventing buffer overflows. *)

     

       406
       406
       -
       

     

       407
       407
       -
       (** Value [65535]. Maximum bytes in record content.

     

       408
       408
       -
           Between 0 and 65535 bytes of data, interpreted

     

       409
       409
       -
           according to the record type. *)

     

       410
       410
       -
       val max_content_length : int

     

       411
       411
       -
       

     

       412
       412
       -
       (** Value [255]. Maximum bytes in record padding.

     

       413
       413
       -
           Between 0 and 255 bytes of data, which are ignored. *)

     

       414
       414
       -
       val max_padding_length : int

     

       415
       415
       -
       

     

       416
       416
       -
       (** Value [8]. Fixed size of record headers.

     

       417
       417
       -
           Number of bytes in a FCGI_Header. Future versions

     

       418
       418
       -
           of the protocol will not reduce this number. *)

     

       419
       419
       -
       val header_length : int

     

       420
       420
       -
       

     

       421
       421
       -
       (** {2 Management Record Variables}

     

       422
       422
       -
           

     

       423
       423
       -
           These string constants identify the standard management variables that

     

       424
       424
       -
           can be queried using FCGI_GET_VALUES records. They allow the web server

     

       425
       425
       -
           to discover application capabilities.

     

       426
       426
       -
           

     

       427
       427
       -
           The initial set provides information to help the server perform application

     

       428
       428
       -
           and connection management. *)

     

       429
       429
       -
       

     

       430
       430
       -
       (** Variable name "FCGI_MAX_CONNS". The maximum number

     

       431
       431
       -
           of concurrent transport connections this application

     

       432
       432
       -
           will accept, e.g. "1" or "10". *)

     

       433
       433
       -
       val fcgi_max_conns : string

     

       434
       434
       -
       

     

       435
       435
       -
       (** Variable name "FCGI_MAX_REQS". The maximum number

     

       436
       436
       -
           of concurrent requests this application will accept,

     

       437
       437
       -
           e.g. "1" or "50". *)

     

       438
       438
       -
       val fcgi_max_reqs : string

     

       439
       439
       -
       

     

       440
       440
       -
       (** Variable name "FCGI_MPXS_CONNS". "0" if this

     

       441
       441
       -
           application does not multiplex connections (i.e.

     

       442
       442
       -
           handle concurrent requests over each connection),

     

       443
       443
       -
           "1" otherwise. *)

     

       444
       444
       -
       val fcgi_mpxs_conns : string

-612

spec/OCAML.md

···

       1
       1
       -
       # OCaml FastCGI Specification

     

       2
       2
       -
       

     

       3
       3
       -
       This document specifies an OCaml interface for the FastCGI protocol using the Eio effects-based IO library. The design follows Eio conventions for structured concurrency, capability-based security, and resource management.

     

       4
       4
       -
       

     

       5
       5
       -
       ## Table of Contents

     

       6
       6
       -
       

     

       7
       7
       -
       1. [Overview](#overview)

     

       8
       8
       -
       2. [Core Types](#core-types)

     

       9
       9
       -
       3. [Protocol Constants](#protocol-constants)

     

       10
       10
       -
       4. [Record Types](#record-types)

     

       11
       11
       -
       5. [Request/Response Model](#requestresponse-model)

     

       12
       12
       -
       6. [Application Interface](#application-interface)

     

       13
       13
       -
       7. [Connection Management](#connection-management)

     

       14
       14
       -
       8. [Role Implementations](#role-implementations)

     

       15
       15
       -
       9. [Error Handling](#error-handling)

     

       16
       16
       -
       10. [Resource Management](#resource-management)

     

       17
       17
       -
       11. [Examples](#examples)

     

       18
       18
       -
       

     

       19
       19
       -
       ## Overview

     

       20
       20
       -
       

     

       21
       21
       -
       The OCaml FastCGI implementation provides a high-level, type-safe interface for building FastCGI applications that can handle multiple concurrent requests efficiently. It leverages OCaml 5's effects system through Eio for structured concurrency and resource safety.

     

       22
       22
       -
       

     

       23
       23
       -
       ### Key Design Principles

     

       24
       24
       -
       

     

       25
       25
       -
       - **Capability-based**: All external resources (network, filesystem) are explicitly passed as capabilities

     

       26
       26
       -
       - **Structured concurrency**: Use Eio switches for automatic resource cleanup

     

       27
       27
       -
       - **Type safety**: Leverage OCaml's type system to prevent protocol errors

     

       28
       28
       -
       - **Performance**: Support connection multiplexing and keep-alive for efficiency

     

       29
       29
       -
       - **Extensibility**: Support all three FastCGI roles with room for future extensions

     

       30
       30
       -
       

     

       31
       31
       -
       ## Core Types

     

       32
       32
       -
       

     

       33
       33
       -
       ```ocaml

     

       34
       34
       -
       (** FastCGI protocol version *)

     

       35
       35
       -
       type version = int

     

       36
       36
       -
       

     

       37
       37
       -
       (** FastCGI record types *)

     

       38
       38
       -
       type record_type = 

     

       39
       39
       -
         | Begin_request

     

       40
       40
       -
         | Abort_request  

     

       41
       41
       -
         | End_request

     

       42
       42
       -
         | Params

     

       43
       43
       -
         | Stdin

     

       44
       44
       -
         | Stdout

     

       45
       45
       -
         | Stderr

     

       46
       46
       -
         | Data

     

       47
       47
       -
         | Get_values

     

       48
       48
       -
         | Get_values_result

     

       49
       49
       -
         | Unknown_type

     

       50
       50
       -
       

     

       51
       51
       -
       (** FastCGI roles *)

     

       52
       52
       -
       type role =

     

       53
       53
       -
         | Responder    (** Handle HTTP requests and generate responses *)

     

       54
       54
       -
         | Authorizer   (** Perform authorization decisions *)

     

       55
       55
       -
         | Filter       (** Process data streams with filtering *)

     

       56
       56
       -
       

     

       57
       57
       -
       (** Request ID for multiplexing *)

     

       58
       58
       -
       type request_id = int

     

       59
       59
       -
       

     

       60
       60
       -
       (** Application status code *)

     

       61
       61
       -
       type app_status = int

     

       62
       62
       -
       

     

       63
       63
       -
       (** Protocol status codes *)

     

       64
       64
       -
       type protocol_status =

     

       65
       65
       -
         | Request_complete      (** Normal completion *)

     

       66
       66
       -
         | Cant_mpx_conn        (** Cannot multiplex connection *)

     

       67
       67
       -
         | Overloaded           (** Application overloaded *)

     

       68
       68
       -
         | Unknown_role         (** Unknown role requested *)

     

       69
       69
       -
       

     

       70
       70
       -
       (** Connection flags *)

     

       71
       71
       -
       type connection_flags = {

     

       72
       72
       -
         keep_conn : bool;  (** Keep connection open after request *)

     

       73
       73
       -
       }

     

       74
       74
       -
       ```

     

       75
       75
       -
       

     

       76
       76
       -
       ## Protocol Constants

     

       77
       77
       -
       

     

       78
       78
       -
       ```ocaml

     

       79
       79
       -
       module Constants = struct

     

       80
       80
       -
         (** Protocol version *)

     

       81
       81
       -
         let version_1 = 1

     

       82
       82
       -
         

     

       83
       83
       -
         (** Standard file descriptor for FastCGI listening socket *)

     

       84
       84
       -
         let listensock_fileno = 0

     

       85
       85
       -
         

     

       86
       86
       -
         (** Record type constants *)

     

       87
       87
       -
         let fcgi_begin_request = 1

     

       88
       88
       -
         let fcgi_abort_request = 2

     

       89
       89
       -
         let fcgi_end_request = 3

     

       90
       90
       -
         let fcgi_params = 4

     

       91
       91
       -
         let fcgi_stdin = 5

     

       92
       92
       -
         let fcgi_stdout = 6

     

       93
       93
       -
         let fcgi_stderr = 7

     

       94
       94
       -
         let fcgi_data = 8

     

       95
       95
       -
         let fcgi_get_values = 9

     

       96
       96
       -
         let fcgi_get_values_result = 10

     

       97
       97
       -
         let fcgi_unknown_type = 11

     

       98
       98
       -
         

     

       99
       99
       -
         (** Role constants *)

     

       100
       100
       -
         let fcgi_responder = 1

     

       101
       101
       -
         let fcgi_authorizer = 2

     

       102
       102
       -
         let fcgi_filter = 3

     

       103
       103
       -
         

     

       104
       104
       -
         (** Flag constants *)

     

       105
       105
       -
         let fcgi_keep_conn = 1

     

       106
       106
       -
         

     

       107
       107
       -
         (** Maximum sizes *)

     

       108
       108
       -
         let max_content_length = 65535

     

       109
       109
       -
         let max_padding_length = 255

     

       110
       110
       -
         let header_length = 8

     

       111
       111
       -
         

     

       112
       112
       -
         (** Management record variables *)

     

       113
       113
       -
         let fcgi_max_conns = "FCGI_MAX_CONNS"

     

       114
       114
       -
         let fcgi_max_reqs = "FCGI_MAX_REQS" 

     

       115
       115
       -
         let fcgi_mpxs_conns = "FCGI_MPXS_CONNS"

     

       116
       116
       -
       end

     

       117
       117
       -
       ```

     

       118
       118
       -
       

     

       119
       119
       -
       ## Record Types

     

       120
       120
       -
       

     

       121
       121
       -
       ```ocaml

     

       122
       122
       -
       (** FastCGI record header *)

     

       123
       123
       -
       type record_header = {

     

       124
       124
       -
         version : int;

     

       125
       125
       -
         record_type : record_type;

     

       126
       126
       -
         request_id : request_id;

     

       127
       127
       -
         content_length : int;

     

       128
       128
       -
         padding_length : int;

     

       129
       129
       -
       }

     

       130
       130
       -
       

     

       131
       131
       -
       (** Begin request record body *)

     

       132
       132
       -
       type begin_request_body = {

     

       133
       133
       -
         role : role;

     

       134
       134
       -
         flags : connection_flags;

     

       135
       135
       -
       }

     

       136
       136
       -
       

     

       137
       137
       -
       (** End request record body *)

     

       138
       138
       -
       type end_request_body = {

     

       139
       139
       -
         app_status : app_status;

     

       140
       140
       -
         protocol_status : protocol_status;

     

       141
       141
       -
       }

     

       142
       142
       -
       

     

       143
       143
       -
       (** Complete FastCGI record *)

     

       144
       144
       -
       type record = {

     

       145
       145
       -
         header : record_header;

     

       146
       146
       -
         content : bytes;

     

       147
       147
       -
         padding : bytes option;

     

       148
       148
       -
       }

     

       149
       149
       -
       

     

       150
       150
       -
       (** Name-value pair for parameters *)

     

       151
       151
       -
       type name_value_pair = {

     

       152
       152
       -
         name : string;

     

       153
       153
       -
         value : string;

     

       154
       154
       -
       }

     

       155
       155
       -
       ```

     

       156
       156
       -
       

     

       157
       157
       -
       ## Request/Response Model

     

       158
       158
       -
       

     

       159
       159
       -
       ```ocaml

     

       160
       160
       -
       (** Request context containing all information for a FastCGI request *)

     

       161
       161
       -
       type 'a request = {

     

       162
       162
       -
         request_id : request_id;

     

       163
       163
       -
         role : role;

     

       164
       164
       -
         flags : connection_flags;

     

       165
       165
       -
         params : (string * string) list;

     

       166
       166
       -
         stdin : 'a Eio.Flow.source;

     

       167
       167
       -
         data : 'a Eio.Flow.source option;  (** Only for Filter role *)

     

       168
       168
       -
       }

     

       169
       169
       -
       

     

       170
       170
       -
       (** Response builder for constructing FastCGI responses *)

     

       171
       171
       -
       type 'a response = {

     

       172
       172
       -
         stdout : 'a Eio.Flow.sink;

     

       173
       173
       -
         stderr : 'a Eio.Flow.sink;

     

       174
       174
       -
       }

     

       175
       175
       -
       

     

       176
       176
       -
       (** Complete response with status *)

     

       177
       177
       -
       type response_result = {

     

       178
       178
       -
         app_status : app_status;

     

       179
       179
       -
         protocol_status : protocol_status;

     

       180
       180
       -
       }

     

       181
       181
       -
       ```

     

       182
       182
       -
       

     

       183
       183
       -
       ## Application Interface

     

       184
       184
       -
       

     

       185
       185
       -
       ```ocaml

     

       186
       186
       -
       (** Application handler signature *)

     

       187
       187
       -
       module Handler = struct

     

       188
       188
       -
         (** Responder handler: process HTTP request and generate response *)

     

       189
       189
       -
         type 'a responder = 'a request -> 'a response -> response_result

     

       190
       190
       -
         

     

       191
       191
       -
         (** Authorizer handler: make authorization decision *)

     

       192
       192
       -
         type 'a authorizer = 'a request -> 'a response -> response_result

     

       193
       193
       -
         

     

       194
       194
       -
         (** Filter handler: process data stream with filtering *)

     

       195
       195
       -
         type 'a filter = 'a request -> 'a response -> response_result

     

       196
       196
       -
         

     

       197
       197
       -
         (** Generic handler that can handle any role *)

     

       198
       198
       -
         type 'a handler = 

     

       199
       199
       -
           | Responder of 'a responder

     

       200
       200
       -
           | Authorizer of 'a authorizer  

     

       201
       201
       -
           | Filter of 'a filter

     

       202
       202
       -
       end

     

       203
       203
       -
       

     

       204
       204
       -
       (** Application configuration *)

     

       205
       205
       -
       type 'a app_config = {

     

       206
       206
       -
         max_connections : int;        (** Maximum concurrent connections *)

     

       207
       207
       -
         max_requests : int;          (** Maximum concurrent requests *)

     

       208
       208
       -
         multiplex_connections : bool; (** Support connection multiplexing *)

     

       209
       209
       -
         handler : 'a Handler.handler; (** Application request handler *)

     

       210
       210
       -
       }

     

       211
       211
       -
       ```

     

       212
       212
       -
       

     

       213
       213
       -
       ## Connection Management

     

       214
       214
       -
       

     

       215
       215
       -
       ```ocaml

     

       216
       216
       -
       (** Connection manager for handling FastCGI protocol *)

     

       217
       217
       -
       module Connection = struct

     

       218
       218
       -
         (** Opaque connection type *)

     

       219
       219
       -
         type 'a t

     

       220
       220
       -
         

     

       221
       221
       -
         (** Create a connection from a network flow *)

     

       222
       222
       -
         val create : sw:Eio.Switch.t -> 'a Eio.Flow.two_way -> 'a t

     

       223
       223
       -
         

     

       224
       224
       -
         (** Accept and process a single request on the connection *)

     

       225
       225
       -
         val process_request : 'a t -> 'a Handler.handler -> response_result Eio.Promise.t

     

       226
       226
       -
         

     

       227
       227
       -
         (** Get connection statistics *)

     

       228
       228
       -
         val stats : 'a t -> {

     

       229
       229
       -
           active_requests : int;

     

       230
       230
       -
           total_requests : int;

     

       231
       231
       -
           bytes_sent : int;

     

       232
       232
       -
           bytes_received : int;

     

       233
       233
       -
         }

     

       234
       234
       -
         

     

       235
       235
       -
         (** Close the connection gracefully *)

     

       236
       236
       -
         val close : 'a t -> unit

     

       237
       237
       -
       end

     

       238
       238
       -
       

     

       239
       239
       -
       (** FastCGI server for accepting and managing connections *)

     

       240
       240
       -
       module Server = struct

     

       241
       241
       -
         (** Server configuration *)

     

       242
       242
       -
         type 'a config = {

     

       243
       243
       -
           app : 'a app_config;

     

       244
       244
       -
           listen_address : [

     

       245
       245
       -
             | `Unix of string           (** Unix domain socket path *)  

     

       246
       246
       -
             | `Tcp of Eio.Net.Ipaddr.t * int  (** TCP address and port *)

     

       247
       247
       -
           ];

     

       248
       248
       -
           backlog : int;               (** Listen backlog size *)

     

       249
       249
       -
           max_connections : int;       (** Maximum concurrent connections *)

     

       250
       250
       -
         }

     

       251
       251
       -
         

     

       252
       252
       -
         (** Run a FastCGI server *)

     

       253
       253
       -
         val run : 

     

       254
       254
       -
           sw:Eio.Switch.t ->

     

       255
       255
       -
           net:'a Eio.Net.t ->

     

       256
       256
       -
           'a config ->

     

       257
       257
       -
           unit

     

       258
       258
       -
         

     

       259
       259
       -
         (** Run server with default configuration *)

     

       260
       260
       -
         val run_default :

     

       261
       261
       -
           sw:Eio.Switch.t ->

     

       262
       262
       -
           net:'a Eio.Net.t ->

     

       263
       263
       -
           handler:'a Handler.handler ->

     

       264
       264
       -
           listen_address:[`Unix of string | `Tcp of Eio.Net.Ipaddr.t * int] ->

     

       265
       265
       -
           unit

     

       266
       266
       -
       end

     

       267
       267
       -
       ```

     

       268
       268
       -
       

     

       269
       269
       -
       ## Role Implementations

     

       270
       270
       -
       

     

       271
       271
       -
       ### Responder

     

       272
       272
       -
       

     

       273
       273
       -
       ```ocaml

     

       274
       274
       -
       (** Responder role implementation *)

     

       275
       275
       -
       module Responder = struct

     

       276
       276
       -
         (** CGI-style environment variables *)

     

       277
       277
       -
         type cgi_env = (string * string) list

     

       278
       278
       -
         

     

       279
       279
       -
         (** HTTP request information *)

     

       280
       280
       -
         type http_request = {

     

       281
       281
       -
           method_ : string;              (** HTTP method (GET, POST, etc.) *)

     

       282
       282
       -
           uri : string;                 (** Request URI *)

     

       283
       283
       -
           query_string : string;        (** Query string parameters *)

     

       284
       284
       -
           content_type : string option; (** Content-Type header *)

     

       285
       285
       -
           content_length : int option;  (** Content-Length header *)

     

       286
       286
       -
           headers : (string * string) list; (** Additional HTTP headers *)

     

       287
       287
       -
           body : 'a Eio.Flow.source;   (** Request body stream *)

     

       288
       288
       -
         }

     

       289
       289
       -
         

     

       290
       290
       -
         (** HTTP response builder *)

     

       291
       291
       -
         type 'a http_response = {

     

       292
       292
       -
           write_status : int -> unit;                    (** Set HTTP status code *)

     

       293
       293
       -
           write_header : string -> string -> unit;      (** Add response header *)

     

       294
       294
       -
           write_body : string -> unit;                  (** Write response body *)

     

       295
       295
       -
           write_body_chunk : bytes -> unit;             (** Write body chunk *) 

     

       296
       296
       -
           finish : unit -> unit;                        (** Complete response *)

     

       297
       297
       -
         }

     

       298
       298
       -
         

     

       299
       299
       -
         (** Convert FastCGI request to HTTP request *)

     

       300
       300
       -
         val request_of_fastcgi : 'a request -> http_request

     

       301
       301
       -
         

     

       302
       302
       -
         (** Create HTTP response writer from FastCGI response *)

     

       303
       303
       -
         val response_of_fastcgi : 'a response -> 'a http_response

     

       304
       304
       -
         

     

       305
       305
       -
         (** Convenience handler wrapper for HTTP-style handlers *)

     

       306
       306
       -
         val http_handler : 

     

       307
       307
       -
           (http_request -> 'a http_response -> unit) -> 

     

       308
       308
       -
           'a Handler.responder

     

       309
       309
       -
       end

     

       310
       310
       -
       ```

     

       311
       311
       -
       

     

       312
       312
       -
       ### Authorizer

     

       313
       313
       -
       

     

       314
       314
       -
       ```ocaml

     

       315
       315
       -
       (** Authorizer role implementation *)

     

       316
       316
       -
       module Authorizer = struct

     

       317
       317
       -
         (** Authorization result *)

     

       318
       318
       -
         type auth_result = 

     

       319
       319
       -
           | Authorized of (string * string) list  (** Authorized with variable bindings *)

     

       320
       320
       -
           | Unauthorized of {                     (** Unauthorized with error response *)

     

       321
       321
       -
               status : int;

     

       322
       322
       -
               headers : (string * string) list;

     

       323
       323
       -
               body : string;

     

       324
       324
       -
             }

     

       325
       325
       -
         

     

       326
       326
       -
         (** Authorization request information *)

     

       327
       327
       -
         type auth_request = {

     

       328
       328
       -
           method_ : string;

     

       329
       329
       -
           uri : string;

     

       330
       330
       -
           remote_addr : string option;

     

       331
       331
       -
           remote_user : string option;

     

       332
       332
       -
           auth_type : string option;

     

       333
       333
       -
           headers : (string * string) list;

     

       334
       334
       -
         }

     

       335
       335
       -
         

     

       336
       336
       -
         (** Convert FastCGI request to authorization request *)

     

       337
       337
       -
         val request_of_fastcgi : 'a request -> auth_request

     

       338
       338
       -
         

     

       339
       339
       -
         (** Convert authorization result to FastCGI response *)

     

       340
       340
       -
         val response_of_result : auth_result -> 'a response -> response_result

     

       341
       341
       -
         

     

       342
       342
       -
         (** Convenience handler wrapper for authorization handlers *)

     

       343
       343
       -
         val auth_handler :

     

       344
       344
       -
           (auth_request -> auth_result) ->

     

       345
       345
       -
           'a Handler.authorizer

     

       346
       346
       -
       end

     

       347
       347
       -
       ```

     

       348
       348
       -
       

     

       349
       349
       -
       ### Filter

     

       350
       350
       -
       

     

       351
       351
       -
       ```ocaml

     

       352
       352
       -
       (** Filter role implementation *)

     

       353
       353
       -
       module Filter = struct

     

       354
       354
       -
         (** Filter request with data stream *)

     

       355
       355
       -
         type 'a filter_request = {

     

       356
       356
       -
           request : 'a request;              (** Base FastCGI request *)

     

       357
       357
       -
           data_stream : 'a Eio.Flow.source; (** File data to filter *)

     

       358
       358
       -
           data_last_modified : float option; (** File modification time *)

     

       359
       359
       -
           data_length : int option;          (** Expected data length *)

     

       360
       360
       -
         }

     

       361
       361
       -
         

     

       362
       362
       -
         (** Convert FastCGI request to filter request *)

     

       363
       363
       -
         val request_of_fastcgi : 'a request -> 'a filter_request

     

       364
       364
       -
         

     

       365
       365
       -
         (** Convenience handler wrapper for filter handlers *)

     

       366
       366
       -
         val filter_handler :

     

       367
       367
       -
           ('a filter_request -> 'a response -> unit) ->

     

       368
       368
       -
           'a Handler.filter

     

       369
       369
       -
       end

     

       370
       370
       -
       ```

     

       371
       371
       -
       

     

       372
       372
       -
       ## Error Handling

     

       373
       373
       -
       

     

       374
       374
       -
       ```ocaml

     

       375
       375
       -
       (** FastCGI specific errors *)

     

       376
       376
       -
       module Error = struct

     

       377
       377
       -
         type t = 

     

       378
       378
       -
           | Protocol_error of string         (** Protocol violation *)

     

       379
       379
       -
           | Invalid_record of string         (** Malformed record *)

     

       380
       380
       -
           | Unsupported_version of int       (** Unsupported protocol version *)

     

       381
       381
       -
           | Unknown_record_type of int       (** Unknown record type *)

     

       382
       382
       -
           | Request_id_conflict of request_id (** Duplicate request ID *)

     

       383
       383
       -
           | Connection_closed                (** Connection unexpectedly closed *)

     

       384
       384
       -
           | Application_error of string      (** Application-specific error *)

     

       385
       385
       -
         

     

       386
       386
       -
         exception Fastcgi_error of t

     

       387
       387
       -
         

     

       388
       388
       -
         (** Convert error to string description *)

     

       389
       389
       -
         val to_string : t -> string

     

       390
       390
       -
         

     

       391
       391
       -
         (** Raise a FastCGI error *)

     

       392
       392
       -
         val raise : t -> 'a

     

       393
       393
       -
       end

     

       394
       394
       -
       ```

     

       395
       395
       -
       

     

       396
       396
       -
       ## Resource Management

     

       397
       397
       -
       

     

       398
       398
       -
       ```ocaml

     

       399
       399
       -
       (** Resource management utilities *)

     

       400
       400
       -
       module Resource = struct

     

       401
       401
       -
         (** Request context with automatic cleanup *)

     

       402
       402
       -
         type 'a request_context = {

     

       403
       403
       -
           request : 'a request;

     

       404
       404
       -
           response : 'a response; 

     

       405
       405
       -
           switch : Eio.Switch.t;  (** Switch for request-scoped resources *)

     

       406
       406
       -
         }

     

       407
       407
       -
         

     

       408
       408
       -
         (** Create a request context with automatic resource management *)

     

       409
       409
       -
         val with_request_context : 

     

       410
       410
       -
           sw:Eio.Switch.t ->

     

       411
       411
       -
           'a request ->

     

       412
       412
       -
           ('a request_context -> 'b) ->

     

       413
       413
       -
           'b

     

       414
       414
       -
         

     

       415
       415
       -
         (** Buffer management for efficient I/O *)

     

       416
       416
       -
         module Buffer = struct

     

       417
       417
       -
           type t

     

       418
       418
       -
           

     

       419
       419
       -
           val create : size:int -> t

     

       420
       420
       -
           val read_into : t -> 'a Eio.Flow.source -> int

     

       421
       421
       -
           val write_from : t -> 'a Eio.Flow.sink -> int -> unit

     

       422
       422
       -
           val clear : t -> unit

     

       423
       423
       -
         end

     

       424
       424
       -
       end

     

       425
       425
       -
       ```

     

       426
       426
       -
       

     

       427
       427
       -
       ## Examples

     

       428
       428
       -
       

     

       429
       429
       -
       ### Basic Responder Application

     

       430
       430
       -
       

     

       431
       431
       -
       ```ocaml

     

       432
       432
       -
       open Eio.Std

     

       433
       433
       -
       

     

       434
       434
       -
       let hello_handler request response =

     

       435
       435
       -
         let http_req = Responder.request_of_fastcgi request in

     

       436
       436
       -
         let http_resp = Responder.response_of_fastcgi response in

     

       437
       437
       -
         

     

       438
       438
       -
         http_resp.write_status 200;

     

       439
       439
       -
         http_resp.write_header "Content-Type" "text/html";

     

       440
       440
       -
         http_resp.write_body "<h1>Hello, FastCGI!</h1>";

     

       441
       441
       -
         http_resp.finish ();

     

       442
       442
       -
         

     

       443
       443
       -
         { app_status = 0; protocol_status = Request_complete }

     

       444
       444
       -
       

     

       445
       445
       -
       let run_server env =

     

       446
       446
       -
         let net = Eio.Stdenv.net env in

     

       447
       447
       -
         let config = {

     

       448
       448
       -
           app = {

     

       449
       449
       -
             max_connections = 10;

     

       450
       450
       -
             max_requests = 50; 

     

       451
       451
       -
             multiplex_connections = true;

     

       452
       452
       -
             handler = Handler.Responder hello_handler;

     

       453
       453
       -
           };

     

       454
       454
       -
           listen_address = `Tcp (Eio.Net.Ipaddr.V4.loopback, 9000);

     

       455
       455
       -
           backlog = 5;

     

       456
       456
       -
           max_connections = 10;

     

       457
       457
       -
         } in

     

       458
       458
       -
         

     

       459
       459
       -
         Switch.run @@ fun sw ->

     

       460
       460
       -
         Server.run ~sw ~net config

     

       461
       461
       -
       

     

       462
       462
       -
       let () = Eio_main.run run_server

     

       463
       463
       -
       ```

     

       464
       464
       -
       

     

       465
       465
       -
       ### File-serving Responder

     

       466
       466
       -
       

     

       467
       467
       -
       ```ocaml

     

       468
       468
       -
       let file_server_handler ~cwd request response =

     

       469
       469
       -
         let http_req = Responder.request_of_fastcgi request in

     

       470
       470
       -
         let http_resp = Responder.response_of_fastcgi response in

     

       471
       471
       -
         

     

       472
       472
       -
         let path = Eio.Path.(cwd / String.drop_prefix http_req.uri 1) in

     

       473
       473
       -
         

     

       474
       474
       -
         match Eio.Path.load path with

     

       475
       475
       -
         | content ->

     

       476
       476
       -
             http_resp.write_status 200;

     

       477
       477
       -
             http_resp.write_header "Content-Type" "text/html";

     

       478
       478
       -
             http_resp.write_body content;

     

       479
       479
       -
             http_resp.finish ()

     

       480
       480
       -
         | exception (Eio.Io (Eio.Fs.E (Not_found _), _)) ->

     

       481
       481
       -
             http_resp.write_status 404;

     

       482
       482
       -
             http_resp.write_header "Content-Type" "text/plain";

     

       483
       483
       -
             http_resp.write_body "File not found";

     

       484
       484
       -
             http_resp.finish ()

     

       485
       485
       -
         | exception ex ->

     

       486
       486
       -
             http_resp.write_status 500;

     

       487
       487
       -
             http_resp.write_header "Content-Type" "text/plain"; 

     

       488
       488
       -
             http_resp.write_body ("Server error: " ^ Printexc.to_string ex);

     

       489
       489
       -
             http_resp.finish ();

     

       490
       490
       -
         

     

       491
       491
       -
         { app_status = 0; protocol_status = Request_complete }

     

       492
       492
       -
       

     

       493
       493
       -
       let run_file_server env =

     

       494
       494
       -
         let net = Eio.Stdenv.net env in

     

       495
       495
       -
         let cwd = Eio.Stdenv.cwd env in

     

       496
       496
       -
         let handler = file_server_handler ~cwd in

     

       497
       497
       -
         

     

       498
       498
       -
         Switch.run @@ fun sw ->

     

       499
       499
       -
         Server.run_default ~sw ~net ~handler:(Handler.Responder handler) 

     

       500
       500
       -
           ~listen_address:(`Tcp (Eio.Net.Ipaddr.V4.loopback, 9000))

     

       501
       501
       -
       ```

     

       502
       502
       -
       

     

       503
       503
       -
       ### Authorization Application

     

       504
       504
       -
       

     

       505
       505
       -
       ```ocaml

     

       506
       506
       -
       let auth_handler auth_req =

     

       507
       507
       -
         match auth_req.remote_user with

     

       508
       508
       -
         | Some user when String.starts_with user "admin_" ->

     

       509
       509
       -
             Authorizer.Authorized [("AUTH_USER", user); ("AUTH_LEVEL", "admin")]

     

       510
       510
       -
         | Some user ->

     

       511
       511
       -
             Authorizer.Authorized [("AUTH_USER", user); ("AUTH_LEVEL", "user")]

     

       512
       512
       -
         | None ->

     

       513
       513
       -
             Authorizer.Unauthorized {

     

       514
       514
       -
               status = 401;

     

       515
       515
       -
               headers = [("WWW-Authenticate", "Basic realm=\"FastCGI\"")];

     

       516
       516
       -
               body = "Authentication required";

     

       517
       517
       -
             }

     

       518
       518
       -
       

     

       519
       519
       -
       let run_auth_server env =

     

       520
       520
       -
         let net = Eio.Stdenv.net env in

     

       521
       521
       -
         let handler = Authorizer.auth_handler auth_handler in

     

       522
       522
       -
         

     

       523
       523
       -
         Switch.run @@ fun sw ->

     

       524
       524
       -
         Server.run_default ~sw ~net ~handler:(Handler.Authorizer handler)

     

       525
       525
       -
           ~listen_address:(`Unix "/tmp/auth.sock")

     

       526
       526
       -
       ```

     

       527
       527
       -
       

     

       528
       528
       -
       ### Filter Application

     

       529
       529
       -
       

     

       530
       530
       -
       ```ocaml

     

       531
       531
       -
       let markdown_filter filter_req response =

     

       532
       532
       -
         let data = Eio.Flow.read_all filter_req.data_stream in

     

       533
       533
       -
         let html = Markdown.to_html data in (* Assuming markdown library *)

     

       534
       534
       -
         

     

       535
       535
       -
         Eio.Flow.copy_string "Content-Type: text/html\r\n\r\n" response.stdout;

     

       536
       536
       -
         Eio.Flow.copy_string html response.stdout;

     

       537
       537
       -
         

     

       538
       538
       -
         { app_status = 0; protocol_status = Request_complete }

     

       539
       539
       -
       

     

       540
       540
       -
       let run_filter_server env =

     

       541
       541
       -
         let net = Eio.Stdenv.net env in

     

       542
       542
       -
         let handler = Filter.filter_handler markdown_filter in

     

       543
       543
       -
         

     

       544
       544
       -
         Switch.run @@ fun sw ->

     

       545
       545
       -
         Server.run_default ~sw ~net ~handler:(Handler.Filter handler)

     

       546
       546
       -
           ~listen_address:(`Tcp (Eio.Net.Ipaddr.V4.loopback, 9001))

     

       547
       547
       -
       ```

     

       548
       548
       -
       

     

       549
       549
       -
       ### Connection Management Example

     

       550
       550
       -
       

     

       551
       551
       -
       ```ocaml

     

       552
       552
       -
       let custom_connection_handler env =

     

       553
       553
       -
         let net = Eio.Stdenv.net env in

     

       554
       554
       -
         

     

       555
       555
       -
         Switch.run @@ fun sw ->

     

       556
       556
       -
         let server_socket = Eio.Net.listen net ~sw ~reuse_addr:true ~backlog:5

     

       557
       557
       -
           (`Tcp (Eio.Net.Ipaddr.V4.loopback, 9000)) in

     

       558
       558
       -
         

     

       559
       559
       -
         let handler = Handler.Responder hello_handler in

     

       560
       560
       -
         

     

       561
       561
       -
         Eio.Net.run_server server_socket (fun flow _addr ->

     

       562
       562
       -
           Switch.run @@ fun conn_sw ->

     

       563
       563
       -
           let conn = Connection.create ~sw:conn_sw flow in

     

       564
       564
       -
           

     

       565
       565
       -
           let rec process_loop () =

     

       566
       566
       -
             match Connection.process_request conn handler with

     

       567
       567
       -
             | response -> process_loop ()

     

       568
       568
       -
             | exception End_of_file -> ()

     

       569
       569
       -
             | exception ex -> 

     

       570
       570
       -
                 Eio.traceln "Connection error: %s" (Printexc.to_string ex)

     

       571
       571
       -
           in

     

       572
       572
       -
           process_loop ()

     

       573
       573
       -
         )

     

       574
       574
       -
       ```

     

       575
       575
       -
       

     

       576
       576
       -
       ## Implementation Notes

     

       577
       577
       -
       

     

       578
       578
       -
       ### Wire Protocol Details

     

       579
       579
       -
       

     

       580
       580
       -
       The implementation must handle:

     

       581
       581
       -
       

     

       582
       582
       -
       1. **Binary record format**: 8-byte headers with version, type, request ID, content length, and padding

     

       583
       583
       -
       2. **Name-value pair encoding**: Variable-length encoding for parameter names and values  

     

       584
       584
       -
       3. **Stream management**: Proper handling of stdin, stdout, stderr, and data streams

     

       585
       585
       -
       4. **Connection multiplexing**: Support multiple concurrent requests over single connection

     

       586
       586
       -
       5. **Error propagation**: Convert protocol errors to appropriate OCaml exceptions

     

       587
       587
       -
       

     

       588
       588
       -
       ### Performance Considerations

     

       589
       589
       -
       

     

       590
       590
       -
       1. **Buffer management**: Reuse buffers to minimize allocations

     

       591
       591
       -
       2. **Streaming I/O**: Process requests in streaming fashion for large payloads

     

       592
       592
       -
       3. **Connection pooling**: Support keep-alive connections for efficiency

     

       593
       593
       -
       4. **Concurrent processing**: Use Eio fibers for handling multiple requests

     

       594
       594
       -
       

     

       595
       595
       -
       ### Security Considerations

     

       596
       596
       -
       

     

       597
       597
       -
       1. **Input validation**: Validate all protocol fields and reject malformed records

     

       598
       598
       -
       2. **Resource limits**: Enforce limits on request size, connection count, etc.

     

       599
       599
       -
       3. **Capability restriction**: Use Eio's capability system to limit access

     

       600
       600
       -
       4. **Error information**: Avoid leaking sensitive information in error messages

     

       601
       601
       -
       

     

       602
       602
       -
       ### Testing Strategy

     

       603
       603
       -
       

     

       604
       604
       -
       The implementation should include:

     

       605
       605
       -
       

     

       606
       606
       -
       1. **Protocol conformance tests**: Verify correct implementation of FastCGI protocol

     

       607
       607
       -
       2. **Interoperability tests**: Test with real web servers (nginx, Apache)

     

       608
       608
       -
       3. **Performance tests**: Measure throughput and latency under load

     

       609
       609
       -
       4. **Error handling tests**: Verify graceful handling of error conditions

     

       610
       610
       -
       5. **Mock testing**: Use Eio_mock for deterministic unit tests

     

       611
       611
       -
       

     

       612
       612
       -
       This specification provides a comprehensive foundation for implementing a robust, efficient, and type-safe FastCGI library for OCaml using the Eio effects system.