Hcs.H1_client

hcs · API reference

HTTP/1.1-specific client.

Use only when you need direct control over HTTP/1.1 behavior. Prefer Client for general application code.

HTTP/1.1 Client implementation on the http sans-I/O codec (Http1.Client_connection).

Provides HTTP/1.1 client functionality over Eio with connection pooling. The transport (TCP/TLS), DNS, pooling, timeouts and redirects live here; the wire protocol is driven by http.

module C = Http1.Client_connection

Configuration

type config = {
  connect_timeout : float;
  read_timeout : float;
  write_timeout : float;
  follow_redirects : int option;
  buffer_size : int;
  max_response_body : int64 option;
  tls : Tls_config.Client.t;
  default_headers : (string * string) list;
  pool : Pool.config;
}
val default_config : config

Config builders

val with_timeout : float -> config -> config
val with_connect_timeout : float -> config -> config
val with_read_timeout : float -> config -> config
val with_write_timeout : float -> config -> config
val with_redirects : int -> config -> config
val without_redirects : config -> config
val with_buffer_size : int -> config -> config
val with_max_response_body : int64 -> config -> config
val with_tls : Tls_config.Client.t -> config -> config
val with_insecure_tls : config -> config
val with_default_header : string -> string -> config -> config
val with_default_headers : (string * string) list -> config -> config
val with_pool_config : Pool.config -> config -> config
val with_max_connections : int -> config -> config
val with_idle_timeout : float -> config -> config
type error = 
  | Connection_failed of string
  | Tls_error of string
  | Timeout
  | Invalid_response of string
  | Response_body_too_large of int64
  | Too_many_redirects

Error type for client operations

type response = {
  status : Status.t;
  headers : Http_core.Headers.t;
  body : string;
}

Response type

Connection type for pooling

type conn = {
  flow : Eio.Flow.two_way_ty Eio.Std.r;
  read_buffer : Http_core.Bigstring.t;
  mutable alive : bool;
}

Internal connection state

Client type

type t = {
  config : config;
  pool : conn Pool.t;
  mutex : Eio.Mutex.t;
  connect : host:string -> port:int -> Eio.Flow.two_way_ty Eio.Std.r;
  resolve : string -> bool;
  now : unit -> float;
  with_timeout : 'a. float -> (unit -> 'a) -> 'a option;
}

HTTP/1.1 client with connection pooling. Uses closures to capture the Eio environment.

Internal helpers

val write_iovecs : 
  [> Eio.Flow.sink_ty ] Eio.Flow.sink ->
  Http_core.Iovec.t list ->
  int

Write the codec's iovecs to the flow; returns the byte count written. A Bigstring iovec (a Fixed/Bigstring body) is sent by reference (zero copy); a Bytes iovec (the serialized head) is small and copied once.

val read_into : 
  [> Eio.Flow.source_ty ] Eio.Flow.source ->
  Cstruct.buffer ->
  off:int ->
  len:int ->
  [> `Eof | `Ok of int ]

Read from flow into the bigstring buffer

val close_conn : conn -> unit

Close a connection safely

val do_request : 
  ?request_body:string ->
  ?max_response_body:int64 ->
  conn ->
  meth:Http_core.Method.t ->
  target:string ->
  headers:Http_core.Headers.t ->
  (response * bool, error) result

Perform an HTTP/1.1 request on a connected flow. Returns the response and whether the connection may be kept alive for reuse.

val create_connection : 
  t ->
  host:string ->
  port:int ->
  is_https:bool ->
  (conn, error) result
val acquire_connection : 
  t ->
  host:string ->
  port:int ->
  is_https:bool ->
  (conn, error) result

Acquire a connection from pool or create new one

val release_connection : 
  t ->
  host:string ->
  port:int ->
  is_https:bool ->
  conn ->
  keep_alive:bool ->
  unit

Release connection back to pool

Public API

val create : 
  sw:Eio.Switch.t ->
  net:[> [> `Generic ] Eio.Net.ty ] Eio.Net.t ->
  clock:[> float Eio.Time.clock_ty ] Eio.Time.clock ->
  ?config:config ->
  unit ->
  t

Create a new HTTP/1.1 client with connection pooling

val close : t -> unit

Close all connections and cleanup

val merge_headers : 
  default_headers:(string * 'a) list ->
  headers:(string * 'a) list ->
  (string * 'a) list
val request : 
  t ->
  Method.t ->
  ?headers:(string * string) list ->
  ?body:string ->
  Uri.t ->
  (response, error) result

Perform an HTTP request with any method using pooled connections.

~body is the optional request body string. ~headers are extra per-request headers merged on top of defaults. The codec frames the body (Content-Length/Transfer-Encoding are set automatically).

Convenience methods

val get : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  (response, error) result
val post : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  body:string ->
  (response, error) result
val put : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  body:string ->
  (response, error) result
val patch : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  body:string ->
  (response, error) result
val delete : 
  t ->
  ?headers:(string * string) list ->
  ?body:string ->
  Uri.t ->
  (response, error) result
val head : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  (response, error) result
val options : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  (response, error) result

Stateless API

val get' : 
  sw:Eio.Switch.t ->
  net:[> [> `Generic ] Eio.Net.ty ] Eio.Net.t ->
  clock:[> float Eio.Time.clock_ty ] Eio.Time.clock ->
  ?config:config ->
  Uri.t ->
  (response, error) result
val post' : 
  sw:Eio.Switch.t ->
  net:[> [> `Generic ] Eio.Net.ty ] Eio.Net.t ->
  clock:[> float Eio.Time.clock_ty ] Eio.Time.clock ->
  ?config:config ->
  Uri.t ->
  body:string ->
  (response, error) result