Chapter 10: Metadata, Headers, and Trailers

Metadata in gRPC is like HTTP headers — key-value pairs sent alongside RPCs for cross-cutting concerns (auth tokens, request IDs, tracing info) without polluting your message definitions.

Three Points Where Metadata Flows

Metadata Types

C++ Examples

Client: Sending Metadata

ClientContext context;

// Add metadata to outgoing request
context.AddMetadata("authorization", "Bearer my-token-123");
context.AddMetadata("x-request-id", "req-456");
context.AddMetadata("x-trace-bin", binary_trace_data);  // -bin suffix = binary

Status status = stub->GetUser(&context, request, &response);

// Read server's initial metadata (sent before response body)
auto server_metadata = context.GetServerInitialMetadata();
auto it = server_metadata.find("server-version");
if (it != server_metadata.end()) {
  std::cout << "Server version: " << it->second << std::endl;
}

// Read trailing metadata (sent after response body)
auto trailers = context.GetServerTrailingMetadata();

Server: Reading and Sending Metadata

Status GetUser(ServerContext* context,
              const GetUserRequest* request,
              User* response) {
  // Read client's metadata
  auto metadata = context->client_metadata();
  auto auth = metadata.find("authorization");
  if (auth == metadata.end()) {
    return Status(StatusCode::UNAUTHENTICATED, "No token");
  }

  // Send initial metadata back to client
  context->AddInitialMetadata("server-version", "1.2.3");

  // Send trailing metadata (sent with status)
  context->AddTrailingMetadata("request-cost", "42ms");

  // ... process request ...
  return Status::OK;
}

Common Metadata Use Cases