What rules govern a custom gRPC metadata key and its value, and where on a call may it travel?

## Metadata is the envelope, not the letter A gRPC call carries two separate channels of information. The **messages** are the schema-defined payload — the prescription id, the eligibility answer. **Metadata** is a list of key-value pairs travelling alongside them, outside the schema: a counter identifier, a correlation key, a credential, a locale. The practical consequence is that metadata is readable without understanding the service. Code that never parses the message can still read a metadata key, which is why cross-cutting concerns live there and business data does not. ## The key rules - A key is built from **digits, `a-z`, `_`, `-` and `.`** — and it is **lowercase**. There is no uppercase form on the wire; a library that lets you write `Counter-Id` is lowercasing it for you. - Keys starting with **`grpc-`** are **reserved for the protocol**. `grpc-timeout`, `grpc-status`, `grpc-message`, `grpc-encoding` and their siblings are protocol fields, and an application key in that namespace risks colliding with a field the transport interprets. - A key ending in **`-bin`** is special, and the suffix is part of the name on the wire. ## Values: printable ASCII, or base64 An ordinary metadata value is limited to **printable ASCII** — the range from space through `~`. That rules out raw bytes, control characters, and any non-ASCII text such as an accented name. The escape hatch is the **`-bin` suffix**. When a key ends in `-bin`, its value is **base64** on the wire and the receiving library hands you the decoded bytes. Two details matter: 1. The base64 form is what the wire carries, so the field is roughly **four bytes for every three** of your data — about a third larger than the raw value. 2. Implementations are required to accept both padded and unpadded base64, so a trailing `=` may or may not be present on a value you receive. Note the asymmetry that catches people: **keys are lowercase, values are not**. `counter-id: STORE-4417` is entirely legal — the uppercase is in the value, which only has to be printable ASCII. ## Where metadata may travel | direction | where | when | |---|---|---| | client to server | request metadata (headers) | once, before the request message | | server to client | leading metadata | before the server's first message | | server to client | trailing metadata | after the last message, with the call's outcome | The asymmetry is real and worth stating plainly: **a client sends metadata only at the start of a call**. There is no client-side trailing metadata to send after its messages. The server has both openings, and when it fails before sending anything at all it may send a single block that serves as both. ## Duplicates, order and size - The **same key may appear more than once**. Repeated entries keep their **relative order**, so a list sent under one key arrives in the order it was sent. - Repeated entries may equivalently be carried as **one comma-joined value**; a receiver has to cope with either shape. - Order **between different keys** is not guaranteed, so never encode meaning in the position of one key relative to another. - The block is **size-bounded** in practice, so metadata is for small facts. Bulk belongs in the message, where the schema describes it and the size limits are the message's. ## The judgment part The question 'should this be metadata or a message field?' has a reliable test: **if the service's contract needs it to answer the call, it is a message field**. A prescription id is part of the request. A correlation key that lets an operator find this call in a log later is metadata — nothing in the eligibility logic reads it, and the service would still work if it were absent. Putting business data in metadata hides it from the schema, from versioning and from anyone reading the `.proto` to learn what the call takes.