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

The router applies whichever propagation algorithm you configure. first_write keeps the first value encountered, last_write uses the most recent, and append combines all values into a comma-separated list.

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

No. Nothing is forwarded unless you explicitly configure it.

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

Either first_write (to use the most restrictive directive) or last_write (to use the final subgraph's directive), depending on your caching strategy.

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

Use the set operation to add a static header globally. This adds the header to every response regardless of what subgraphs return.

Do Cosmo Router response header rules apply to GraphQL subscriptions?

Yes. The rules work with all response types: queries, mutations, and subscriptions.

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

They are filtered out automatically. The router strips hop-by-hop headers and does not forward them to clients.

GraphQL Response Header Operations | Cosmo by WunderGraph

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

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

Hop-by-hop headers filtered automatically. Explicit config for everything else.

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

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.

Cache control

Propagate Cache-Control headers from subgraphs to clients and CDNs. Pick the algorithm that matches your caching policy.

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

01

Many upstreams, one downstream.

Subgraphs respond in parallel

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

02

first · last · append; pick deliberately.

Apply the propagation algorithm

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

03

Force security baselines.

Apply `set` rules

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

04

CDN sees coherent directives.

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.

Start Free Read the Docs

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