Skip to content

Commit e08034c

Browse files
ericgribkoffericgribkoff
authored
documentation: new server reflection tutorial
1 parent 0c0ce37 commit e08034c

1 file changed

Lines changed: 165 additions & 0 deletions

File tree

‎documentation/server-reflection-tutorial.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
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 with constructing RPC
5+
requests and responses without precompiled service information. It is used by
6+
the gRPC command line tool (gRPC CLI), which can be used to introspect server
7+
protos and send/receive test RPCs. Reflection is only supported for
8+
proto-based services.
9+
10+
## Enable Server Reflection
11+
12+
gRPC-Java Server Reflection is implemented by
13+
`io.grpc.protobuf.service.ProtoReflectionService` in the `grpc-services`
14+
package. To enable server reflection, you need to add the
15+
`ProtoReflectionService` to your gRPC server.
16+
17+
For example, to enable server reflection in
18+
`examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java`, we
19+
need to make the following changes:
20+
21+
```diff
22+
--- a/examples/build.gradle
23+
+++ b/examples/build.gradle
24+
@@ -27,6 +27,7 @@ def grpcVersion = '1.1.0-SNAPSHOT' // CURRENT_GRPC_VERSION
25+
dependencies {
26+
compile "io.grpc:grpc-netty:${grpcVersion}"
27+
compile "io.grpc:grpc-protobuf:${grpcVersion}"
28+
+ compile "io.grpc:grpc-services:${grpcVersion}"
29+
compile "io.grpc:grpc-stub:${grpcVersion}"
30+
31+
testCompile "junit:junit:4.11"
32+
diff --git a/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java b/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java
33+
index ce1158a4..788bcc62 100644
34+
--- a/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java
35+
+++ b/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java
36+
@@ -33,6 +33,7 @@ package io.grpc.examples.helloworld;
37+
38+
import io.grpc.Server;
39+
import io.grpc.ServerBuilder;
40+
+import io.grpc.protobuf.service.ProtoReflectionService;
41+
import io.grpc.stub.StreamObserver;
42+
43+
import java.io.IOException;
44+
@@ -51,6 +52,7 @@ public class HelloWorldServer {
45+
int port = 50051;
46+
server = ServerBuilder.forPort(port)
47+
.addService(new GreeterImpl())
48+
+ .addService(ProtoReflectionService.getInstance())
49+
.build()
50+
.start();
51+
logger.info("Server started, listening on " + port);
52+
```
53+
54+
In the following examples, we assume you have made these changes to
55+
enable reflection in `HelloWorldServer.java`.
56+
57+
## gRPC CLI
58+
59+
After enabling server reflection in a server application, you can use gRPC
60+
CLI to get information about its available services. gRPC CLI is written
61+
in C++. Instructions on how to build gRPC CLI can be found at
62+
[command_line_tool.md](https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md).
63+
64+
## Use gRPC CLI to check services
65+
66+
First, build and start the `hello-world-server`:
67+
68+
```sh
69+
$ cd examples/
70+
$ ./gradlew installDist
71+
$ build/install/examples/bin/hello-world-server
72+
```
73+
74+
Open a new terminal and make sure you are in the directory where the `grpc_cli`
75+
binary is located:
76+
77+
```sh
78+
$ cd <grpc-cpp-directory>/bins/opt
79+
```
80+
81+
### List services
82+
83+
`grpc_cli ls` command lists services and methods exposed at a given port:
84+
85+
- List all the services exposed at a given port
86+
87+
```sh
88+
$ ./grpc_cli ls localhost:50051
89+
```
90+
91+
output:
92+
```sh
93+
helloworld.Greeter
94+
grpc.reflection.v1alpha.ServerReflection
95+
```
96+
97+
- List one service with details
98+
99+
`grpc_cli ls` command inspects a service given its full name (in the format of
100+
\<package\>.\<service\>). It can print information with a long listing format
101+
when `-l` flag is set. This flag can be used to get more details about a
102+
service.
103+
104+
```sh
105+
$ ./grpc_cli ls localhost:50051 helloworld.Greeter -l
106+
```
107+
108+
output:
109+
```sh
110+
filename: helloworld.proto
111+
package: helloworld;
112+
service Greeter {
113+
rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
114+
}
115+
116+
```
117+
118+
### List methods
119+
120+
- List one method with details
121+
122+
`grpc_cli ls` command also inspects a method given its full name (in the
123+
format of \<package\>.\<service\>.\<method\>).
124+
125+
```sh
126+
$ ./grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l
127+
```
128+
129+
output:
130+
```sh
131+
rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
132+
```
133+
134+
### Inspect message types
135+
136+
We can use`grpc_cli type` command to inspect request/response types given the
137+
full name of the type (in the format of \<package\>.\<type\>).
138+
139+
- Get information about the request type
140+
141+
```sh
142+
$ ./grpc_cli type localhost:50051 helloworld.HelloRequest
143+
```
144+
145+
output:
146+
```sh
147+
message HelloRequest {
148+
optional string name = 1[json_name = "name"];
149+
}
150+
```
151+
152+
### Call a remote method
153+
154+
We can send RPCs to a server and get responses using `grpc_cli call` command.
155+
156+
- Call a unary method
157+
158+
```sh
159+
$ ./grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'"
160+
```
161+
162+
output:
163+
```sh
164+
message: "Hello gRPC CLI"
165+
```

0 commit comments

Comments
 (0)