What Is gRPC Reflection? Explained

gRPC reflection is a protocol that lets a gRPC server describe its own services at runtime, so clients and tools can discover and call methods without the .proto file.

Because gRPC uses a binary protobuf format, you normally need the .proto schema to talk to a server. gRPC reflection removes that requirement at runtime: the server can hand out its own service definitions on request. This makes interactive debugging and CI smoke tests of gRPC services far easier, the way curl makes REST easy to poke.

What gRPC reflection is

gRPC reflection is a standard service that a gRPC server can enable to expose metadata about the services and methods it offers. A client queries this reflection service to learn the available methods and message shapes, then constructs calls dynamically - no local schema needed.

Why it is useful

Without reflection, every tool that calls a gRPC server needs the matching .proto files compiled in. Reflection lets generic tools like grpcurl list methods and invoke them on the fly, which is exactly what you want for exploratory testing and quick health checks.

The security tradeoff

Reflection advertises your services to anyone who can reach the server. That is great in development but is often disabled in production to avoid revealing the API surface. A common pattern is reflection on in dev and CI environments, off in production.

gRPC reflection in CI

In a pipeline you can spin up the gRPC service as a service container and use a reflection-aware tool to call a method as a smoke test - confirming the server is up and responding correctly - without compiling protobufs into the test job at all.

gRPC smoke test using reflection

# Smoke-test a gRPC service via reflection in CI
steps:
  - run: grpcurl -plaintext localhost:50051 list
  - run: grpcurl -plaintext -d '{"id":1}' localhost:50051 my.Service/Get

Latchkey note

Service containers and tools like grpcurl run on Latchkey runners exactly as on GitHub-hosted ones, so reflection-based gRPC smoke tests work without any special configuration.

Key takeaways

gRPC reflection lets a server describe its own services at runtime so clients need no local .proto.
It powers generic tools like grpcurl for interactive calls and CI smoke tests.
Reflection exposes the API surface, so it is usually enabled in dev and CI but disabled in production.