(** FastCGI request handling with functional state management and Eio flows.

    This module provides a functional approach to FastCGI request processing,
    using immutable data structures and higher-order functions. Input and output
    are handled through Eio flows for efficient streaming I/O. *)

(** {1 Request Roles} *)

(** FastCGI application roles defining request processing behavior *)
type role =
  | Responder   (** Standard CGI-like request/response processing *)
  | Authorizer  (** Authorization decision with optional variables *)
  | Filter      (** Content filtering with additional data stream *)

(** [pp_role ppf role] pretty-prints a FastCGI role *)
val pp_role : Format.formatter -> role -> unit

(** [role_of_begin_request record] extracts role from BEGIN_REQUEST record *)
val role_of_begin_request : Fastcgi_record.t -> (role, string) result

(** {1 Request Context} *)

(** Immutable request context containing all request data *)
type t = private {
  request_id : Fastcgi_record.request_id;  (** Request identifier *)
  role : role;                             (** Application role *)
  keep_conn : bool;                        (** Connection keep-alive flag *)
  params : Fastcgi_record.KV.t;            (** Environment parameters *)
  stdin_data : string;                     (** Complete STDIN content *)
  data_stream : string option;             (** DATA stream for Filter role *)
}

(** [pp ppf request] pretty-prints a request context *)
val pp : Format.formatter -> t -> unit

(** [create record] creates request context from BEGIN_REQUEST record *)
val create : Fastcgi_record.t -> (t, string) result

(** {1 Stream Processing} *)

(** [read_params buf_read] reads PARAMS stream from buf_read until empty record.
    Returns the accumulated parameters. *)
val read_params : Eio.Buf_read.t -> (Fastcgi_record.KV.t, string) result

(** [read_stdin buf_read] reads STDIN stream from buf_read until empty record.
    Returns the accumulated data. *)
val read_stdin : Eio.Buf_read.t -> (string, string) result

(** [read_data buf_read] reads DATA stream from buf_read until empty record.
    Returns the accumulated data for Filter role. *)
val read_data : Eio.Buf_read.t -> (string, string) result

(** [read_request buf_read] reads a complete FastCGI request from buf_read.
    Processes BEGIN_REQUEST, PARAMS, STDIN, and DATA records until complete.
    Returns the populated request context. *)
val read_request : Eio.Buf_read.t -> (t, string) result

(** {1 Response Generation} *)

(** Response status codes *)
type app_status = int
type protocol_status = 
  | Request_complete
  | Cant_mpx_conn  
  | Overloaded
  | Unknown_role

(** [pp_protocol_status ppf status] pretty-prints protocol status *)
val pp_protocol_status : Format.formatter -> protocol_status -> unit

(** [write_stdout_records buf_write request_id content] writes STDOUT stream records.
    Splits content into chunks and writes with terminator. *)
val write_stdout_records : Eio.Buf_write.t -> Fastcgi_record.request_id -> string -> unit

(** [write_stderr_records buf_write request_id content] writes STDERR stream records.
    Splits content into chunks and writes with terminator. *)
val write_stderr_records : Eio.Buf_write.t -> Fastcgi_record.request_id -> string -> unit

(** [write_end_request buf_write request_id app_status protocol_status] writes END_REQUEST record. *)
val write_end_request : Eio.Buf_write.t -> Fastcgi_record.request_id -> app_status -> protocol_status -> unit