How does the restrictive algorithm work?

`no-cache` and `no-store` directives take priority and override all other settings. Among remaining directives, the smallest `max-age` value from any subgraph is selected. The earliest `Expires` header timestamp is used. Mutations automatically get `no-cache`. Error responses get `no-store, no-cache, must-revalidate`.

Can I apply the policy to only some subgraphs?

Yes. Set `enabled: false` in the global `cache_control_policy` to disable global enforcement, then configure subgraph-specific values only. The restrictive algorithm still applies across any subgraphs that do have a policy.

What happens if no subgraph returns a Cache-Control header?

If a global default is configured, that value is used. If no global default is set and no subgraph returns a Cache-Control header, no Cache-Control header is set on the response.

Does this work with CDNs like Cloudflare or Fastly?

Yes. The router sets the standard `Cache-Control` HTTP header. CDNs honor this header according to their standard caching behavior. CDN edge caching becomes particularly effective when combined with APQ GET requests.

What is the interaction with header propagation rules?

You can inject a `Cache-Control` value into a subgraph response via a `set` operation in header propagation rules. The restrictive algorithm considers this injected value alongside the subgraph's actual response header.

Are mutations always protected?

Yes, when a global cache control policy is enabled. Mutations automatically receive `Cache-Control: no-cache` regardless of subgraph settings. This behavior is not configurable—it is a safety guarantee.

Cache Control for Federated GraphQL | Cosmo by WunderGraph

The problem

Cache policies across subgraphs do not coordinate themselves

In a federated graph, each subgraph has different caching requirements. Without coordination, you get stale data, exposed sensitive fields, or missed caching opportunities.

Subgraphs have conflicting cache requirements

Product data might be safe to cache for minutes. Pricing data should never be cached. Without coordination, setting a single policy for the whole graph means either stale data or missed caching opportunities.

Sensitive data can leak into CDN caches

A permissive cache policy on one subgraph can expose sensitive fields to CDN caching when they appear alongside cacheable data in the same response.

Mutations and errors are not always protected

Mutation results and error responses should never be cached. Without automatic handling, they can be served stale by CDNs or browsers.

Our solution

Restrictive by design

The router evaluates Cache-Control directives from every subgraph involved in a response and applies the strictest policy. You set a global default and per-subgraph overrides. The algorithm handles the rest.

How cache policy aggregation works

Set `cache_control_policy.enabled: true` in your router configuration. Define a global default value, for example `max-age=180, public`.
Add per-subgraph overrides where specific policies are needed. A pricing subgraph might get `no-cache`; a static content subgraph might get `max-age=3600, public`.
On each request, the router collects Cache-Control headers from all subgraph responses involved in the query.
The restrictive algorithm runs: `no-cache` and `no-store` take priority over everything. The smallest `max-age` value wins. The earliest `Expires` header is used.
GraphQL mutations automatically receive `Cache-Control: no-cache` when a global policy is enabled, regardless of subgraph settings.
Responses with any errors automatically receive `Cache-Control: no-store, no-cache, must-revalidate`.

One config block. Correct headers on every response.

Cache Control

Before & After

Before Cosmo	With Cosmo
Manual cache header coordination across subgraphs	Automatic restrictive policy aggregation at the router
Risk of caching sensitive data when subgraphs share a response	`no-cache` and `no-store` always take precedence
No automatic handling of mutations	Mutations automatically receive `no-cache`
Error responses served stale from cache	Errors automatically receive `no-store, no-cache, must-revalidate`

Algorithm

Restrictive policy rules

no-cache / no-store

Override all other directives. If any subgraph returns either, the response gets that directive.

max-age

The smallest value across all subgraphs and the global default is selected.

Expires

The earliest expiration timestamp wins.

How Cache Control works in Cosmo Router

01

One config block.

Configure

Define a global default policy and per-subgraph overrides in your router configuration. The global value sets the baseline; subgraph values narrow it where needed.

02

Per-subgraph collection.

Evaluate

On each request, the router collects Cache-Control directives from every subgraph response that contributed to the federated result.

03

Strictest policy wins.

Apply strictest

`no-cache` and `no-store` override everything. Among remaining directives, the smallest `max-age` wins. The earliest `Expires` header is used. Mutations get `no-cache` automatically.

04

Errors never cached.

Protect errors

If the final response contains any errors, the router sets `Cache-Control: no-store, no-cache, must-revalidate` regardless of the configured policy.

Capabilities

Policies, overrides, and automatic protection

Global defaults, per-subgraph overrides, and automatic safety for mutations and errors.

Global default policy

Set a baseline `Cache-Control` value for all responses. Per-subgraph overrides narrow the policy where data requires stricter caching behavior.

Per-subgraph overrides

Configure individual subgraphs with their own cache directives. The restrictive algorithm applies the strictest setting across all subgraphs accessed by a query.

Automatic mutation handling

When a global cache policy is enabled, GraphQL mutations automatically receive `Cache-Control: no-cache`. Mutation results are never cached.

Error response protection

Responses with errors automatically receive `no-store, no-cache, must-revalidate`, preventing clients or CDNs from re-serving a stale error response.

Correct cache headers across your federated graph

Enable `cache_control_policy` in your router config. Set a global default. Override per subgraph where needed.

Start Free Read the Docs

The strictest cache header wins, automatically.