GraphQL Router Config Hot Reload | Cosmo by WunderGraph - WunderGraph
Update the router without dropping a single request
CDN polling by default, file watching for local dev, and a signal for on-demand reloads. In-flight requests always finish cleanly.
In-flight requests finish on the old config. New requests use the new one. No restart, no dropped connections.
From publish to handoff
Schema publishCLI / registryCDN updateartifact liveRouter polldetect + buildDual instancesgrace overlapOld retiredclean shutdownOld + new graphIn-flight requests → oldNew requests → new
Why GraphQL router config changes are usually disruptive
Production routers sit in the middle of every client. Restarting them is a blunt instrument, and coordinating a whole fleet without mixed behavior is even harder.
Restarts drop connections.
A process restart terminates open HTTP and WebSocket connections. Clients see errors. Kubernetes rolling restarts stretch the pain across a rollout window instead of eliminating it.
Fleet rollouts are hard to coordinate.
Ten routers behind a load balancer all need the new config. Doing that without a window of mixed behavior (some routers on the old schema, some on the new) takes effort you'd rather spend elsewhere.
Emergency changes are slow.
When you need to flip a setting right now, waiting for the next poll cycle or the next deploy window is the wrong answer.
Update router config live: no dropped requests, no restarts
Cosmo Router hot reload lets you apply schema and configuration changes without restarting the process. The router polls the CDN for new configs, spins up a new engine alongside the old one, hands off traffic gracefully, then retires the old instance with no dropped requests.
For local development, watch_config reloads a file-based config whenever it changes on disk. For on-demand reloads in production, sending SIGHUP to the router process triggers an immediate reload.
How the pieces fit
- Cosmo Router hot reload applies schema and configuration changes without restarting the process.
- The router polls the CDN for new configs, spins up a new engine alongside the old one, hands off traffic gracefully, then retires the old instance with no dropped requests.
- For local development, watch_config reloads a file-based config whenever it changes on disk.
- For on-demand reloads in production, sending SIGHUP to the router process triggers an immediate reload.
Before & After
| Before Cosmo | With Cosmo |
|---|---|
| Config changes require a restart, dropping connections | Graceful handoff keeps in-flight requests on the old instance |
| Fleet rollouts produce windows of mixed schema behavior | Every router polls the same CDN and converges within the poll interval |
| Dev iteration loops through a restart every config tweak | watch_config reloads on save for local work |
| Emergency changes wait for the next deploy | SIGHUP triggers an immediate reload on demand |
Graceful handoff and limitations
During the grace period, both instances serve traffic. Memory use temporarily roughly doubles for the federated graph, so size the router pods with that headroom in mind. The query planner cache on the new instance is cold, so there is a brief latency bump on first requests per operation.
Limitations
- WebSocket and Server-Sent Events connections attached to the old instance close when the old instance retires. Clients reconnect.
- Changes to the
watch_configsection itself are not hot-reloaded; a restart is still required to change watch behavior. - Environment variable and command-line flag changes require a full restart.
How config hot reload works
01
Poll, watch, or signal: same handoff path.
Detect a new config
The router polls the CDN every 15 seconds by default, with jitter so replicas do not align. File-based config uses watch_interval; SIGHUP forces an immediate check.
02
Planner cache starts cold on the new instance.
Build a new graph instance
A new in-memory graph builds with a fresh query planner while the current instance keeps serving traffic.
03
No restart, no pod churn.
Route new traffic to the new instance
New requests go to the new instance; in-flight work finishes on the old one.
04
WebSockets on the old instance close at retire time.
Retire the old instance
When the grace period ends (default 30 seconds), the old instance is removed. shutdown_delay defaults to 60 seconds so long-lived server resources can close cleanly.
Cosmo Router hot reload use cases
Zero-downtime schema deploys, fast local iteration, emergency rollouts, and observability hooks, all from one runtime behavior.
Zero-downtime schema deploys
Hot reload
Schema published via CLI lands on CDN; every router picks it up on the next poll and swaps engines. No pod restarts.
Local development iteration
watch_config
Enable watch_config with a short interval; saved changes apply within seconds. No manual restart.
Example YAML configuration
Configuration
Polling defaults, execution config watching, and router config watch, tuned for prod and local dev. Optional startup_delay under watch_config spreads reloads in clusters.
Emergency rollouts
On demand
Edit the config on the pod and send kill -HUP <pid>. The router reloads immediately.
Metrics & monitoring
Observability
Reload events are logged. Alert on failed reloads and on plan cache miss rate spiking after a reload.