gazagnaire.org
nox-grpc#
gRPC over HTTP/2, in pure OCaml, with an I/O-free core.
nox-grpc implements the gRPC wire protocol as an I/O-free state
machine: bytes and state in, bytes and events out, no sockets of its own. The
same core runs under Eio (via nox-grpc-eio), in dune test, and in fuzz
harnesses. Messages are carried with nox-protobuf and the
transport is nox-h2.
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
Status#
Early. The protocol foundation is in place and tested; the transport-coupled layers are landing on top.
| Layer | Module | State |
|---|---|---|
| Status codes | Grpc.Status |
done |
| Message framing (length-prefixed) | Grpc.Message |
done |
Compression algorithms (grpc-encoding) |
Grpc.Compression |
names done; gzip/deflate via bytesrw next |
| Call metadata / trailers | Grpc.Metadata |
next |
| Message serialization (protobuf) | Grpc.Codec |
next |
| Method / service descriptors | Grpc.Method |
next |
| Client / server state machines | Grpc.Client / Grpc.Server |
next |
| Eio adapter (multicore server, client) | nox-grpc-eio |
next |
Design#
The library follows the project's protocol-library pattern: a pure
core with the framing layer (Message), the serialization layer (Codec), and
the per-side state machines (Client / Server), plus a thin Eio adapter that
only shuttles bytes between a flow and the core. The server adapter targets
multicore throughput with an Eio.Executor_pool over the nox-h2-eio server
loop, in the manner of respond.
References#
- gRPC over HTTP/2 wire spec:
grpc/grpc:doc/PROTOCOL-HTTP2.md - Status codes:
grpc.io status-codes guide /
doc/statuscodes.md - Compression:
grpc/grpc:doc/compression.md - Reference implementation we benchmark against: the Go implementation,
grpc/grpc-go. - Prior OCaml implementation (on
anmonteiro/ocaml-h2+ocaml-protoc-plugin):dialohq/ocaml-grpc.