Hcs.Grpc.Server

hcs · API reference

A gRPC server is a set of services, each a set of named RPCs, dispatched by request path /package.Service/Method. Build one with v / add_service / Service.add_rpc, then mount handler as an HCS request handler.

type ctx = {
  metadata : (string * string) list; (* Request headers (call metadata), excluding HTTP/2 pseudo-headers. *)
  service : string; (* Matched service name, e.g. package.Service. *)
  rpc : string; (* Matched method name. *)
}

Per-call context passed to every handler.

Raw (string) handler types

A reader unit -> string option yields request messages in order, None at end-of-stream; a writer string -> unit sends a response message. Handlers return Ok payload / Ok () for success (status OK) or Error status to fail the call with that status. A raised exception becomes Internal.

type unary = ctx -> string -> (string, Status.t) result
type client_streaming =
  ctx ->
  (unit -> string option) ->
  (string, Status.t) result
type server_streaming =
  ctx ->
  string ->
  (string -> unit) ->
  (unit, Status.t) result
type bidi =
  ctx ->
  (unit -> string option) ->
  (string -> unit) ->
  (unit, Status.t) result
type rpc

A registered method of one of the four kinds.

val unary_raw : unary -> rpc
val client_streaming_raw : client_streaming -> rpc
val server_streaming_raw : server_streaming -> rpc
val bidi_raw : bidi -> rpc

Typed handlers

Wrap a handler over decoded request / encoded response values. decode runs at the boundary; if it raises, the call fails with Internal.

val unary : 
  decode:(string -> 'req) ->
  encode:('resp -> string) ->
  (ctx -> 'req -> ('resp, Status.t) result) ->
  rpc
val client_streaming : 
  decode:(string -> 'req) ->
  encode:('resp -> string) ->
  (ctx -> (unit -> 'req option) -> ('resp, Status.t) result) ->
  rpc
val server_streaming : 
  decode:(string -> 'req) ->
  encode:('resp -> string) ->
  (ctx -> 'req -> ('resp -> unit) -> (unit, Status.t) result) ->
  rpc
val bidi : 
  decode:(string -> 'req) ->
  encode:('resp -> string) ->
  (ctx -> (unit -> 'req option) -> ('resp -> unit) -> (unit, Status.t) result) ->
  rpc
module Service : sig ... end
type t

A gRPC server: a set of named services.

val v : unit -> t
val add_service : name:string -> Service.t -> t -> t

Register service under name (the package.Service path segment).

val handler : sw:Eio.Switch.t -> t -> Server.request -> Response.t

handler ~sw t is an HCS request handler dispatching to t's methods. Server-streaming and bidirectional handlers run on fibers forked into sw so their writes stream out concurrently, so pass a switch that lives for the server's lifetime. An unknown path yields Unimplemented.