Lesson 10 · Errors, deadlines & metadata

Metadata: headers in & out

How the auth token and trace ride the request — gRPC's version of headers.

Your win: explain what metadata is, read/write it in Go, and trace how our auth token becomes a handler's identity — the synchronous cousin of the Kafka header propagation you already learned.

In plain English Plain English: metadata is the header-like side channel around an RPC where auth tokens, request IDs, and trace information travel.

Metadata = headers, separate from the message

Metadata is a set of key–value pairs sent alongside a request or response — not part of the message body. It carries the auth token, a request id, tracing context. Under the hood it's literally HTTP/2 headers: keys are ASCII & case-insensitive, must not start with the reserved grpc- prefix, and binary values use a -bin suffix.1

message = the WHAT (SendEmailRequest fields) metadata = the ABOUT-THIS-CALL (token, x-request-id, trace) — rides in HTTP/2 headers

Reading & writing it in Go

// server: read incoming metadata
md, ok := metadata.FromIncomingContext(ctx)
token := md.Get("token")

// client: attach outgoing metadata
ctx = metadata.AppendToOutgoingContext(ctx, "token", jwt)
// or metadata.NewOutgoingContext(ctx, md)

The metadata → context bridge (our auth)

This is the move to internalise: the auth interceptor reads the token from metadata, verifies the JWT, and injects the resulting claims into context — so handlers read identity from ctx, never from metadata or the request:

internal/usermgmt/pkg/interceptors/auth.go:124 
md, _ := metadata.FromIncomingContext(ctx)
token := md.Get("token")          // metadata (the header)
// …verify JWT…
ctx = interceptors.ContextWithJWTClaims(ctx, claims)  // context (Part 4 / Go L17)
Anchor — propagation, in and out On the way in, the gateway maps the HTTP Authorization header → token metadata (gateway.WithMetadata). On the way out, when a service calls downstream, UnaryClientAttachHeaderInterceptor (bootstrap/resource.go:364) copies token/ pkg/version from the incoming metadata onto the outgoing call — so identity travels the whole call chain.
The parallel to lock in Recall the Kafka course: claims & trace propagate across an async boundary via Kafka message headers. gRPC metadata is the synchronous cousin — same idea (identity/trace travel with the call, outside the payload), different transport. Recognising that pattern once means you understand both.
Read this next

gRPC — Metadata guide + grpc-go metadata doc

What metadata is, header vs trailer, and the Go metadata API for reading incoming and setting outgoing.

→ grpc.io/docs/guides/metadata
→ grpc-go — metadata

Common mistake Common mistake: mixing business payload into metadata or treating metadata like random context baggage instead of structured call headers.

Check yourself (from memory)

Q1. gRPC metadata is transmitted as…

Metadata rides in HTTP/2 headers (and trailers) — alongside, not inside, the message.

Q2. A server reads incoming metadata with…

FromIncomingContext on the server; NewOutgoingContext/AppendToOutgoingContext on the client.

Q3. In our services, the auth interceptor reads which header?

It reads token, verifies the JWT, and injects claims into context — the metadata→context bridge.
What is gRPC metadata, how does our auth use it, and what's the Kafka parallel?
recall, then click to reveal
Metadata = key-value HEADERS sent alongside a request/response (over HTTP/2), separate from the message body — for auth token, request-id, trace. Server reads it via metadata.FromIncomingContext(ctx); client sets it via metadata.NewOutgoingContext/AppendToOutgoingContext. Our auth interceptor reads the token header, verifies the JWT, and injects claims into context; downstream calls copy token/pkg/version outward via UnaryClientAttachHeaderInterceptor. Parallel: Kafka propagates claims/trace across an async boundary via message headers — gRPC metadata is the synchronous cousin.
🎓 That's Part 3 Status codes, deadlines & cancellation, and metadata — the cross-cutting concerns every call carries. Part 4 is where they come together: interceptors, the middleware that reads that metadata, enforces those deadlines, and shapes those statuses.
Ready for Part 4 (interceptors, middleware & auth), or a mixed quiz across Lessons 8–10 first? Ask me.

1. gRPC — Metadata; grpc-go metadata doc.