diff --git a/content/en/docs/guides/reflection.md b/content/en/docs/guides/reflection.md new file mode 100644 index 0000000..4a85db1 --- /dev/null +++ b/content/en/docs/guides/reflection.md @@ -0,0 +1,78 @@ +--- +title: Reflection +description: >- + Explains how reflection can be used to improve the transparency and + interpretability of RPCs. +--- + +### Overview + +Reflection is [a +protocol](https://github.com/grpc/grpc-proto/blob/master/grpc/reflection/v1/reflection.proto) +that gRPC servers can use to declare the protobuf-defined APIs they export over +a standardized RPC service, including all types referenced by the request and +response messages. Clients can then use this information to encode requests and +decode responses in human-readable manner. + +Reflection is used heavily by debugging tools such as +[`grpcurl`](https://github.com/fullstorydev/grpcurl) and +[Postman](https://learning.postman.com/docs/sending-requests/grpc/grpc-client-overview/). +One coming from the REST world might compare the gRPC reflection API to serving +an OpenAPI document on the HTTP server presenting the REST API being described. + +### Transparency and Interpretability + +A big contributor to gRPC's stellar performance is the use of Protobuf for +serialization -- a _binary_ non-human-readable protocol. While this greatly +speeds up an RPC, it can also make it more difficult to manually interact with a +server. Hypothetically, in order to manually send a gRPC request to a server +over HTTP/2 using `curl`, you would have to: + +1. Know which RPC services the server exposed. +2. Know the protobuf definition of the request message and all types it +references. +3. Know the protobuf definition of the response message all the types _it_ +references. + +Then, you'd have to use that knowledge to hand-craft your request message(s) into +binary and painstakingly decode the response message(s). This would be time +consuming, frustrating, and error prone. Instead, the reflection protocol +enables tools to automate this whole process, making it invisible. + +### Enabling Reflection on a gRPC Server + +Reflection is _not_ automatically enabled on a gRPC server. The server author +must call a few additional functions to add a reflection service. These API calls +differ slightly from language to language and, in some languages, require adding +a dependency on a separate package, named something like `grpc-reflection` + +Follow these links below for details on your specific language: + +| Language | Guide | +|----------|------------------| +| Java | [Java example] | +| Go | [Go example] | +| C++ | [C++ example] | +| Python | [Python example] | + +[Java example]: https://github.com/grpc/grpc-java/tree/master/examples/example-reflection + +[Go example]: https://github.com/grpc/grpc-go/tree/master/examples/features/reflection + +[C++ example]: https://github.com/grpc/grpc/tree/master/examples/cpp/reflection + +[Python example]: https://github.com/grpc/grpc/blob/master/examples/python/helloworld/greeter_server_with_reflection.py + +### Tips + +Reflection works so seamlessly with tools such as `grpcurl` that oftentimes, +people aren't even aware that it's happening under the hood. However, if +reflection isn't exposed, things won't work seamlessly at all. Instead, the +client will fail with nasty errors. People often run into this when writing the +routing configuration for a gRPC service. The _reflection_ service must be +routed to the appropriate backend as well as the application's main RPC service. + +If your gRPC API is accessible to public users, you may _not_ want to expose the +reflection service, as you may consider this a security issue. Ultimately, you +will need to make a call here that strikes the best balance between security and +ease-of-use for you and your users.