Table of Contents
- Protocol Buffer
- Rust and gRPC
- Creating a Server
- Creating a Client
- Streaming in gRPC
HTTP and JSON is a very popular method for creating web APIs. HTTP and JSON make sense because it uses a very popular protocol. HTTP and JSON are text-based protocol which causes a performance problem since serializing JSON is a slow process, most HTTP and JSON or Rest APIs do not support streaming which means we cannot start processing the data before it arrives. Rest APIs have very good tooling and community support. Almost every programming language has a high-quality implementation for HTTP and serializing JSON. Rest architecture doesn’t fit every use case, it is difficult to provide client library for Rest APIs for every language and maintain these libraries. Since there is no language-independent method for defining the structure of JSON and HTTP requests, therefore, it is difficult to generate client libraries. gRPC is an attempt to tackle these problems.
Brief Intro to gRPC
gRPC is an open-source remote procedure call system developed by Google. gRPC allows the system to communicate in and out of data centers, efficiently transferring data from mobile, IoT devices, backends to one and other. gRPC came with plug able support for load balancing, authentication, tracing, etc. gRPC supports bidirectional streaming over HTTP/2. gRPC provides an idiomatic implementation in 10 languages. gRPC can generate efficient client libraries and uses the protocol buffer format for transferring data over the wire. Protocol buffers are a binary format for data transmission. Since protocol buffers are a binary protocol, it can be serialized fast and the structure of each message must be predefined.
A Little about Rust
Rust is a systems programming language. Rust provides high level ergonomic with low-level control. Rust provides control over memory management without the hassle associated with it. Rust has good support for Asynchronous operation making it a good fit for writing networking applications. Rust has zero cost abstraction making it blazing fast.
Protocol buffers are extensible, language-neutral data serializing mechanism. It is fast, small, and simple. Protocol buffers have a predefined structure with its syntax for defining messages and services. Services are functions that can be executed and messages are arguments passed to the function and values returned by these functions. There are two versions of protocol buffers. This tutorial would use version 3.
Protocol Buffers have a very simple syntax. There are two things to be defined in a protocol buffer.
serviceIt defines all the functionality that can be called on a particular service or server.
messageIt defines arguments and returns values of an
package must be defined in every protocol buffer file. Protocol buffer files are saved with
A service is defined by using
service keyword then defining call using
send is the name of the call, it can be used to make a call,
SayRequest define the argument
send call takes and
SayResponse defines the value returned by the call. Any number of the call can be defined in service.
Implementation of these function is not defined in the
*.proto* file, these implementations are provided by the server
Assign Number to Fields The number assigned to a field is very important because it is used to recognize the field in binary data. It takes 1 byte to encode 0-15 numbers and 2 bytes for encoding 16-2047, it is wise to use 0-15 for frequently occurring data. It is also recommended to reserve a few numbers so that, these reserved numbers can be used later if some changes are made to format.
Different Data Types
Prototype support many data types include string, int, float, boolean, etc. These types can be repeated using
repeated field attributes.
Protocol buffer syntax is explained in great detail in official documentation.
Rust and gRPC
Rust ecosystem has grown quite big with very good quality crates.
tonic is very performant gRPC implementation for Rust. This tutorial uses
tonic as the gRPC implementation and
tonic-build for compiling
.proto files to client libraries.
Let us start by creating a new cargo project using
cargo init. Now we need to create an add a few dependencies and build dependencies. These will help us with our server and client.
This should be a configuration for
prost provides basic types for gRPC,
tokio provide asynchronous runtime and
futures for handling asynchronous streams.
Compiling Protocol Buffers
We would use
build.rs for compiling our
.proto files and include then in binary.
tonic-build crate provides a method
compile_protos which take the path to
.ptoto file and compile it to rust definitions. First, we create a folder in the root directory named
proto it will contain all of out
.proto files. We create a
say.proto file in this directory. With our
Say service shown in the above example.
We create a
build.rs with the following code.
The above code will compile
proto/say.proto file and save it in an
OUT_DIR and add an environment variable
OUT_DIR which is available at build time so that we can use it later in our code. We can also provide different options for compiling the protocol buffers. Now your directory structure should look like this:
Now we have compiled our
.proto files we would use it in our code using
tonic utility. We would create a module for our server and client. Let us name it
hell.rs and we would add the following code.
Creating a Server
Now we have compiled the protocol buffers we are ready to build our server. We have to provide the implementation for every service and
rpc we defined. Service would be defined as traits and
rpc would be a member function on these traits. Since Rust doesn't support async traits we have to use an
asyc_trait macro for overcoming this limitation. We create a file named
server.rs and add the following code.
**tonic-build** would automatically compile
**.proto** following rust naming conventions and best practices.
In Rust, messages are represented as structs and services as traits and RPC as functions. We
impl the trait for our struct and pass it to our server. In our example, we would create a send function which takes
Request as an argument which contains details about the request and wraps our message
SayRequest which can be accessed using
.get_ref method. Now let us run this by adding a bin block to our
This will help us testing and maintaining code in save repo but it is not suggested for a large project.
Now if we run this with command
--``bin server. We can see our server running at
Creating a Client
Our server is ready, now let's test it by creating a client. Since we have compiled our protocol buffer we can import our
hello.rs file and use it. We create a
client.rs file and add the following code.
We add a bin key to our
We create a channel that is an HTTP/2 connection that can be used then from our client. HTTP/2 support streams that can be used by gRPC. Now if we run our client with command
--bin client we can see see the response.
Error handling in gRPC is done using Status.
Status enum which can be returned in case of error with appropriate error message.
gRPC support bare-bone error handling but you can extend yourself using protocol buffer here is detail explanation
Streaming In gRPC
HTTP/2 supports streaming and gRPC provides a nice interface for using it. We can start sending the response even before the client finish sends the request. We can use it to provide an efficient service. The server has not to wait for the request from the client to complete the request. We need to make a few changes to our protocol buffers so that it reflects that we support streaming. We need to make changes to our rust code also. Rust has quite good support for asynchronous I/O. We would
tokio to stream response and request.
We would start by the streaming server since most of the time server would be sending a large amount of data. We would use a queue for sending data by multiplexing different task on a single thread.
tokio provide very excellent multi sender single receiver channel.
Changes to protocol buffers
We change the code of protocol buffer to the following. We use a stream keyword in
rpc and specify that the
rpc call will return a stream of messages
Changes to Server Code
We would use
tokio::sync::mpsc for communicating between futures. We send multiple responses using this channel. We would use
tokio::spawn to create a new task that can be then scheduled. We add the following code to our
We need to change the main function, we just add a new function to trait and a type to specify our output. In this new
send_stream function we create a channel so that we can send a response and return the receiver. The receiver implements the
Stream trait so it can be streamed by HTTP/2 and the sender can be used by multiple threads and it implements
Sink trait. We have created a bounded channel but we can also use an unbounded channel.
Changes in Client Code We need to make changes to response handling. Since it would be a stream now, we would just listen to this stream and print the response. Streams help to write non-blocking code and use resources more efficiently.
Sometimes all the data is not available, for example in a game all the data is not available then it would make stream the data and send all the data available and sending rest when available. This allows using data more efficiently on user devices. We need a few changes to our code.
Changes to protocol buffer
We would use the
stream keyword to specify the argument is a stream. We would use
stream to specify that our
rpc takes a stream as an argument.
Changes to Server We need our server to accept the stream as the request. We would listen on the stream and collect. Then we would respond when the stream finishes. It will save our resources since we can wait on stream asynchronously.
Changes to Client
We would now program our client to send a stream to our server. For this, we would mimic a stream using
futures crate and create a stream from a vector.
The bidirectional stream is also supported by gRPC. The bidirectional stream is just a combination of streaming requests and streaming responses. Here is a quick example.
Authentication is a very important aspect of a system. gRPC comes with plug able authentication support. gRPC support mainly two types of authentication:
- Token-based authentication
- TLS based authentication
In this tutorial, we would use JWT based authentication. JWT or JSON web token provides an open-source and stateless authentication mechanism. We would
jsonwebtoken crate for creating JWT and validating it. We would just see how we can use JWT with gRPC.
Server We would need to add an interceptor, that would validate token, if the token is not valid, we would just close the request, if the token is valid then we forward the request to our handlers.
If we return
Ok then the request would be passed on to functions but if we return
Err with status the request is closed with provided status. We create a service with this interceptor.
Client We need to add an interceptor to our client also. We would add it to our main function as a closure.
Mutual TLS Based Authentication
TLS stands for Transport Layer Security, it is recommended by gRPC documentation to encrypt HTTP/2 connection with TLS. We would TLS to authenticate both client and server. This is called Mutual TLS. We would create a private key and public key for both client and server. We would also create a Certificate Authority certificate so that we can sign our TLS certificate. We would require OpenSSL for creating certificates.
OpenSSL is a command-line utility for creating keys and encryption-related stuff. We would start by creating a Certification Authority certificate.
This would act as our signing key. We would use it to sign our TLS certificate. Next, we create our certificate which is called the root CA certificate. It is used to validate if our TLS certificate is validated or not.
This command would ask you a few questions. Details enter in this doesn’t matter. If you can get this certificate on every device on earth you become a certificate signing authority like Let’s Encrypt etc. Now let's create our server key and certificate.
This command will generate a key for our server. Now we create a certificate signing request for our key.
This would ask you some questions. Now we create a
server.ext file. This file would contain our name, our domain, or subdomain.
We add our identity in the form of DNS. Now we run the following command
You don’t need to provide your private key or server key. This might ask you a few questions and passcode provided when generating the Certificate Authority key. You can generate a Certificate for the client using the same certificate authority. Now we have all the required certificates to let configure our server and client.
Configuring Client and Server
tonic support TLS using
rust-tls. We can configure TLS by following the method.
This shows how to configure the client for TLS.
This shows how to configure for TLS.
We have gone through basic protocol buffer and gRPC. We have created our server. We also created a client for interacting with the server. We learned how to compile our
.proto file in rust client. We also learned how to stream responses and requests. We also created a bidirectional stream. We learned two different authentication strategy. We implemented JWT and Mutual TLS based authentication. Now you have a basic understanding of gRPC, you can create your own micro-service based app. gRPC comes with support for load-balancing,tracing and health tracking. Now you can explore further functionality of gRPC.