What is gRPC metadata and how do you use it?
Understand gRPC metadata: key-value pairs sent with an RPC over HTTP/2 headers. Learn to send auth tokens, trace IDs, and binary values on client and server.
Expected Interview Answer
gRPC metadata is a set of key-value pairs sent alongside an RPC — separate from the message body — used to carry auxiliary information such as authentication tokens, tracing IDs, and deadlines between client and server.
Metadata is transmitted as HTTP/2 headers and trailers. Clients attach request metadata before a call, and servers can read it and send back their own response headers and trailing metadata. Keys are case-insensitive ASCII; values are either ASCII strings or, when the key ends in '-bin', binary. It is the idiomatic place for cross-cutting context like bearer tokens or correlation IDs that interceptors and handlers read without polluting your protobuf message definitions.
- Carries context without changing the message schema
- Standard place for auth tokens and correlation IDs
- Supports both text and binary values
- Readable by interceptors for cross-cutting logic
- Maps naturally onto HTTP/2 headers and trailers
AI Mentor Explanation
Think of the information written on the back of a team sheet handed to the umpire — captain, substitutes, playing conditions — kept separate from the ball-by-ball scorecard itself. gRPC metadata is that team sheet: contextual details travel alongside the actual play, letting officials act correctly without cluttering the record of runs and wickets.
Step-by-Step Explanation
Step 1
Create metadata on the client
Build a key-value collection, for example adding an 'authorization' bearer token or a request-id correlation key.
Step 2
Attach it to the outgoing call
Send the metadata with the RPC via call options or an outgoing context so it travels as HTTP/2 headers.
Step 3
Read it on the server
Extract the incoming metadata from the request context inside the handler or an interceptor.
Step 4
Send response metadata
The server can set header metadata before the response and trailing metadata after it completes.
Step 5
Handle binary values correctly
Use a '-bin' key suffix for binary data so it is base64-encoded on the wire, and keep keys lowercase ASCII.
What Interviewer Expects
- Defines metadata as key-value pairs sent with an RPC
- Knows it maps onto HTTP/2 headers and trailers
- Understands request vs response (header and trailing) metadata
- Names real uses like auth tokens and correlation IDs
- Knows the '-bin' suffix convention for binary values
Common Mistakes
- Confusing metadata with the protobuf message body
- Putting large payloads in metadata instead of the message
- Assuming keys are case-sensitive when they are not
- Forgetting binary values need a '-bin' key suffix
- Reading request metadata after the stream has closed
Best Answer (HR Friendly)
“gRPC metadata is extra information sent along with a network request, like a login token or a tracking ID, kept separate from the main data. It works like the label on a parcel: it tells the system who sent it and how to handle it without changing the contents inside.”
Code Example
// Client: attach metadata
md := metadata.Pairs("authorization", "Bearer "+token, "request-id", reqID)
ctx := metadata.NewOutgoingContext(context.Background(), md)
resp, err := client.GetUser(ctx, &pb.GetUserRequest{Id: 42})
// Server: read incoming metadata
func (s *server) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
md, ok := metadata.FromIncomingContext(ctx)
if ok {
auth := md.Get("authorization")
log.Printf("auth=%v", auth)
}
return &pb.User{Id: req.Id}, nil
}Follow-up Questions
- How does gRPC metadata map onto HTTP/2 headers and trailers?
- What is the difference between header and trailing metadata?
- How do you send binary values in metadata?
- How do interceptors typically use metadata?
- Why should you avoid putting large data in metadata?
MCQ Practice
1. What is gRPC metadata primarily used for?
Metadata carries auxiliary key-value information such as auth tokens and tracing IDs alongside the RPC, separate from the message body.
2. How is gRPC metadata transmitted on the wire?
gRPC runs over HTTP/2, and metadata is carried as HTTP/2 request/response headers and trailing headers.
3. What convention marks a metadata value as binary?
Keys ending in '-bin' hold binary values, which gRPC base64-encodes for transport.
Flash Cards
What is gRPC metadata? — Key-value pairs sent with an RPC, separate from the message body, for context like auth tokens and trace IDs.
How is metadata carried? — As HTTP/2 headers (request and response) and trailing headers.
Header vs trailing metadata? — Header metadata is sent before the response; trailing metadata is sent after the RPC completes.
Binary metadata convention? — Keys ending in '-bin' hold binary values, which are base64-encoded on the wire.