grpc-rust: the gRPC Rust stack in the middle of a rename

One repository, two naming generations

The first thing to understand about this repository is that its documentation and its published crates disagree about what the project is called. The owner is the gRPC organisation and the repository is grpc-rust, but the README still opens with a banner served from the hyperium tonic repository, describes the library as tonic, and sends you to a hyperium issues page and a hyperium website for help. Every documentation link in the README points at hyperium, not at grpc.

Meanwhile the release feed shows what is actually shipping. The three most recent releases, all dated 2026-05-28, are grpc-v0.9.0, grpc-protobuf-v0.9.0 and protoc-gen-rust-grpc-v0.9.0, each titled gRPC-Rust Initial Preview Release and each linking to a gRPC.io quickstart page. So the code generation plugin and the runtime both now exist under grpc- names, published from this repository.

The Cargo.toml makes the transition concrete. The workspace lists tonic, tonic-build, tonic-health, tonic-protobuf, tonic-types, tonic-reflection, tonic-prost, tonic-prost-build and tonic-web, and alongside them grpc, grpc-benchmark, grpc-google, grpc-protobuf, grpc-protobuf-build, grpc-xds and protoc-gen-rust-grpc. Two naming generations, one resolver, one build.

Three layers: generic traits, HTTP/2 on hyper, codegen on prost

The architecture explanation in the README is worth keeping, because it survives any rename. tonic is composed of three main components: the generic gRPC implementation, the HTTP/2 implementation, and the code generation powered by prost.

The generic layer is the interesting design choice. It can support any HTTP/2 implementation and any encoding through a set of generic traits, which means gRPC is not welded to hyper in the type system. The HTTP/2 layer is built on hyper, and the README credits hyper as a fast HTTP/1.1 and HTTP/2 client and server on top of the tokio stack. The codegen layer turns protobuf definitions into clients and servers.

The stated reason the library exists at all is first class support of async/await, and the position it takes is that of a building block for production systems written in Rust rather than a complete framework. The feature list stays short and specific: bi-directional streaming, high performance async io, interoperability, TLS backed by rustls, load balancing, custom metadata, authentication, and health checking. Notably absent from that list is anything about HTTP/JSON transcoding, which is where a different project in the same ecosystem does that job.

The workspace lists what the crates actually cover

The Cargo.toml is the most informative file in the repository, more so than the README, because it enumerates the shipped surface. Alongside the tonic crates it includes tonic-xds and grpc-xds, plus xds-client, xds-client-opentelemetry and xds-test-util, which is the xDS control plane surface. There is a dedicated tests/ tree with members for compression, well-known types, deprecated methods, extern paths, compile-time behaviour, web, default stubs and disable_comments, most of which exist to pin down behaviour that is easy to regress in a compiler.

Two policy settings are worth copying into your own workspace. The declared MSRV is 1.88, matching the README's statement that tonic's MSRV is 1.88, and linting is configured at the workspace level rather than per crate:

[workspace.package]
rust-version = "1.88"

The lints table denies broken intra-doc links in rustdoc, denies uninlined format args in clippy, and warns on missing docs, missing debug implementations, rust_2018_idioms and unreachable pub. A library workspace that warns on missing documentation for public items is telling you it expects to be consumed by people who will read the docs, which is the right default for an RPC runtime.

The resolver is pinned as well:

[workspace]
resolver = "2"

One hard dependency you cannot avoid: protoc

The one external tool the README names is the Protocol Buffers compiler. tonic-build uses protoc in some of its APIs, specifically the ones that compile Protocol Buffers resource files such as `tonic_build::compile_protos()`. The README links both the compiler downloads page and the docs page for that function.

This is the operational fact that catches people out. Adding a Rust gRPC library to a build means adding a native binary dependency to your CI image, and on some platforms a specific version of it. The project ships a flake.nix and flake.lock at the repository root, so there is a Nix path for pinning it, but for everyone else the version of protoc in your build image is now part of your reproducibility surface.

The alternative is code generation as a separate step, generating Rust files into the tree and committing them. The tree suggests both paths are supported, since there is a codegen/ directory alongside tonic-build. Whether you generate at build time or check in output is a decision about your CI, not about the library.

Where to start reading: helloworld, then routeguide

The README's Getting Started section names two tutorials in order. The helloworld tutorial is described as a basic example, appropriate for first time users, and the routeguide tutorial as a complete example using all of the features. Both are markdown files inside examples/, alongside a proto/ directory, a src/ directory, generated/ output and a data/ directory.

That ordering is a real recommendation about how to evaluate the library. helloworld tells you whether the build works in your environment. routeguide tells you whether you can live with the API, and it is the one to read before choosing tonic over writing the HTTP/2 handling yourself.

For the parts the tutorials do not cover, the README points at the interop directory, which it describes as showing examples of many of the gRPC features. Interop test implementations are an underrated reference, because the gRPC interop suite is a shared conformance battery, so reading it tells you what other implementations do rather than what this author prefers.

The README also directs you to tonic-health, which implements the standard gRPC health checking service and doubles as an example of both unary and response streaming. For load balancer health checks in production, that crate is often the first thing you actually need.

Where tonic stops and other tools take over

The honest boundary here is that tonic is a gRPC implementation, not an HTTP API layer. If your requirement is that the same service answers JSON over HTTP/1.1 for browsers and clients that do not speak gRPC, this repository does not provide that. The README's feature list has no transcoding entry, and the workspace has no gateway crate. Doing that means adding a separate proxy generator or an HTTP framework alongside tonic, and accepting a second description of your API surface.

There is also the master branch warning, which is easy to skim past. The README says tonic's master branch is currently preparing breaking changes and points readers who want recently released code at the 0.14.x branch. Applied to grpc-rust, the meaning is that master carries work in progress while the released line is what your dependency resolver will find.

For load balancing and control plane features, xDS support is present in the workspace rather than absent, which is unusual for a Rust gRPC implementation and is the main reason to look here over a thinner alternative. The cost is a workspace with more than thirty members and two parallel naming schemes, and you should expect to spend time on that rather than on gRPC itself.

Editorial conclusion

grpc-rust is worth following if you write Rust services and want gRPC without leaving the async ecosystem, but the naming is unsettled right now. The README still points at hyperium for issues and the website, the crates published in May 2026 carry grpc- names, and the workspace keeps tonic- and grpc- directories together, so pick your crate names deliberately rather than by copying an older tutorial. Start with tonic-build for code generation, watch the master branch note about breaking changes, and check whether tonic 0.14.x or the grpc 0.9.0 line is the one your dependency tree resolves to before you commit.

Frequently asked questions

Official sources

1. grpc/grpc-rust on GitHub
2. License: MIT
3. Project website
4. README
5. Releases