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 reflection allows clients to discover service definitions, methods, and message types at runtime without needing proto files. This lesson covers how to enable reflection, use reflection-based tools, and build dynamic gRPC clients.

What You'll Learn

• How to enable reflection on a gRPC server
• How to use grpcurl for debugging
• How to build dynamic clients with reflection
• How reflection works internally
• Security considerations for reflection

Why It Matters

Reflection simplifies development, debugging, and tooling for gRPC services. Developers can inspect and call any gRPC endpoint without compiling proto files, making ad-hoc testing and troubleshooting much faster.

Real-World Use

An operations team uses grpcurl with reflection to debug production gRPC services. When a customer reports an issue, they can inspect available endpoints, check message formats, and send test requests without redeploying or accessing proto files.

Flow Chart

flowchart LR
    A[Client/Tool] -->|Reflection Request| B[gRPC Server]
    B --> C{Reflection Enabled}
    C -->|Yes| D[List Services]
    C -->|Yes| E[List Methods]
    C -->|Yes| F[Get Message Schema]
    D --> G[Dynamic Invocation]
    E --> G
    F --> G
    G --> H[Response]
    C -->|No| I[Unimplemented Error]

Code Examples

Example 1: Enabling Reflection in Go

package main

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/reflection"
)

func main() {
    server := grpc.NewServer()

    pb.RegisterGreeterServer(server, &greeterServer{})

    // Enable reflection
    reflection.Register(server)

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

Expected output: Server starts on port 50051 with reflection enabled. Clients can discover services without proto files.

Example 2: Using grpcurl with Reflection

# List all services
grpcurl -plaintext localhost:50051 list

# List methods for a service
grpcurl -plaintext localhost:50051 list helloworld.Greeter

# Describe a message type
grpcurl -plaintext localhost:50051 describe helloworld.HelloRequest

# Call a method
grpcurl -plaintext \
  -d '{"name": "Alice"}' \
  localhost:50051 \
  helloworld.Greeter/SayHello

Expected output: grpcurl discovers all registered services, their methods, and message schemas via reflection, then invokes SayHello dynamically.

Example 3: Dynamic Client in Node.js

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

async function dynamicInvoke() {
  const client = new grpc.Client(
    'localhost:50051',
    grpc.credentials.createInsecure()
  );

  const serviceList = await new Promise(
    (resolve, reject) => {
      client.listServices(
        (error, response) => {
          if (error) reject(error);
          else resolve(response.service);
        });
    });

  console.log('Available services:',
    serviceList);
  
  // Use reflection to get proto definition
  const descriptor = await client.getDescriptor(
    'helloworld.Greeter');

  const dynamicClient = new grpc.Client(
    'localhost:50051',
    grpc.credentials.createInsecure(),
    {
      'grpc.service_config': JSON.stringify({
        methodConfig: [{
          name: [{service:
            'helloworld.Greeter'}]
        }]
      })
    }
  );
}

Expected output: Client discovers services dynamically and prints available service names from the server.

Common Mistakes

Practice Questions

1. How does gRPC reflection discover service definitions?
2. What is the difference between reflection and service discovery?
3. How do you use grpcurl to list all methods of a service?
4. What security risks does reflection introduce?
5. Can reflection work across different programming languages?

Challenge

Build a gRPC reflection client that connects to any gRPC server with reflection enabled, discovers all services and methods, generates a visual API documentation page, and allows invoking any method through a web interface.

FAQ

Mini Project

Build a gRPC API explorer similar to Swagger UI but for gRPC. Connect to a reflection-enabled server, display all services and methods, show message schemas with field descriptions, and provide a form to invoke methods with custom payloads.

What's Next

Learn how to use gRPC in browser applications