(** One-shot HTTP client for stateless requests

    The One module provides a stateless HTTP client for single requests without
    session state like cookies, connection pooling, or persistent configuration.
    Each request opens a new connection that is closed after use.

    For stateful requests with automatic cookie handling, connection pooling,
    and persistent configuration, use the main {!Requests} module instead.

    {2 Examples}

    {[
      open Eio_main

      let () = run @@ fun env ->
      Switch.run @@ fun sw ->

      (* Simple GET request *)
      let response = One.get ~sw
        ~clock:env#clock ~net:env#net
        "https://example.com" in
      Printf.printf "Status: %d\n" (Response.status_code response);
      Response.close response;

      (* POST with JSON body *)
      let response = One.post ~sw
        ~clock:env#clock ~net:env#net
        ~body:(Body.json {|{"key": "value"}|})
        ~headers:(Headers.empty |> Headers.content_type Mime.json)
        "https://api.example.com/data" in
      Response.close response;

      (* Download file with streaming *)
      One.download ~sw
        ~clock:env#clock ~net:env#net
        "https://example.com/large-file.zip"
        ~sink:(Eio.Path.(fs / "download.zip" |> sink))
    ]}
*)

(** Log source for one-shot request operations *)
val src : Logs.Src.t

(** {1 HTTP Request Methods}

    All functions are stateless - they open a new TCP connection for each request
    and close it when the switch closes. No connection pooling or reuse. *)

val request :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?body:Body.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?follow_redirects:bool ->
  ?max_redirects:int ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  method_:Method.t ->
  string ->
  Response.t
(** [request ~sw ~clock ~net ?headers ?body ?auth ?timeout ?follow_redirects
    ?max_redirects ?verify_tls ?tls_config ~method_ url] makes a single HTTP
    request without connection pooling.

    Each call opens a new TCP connection (with TLS if https://), makes the
    request, and closes the connection when the switch closes.

    @param sw Switch for resource management (response/connection bound to this)
    @param clock Clock for timeouts
    @param net Network interface for TCP connections
    @param headers Request headers (default: empty)
    @param body Request body (default: none)
    @param auth Authentication to apply (default: none)
    @param timeout Request timeout (default: 30s connect, 60s read)
    @param follow_redirects Whether to follow HTTP redirects (default: true)
    @param max_redirects Maximum redirects to follow (default: 10)
    @param verify_tls Whether to verify TLS certificates (default: true)
    @param tls_config Custom TLS configuration (default: system CA certs)
    @param method_ HTTP method (GET, POST, etc.)
    @param url URL to request
*)

val get :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?follow_redirects:bool ->
  ?max_redirects:int ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  string ->
  Response.t
(** GET request. See {!request} for parameter details. *)

val post :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?body:Body.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  string ->
  Response.t
(** POST request. See {!request} for parameter details. *)

val put :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?body:Body.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  string ->
  Response.t
(** PUT request. See {!request} for parameter details. *)

val delete :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  string ->
  Response.t
(** DELETE request. See {!request} for parameter details. *)

val head :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  string ->
  Response.t
(** HEAD request. See {!request} for parameter details. *)

val patch :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?body:Body.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  string ->
  Response.t
(** PATCH request. See {!request} for parameter details. *)

val upload :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?method_:Method.t ->
  ?mime:Mime.t ->
  ?length:int64 ->
  ?on_progress:(sent:int64 -> total:int64 option -> unit) ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  source:Eio.Flow.source_ty Eio.Resource.t ->
  string ->
  Response.t
(** Upload from stream. See {!request} for parameter details. *)

val download :
  sw:Eio.Switch.t ->
  clock:_ Eio.Time.clock ->
  net:_ Eio.Net.t ->
  ?headers:Headers.t ->
  ?auth:Auth.t ->
  ?timeout:Timeout.t ->
  ?on_progress:(received:int64 -> total:int64 option -> unit) ->
  ?verify_tls:bool ->
  ?tls_config:Tls.Config.client ->
  string ->
  sink:Eio.Flow.sink_ty Eio.Resource.t ->
  unit
(** Download to stream. See {!request} for parameter details. *)