gRPC Reflection — Complete Guide

In this tutorial, you will learn about grpc Reflection. We cover key concepts, practical examples, and best practices to help you master this topic.

gRPC server reflection allows clients to discover service definitions, method signatures, and message types at runtime without access to the .proto file. This enables CLI tools, debugging proxies, and dynamic clients.

What You'll Learn

• Server reflection protocol
• Enabling reflection on gRPC servers
• Using grpcurl for ad-hoc RPC calls
• Building dynamic gRPC clients
• Security considerations for reflection

Why It Matters

Reflection eliminates the need to distribute .proto files with every client. Tools like grpcurl provide curl-like debugging. Administrative tools can introspect running services dynamically.

Real-World Use

gRPC health checking and reflection are standard on Google Cloud services. Envoy proxy uses reflection for dynamic service discovery. grpcurl is the standard debugging tool for gRPC services.

flowchart LR
    Tool[grpcurl / Custom Client] -->|Reflection Request| Server[gRPC Server]
    Server -->|Service List| Tool
    Tool -->|Describe Service| Server
    Server -->|Full Service Definition| Tool
    Tool -->|Invoke RPC| Server
    Server -->|Response| Tool

Teacher Mindset

Reflection turns a gRPC server into a self-describing API. Enable it in development and staging environments. Be cautious in production as it exposes your full schema.

Code Examples

// Example 1: Enabling reflection on a server
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const { ReflectionService } = require('@grpc/reflection');

const server = new grpc.Server();
server.addService(OrderService, implementation);

// Enable reflection
const reflection = new ReflectionService(packageDefinition);
reflection.addToServer(server);

server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => {
  server.start();
});

# Example 2: Using grpcurl for reflection
# List all services
grpcurl -plaintext localhost:50051 list

# Describe a service
grpcurl -plaintext localhost:50051 describe ecommerce.OrderService

# Describe a message type
grpcurl -plaintext localhost:50051 describe ecommerce.GetOrderRequest

# Invoke an RPC
grpcurl -plaintext -d '{"order_id": "123"}' \
  localhost:50051 ecommerce.OrderService/GetOrder

// Example 3: Go server with reflection
import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/reflection"
)

func main() {
    server := grpc.NewServer()
    pb.RegisterOrderServiceServer(server, &orderServer{})

    // Enable reflection
    reflection.Register(server)

    lis, _ := net.Listen("tcp", ":50051")
    server.Serve(lis)
}

Common Mistakes

• Enabling reflection in production without access control
• Forgetting that reflection exposes internal message types
• Assuming all gRPC servers support reflection by default
• Using reflection for performance-critical runtime decisions
• Not updating proto files when reflection is the only documentation

Practice

1. Enable reflection on your order service server.
2. Use grpcurl to list all available services.
3. Describe a service method using reflection.
4. Invoke an RPC method using grpcurl.
5. Challenge: Build a simple web UI that uses reflection to list and invoke gRPC methods.

FAQ

Mini Project

Add reflection to your order service. Use grpcurl to explore the service definition, message types, and invoke a unary RPC. Write a short script that uses reflection to generate an HTML documentation page for your service.

What's Next

Next, you will learn about gRPC-Web for calling gRPC services from browser applications.