Reflection

Overview

Reflection is a protocol 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 and Postman. 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:

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.