What does a GraphQL federation router do?

It is the single entry point for a federated graph. For each client operation, the router builds a query plan, calls the subgraphs that own the requested fields, and merges their responses into one result. Cosmo Router caches plans, so repeat operations skip planning.

Is Cosmo Router open source?

Yes. The router is Apache 2.0 licensed. Self-hosted Cosmo is free and open source. On Cosmo Cloud, some router features depend on the plan, such as rate limiting, persisted operations, and cache warming. See the pricing page.

How does Cosmo Router pick up schema changes without downtime?

It polls the CDN for a new execution config every 10 seconds by default, plus up to 5 seconds of jitter. When a new valid config arrives, it builds a new engine and runs both side by side. In-flight requests finish on the old engine, new requests go to the new one, and the old engine is cleaned up once its requests are served. grace_period (30 seconds by default) sets the maximum time for that graceful shutdown.

Does a config reload affect subscriptions?

Yes. WebSocket and SSE connections are long-lived, so they close when the old engine shuts down. Clients must reconnect.

Which metrics should I watch?

Start with router_http_requests_total, router_http_requests_error_total, router_http_request_duration_milliseconds, router_http_requests_in_flight, and router_graphql_operation_planning_time. Requests to subgraphs carry the wg_subgraph_name label, so you can see which subgraph is slow or failing.

Can I run it air-gapped, without the Cosmo Control Plane?

Yes. The router can run from a static execution config file with no control plane connection. File watching is on by default, so it hot-reloads when the file changes. Every schema change then needs a new file, so automate that step. Without a graph token the default Cosmo Cloud telemetry export is off, so point metrics and traces at your own collectors.

What happens if the Cosmo Control Plane is unreachable?

Serving requests does not depend on the control plane. The router uses it to register and report fleet health. It gets its execution config from the CDN, an S3-compatible storage provider, or a file.

Does it support Apollo Federation v1 and v2?

Yes. Cosmo supports both Federation v1 and v2 directives.

How is it different from Apollo Router?

Cosmo Router is Apache 2.0 licensed. Apollo Router is source-available under the Elastic License v2. Cosmo Router is written in Go on graphql-go-tools and is extended with Go custom modules.

The router itself is free and open source. Cosmo Cloud pricing covers the managed control plane, schema registry, observability, and plan-dependent router features such as rate limiting and persisted operations. See the pricing page.

GraphQL Federation Router | Cosmo by WunderGraph

The problem

Federation gateways should scale with your graph, not fight it

Planning cost, licensing, and deploy friction compound as teams ship more subgraphs.

Planning cost grows with the graph

Query planning is expensive, and it gets more expensive as schemas and traffic grow. A router has to cache plans, and keep that cache warm across schema changes, or latency rises.

Source-available licensing limits what you can do

Some federation routers ship under source-available licenses. Apollo Router uses the Elastic License v2, which you can self-host but can't offer to others as a managed service.

Schema changes have to roll out live

Every subgraph publish that composes produces a new router config. The router has to pick it up without dropping in-flight requests, and long-lived subscriptions have to reconnect.

Our solution

One router for your whole federated graph: fast, open source, and live-reloading

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 the CDN.
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 (every 10 seconds by default, plus up to 5 seconds of jitter, configurable; pull-based, not push). It swaps engines without a restart. The main plan cache starts cold on the new engine, so planning latency rises until hot paths warm again. The cache warmer can rewarm plans when the new engine starts.
The router registers with the Cosmo Control Plane to report fleet health, but serving requests does not depend on the control plane. Config comes from the CDN, an S3-compatible storage provider, or a file.

Open source. The same router on every Cosmo plan.

Federation router

Before & After

Before Cosmo	With Cosmo
Source-available license (Apollo Router: Elastic License v2)	Apache 2.0: run it anywhere, fork it if you want
Apollo Router 1.60 and later: no Federation v1 supergraphs	Federation v1 and v2 supported

Operations

What ships with the router

Beyond federation routing and CDN-driven hot reload, you get hooks teams expect in production: HTTP endpoints for Kubernetes health checks, GraphQL Playground for trying queries against your graph, OpenTelemetry hooks for traces, and configurable logging, metrics, and tracing (exact flags live in the docs).

How the federation router runs

01

CDN or file: your topology.

Pull the execution config

Router fetches the current execution config from the CDN. A static file is also supported for air-gapped deployments.

02

Federation v1 and v2.

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.

03

Plans reused until the next config reload.

Serve requests with cached plans

Cache hit: execute. Cache miss: plan, cache, execute. Responses aggregated on the unified endpoint.

04

Graceful handoff, no restart.

Hot-reload on config change

Router polls the CDN every 10 seconds by default. 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. WebSocket and SSE subscriptions close when the old engine shuts down, and clients reconnect.

Observability

See what the router is doing

Metrics and traces come from one OpenTelemetry pipeline. Prometheus is an exporter on the same instrumentation.

Per-subgraph metrics

OTEL · Prometheus

Rate, errors, and duration for router and subgraph requests. Subgraph requests carry wg_subgraph_name, so a slow or failing subgraph stands out. The Prometheus endpoint defaults to 127.0.0.1:8088/metrics.

Query planning time

Histogram

router_graphql_operation_planning_time shows how long planning takes. Watch it after a config reload, when the main plan cache starts cold.

Traces and query plans

OTLP · ART

Traces export over OTLP, to Cosmo Cloud by default. Exporters are configurable; see pricing for plan details. Advanced Request Tracing returns the query plan and subgraph fetches for a single request. In production, it needs a control plane connection and a token signed by Studio.

Cache warming after reload

Cache warmer

CDN-based warming precomputes plans for known slow operations. With cache_warmup enabled, the in-memory fallback rewarms operations that were slow to plan (over 100ms by default) after a reload, as the primary source or when the CDN manifest is unavailable. CDN-based warming is an Enterprise feature; see pricing.

Details: Prometheus metrics, OpenTelemetry, Advanced Request Tracing, and the cache warmer. Subscriptions over Kafka, NATS, or Redis run through Cosmo Streams.

Use cases

Where teams deploy Cosmo Router first

Production gateway, zero-downtime schema publishes, and air-gapped self-hosting.

Production federation gateway

Platform

Teams publish schema updates via CLI. The control plane composes the federated schema and uploads it to the CDN. The router picks up the new config on its next poll and swaps its engine. No restart.

Zero-downtime schema updates

CDN poll

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

Static config

Deploy with a static execution config instead of CDN polling, and send metrics and traces to your own collectors instead of Cosmo Cloud. Serving requests needs no connection to Cosmo Cloud.

Run the open-source federation router

Apache 2.0. Go. Cached plans. Hot config reload.

Start Free Read the Docs

Run GraphQL federation at scale without vendor lock-in