The past couple of weeks I have been digging into gRPC and HTTP2 in my spare time. I needed a way to review the requests and responses, and an easy way to explore gRPC servers. I also wanted something to dump protocol buffers in a human readable format. It turns out grpcurl was written for just this purpose, and has been super useful for groking gRPC.
Grpccurl has a number of useful options. The list option can be used to display the service interfaces your gRPC server exposes:
$ grpcurl -v prefetch.net:443 list
build.stack.fortune.FortuneTeller
grpc.reflection.v1alpha.ServerReflection
In the previous example, I listed the service interfaces in the fortune teller sample application. In order for this to work, the server you are curling must support reflection. Once you have the list of service interfaces, you can list the methods they expose by passing the service name to list:
$ grpcurl -v prefetch.net:443 list build.stack.fortune.FortuneTeller
build.stack.fortune.FortuneTeller.Predict
To get additional information on the methods returned, you can pass a method name to describe:
$ grpcurl -v prefetch.net:443 describe build.stack.fortune.FortuneTeller.Predict
build.stack.fortune.FortuneTeller.Predict is a method:
rpc Predict ( .build.stack.fortune.PredictionRequest ) returns ( .build.stack.fortune.PredictionResponse );
This will describe the type of the symbol, and print the request and response types. The describe option can also be used to print additional detail about the request and response objects:
$ grpcurl -v prefetch.net:443 describe .build.stack.fortune.PredictionResponse
build.stack.fortune.PredictionResponse is a message:
message PredictionResponse {
string message = 1;
}
In the output above, we can see that the server returns a message with a string. To invoke a gRPC method, you can pass the method as an argument:
$ grpcurl -v prefetch.net:443 build.stack.fortune.FortuneTeller.Predict
Resolved method descriptor:
rpc Predict ( .build.stack.fortune.PredictionRequest ) returns ( .build.stack.fortune.PredictionResponse );
Request metadata to send:
(empty)
Response headers received:
access-control-allow-credentials: true
content-type: application/grpc
date: Mon, 20 Apr 2020 15:24:34 GMT
server: nginx
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
Response contents:
{
"message": "Life is a POPULARITY CONTEST! I'm REFRESHINGLY CANDID!!"
}
Response trailers received:
(empty)
Sent 0 requests and received 1 response
With the verbose flag, you can dump the response headers and response payload as a JSON object. This is a super cool utility, and super, super helpful when exploring and debugging gRPC code.