(** HTTP response writing utilities. *)

(** HTTP response status codes per
    {{:https://datatracker.ietf.org/doc/html/rfc7231#section-6}RFC 7231 Section 6}. *)
type status =
  (* 1xx Informational *)
  | Continue                (** 100 - for Expect: 100-continue *)
  | Switching_protocols     (** 101 - for Upgrade *)
  (* 2xx Success *)
  | Success                 (** 200 OK *)
  | Created                 (** 201 *)
  | Accepted                (** 202 *)
  | No_content              (** 204 *)
  | Partial_content         (** 206 - for Range requests *)
  (* 3xx Redirection *)
  | Moved_permanently       (** 301 *)
  | Found                   (** 302 *)
  | See_other               (** 303 *)
  | Not_modified            (** 304 *)
  | Temporary_redirect      (** 307 *)
  | Permanent_redirect      (** 308 *)
  (* 4xx Client Error *)
  | Bad_request             (** 400 *)
  | Unauthorized            (** 401 *)
  | Forbidden               (** 403 *)
  | Not_found               (** 404 *)
  | Method_not_allowed      (** 405 *)
  | Not_acceptable          (** 406 *)
  | Request_timeout         (** 408 *)
  | Conflict                (** 409 *)
  | Gone                    (** 410 *)
  | Length_required         (** 411 *)
  | Precondition_failed     (** 412 *)
  | Payload_too_large       (** 413 *)
  | Uri_too_long            (** 414 *)
  | Unsupported_media_type  (** 415 *)
  | Range_not_satisfiable   (** 416 *)
  | Expectation_failed      (** 417 *)
  | Unprocessable_entity    (** 422 *)
  | Upgrade_required        (** 426 *)
  | Precondition_required   (** 428 *)
  | Too_many_requests       (** 429 *)
  (* 5xx Server Error *)
  | Internal_server_error   (** 500 *)
  | Not_implemented         (** 501 *)
  | Bad_gateway             (** 502 *)
  | Service_unavailable     (** 503 *)
  | Gateway_timeout         (** 504 *)
  | Http_version_not_supported (** 505 *)

(** Get numeric status code. *)
val status_code : status -> int

(** Get reason phrase. *)
val status_reason : status -> string

(** Get "CODE Reason" string. *)
val status_to_string : status -> string

(** Pretty-print status. *)
val pp_status : Stdlib.Format.formatter -> status -> unit

(** {2 Response Writers} *)

(** Write "HTTP/1.x CODE Reason\r\n" at offset. Returns new offset. *)
val write_status_line : Base_bigstring.t -> off:int -> status -> Version.t -> int

(** Write "Name: Value\r\n" at offset using string name. Returns new offset. *)
val write_header : Base_bigstring.t -> off:int -> string -> string -> int

(** Write header with integer value using string name. Returns new offset. *)
val write_header_int : Base_bigstring.t -> off:int -> string -> int -> int

(** Write "Name: Value\r\n" using typed header name. Returns new offset. *)
val write_header_name : Base_bigstring.t -> off:int -> Header_name.t -> string -> int

(** Write header with integer value using typed header name. Returns new offset. *)
val write_header_name_int : Base_bigstring.t -> off:int -> Header_name.t -> int -> int

(** Write "\r\n". Returns new offset. *)
val write_crlf : Base_bigstring.t -> off:int -> int

(** Write "Content-Length: N\r\n". Returns new offset. *)
val write_content_length : Base_bigstring.t -> off:int -> int -> int

(** Write "Connection: keep-alive\r\n" or "Connection: close\r\n". *)
val write_connection : Base_bigstring.t -> off:int -> keep_alive:bool -> int

(** {2 Chunked Transfer Encoding} *)

(** Write "Transfer-Encoding: chunked\r\n". Returns new offset. *)
val write_transfer_encoding_chunked : Base_bigstring.t -> off:int -> int

(** Write chunk header "<hex-size>\r\n". Returns new offset. *)
val write_chunk_header : Base_bigstring.t -> off:int -> size:int -> int

(** Write chunk footer "\r\n" after chunk data. Returns new offset. *)
val write_chunk_footer : Base_bigstring.t -> off:int -> int

(** Write final chunk "0\r\n\r\n". Returns new offset. *)
val write_final_chunk : Base_bigstring.t -> off:int -> int