(** HTTP headers management with case-insensitive keys

    This module provides an efficient implementation of HTTP headers with
    case-insensitive header names as per RFC 7230. Headers can have multiple
    values for the same key (e.g., multiple Set-Cookie headers).

    {2 Examples}

    {[
      let headers =
        Headers.empty
        |> Headers.content_type Mime.json
        |> Headers.bearer "token123"
        |> Headers.set "X-Custom" "value"
    ]}
*)

(** Log source for header operations *)
val src : Logs.Src.t

type t
(** Abstract header collection type. Headers are stored with case-insensitive
    keys and maintain insertion order. *)

(** {1 Creation and Conversion} *)

val empty : t
(** [empty] creates an empty header collection. *)

val of_list : (string * string) list -> t
(** [of_list pairs] creates headers from an association list.
    Later entries override earlier ones for the same key. *)

val to_list : t -> (string * string) list
(** [to_list headers] converts headers to an association list.
    The order of headers is preserved. *)

(** {1 Manipulation} *)

val add : string -> string -> t -> t
(** [add name value headers] adds a header value. Multiple values
    for the same header name are allowed (e.g., for Set-Cookie). *)

val set : string -> string -> t -> t
(** [set name value headers] sets a header value, replacing any
    existing values for that header name. *)

val get : string -> t -> string option
(** [get name headers] returns the first value for a header name,
    or [None] if the header doesn't exist. *)

val get_all : string -> t -> string list
(** [get_all name headers] returns all values for a header name.
    Returns an empty list if the header doesn't exist. *)

val remove : string -> t -> t
(** [remove name headers] removes all values for a header name. *)

val mem : string -> t -> bool
(** [mem name headers] checks if a header name exists. *)

val merge : t -> t -> t
(** [merge base override] merges two header collections.
    Headers from [override] replace those in [base]. *)

(** {1 Common Header Builders}

    Convenience functions for setting common HTTP headers.
*)

val content_type : Mime.t -> t -> t
(** [content_type mime headers] sets the Content-Type header. *)

val content_length : int64 -> t -> t
(** [content_length length headers] sets the Content-Length header. *)

val accept : Mime.t -> t -> t
(** [accept mime headers] sets the Accept header. *)

val authorization : string -> t -> t
(** [authorization value headers] sets the Authorization header with a raw value. *)

val bearer : string -> t -> t
(** [bearer token headers] sets the Authorization header with a Bearer token.
    Example: [bearer "abc123"] sets ["Authorization: Bearer abc123"] *)

val basic : username:string -> password:string -> t -> t
(** [basic ~username ~password headers] sets the Authorization header with
    HTTP Basic authentication (base64-encoded username:password). *)

val user_agent : string -> t -> t
(** [user_agent ua headers] sets the User-Agent header. *)

val host : string -> t -> t
(** [host hostname headers] sets the Host header. *)

val cookie : string -> string -> t -> t
(** [cookie name value headers] adds a cookie to the Cookie header.
    Multiple cookies can be added by calling this function multiple times. *)

val range : start:int64 -> ?end_:int64 -> unit -> t -> t
(** [range ~start ?end_ () headers] sets the Range header for partial content.
    Example: [range ~start:0L ~end_:999L ()] requests the first 1000 bytes. *)

(** {1 Aliases} *)

val get_multi : string -> t -> string list
(** [get_multi] is an alias for {!get_all}. *)

(** Pretty printer for headers *)
val pp : Format.formatter -> t -> unit

(** Brief pretty printer showing count only *)
val pp_brief : Format.formatter -> t -> unit