examples

Examples

Set of examples that show off the features provided by tonic and grpc.

In order to build these examples, you must have the protoc Protocol Buffers compiler. You need to have installed either:

• the protoc binary, made available in your PATH. This is the default.

• A compatible C++ compiler and CMake as described in the protoc-gen-rust-grpc crate. Choose this option by passing --features protoc-gen-rust-grpc to cargo.

If you choose to install protobuf, here are the steps for a variety of operating systems.

Ubuntu:

sudo apt update && sudo apt upgrade -y
sudo apt install -y protobuf-compiler libprotobuf-dev

Alpine Linux:

sudo apk add protoc protobuf-dev

macOS:

Assuming Homebrew is already installed. (If not, see instructions for installing Homebrew on the Homebrew website.)

brew install protobuf

grpc crate examples

For the examples related to the grpc crate, the generated code is checked into the repo to allow building without protoc. To rebuild the generated code you must set GRPC_RUST_REGENERATE_PROTO=1 in your environment. This requires that you have installed either:

• the protoc and protoc-gen-rust-grpc binaries, made available in your PATH. See above for protoc. protoc-gen-rust-grpc can be downloaded from our releases.

• A compatible C++ compiler and CMake as described in the protoc-gen-rust-grpc crate. Choose this option by passing --features grpc-protobuf-build/build-plugin to cargo.

Helloworld

Client

$ cargo run --bin grpc-helloworld-client

Server

The grpc crate currently does not support servers; run the Tonic helloworld server instead:

$ cargo run --bin helloworld-server

RouteGuide

Client

$ cargo run --bin grpc-routeguide-client

Server

The grpc crate currently does not support servers; run the Tonic routeguide server instead:

$ cargo run --bin routeguide-server

Helloworld

Client

$ cargo run --bin helloworld-client

Server

$ cargo run --bin helloworld-server

RouteGuide

Client

$ cargo run --bin routeguide-client

Server

$ cargo run --bin routeguide-server

Authentication

Client

$ cargo run --bin authentication-client

Server

$ cargo run --bin authentication-server

Load Balance

Client

$ cargo run --bin load-balance-client

Server

$ cargo run --bin load-balance-server

Dynamic Load Balance

Client

$ cargo run --bin dynamic-load-balance-client

Server

$ cargo run --bin dynamic-load-balance-server

TLS (rustls)

Client

$ cargo run --bin tls-client

Server

$ cargo run --bin tls-server

Health Checking

Server

$ cargo run --bin health-server

Server Reflection

Server

$ cargo run --bin reflection-server

Tower Middleware

Server

$ cargo run --bin tower-server

Autoreloading Server

Server

systemfd --no-pid -s http::[::1]:50051 -- cargo watch -x 'run --bin autoreload-server'

Notes:

If you are using the codegen feature, then the following dependencies are required:

• bytes
• prost
• prost-derive

The autoload example requires the following crates installed globally:

• systemfd
• cargo-watch

Richer Error

Both clients and both servers do the same thing, but using the two different approaches. Run one of the servers in one terminal, and then run the clients in another.

Client using the ErrorDetails struct

$ cargo run --bin richer-error-client

Client using a vector of error message types

$ cargo run --bin richer-error-client-vec

Server using the ErrorDetails struct

$ cargo run --bin richer-error-server

Server using a vector of error message types

$ cargo run --bin richer-error-server-vec