(** HTTP response handling

    This module represents HTTP responses and provides functions to access
    status codes, headers, and response bodies. Responses support streaming
    to efficiently handle large payloads.

    {2 Examples}

    {[
      (* Check response status *)
      if Response.ok response then
        Printf.printf "Success!\n"
      else
        Printf.printf "Error: %d\n" (Response.status_code response);

      (* Access headers *)
      match Response.content_type response with
      | Some mime -> Printf.printf "Type: %s\n" (Mime.to_string mime)
      | None -> ()

      (* Stream response body *)
      let body = Response.body response in
      Eio.Flow.copy body (Eio.Flow.buffer_sink buffer)

      (* Response automatically closes when the switch is released *)
    ]}

    {b Note}: Responses are automatically closed when the switch they were
    created with is released. Manual cleanup is not necessary.
*)

open Eio

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

type t
(** Abstract response type representing an HTTP response. *)

val make : sw:Eio.Switch.t -> status:int -> headers:Headers.t ->
  body:Eio.Flow.source_ty Eio.Resource.t -> url:string -> elapsed:float -> t
(** [make ~sw ~status ~headers ~body ~url ~elapsed] creates a response.
    Internal function primarily used for caching. *)

(** {1 Status Information} *)

val status : t -> Status.t
(** [status response] returns the HTTP status as a {!Status.t} value. *)

val status_code : t -> int
(** [status_code response] returns the HTTP status code as an integer (e.g., 200, 404). *)

val ok : t -> bool
(** [ok response] returns [true] if the status code is in the 2xx success range.
    This is an alias for {!Status.is_success}. *)

(** {1 Header Access} *)

val headers : t -> Headers.t
(** [headers response] returns all response headers. *)

val header : string -> t -> string option
(** [header name response] returns the value of a specific header, or [None] if not present.
    Header names are case-insensitive. *)

val content_type : t -> Mime.t option
(** [content_type response] returns the parsed Content-Type header as a MIME type,
    or [None] if the header is not present or cannot be parsed. *)

val content_length : t -> int64 option
(** [content_length response] returns the Content-Length in bytes,
    or [None] if not specified or chunked encoding is used. *)

val location : t -> string option
(** [location response] returns the Location header value, typically used in redirects.
    Returns [None] if the header is not present. *)

(** {1 Response Metadata} *)

val url : t -> string
(** [url response] returns the final URL after following any redirects.
    This may differ from the originally requested URL. *)

val elapsed : t -> float
(** [elapsed response] returns the time taken for the request in seconds,
    including connection establishment, sending the request, and receiving headers. *)

(** {1 Response Body} *)

val body : t -> Flow.source_ty Resource.t
(** [body response] returns the response body as an Eio flow for streaming.
    This allows efficient processing of large responses without loading them
    entirely into memory.

    Example:
    {[
      let body = Response.body response in
      let buffer = Buffer.create 4096 in
      Eio.Flow.copy body (Eio.Flow.buffer_sink buffer);
      Buffer.contents buffer
    ]}
*)


(** {1 Pretty Printing} *)

val pp : Format.formatter -> t -> unit
(** Pretty print a response summary *)

val pp_detailed : Format.formatter -> t -> unit
(** Pretty print a response with full headers *)

(** {1 Private API} *)

(** Internal functions exposed for use by other modules in the library.
    These are not part of the public API and may change between versions. *)
module Private : sig
  val make :
    sw:Eio.Switch.t ->
    status:int ->
    headers:Headers.t ->
    body:Flow.source_ty Resource.t ->
    url:string ->
    elapsed:float ->
    t
  (** [make ~sw ~status ~headers ~body ~url ~elapsed] constructs a response.
      The response will be automatically closed when the switch is released.
      This function is used internally by the Client module. *)
end