mirror of https://github.com/grpc/grpc.io.git
120 lines
5.5 KiB
Markdown
120 lines
5.5 KiB
Markdown
---
|
|
title: Metadata
|
|
description: >-
|
|
Explains what metadata is, how it is transmitted, and what it is used for.
|
|
---
|
|
{{< youtube id="psYQFbPgIOI" class="youtube-video" title="gRPC metadata limits:The Good, The Bad and The Ugly" >}}
|
|
### 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](/docs/what-is-grpc/core-concepts/#metadata)
|
|
|
|
#### 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](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md)
|
|
, 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](/docs/guides/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 G1]
|
|
* [proposal: L7 go metadata api][proposal L7]
|
|
* [proposal: L48 node metadata options][proposal L48]
|
|
* [proposal: L42 python metadata flags][proposal L42]
|
|
* [proposal: L11 ruby interceptors][proposal L11]
|
|
|
|
### Language Support
|
|
|
|
| Language | Examples | Notes |
|
|
|----------|--------------------------------------------|--------------------|
|
|
| Java | [Java Header]<br>[Java Error Handling] | |
|
|
| Go | [Go Metadata]<br>[Go Metadata Interceptor] | [Go Documentation] |
|
|
| C++ | [C++ Metadata] | |
|
|
| Node | [Node Metadata] | |
|
|
| Python | [Python Metadata] | |
|
|
| Ruby | | Example upcoming |
|
|
|
|
[proposal L7]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/L7-go-metadata-api.md
|
|
|
|
[proposal G1]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/G1-true-binary-metadata.md
|
|
|
|
[proposal L48]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/L48-node-metadata-options.md
|
|
|
|
[proposal L42]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/L42-python-metadata-flags.md
|
|
|
|
[proposal L11]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/L11-ruby-interceptors.md
|
|
|
|
[Java Header]: https://github.com/grpc/grpc-java/tree/master/examples/src/main/java/io/grpc/examples/header
|
|
|
|
[Java Error Handling]: https://github.com/grpc/grpc-java/tree/master/examples/src/main/java/io/grpc/examples/errorhandling
|
|
|
|
[Node Metadata]: https://github.com/grpc/grpc-node/tree/master/examples/metadata
|
|
|
|
[Go Metadata]: https://github.com/grpc/grpc-go/tree/master/examples/features/metadata
|
|
|
|
[Go Metadata interceptor]: https://github.com/grpc/grpc-go/tree/master/examples/features/metadata_interceptor
|
|
|
|
[C++ Metadata]: https://github.com/grpc/grpc/tree/master/examples/cpp/metadata
|
|
|
|
[Python Metadata]: https://github.com/grpc/grpc/tree/master/examples/python/metadata
|
|
|
|
[Go Documentation]: https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md
|