Metadata

Overview

Metadata is a side channel that allows clients and servers to provide information to each other that is associated with an RPC.

gRPC metadata is a key-value pair of data that is sent with initial or final gRPC requests or responses. It is used to provide additional information about the call, such as authentication credentials, tracing information, or custom headers.

gRPC metadata is implemented using HTTP/2 headers. The keys are ASCII strings, while the values can be either ASCII strings or binary data. The keys are case insensitive and must not start with the prefix grpc-, which is reserved for gRPC itself.

gRPC metadata can be sent and received by both the client and the server. Headers are sent from the client to the server before the initial request and from the server to the client before the initial response of an RPC call. Trailers are sent by the server when it closes an RPC.

gRPC metadata is useful for a variety of purposes, such as:

• Authentication: gRPC metadata can be used to send authentication credentials to the server. This can be used to implement different authentication schemes, such as OAuth2 or JWT using the standard HTTP Authorization header.
• Tracing: gRPC metadata can be used to send tracing information to the server. This can be used to track the progress of a request through a distributed system.
• Custom headers: gRPC metadata can be used to send custom headers to the server or from the server to the client. This can be used to implement application-specific features, such as load balancing, rate limiting or providing detailed error messages from the server to the client.
• Internal usages: gRPC uses HTTP/2 headers and trailers, which will be integrated with the metadata specified by your application.

See Core Concepts

Be Aware

WARNING: Servers may limit the size of Request-Headers, with a default of 8 KiB suggested.

Custom metadata must follow the “Custom-Metadata” format listed in PROTOCOL-HTTP2 , with the exception of binary headers not needing to be base64 encoded.

Headers

Headers are sent before the initial request data message from the client to the server and similarly before the initial response data from the server to the client. The header includes things like authentication credentials and how to handle the RPC. Some of the headers, such as authorization, are generated by gRPC for you.

Custom header handling is language dependent, generally through interceptors.

Trailers

Trailers are a special kind of header that is sent after the message data. They are used internally to communicate the outcome of an RPC. At the application level, custom trailers can be used to communicate things not directly part of the data, such as server utilization and query cost. Trailers are sent only by the server.

For more details, please see the following gRFCs

• proposal: G1 true binary metadata
• proposal: L7 go metadata api
• proposal: L48 node metadata options
• proposal: L42 python metadata flags
• proposal: L11 ruby interceptors

Language Support