server-reflection-tutorial.md

gRPC Server Reflection Tutorial

gRPC Server Reflection provides information about publicly-accessible gRPC services on a server, and assists clients at runtime to construct RPC requests and responses without precompiled service information. It is used by gRPCurl, which can be used to introspect server protos and send/receive test RPCs.

Enable Server Reflection

gRPC-go Server Reflection is implemented in package reflection. To enable server reflection, you need to import this package and register reflection service on your gRPC server.

For example, to enable server reflection in example/helloworld, we need to make the following changes:

--- a/examples/helloworld/greeter_server/main.go
+++ b/examples/helloworld/greeter_server/main.go
@@ -40,6 +40,7 @@ import (
        "google.golang.org/grpc"
        pb "google.golang.org/grpc/examples/helloworld/helloworld"
+       "google.golang.org/grpc/reflection"
 )

 const (
@@ -61,6 +62,8 @@ func main() {
        }
        s := grpc.NewServer()
        pb.RegisterGreeterService(s, &pb.GreeterService{SayHello: sayHello})
+       // Register reflection service on gRPC server.
+       reflection.Register(s)
        if err := s.Serve(lis); err != nil {
                log.Fatalf("failed to serve: %v", err)
        }

An example server with reflection registered can be found at examples/features/reflection/server.

gRPCurl

After enabling Server Reflection in a server application, you can use gRPCurl to check its services. gRPCurl is built with Go and has packages available. Instructions on how to install and use gRPCurl can be found at gRPCurl Installation.

Use gRPCurl to check services

First, start the helloworld server in grpc-go directory:

$ cd <grpc-go-directory>/examples
$ go run features/reflection/server/main.go

output:

server listening at [::]:50051

After installing gRPCurl, open a new terminal and run the commands from the new terminal.

NOTE: gRPCurl expects a TLS-encrypted connection by default. For all of the commands below, use the -plaintext flag to use an unencrypted connection.

List services and methods

The list command lists services exposed at a given port:

• List all the services exposed at a given port

  $ grpcurl -plaintext localhost:50051 list

  output:

  grpc.examples.echo.Echo
  grpc.reflection.v1alpha.ServerReflection
  helloworld.Greeter

• List all the methods of a service

  The list command lists methods given the full service name (in the format of <package>.<service>).

  $ grpcurl -plaintext localhost:50051 list helloworld.Greeter

  output:

  helloworld.Greeter.SayHello

Describe services and methods

• Describe all services

  The describe command inspects a service given its full name (in the format of <package>.<service>).

  $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter

  output:

  helloworld.Greeter is a service:
  service Greeter {
    rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
  }

• Describe all methods of a service

  The describe command inspects a method given its full name (in the format of <package>.<service>.<method>).

  $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter.SayHello

  output:

  helloworld.Greeter.SayHello is a method:
  rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );

Inspect message types

We can use the describe command to inspect request/response types given the full name of the type (in the format of <package>.<type>).

• Get information about the request type

  $ grpcurl -plaintext localhost:50051 describe helloworld.HelloRequest

  output:

  helloworld.HelloRequest is a message:
  message HelloRequest {
    string name = 1;
  }

Call a remote method

We can send RPCs to a server and get responses using the full method name (in the format of <package>.<service>.<method>). The -d <string> flag represents the request data and the -format text flag indicates that the request data is in text format.

• Call a unary method

  $ grpcurl -plaintext -format text -d 'name: "gRPCurl"' \
    localhost:50051 helloworld.Greeter.SayHello

  output:

  message: "Hello gRPCurl"