GraphQL Response Header Operations | Cosmo by WunderGraph - WunderGraph

Control which response headers clients see, even when they come from multiple subgraphs

Choose how headers from parallel subgraphs combine: keep the first, take the last, or merge them all. Override per subgraph when you need them.

Nothing forwarded by default. Every header that reaches clients is there because you said so.

The problem

Federated responses need a merge policy

Parallel subgraph calls mean parallel header sets. The router has to combine them on purpose, not by accident.

Picking one header value arbitrarily is a caching bug

If one subgraph says Cache-Control: no-store and another says max-age=300, the answer cannot be whichever came back first. That is how stale data leaks into caches.

Merging headers in client code is a losing game

Forcing every client to understand which subgraph sent which header inverts the responsibility and makes the federated graph look leaky.

Losing cache headers kills CDN caching

If the router drops Cache-Control because it doesn't know how to aggregate, every request has to hit the router. A CDN tier sitting in front does nothing useful.

Our solution

Merge response headers from multiple subgraphs predictably, every time

Cosmo Router response header operations let you control which headers from your subgraphs reach the client, with three deterministic algorithms plus set for baseline security and caching headers.

What happens at response time

  1. Choose propagation rules per header name or pattern. Nothing reaches the client without a rule.
  2. Apply set after propagation so baseline security and caching headers are always present.
  3. Use headers.subgraphs.<name>.response when one service needs a different merge policy.

Response headers

Before & After

Before Cosmo With Cosmo
Arbitrary header selection from parallel responses Deterministic algorithms (first_write, last_write, append)
Cache headers dropped or inconsistent Controlled propagation of Cache-Control directives
Custom router middleware to merge headers Declarative YAML configuration
No way to guarantee security headers on every response set operation injects headers on every response

Router controls

Three capabilities

  1. Deterministic behaviour: Three algorithms handle headers from parallel subgraph responses: first_write keeps the first value, last_write uses the most recent, append combines all values.
  2. Cache control: Propagate Cache-Control headers from subgraphs to clients and CDNs. Pick the algorithm that matches your caching policy.
  3. Security by default: No response headers forwarded unless explicitly configured. Use set to inject required security headers globally regardless of what subgraphs return.

How response header operations work

Subgraphs respond in parallel

Router executes the query plan; each subgraph call returns its own response headers.

Apply the propagation algorithm

For each configured propagation rule, the router applies the algorithm to collected header values.

Apply set rules

Static headers from set are applied after propagation. When both touch the same header name, the set value wins.

Return to client

Client receives a single response with headers assembled the way you configured.

Make CDN and browser caching deterministic

Declare how parallel subgraph headers merge, then enforce security headers on every response.

FAQ

Response header operations

What happens if two GraphQL subgraphs return different values for the same response header?

Are subgraph response headers forwarded to clients by default in Cosmo Router?

Which response header propagation algorithm should I use for Cache-Control?

How do I guarantee a security header is always present on Cosmo Router responses?

Do Cosmo Router response header rules apply to GraphQL subscriptions?

How does Cosmo Router handle hop-by-hop headers like Connection and Transfer-Encoding?

Full reference in the response headers documentation.