Hcs.Grpc.Client

A gRPC client over a base address (e.g. "http://localhost:50051" for h2c, or "https://host:443" for HTTP/2 over TLS). Each call extends the base with /service/rpc.

unary, server_streaming and client_streaming are multiplexed as concurrent streams over a single persistent HTTP/2 connection (lazily established on first use and re-established if it drops) — the model gRPC expects. bidi runs on its own dedicated connection, since it needs a request body produced incrementally over the life of the call.

type t

type error = 
  | Transport of string (* A transport-level failure (no gRPC trailers were received). The gRPC-level outcome of a completed call is the returned Status.t. *)

val create : 
  sw:Eio.Switch.t ->
  net:_ Eio.Net.t ->
  clock:_ Eio.Time.clock ->
  ?config:H2_client.config ->
  address:string ->
  unit ->
  t

val unary : 
  t ->
  service:string ->
  rpc:string ->
  ?metadata:(string * string) list ->
  string ->
  (string option * Status.t, error) result

Send one message, receive one. The response message is present iff the call returned data; check the Status.t for the gRPC outcome.

val server_streaming : 
  t ->
  service:string ->
  rpc:string ->
  ?metadata:(string * string) list ->
  string ->
  on_message:(string -> unit) ->
  (Status.t, error) result

Send one message; on_message is called for each response message as it arrives, then the final status is returned.

val client_streaming : 
  t ->
  service:string ->
  rpc:string ->
  ?metadata:(string * string) list ->
  (unit -> string option) ->
  (string option * Status.t, error) result

Stream request messages from the generator (until it returns None), then receive one response message and the final status.

type stream = {
  send : string -> unit; (* Send a request message. *)
  close : unit -> unit; (* Half-close the request stream (no more sends). *)
  recv : unit -> string option; (* Receive the next response message; None at end-of-stream. *)
}

A live bidirectional call handle.

val bidi : 
  t ->
  service:string ->
  rpc:string ->
  ?metadata:(string * string) list ->
  (stream -> 'a) ->
  ('a * Status.t, error) result

Run f with a bidirectional stream. f should stream.close once it has sent all requests and drain stream.recv to None; the call's final status is returned alongside f's result.

Interoperates with standard gRPC peers (verified against grpc-go in both directions). Known limitation: a separate-process hcs client ↔ hcs server bidirectional call can occasionally truncate the final response message. The underlying HTTP/2 codec pulls a streaming response producer from both its reader (on WINDOW_UPDATE) and writer fibers, and the producer blocks on a queue; under this client's window-update timing the two pulls can split the queue. In-process bidi and bidi against standard gRPC servers are unaffected.