- OCaml 86%
- C 9%
- Go 4%
- Shell 1%
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 #
- The gRPC over HTTP/2 wire specification:
doc/PROTOCOL-HTTP2.md. - Status codes: the grpc.io status-codes guide
and
doc/statuscodes.md. - Compression:
doc/compression.md. - The Go implementation,
grpc/grpc-go, is the reference the benchmarks compare against. - An earlier OCaml implementation, built on
anmonteiro/ocaml-h2andocaml-protoc-plugin:dialohq/ocaml-grpc.
License #
ISC. See LICENSE.md.