gRPC over HTTP/2 in pure OCaml
README.md

nox-grpc #

gRPC over HTTP/2 in pure OCaml, with an I/O-free core.

Most service meshes, Kubernetes components and cloud APIs call each other over gRPC. (Kubernetes runs containers on a cluster of machines and restarts them when they fail. A service mesh puts a proxy beside each service; the proxies carry the calls between services and add routing, encryption and retries.) An OCaml service that wants to take part has to speak both ends of the protocol.

On the wire, a gRPC call is an HTTP/2 stream. Metadata and the timeout travel in headers. Each message goes in DATA frames, preceded by 5 bytes: a 1-byte compressed flag and a 4-byte big-endian length. The outcome of the call comes last, in a trailer, which is a final HEADERS frame sent after the last DATA frame and carrying grpc-status and grpc-message.

nox-grpc implements this protocol as pure state machines. You feed in bytes and the current state, and get back bytes to send and events to act on; the library never opens a socket. The same core runs under Eio through nox-grpc-eio, in unit tests and in fuzz harnesses. Messages are encoded with nox-protobuf and carried over nox-h2.

The package is young. Every layer in the table below is implemented and tested, and the Eio adapter serves and calls all four call shapes (unary, server streaming, client streaming and bidirectional streaming). Compression is named but not yet applied. The core parses grpc-encoding and takes the compressor as a parameter, and gzip and deflate through bytesrw are still to be written. Nobody has yet measured end-to-end throughput against a Go server.

Installation #

Install with opam:

$ opam install nox-grpc

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install nox-grpc

API #

The core, nox-grpc, has one module per layer of the protocol:

Layer Module
Status codes Grpc.Status
Length-prefixed message framing Grpc.Message
Compression algorithm names (grpc-encoding) Grpc.Compression
Call metadata and trailers Grpc.Metadata
Call timeouts (grpc-timeout) Grpc.Timeout
Message serialisation (protobuf or raw bytes) Grpc.Codec
Method descriptors and call shapes Grpc.Method
Client and server call state machines Grpc.Client, Grpc.Server

nox-grpc-eio adds two modules. Grpc_eio.Server registers a handler for each method and can spread connections over several domains. Grpc_eio.Client opens a connection and runs calls over it.

Design #

The core is pure. It holds the framing layer (Message), the serialisation layer (Codec) and one state machine per side (Client and Server). The Eio adapter is thin and only moves bytes between a flow and the core. On the server side it runs the nox-h2-eio server loop, and it can hand connections to an Eio.Executor_pool to use more than one core.

References #

License #

ISC. See LICENSE.md.