google.golang.org/grpc@v1.72.2/Documentation/server-reflection-tutorial.md (about)

     1  # gRPC Server Reflection Tutorial
     2  
     3  gRPC Server Reflection provides information about publicly-accessible gRPC
     4  services on a server, and assists clients at runtime to construct RPC requests
     5  and responses without precompiled service information. It is used by
     6  [gRPCurl](https://github.com/fullstorydev/grpcurl), which can be used to
     7  introspect server protos and send/receive test RPCs.
     8  
     9  ## Enable Server Reflection
    10  
    11  gRPC-go Server Reflection is implemented in package
    12  [reflection](https://github.com/grpc/grpc-go/tree/master/reflection). To enable
    13  server reflection, you need to import this package and register reflection
    14  service on your gRPC server.
    15  
    16  For example, to enable server reflection in `example/helloworld`, we need to
    17  make the following changes:
    18  
    19  ```diff
    20  --- a/examples/helloworld/greeter_server/main.go
    21  +++ b/examples/helloworld/greeter_server/main.go
    22  @@ -40,6 +40,7 @@ import (
    23          "google.golang.org/grpc"
    24          pb "google.golang.org/grpc/examples/helloworld/helloworld"
    25  +       "google.golang.org/grpc/reflection"
    26   )
    27  
    28   const (
    29  @@ -61,6 +62,8 @@ func main() {
    30          }
    31          s := grpc.NewServer()
    32          pb.RegisterGreeterService(s, &pb.GreeterService{SayHello: sayHello})
    33  +       // Register reflection service on gRPC server.
    34  +       reflection.Register(s)
    35          if err := s.Serve(lis); err != nil {
    36                  log.Fatalf("failed to serve: %v", err)
    37          }
    38  ```
    39  
    40  An example server with reflection registered can be found at
    41  `examples/features/reflection/server`.
    42  
    43  ## gRPCurl
    44  
    45  After enabling Server Reflection in a server application, you can use gRPCurl
    46  to check its services. gRPCurl is built with Go and has packages available.
    47  Instructions on how to install and use gRPCurl can be found at
    48  [gRPCurl Installation](https://github.com/fullstorydev/grpcurl#installation).
    49  
    50  ## Use gRPCurl to check services
    51  
    52  First, start the helloworld server in grpc-go directory:
    53  
    54  ```sh
    55  $ cd <grpc-go-directory>/examples
    56  $ go run features/reflection/server/main.go
    57  ```
    58  
    59  output:
    60  ```sh
    61  server listening at [::]:50051
    62  ```
    63  
    64  After installing gRPCurl, open a new terminal and run the commands from the new
    65  terminal.
    66  
    67  **NOTE:** gRPCurl expects a TLS-encrypted connection by default. For all of
    68  the commands below, use the `-plaintext` flag to use an unencrypted connection.
    69  
    70  ### List services and methods
    71  
    72  The `list` command lists services exposed at a given port:
    73  
    74  - List all the services exposed at a given port
    75  
    76    ```sh
    77    $ grpcurl -plaintext localhost:50051 list
    78    ```
    79  
    80    output:
    81    ```sh
    82    grpc.examples.echo.Echo
    83    grpc.reflection.v1alpha.ServerReflection
    84    helloworld.Greeter
    85    ```
    86  
    87  - List all the methods of a service
    88  
    89    The `list` command lists methods given the full service name (in the format of
    90    \<package\>.\<service\>).
    91  
    92    ```sh
    93    $ grpcurl -plaintext localhost:50051 list helloworld.Greeter
    94    ```
    95  
    96    output:
    97    ```sh
    98    helloworld.Greeter.SayHello
    99    ```
   100  
   101  ### Describe services and methods
   102  
   103  - Describe all services
   104  
   105    The `describe` command inspects a service given its full name (in the format
   106    of \<package\>.\<service\>).
   107  
   108    ```sh
   109    $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter
   110    ```
   111  
   112    output:
   113    ```sh
   114    helloworld.Greeter is a service:
   115    service Greeter {
   116      rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
   117    }
   118    ```
   119  
   120  - Describe all methods of a service
   121  
   122    The `describe` command inspects a method given its full name (in the format of
   123    \<package\>.\<service\>.\<method\>).
   124  
   125    ```sh
   126    $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter.SayHello
   127    ```
   128  
   129    output:
   130    ```sh
   131    helloworld.Greeter.SayHello is a method:
   132    rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
   133    ```
   134  
   135  ### Inspect message types
   136  
   137  We can use the `describe` command to inspect request/response types given the
   138  full name of the type (in the format of \<package\>.\<type\>).
   139  
   140  - Get information about the request type
   141  
   142    ```sh
   143    $ grpcurl -plaintext localhost:50051 describe helloworld.HelloRequest
   144    ```
   145  
   146    output:
   147    ```sh
   148    helloworld.HelloRequest is a message:
   149    message HelloRequest {
   150      string name = 1;
   151    }
   152    ```
   153  
   154  ### Call a remote method
   155  
   156  We can send RPCs to a server and get responses using the full method name (in
   157  the format of \<package\>.\<service\>.\<method\>). The `-d <string>` flag
   158  represents the request data and the `-format text` flag indicates that the
   159  request data is in text format.
   160  
   161  - Call a unary method
   162  
   163    ```sh
   164    $ grpcurl -plaintext -format text -d 'name: "gRPCurl"' \
   165      localhost:50051 helloworld.Greeter.SayHello
   166    ```
   167  
   168    output:
   169    ```sh
   170    message: "Hello gRPCurl"
   171    ```