# GraphQL Extensions Forwarding - Queries, Mutations, and Subscriptions

Use the `extensions` field to send extra data from clients to subgraphs without stuffing it into headers.

## The problem

### Structured context should not live in headers
Headers flatten everything. Subscriptions cannot vary headers per operation. The GraphQL spec already has a place for extra JSON: use it.

### Headers are a poor fit for structured data
HTTP headers are flat strings. Sending `{"features":{"newCheckout":true,"betaSearch":false}}` through a header means encoding JSON as a string and decoding it everywhere it lands.

### WebSocket subscriptions have no per-operation headers
A WebSocket connection is established once. After that, every subscription operation flows over the same socket. There is no way to attach a different `Authorization` header to operation #2 vs. operation #1.

### Custom workarounds fragment the API
Teams invent sidecar endpoints, bespoke envelope formats, or hidden query arguments to work around the header limitation. None of that is standard.

## Our solution

### Pass any JSON context from clients to subgraphs, including subscriptions
The GraphQL `extensions` object is the spec-backed place for structured client context. Cosmo Router forwards it to subgraphs by default—queries, mutations, and subscriptions—without a feature flag or a custom side channel.

### What happens at request time
1. The router attaches the client's `extensions` object to each outgoing subgraph request, so structured payloads stay JSON-shaped end to end for queries, mutations, and subscriptions.
2. GraphQL over HTTP defines `extensions` as a JSON object next to `query` and `variables`. Clients put whatever structured data they need there, and the router forwards it untouched to every subgraph involved in the operation.
3. For `graphql-ws` subscriptions, `extensions` lives in the subscription message payload—the reliable way to attach per-operation data on a shared WebSocket. No configuration; it works by default.
4. Subgraphs read the fields they care about; the router does not reshape or flatten the JSON.

## Behavior
### Technical behavior
- Forwarding is automatic for queries and mutations over HTTP.
- For subscriptions, requires a `graphql-ws` compatible setup on both router and subgraph.
- The JSON structure is preserved exactly; the router does not reshape or flatten it.
- Subgraphs must be designed to read and act on the fields they expect. The router does not validate the contents.
- No configuration required, enabled by default.

## Use cases

### Patterns teams use first
Auth tokens, feature flags, and client metadata: same field, different payloads.

### Standards compliant
Implements the `extensions` field as defined in the GraphQL over HTTP specification. Works with any GraphQL client library that supports it.

### Subscription support
The reliable way to send per-subscription initialization data. WebSocket connections are established once; `extensions` in the subscription payload carries per-operation tokens after that.

### Flexible data structure
Send any JSON object (auth tokens, feature flags, client metadata) without encoding it into a flat header string.

## How extensions forwarding works

### Client sends extensions
Structured context lives in the JSON body under the `extensions` field—not squeezed into header strings—including `graphql-ws` subscription payloads.

### Router receives the payload
The `extensions` field is preserved as received.

### Extensions travel downstream
Extensions travel with every subgraph call on outgoing requests.

### Subgraphs consume what they need
Each subgraph reads the fields it cares about and ignores the rest.