Hcs.Client

hcs · API reference

High-level HTTP client.

Use this module for ordinary outbound HTTP requests. It selects HTTP/1.1 or HTTP/2 support through the configured client stack and exposes convenience helpers for common request shapes. Prefer Http to build requests when you want a small request DSL, and pass those requests to the client execution functions.

Intended use: application clients, service-to-service calls, test clients, and one-off HTTP requests.

Unified HTTP Client supporting HTTP/1.1 and HTTP/2.

This module provides a high-level HTTP client that automatically selects the appropriate protocol based on ALPN negotiation or configuration. Connections are pooled for high performance.

type protocol = 
  | HTTP_1_1
  | HTTP_2

type config = {
  connect_timeout : float;
  read_timeout : float;
  write_timeout : float;
  follow_redirects : int option;
  preferred_protocol : protocol 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

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_http2 : config -> config

val with_http11 : 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

type error = 
  | Connection_failed of string
  | Tls_error of string
  | Protocol_error of string
  | Timeout
  | Invalid_response of string
  | Response_body_too_large of int64
  | Too_many_redirects

type response = {
  status : int;
  headers : (string * string) list;
  body : string;
  protocol : protocol;
}

type t = {
  config : config;
  h1_client : H1_client.t;
  h2_client : H2_client.t;
}

val status_to_int : Status.t -> int

val headers_to_list : Http_core.Headers.t -> (string * string) list

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

val close : t -> unit

val should_use_h2 : config -> Uri.t -> bool

val map_h1_error : H1_client.error -> error

val map_h2_error : H2_client.error -> error

val to_hcs_method : 
  Http.meth ->
  [> `CONNECT
  | `DELETE
  | `GET
  | `HEAD
  | `OPTIONS
  | `Other of string
  | `POST
  | `PUT
  | `TRACE ]

Convert an HTTP request method to the http codec method used by both clients.

val request : 
  t ->
  Http.meth ->
  ?headers:(string * string) list ->
  ?body:string ->
  Uri.t ->
  (response, error) result

Perform an HTTP request with any method using the unified client.

~headers are extra per-request headers merged on top of defaults. ~body is the optional request body string.

Convenience methods

val get : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  (response, error) result

Perform a GET request

val post : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  body:string ->
  (response, error) result

Perform a POST request

val put : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  body:string ->
  (response, error) result

Perform a PUT request

val patch : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  body:string ->
  (response, error) result

Perform a PATCH request

val delete : 
  t ->
  ?headers:(string * string) list ->
  ?body:string ->
  Uri.t ->
  (response, error) result

Perform a DELETE request

val head : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  (response, error) result

Perform a HEAD request

val options : 
  t ->
  ?headers:(string * string) list ->
  Uri.t ->
  (response, error) result

Perform an OPTIONS request

val execute : t -> Http.request -> (response, error) result

Execute an Http.request built with the Http DSL

This bridges the Http request builder to the actual client execution.

let req =
  Http.post (Uri.of_string "https://api.example.com/users")
  |> Http.bearer "my-token"
  |> Http.body_json {|{"name":"Alice"}|}
  |> Http.build
in
Client.execute client req

val execute_many : 
  ?max_concurrent:int ->
  t ->
  Http.request list ->
  (response, error) result list

Execute multiple Http.requests.

When every request is configured for HTTP/2, requests are multiplexed over HTTP/2 with up to max_concurrent streams in flight per connection chunk. Results preserve input order. Requests that are not configured for HTTP/2 fall back to sequential execution.

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

Perform a GET request (creates temporary client, no pooling benefit)

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

Perform a POST request (creates temporary client, no pooling benefit)