GraphQL Federation Router | Cosmo by WunderGraph - WunderGraph
Run GraphQL federation at scale without vendor lock-in
Routes every GraphQL query across your subgraphs, caches the plan for speed, and keeps serving even when the control plane is unreachable.
The problem
Federation gateways should scale with your graph, not fight it
Planning cost, licensing, and deploy friction compound as teams ship more subgraphs.
Gateways slow down as the graph grows
Query planning is expensive, and a gateway that re-plans every request struggles once traffic and schema complexity climb. Latency creeps up, and the gateway becomes the thing you tune around instead of the thing you trust.
Proprietary licensing locks you in
Some federation gateways ship under a license that limits what you can run, where, and for how long. The roadmap is someone else's. So is the pricing.
Schema changes cause downtime
Updating a federated schema often means restarting the gateway or draining traffic. That is a deploy coordination problem no one wants to solve on a Friday.
Our solution
One router for your whole federated graph: fast, open source, and always up
Cosmo Router is an open-source GraphQL federation router built in Go that routes queries across your subgraphs, caches query plans for speed, and reloads configuration live so your API stays up when schemas change.
How it behaves at runtime
- Fetches the current execution config from a CDN using its graph API token.
- Builds an optimized query plan for each operation and caches it so repeat traffic skips replanning.
- Routes requests to subgraphs and aggregates responses.
- When the composed schema updates, the router discovers it on the next CDN poll (default every 15 seconds, configurable; pull-based, not push). It swaps planners without restart. The plan cache is rebuilt cold on the new engine, so expect a short window of higher planning latency until hot paths warm again.
- The router runs independently: it registers with the Cosmo Control Plane for health reporting, but does not depend on the control plane to serve requests. If the control plane is unreachable, the router keeps serving traffic from its cached config.
Before & After
| Before Cosmo | With Cosmo |
|---|---|
| Gateway re-plans every query, latency grows with load | Query plans cached for reuse, planning cost paid once |
| Proprietary license dictates where and how you deploy | Apache 2.0: run it anywhere, fork it if you want |
| Schema deploys require gateway restarts or traffic drain | Hot-reload from CDN, engine swapped in place |
| Gateway stops serving if the control plane goes down | Router keeps serving from cached config regardless |
Use cases
Where teams deploy Cosmo Router first
- Production federation gateway: Teams publish schema updates via CLI. The control plane composes the federated schema and pushes it to the CDN. The router picks up the new config on its next poll and swaps its engine. No restart. No client disruption.
- Zero-downtime schema updates: Developers push schema changes without coordinating router restarts. The router polls for updates, builds a new query planner, and transitions traffic live. In-flight requests finish on the old engine.
- Self-hosted, air-gapped federation: Deploy with a static execution config instead of CDN polling. No outbound dependency on Cosmo Cloud at request time. Full federation capabilities inside isolated infrastructure.
How the federation router runs
- Pull the execution config: Router fetches the current execution config from the CDN using its graph API token. A static file is also supported for air-gapped deployments.
- Build the query planner: Router builds an optimized query planner from the federated schema. For each operation, it decides which subgraphs to call and in what order.
- Serve requests with cached plans: Cache hit: execute. Cache miss: plan, cache, execute. Responses aggregated on the unified endpoint.
- Hot-reload on config change: Router polls the CDN on a configured interval. On a new valid config, it builds a new planner and swaps the engine live. In-flight requests finish on the old engine; new ones run on the new.
FAQ
GraphQL federation router
- Is Cosmo Router actually open source, or is it open-core?
- Can I run the router without the Cosmo Control Plane?
- Does it support Apollo Federation v1 and v2?
- What happens if the Cosmo Control Plane is unreachable?
- How is it different from Apollo Router?
- What does it cost?