Hcs.Grpc

gRPC over HTTP/2.

Build gRPC servers and clients on top of HCS's HTTP/2 transport, mirroring the Websocket and Sse transports. Messages are length-prefixed and the call status travels in HTTP/2 trailers (grpc-status/grpc-message). The module is codec-agnostic: handlers and calls exchange raw message strings, and typed wrappers take decode / encode functions so any payload format (protobuf, JSON, …) plugs in.

A gRPC server must run over HTTP/2 and, for bidirectional streaming, with incremental request bodies enabled:

let svc =
  Hcs.Grpc.Server.Service.v ()
  |> Hcs.Grpc.Server.add_rpc ~name:"SayHello"
       ~rpc:
         (Hcs.Grpc.Server.unary_raw (fun _ctx msg -> Ok ("hello " ^ msg)))
in
let server =
  Hcs.Grpc.Server.(v () |> add_service ~name:"greeter.Greeter" svc)
in
let config =
  Hcs.Server.default_config
  |> Hcs.Server.with_protocol Hcs.Server.Http2_only
  |> Hcs.Server.with_streaming_request_body true
in
Hcs.Server.run ~sw ~net ~clock ~config (Hcs.Grpc.Server.handler ~sw server)

gRPC over HTTP/2.

A transport module in the spirit of Websocket and Sse: it provides the gRPC wire protocol (length-prefixed messages, status in HTTP/2 trailers) and leaves the payload codec to the caller. Handlers and calls exchange raw message strings; the typed constructors take decode / encode so protobuf, JSON, or any other format plugs in at the boundary.

gRPC runs over HTTP/2. Serve a gRPC server with Server.handler behind a server configured for HTTP/2; enable Hcs.Server.with_streaming_request_body for bidirectional streaming so request messages are delivered to the handler as they arrive.

Status

module Status : sig ... end

A gRPC call result. The code is one of the 17 canonical codes; the optional message is human-readable detail. The status travels in the response trailers as grpc-status (the integer code) and grpc-message (percent-encoded).

Message framing

module Message : sig ... end

The gRPC length-prefix framing: each message is a 1-byte compressed-flag, a 4-byte big-endian length, then the payload. Compression is not supported (the flag is always written as 0).

Server

module Server : sig ... end

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.

Client

module Client : sig ... end

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.