Universal gRPC client demonstration [Evans]

https://mrturkmen.com/gRPC-calls-with-evans/

In this post, I am going to write demo for a tool which I have just met, it is called Evans. It is basically universal gRPC client. What it means ? Basically when you have gRPC server and would like to test gRPC calls without creating client, you can test server side calls with Evans. It is known that gRPC is very common communication method between microservices, it can be used for internal and external communication. I do not have intention to explain what gRPC is in this post since it is not the purpose. If required documentation of gRPC can be investigated.

Create a simple gRPC server

gRPC server is basically an API endpoint where clients can make requests, since it is an API, first thing could be to define which methods will be used for this service.

For simplicity and purpose of this post, I have created a basic microservice which will has four calls namely, Add,Delete,List and Find. Since the purpose is to understand how evans works, the gRPC server does not need to be complex or includes lots of calls.

Sample repository

If you have already a running gRPC server, you can direcly pass to demonstration of evans, if not, you can clone https://github.com/mrturkmencom/BookShelf repository and test evans out.

Defining calls

Following proto file would be enough for BookShelf service.

// it is important to declare syntax version
syntax = "proto3";
service BookShelf {
rpc AddBook(AddBookRequest) returns (AddBookResponse) {}
rpc ListBook (ListBooksRequest) returns (ListBooksResponse) {}
rpc DelBook (DelBookRequest) returns (DelBookResponse){}
rpc FindBook (FindBookRequest) returns (FindBookResponse){}
}
message AddBookRequest {
BookInfo book = 1;
message BookInfo {
string isbn =1;
string name =2;
string author=3;
string addedBy=4;
}
}message AddBookResponse {
string message = 1;
}
message ListBooksRequest {
// no need to have anything
// could be extended to list books based on category ...
}
message ListBooksResponse {
repeated BookInfo books =1;
message BookInfo {
string isbn =1;
string name =2;
string author=3;
string addedBy=4;
}
}
message DelBookRequest {
string isbn =1;
}
message DelBookResponse {
string message =1;
}
message FindBookRequest {
string isbn =1;
}
message FindBookResponse {
Book book = 1;
message Book {
string isbn =1;
string name =2;
string author=3;
string addedBy=4;
}
}

Once proto file is declared, it becomes more easy to continue. For the demostration purposes, I will store information of books in memory. However, as you know, it is NOT acceptable for any production level application.

Compile Proto file

$  protoc -I proto/ proto/bs.proto --go_out=plugins=grpc:proto

It will generate ready to use Go source code for your rpc calls which are defined in proto file.

Afterwards, necessary piece of codes should be implemented, which are in memory store and book struct. For the aim of this post, I assumed that you have created all rest of the code as given in example gRPC server (-BookShelf-).

NOTE: Generating source code through protoc requires to have protoc tool to be installed before hand. Installation of protoc is over here

Run gRPC server

You can start gRPC server with:

$ go run server/main.go
BookShelf gRPC server is running ....

Once gRPC server is up and running, you can use evans tool for inspecting gRPC server for available inquires.

Demonstration of EVANS

It has plenty of features which are very handy to use for automating and testing some stuff on top of existing gRPC server or new one.

Let’s make a demo, when you are using evans your gRPC server should be up and running, in order to make communication with universal gRPC client — evans. I assumed that you have followed readme file of evans and installed it correctly.

Note that port 9000 is given because it is port of gRPC server.

❯ evans -r -p 9000  ______
| ____|
| |__ __ __ __ _ _ __ ___
| __| \ \ / / / _. | | '_ \ / __|
| |____ \ V / | (_| | | | | | \__ \
|______| \_/ \__,_| |_| |_| |___/
more expressive universal gRPC clientBookShelf@127.0.0.1:9000> show services +-----------+----------+------------------+-------------------+
| SERVICE | RPC | REQUEST TYPE | RESPONSE TYPE |
+-----------+----------+------------------+-------------------+
| BookShelf | AddBook | AddBookRequest | AddBookResponse |
| BookShelf | ListBook | ListBooksRequest | ListBooksResponse |
| BookShelf | DelBook | DelBookRequest | DelBookResponse |
| BookShelf | FindBook | FindBookRequest | FindBookResponse |
+-----------+----------+------------------+-------------------+
BookShelf@127.0.0.1:9000>

As you can observe all calls which are used in proto file can be used through evans, moreover its usage is pretty straitforward.

You can check demonstration video below.

⚠️ You may wish to change the video quality to 1080p60

If you have any questions, fix, or something else, do not hesitate to contact with me.

Software Engineer at Aalborg University, Denmark