README.md
1# Examples
2
3Set of examples that show off the features provided by `tonic`.
4
5In order to build these examples, you must have the `protoc` Protocol Buffers compiler
6installed, along with the Protocol Buffers resource files.
7
8Ubuntu:
9
10```bash
11sudo apt update && sudo apt upgrade -y
12sudo apt install -y protobuf-compiler libprotobuf-dev
13```
14
15Alpine Linux:
16
17```sh
18sudo apk add protoc protobuf-dev
19```
20
21macOS:
22
23Assuming [Homebrew](https://brew.sh/) is already installed. (If not, see instructions for installing Homebrew on [the Homebrew website](https://brew.sh/).)
24
25```zsh
26brew install protobuf
27```
28
29## Helloworld
30
31### Client
32
33```bash
34$ cargo run --bin helloworld-client
35```
36
37### Server
38
39```bash
40$ cargo run --bin helloworld-server
41```
42
43## RouteGuide
44
45### Client
46
47```bash
48$ cargo run --bin routeguide-client
49```
50
51### Server
52
53```bash
54$ cargo run --bin routeguide-server
55```
56
57## Authentication
58
59### Client
60
61```bash
62$ cargo run --bin authentication-client
63```
64
65### Server
66
67```bash
68$ cargo run --bin authentication-server
69```
70
71## Load Balance
72
73### Client
74
75```bash
76$ cargo run --bin load-balance-client
77```
78
79### Server
80
81```bash
82$ cargo run --bin load-balance-server
83```
84
85## Dynamic Load Balance
86
87### Client
88
89```bash
90$ cargo run --bin dynamic-load-balance-client
91```
92
93### Server
94
95```bash
96$ cargo run --bin dynamic-load-balance-server
97```
98
99## TLS (rustls)
100
101### Client
102
103```bash
104$ cargo run --bin tls-client
105```
106
107### Server
108
109```bash
110$ cargo run --bin tls-server
111```
112
113## Health Checking
114
115### Server
116
117```bash
118$ cargo run --bin health-server
119```
120
121## Server Reflection
122
123### Server
124```bash
125$ cargo run --bin reflection-server
126```
127
128## Tower Middleware
129
130### Server
131
132```bash
133$ cargo run --bin tower-server
134```
135
136## Autoreloading Server
137
138### Server
139```bash
140systemfd --no-pid -s http::[::1]:50051 -- cargo watch -x 'run --bin autoreload-server'
141```
142
143### Notes:
144
145If you are using the `codegen` feature, then the following dependencies are
146**required**:
147
148* [bytes](https://crates.io/crates/bytes)
149* [prost](https://crates.io/crates/prost)
150* [prost-derive](https://crates.io/crates/prost-derive)
151
152The autoload example requires the following crates installed globally:
153
154* [systemfd](https://crates.io/crates/systemfd)
155* [cargo-watch](https://crates.io/crates/cargo-watch)
156
157## Richer Error
158
159Both clients and both servers do the same thing, but using the two different
160approaches. Run one of the servers in one terminal, and then run the clients
161in another.
162
163### Client using the `ErrorDetails` struct
164
165```bash
166$ cargo run --bin richer-error-client
167```
168
169### Client using a vector of error message types
170
171```bash
172$ cargo run --bin richer-error-client-vec
173```
174
175### Server using the `ErrorDetails` struct
176
177```bash
178$ cargo run --bin richer-error-server
179```
180
181### Server using a vector of error message types
182
183```bash
184$ cargo run --bin richer-error-server-vec
185```