mirror of https://github.com/grpc/grpc.io.git
82 lines
3.7 KiB
Markdown
82 lines
3.7 KiB
Markdown
---
|
|
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] |
|
|
| Javascript | [Javascript 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
|
|
|
|
[Javascript example]: https://github.com/grpc/grpc-node/blob/master/examples/reflection/server.js
|
|
|
|
### 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.
|