Structure of Tonic's proto include

When developing gRPC using Tonic _, it is necessary to properly incorporate protobuf in addition to building the server process.
Tonic uses PROST! , which is slightly different from the flow generated by the protoc command.

Alain , a code generation CLI tool equivalent to the logic of this article, is distributed as open source.

proto include

Consider the following example of embedding protobuf code.

syntax = "proto3";

package example.duck;

service ExampleDuck {
  rpc LameDuck(Dummy) returns (Dummy) {}
}

message Dummy {}

First, include proto using a macro.

pub mod example {
  pub mod duck {
        tonic::include_proto!("example.duck");
  }
}

At this time, it is important to define the mod hierarchy aligned with the protobuf package namespace.
If you make a mistake in the structure, you will face very confusing errors such as over-nested code output .

proto definition reference

The included proto definition is assigned to the namespace of the rust project along with the mod structure. In the previous example, it will be imported with a name like crate :: example :: duck::Dummy. Note that rpc is a snake case like crate::example::duck :: lame_duck().

In addition, structures such as servers are automatically generated according to the tool naming convention. There is an auto-generated file in the target / directory, and in individual cases you will have to check the code.

  • example::duck::LameDuckServer
  • example::duck::LameDuckClient
  • example::duck::LameDuckService

For the server implementation, if you do not implement all the rpc defined in proto, a compile-time error will occur.

Request and Response structure

Request is a tonic::Request<example::duck::Dummy> wrapping a protobuf message with tonic::Request. The message can be retrieved with into_inner().

Response is a Result type that returns tonic::Response or tonic::Status, such as Result<tonic::Response<example::duck::Dummy, tonic::Status>.

Build script

Tonic expects a flow to compile protobuf into rust code when running cargo build. Therefore, put the following build.rs in the project root.

fn main() -> Result<(), Box<dyn std::error::Error>> {
    tonic_build::compile_protos("proto/example_duck.proto")?;
    Ok(())
}

Note that the tonic-build crate is required for protobuf compilation, so add it to the build-dependencies of Cargo.toml.

[build-dependencies]
tonic-build	=  { version = "0.4", features = ["prost"] }

gRPC-Web over HTTP/3

gRPC-Web is a proxy protocol for accessing gRPC services from browsers, built on top of simple HTTP requests that browsers support.

Native gRPC relies on HTTP/2, and there is ongoing discussion regarding HTTP/3 support .

It’s not obvious whether gRPC-Web supports HTTP/3. Given its purpose of browser support, it works not only on HTTP/2 but also on HTTP/1.1.

There have been no protocol updates or precedents for standardization for gRPC-Web.

gRPC-Web seemingly works on HTTP/3

In reality, when a frontend proxy provides HTTP/3, gRPC-Web also operates on HTTP/3. For instance, Google’s application load balancer among its load balancer products provides HTTP/3, and when providing gRPC-Web services behind it, connections are made over HTTP/3.

The specific version of HTTP used for each connection depends on a browser. It is speculated that gRPC-Web client libraries often implement using the fetchAPI, and in the case of Chrome, it actively utilizes HTTP/3 for fetch().

Since HTTP/3 connects via Quic/UDP, performance improvements can be expected as a WAN protocol. However, this browser behavior also indicates that individual gRPC-Web services have no means of controlling the HTTP version.

Although our production clusters unintentionally ended up with gRPC-Web over HTTP/3 configurations, no issues have occurred, even including server-side streaming. We have good results of reproducing the actual configuration with our test suites, and it’s safe to say that it’s been operating stably.

gRPC-Web over HTTP/3 configuration

The functionality of the GCP load balancer automatically enables gRPC-Web to support HTTP/3, so we haven’t verified the necessary configuration. However, the load balancer only performs protocol conversion and minimal HTTP header manipulation.

For gRPC-Web proxies, Envoy is often adopted. It is presumed that by defining downstream settings for HTTP/3 in addition to the existing upstream settings, gRPC-Web can be delivered over HTTP/3. Specifically, it should suffice to configure HTTP/3 on the UDP port downstream of Envoy and advertise alt-svc on the TCP port for HTTP/2.

⁋ May 17, 2021↻ Oct 13, 2026