From 8eaa1840af464b1074e8ffbd7190b33553a19393 Mon Sep 17 00:00:00 2001 From: Yuchen Zeng Date: Mon, 12 Sep 2016 19:19:26 -0700 Subject: [PATCH 1/6] Add server reflection tutorial --- doc/server_reflection_tutorial.md | 190 ++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 doc/server_reflection_tutorial.md diff --git a/doc/server_reflection_tutorial.md b/doc/server_reflection_tutorial.md new file mode 100644 index 00000000000..11e079a71d6 --- /dev/null +++ b/doc/server_reflection_tutorial.md @@ -0,0 +1,190 @@ +# gRPC Server Reflection Tutorial + +gRPC Server Reflection provides information about publicly-accessible gRPC +services on a server, and assists clients in runtime to construct RPC +requests/responses without precompiled service information. It has been +supported by gRPC CLI, which could be used to introspect server protos and +send/receive test RPCs. + +## Eanble Server Reflection + +### Enable server reflection in C++ servers + +C++ Server Reflection is offered as an add-on library, `libgrpc++_reflction`. +To enable C++ server reflection, you can simply link this library to your server +binary. + +Some platforms (e.g. Ubuntu 11.10 onwards) only link in libraries that directly +contain symbols used by the application. On these platforms, LD flag +`--no-as-needed` is needed for for dynamic linking and `--whole-archive` is +needed for for static linking. + +Here is an [example](examples/cpp/helloworld/Makefile#L37#L45) for enabling c++ +server reflection on Linux and MacOS. + +## Test services using Server Reflection + +gRPC Server Reflection has been supported by gRPC CLI. After enabling Server +Reflection in a server application, you can use gRPC CLI to test its services. + +Instructions on how to use gRPC CLI can be found at +[command_line_tool.md](doc/command_line_tool.md), or using `grpc_cli help` +command. + +Here we use `examples/cpp/helloworld` as an example to show the use of gRPC +Server Reflection and gRPC CLI. First, we need to build gRPC CLI and setup an +example server with Server Reflection enabled. + +- Setup an example server + + Server Reflection has already been enabled in the + [Makefile](examples/cpp/helloworld/Makefile) of the helloworld example. We can + simply make it and run the greeter_server. + + ```sh + $ make -C examples/cpp/helloworld + $ examples/cpp/helloworld/greeter_server & + ``` + +- Build gRPC CLI + + ```sh + make grpc_cli + ``` + +### List services + +`grpc_cli ls` command can list services and methods exposed at a given port + +- List all the services exposed at a given port + + ```sh + $ bins/opt/grpc_cli ls localhost:50051 + ``` + + output: + ```sh + helloworld.Greeter + grpc.reflection.v1alpha.ServerReflection + ``` + +- List one service with details + + `grpc_cli ls` command can inspect one service given its full name (in the + format of \.\). It can print information with a long + listing format when `-l` flag is set. This flag can be used to get more + details about a service. + + ```sh + $ bins/opt/grpc_cli ls localhost:50051 helloworld.Greeter -l + ``` + + output: + ```sh + filename: helloworld.proto + package: helloworld; + service Greeter { + rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {} + } + + ``` + +### List methods + +- List one method with details + + `grpc_cli ls` command can also inspect one method given its full name (in the + format of \.\.\). + + ```sh + $ bins/opt/grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l + ``` + + output: + ```sh + rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {} + ``` + +### Inspect message types + +We can use`grpc_cli type` command to inspect request/response types given the +full name of the type (in the format of \.\). + +- Get information about the request type + + ```sh + $ bins/opt/grpc_cli type localhost:50051 helloworld.HelloRequest + ``` + + output: + ```sh + message HelloRequest { + optional string name = 1; + } + ``` + +### Call a remote method + +We can send RPCs to a server and get responses using `grpc_cli call` command. + +- Call a unary method + + ```sh + $ bins/opt/grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'" + ``` + + output: + ```sh + message: "Hello gRPC CLI" + ``` + +## Use Server Reflection in a C++ client + +Server Reflection can be used by clients to get information about gRPC services +in runtime. We've provided a descriptor database called +[grpc::ProtoReflectionDescriptorDatabase](test/cpp/util/proto_reflection_descriptor_database.h) +which implements the +[google::protobuf::DescriptorDatabase](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.descriptor_database#DescriptorDatabase) +interface. It manages the communication between clients and reflection services +and the storage of received information. Clients can use it as using a local +descriptor database. + +- To use Server Reflection with grpc::ProtoReflectionDescriptorDatabase, first + initialize an instance with a grpc::Channel. + + ```c++ + std::shared_ptr channel = + grpc::CreateChannel(server_address, server_cred); + grpc::ProtoReflectionDescriptorDatabase reflection_db(channel); + ``` + +- Then use this instance to feed a + [google::protobuf::DescriptorPool](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.descriptor#DescriptorPool). + + ```c++ + google::protobuf::DescriptorPool desc_pool(&reflection_db); + ``` + +- Example usage of this descriptor pool + + * Get Service/method descriptors. + + ```c++ + const google::protobuf::ServiceDescriptor* service_desc = + desc_pool->FindServiceByName("helloworld.Greeter"); + const google::protobuf::MethodDescriptor* method_desc = + desc_pool->FindMethodByName("helloworld.Greeter.SayHello"); + ``` + + * Get message type descriptors. + + ```c++ + const google::protobuf::Descriptor* request_desc = + desc_pool->FindMessageTypeByName("helloworld.HelloRequest"); + ``` + + * Feed [google::protobuf::DynamicMessageFactory](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.dynamic_message#DynamicMessageFactory). + + ```c++ + google::protobuf::DynamicMessageFactory(&desc_pool); + ``` From c6e90761230f6f68df35e0265a799e3e8cdbb0b7 Mon Sep 17 00:00:00 2001 From: Yuchen Zeng Date: Tue, 13 Sep 2016 11:09:05 -0700 Subject: [PATCH 2/6] Address review comments --- doc/server_reflection_tutorial.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/doc/server_reflection_tutorial.md b/doc/server_reflection_tutorial.md index 11e079a71d6..7ab8eeab358 100644 --- a/doc/server_reflection_tutorial.md +++ b/doc/server_reflection_tutorial.md @@ -2,29 +2,28 @@ gRPC Server Reflection provides information about publicly-accessible gRPC services on a server, and assists clients in runtime to construct RPC -requests/responses without precompiled service information. It has been -supported by gRPC CLI, which could be used to introspect server protos and +requests and responses without precompiled service information. It has been +supported by gRPC CLI, which can be used to introspect server protos and send/receive test RPCs. -## Eanble Server Reflection +## Enable Server Reflection ### Enable server reflection in C++ servers -C++ Server Reflection is offered as an add-on library, `libgrpc++_reflction`. -To enable C++ server reflection, you can simply link this library to your server -binary. +C++ Server Reflection is an add-on library, `libgrpc++_reflction`. To enable C++ +server reflection, you can link this library to your server binary. Some platforms (e.g. Ubuntu 11.10 onwards) only link in libraries that directly contain symbols used by the application. On these platforms, LD flag `--no-as-needed` is needed for for dynamic linking and `--whole-archive` is needed for for static linking. -Here is an [example](examples/cpp/helloworld/Makefile#L37#L45) for enabling c++ -server reflection on Linux and MacOS. +This [Makefile](examples/cpp/helloworld/Makefile#L37#L45) demonstrates enabling +c++ server reflection on Linux and MacOS. ## Test services using Server Reflection -gRPC Server Reflection has been supported by gRPC CLI. After enabling Server +gRPC Server Reflection is supported by gRPC CLI. After enabling Server Reflection in a server application, you can use gRPC CLI to test its services. Instructions on how to use gRPC CLI can be found at @@ -54,7 +53,7 @@ example server with Server Reflection enabled. ### List services -`grpc_cli ls` command can list services and methods exposed at a given port +`grpc_cli ls` command lists services and methods exposed at a given port - List all the services exposed at a given port @@ -70,10 +69,10 @@ example server with Server Reflection enabled. - List one service with details - `grpc_cli ls` command can inspect one service given its full name (in the - format of \.\). It can print information with a long - listing format when `-l` flag is set. This flag can be used to get more - details about a service. + `grpc_cli ls` command inspects a service given its full name (in the format of + \.\). It can print information with a long listing format + when `-l` flag is set. This flag can be used to get more details about a + service. ```sh $ bins/opt/grpc_cli ls localhost:50051 helloworld.Greeter -l @@ -93,7 +92,7 @@ example server with Server Reflection enabled. - List one method with details - `grpc_cli ls` command can also inspect one method given its full name (in the + `grpc_cli ls` command also inspects a method given its full name (in the format of \.\.\). ```sh @@ -141,7 +140,7 @@ We can send RPCs to a server and get responses using `grpc_cli call` command. ## Use Server Reflection in a C++ client Server Reflection can be used by clients to get information about gRPC services -in runtime. We've provided a descriptor database called +at runtime. We've provided a descriptor database called [grpc::ProtoReflectionDescriptorDatabase](test/cpp/util/proto_reflection_descriptor_database.h) which implements the [google::protobuf::DescriptorDatabase](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.descriptor_database#DescriptorDatabase) From a8f2621d78e27b5d1cc6b0c462d2d1e22ab7704c Mon Sep 17 00:00:00 2001 From: Yuchen Zeng Date: Tue, 13 Sep 2016 11:14:28 -0700 Subject: [PATCH 3/6] Fix dead links --- doc/server_reflection_tutorial.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/doc/server_reflection_tutorial.md b/doc/server_reflection_tutorial.md index 7ab8eeab358..ae00ffbc293 100644 --- a/doc/server_reflection_tutorial.md +++ b/doc/server_reflection_tutorial.md @@ -18,8 +18,8 @@ contain symbols used by the application. On these platforms, LD flag `--no-as-needed` is needed for for dynamic linking and `--whole-archive` is needed for for static linking. -This [Makefile](examples/cpp/helloworld/Makefile#L37#L45) demonstrates enabling -c++ server reflection on Linux and MacOS. +This [Makefile](../examples/cpp/helloworld/Makefile#L37#L45) demonstrates +enabling c++ server reflection on Linux and MacOS. ## Test services using Server Reflection @@ -27,8 +27,7 @@ gRPC Server Reflection is supported by gRPC CLI. After enabling Server Reflection in a server application, you can use gRPC CLI to test its services. Instructions on how to use gRPC CLI can be found at -[command_line_tool.md](doc/command_line_tool.md), or using `grpc_cli help` -command. +[command_line_tool.md](command_line_tool.md), or using `grpc_cli help` command. Here we use `examples/cpp/helloworld` as an example to show the use of gRPC Server Reflection and gRPC CLI. First, we need to build gRPC CLI and setup an @@ -37,8 +36,8 @@ example server with Server Reflection enabled. - Setup an example server Server Reflection has already been enabled in the - [Makefile](examples/cpp/helloworld/Makefile) of the helloworld example. We can - simply make it and run the greeter_server. + [Makefile](../examples/cpp/helloworld/Makefile) of the helloworld example. We + can simply make it and run the greeter_server. ```sh $ make -C examples/cpp/helloworld @@ -141,7 +140,7 @@ We can send RPCs to a server and get responses using `grpc_cli call` command. Server Reflection can be used by clients to get information about gRPC services at runtime. We've provided a descriptor database called -[grpc::ProtoReflectionDescriptorDatabase](test/cpp/util/proto_reflection_descriptor_database.h) +[grpc::ProtoReflectionDescriptorDatabase](../test/cpp/util/proto_reflection_descriptor_database.h) which implements the [google::protobuf::DescriptorDatabase](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.descriptor_database#DescriptorDatabase) interface. It manages the communication between clients and reflection services From dcc16b40fb618b410074f033c0a3aca8d18953e6 Mon Sep 17 00:00:00 2001 From: Yuchen Zeng Date: Tue, 13 Sep 2016 11:16:16 -0700 Subject: [PATCH 4/6] Address review comments --- doc/server_reflection_tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/server_reflection_tutorial.md b/doc/server_reflection_tutorial.md index ae00ffbc293..5417ae0bd50 100644 --- a/doc/server_reflection_tutorial.md +++ b/doc/server_reflection_tutorial.md @@ -1,7 +1,7 @@ # gRPC Server Reflection Tutorial gRPC Server Reflection provides information about publicly-accessible gRPC -services on a server, and assists clients in runtime to construct RPC +services on a server, and assists clients at runtime to construct RPC requests and responses without precompiled service information. It has been supported by gRPC CLI, which can be used to introspect server protos and send/receive test RPCs. From 3bf43dd311561670414ee7e1d7167c893a384d1a Mon Sep 17 00:00:00 2001 From: Yuchen Zeng Date: Tue, 13 Sep 2016 11:41:49 -0700 Subject: [PATCH 5/6] Address review comments --- doc/server_reflection_tutorial.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/server_reflection_tutorial.md b/doc/server_reflection_tutorial.md index 5417ae0bd50..2b8f5ea8f63 100644 --- a/doc/server_reflection_tutorial.md +++ b/doc/server_reflection_tutorial.md @@ -2,9 +2,9 @@ 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 has been -supported by gRPC CLI, which can be used to introspect server protos and -send/receive test RPCs. +requests and responses without precompiled service information. It is used by +gRPC CLI, which can be used to introspect server protos and send/receive test +RPCs. ## Enable Server Reflection @@ -23,8 +23,8 @@ enabling c++ server reflection on Linux and MacOS. ## Test services using Server Reflection -gRPC Server Reflection is supported by gRPC CLI. After enabling Server -Reflection in a server application, you can use gRPC CLI to test its services. +After enabling Server Reflection in a server application, you can use gRPC CLI +to test its services. Instructions on how to use gRPC CLI can be found at [command_line_tool.md](command_line_tool.md), or using `grpc_cli help` command. From 82f308303428f932d35710c8fac2c6eeb1a59143 Mon Sep 17 00:00:00 2001 From: Yuchen Zeng Date: Tue, 13 Sep 2016 14:24:25 -0700 Subject: [PATCH 6/6] Address review comments --- doc/server_reflection_tutorial.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/doc/server_reflection_tutorial.md b/doc/server_reflection_tutorial.md index 2b8f5ea8f63..ecb176723cc 100644 --- a/doc/server_reflection_tutorial.md +++ b/doc/server_reflection_tutorial.md @@ -48,8 +48,12 @@ example server with Server Reflection enabled. ```sh make grpc_cli + cd bins/opt ``` + gRPC CLI binary `grpc_cli` can be found at `bins/opt/` folder. This tool is + still new and does not have a `make install` target yet. + ### List services `grpc_cli ls` command lists services and methods exposed at a given port @@ -57,7 +61,7 @@ example server with Server Reflection enabled. - List all the services exposed at a given port ```sh - $ bins/opt/grpc_cli ls localhost:50051 + $ grpc_cli ls localhost:50051 ``` output: @@ -74,7 +78,7 @@ example server with Server Reflection enabled. service. ```sh - $ bins/opt/grpc_cli ls localhost:50051 helloworld.Greeter -l + $ grpc_cli ls localhost:50051 helloworld.Greeter -l ``` output: @@ -95,7 +99,7 @@ example server with Server Reflection enabled. format of \.\.\). ```sh - $ bins/opt/grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l + $ grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l ``` output: @@ -111,7 +115,7 @@ full name of the type (in the format of \.\). - Get information about the request type ```sh - $ bins/opt/grpc_cli type localhost:50051 helloworld.HelloRequest + $ grpc_cli type localhost:50051 helloworld.HelloRequest ``` output: @@ -128,7 +132,7 @@ We can send RPCs to a server and get responses using `grpc_cli call` command. - Call a unary method ```sh - $ bins/opt/grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'" + $ grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'" ``` output: