An Introduction to Cosmo Router — Blazingly Fast Open-Source Federation V1/V2 Gateway - WunderGraph
Prithwish Nath
October 23, 2023 · 12min read
Enterprises have diverse data dependencies — internal microservices with specialized data domains, legacy systems with proprietary data formats, and third-party APIs and SaaS applications with their unique data models and endpoints.
TL;DR: different (and often legacy) technologies that need to be brought together, somehow.
Federated GraphQL has emerged as the go-to solution for such composition in the enterprise sphere, and the Router (or, Gateway) in Federation acts as the linchpin that binds all these disparate data sources together, making them accessible through a single, cohesive API, while still ensuring adaptability. It is, in fact, key to how Federated GraphQL allows for scalable and modular architectures.
Today, we’ll look at WunderGraph Cosmo’s high-performance, open-source, Federation V1/V2 compatible Router. We’ll cover what it does, why it’s so important to the Cosmo stack, how you can host it yourself, and even customize and extend it with Go code of your own.
WunderGraph Cosmo — A Primer
WunderGraph Cosmo is a fully open source (Apache 2.0 License) platform to build, manage, and collaborate on federated graphs at scale. It’s a drop-in replacement for Apollo GraphOS/Studio, and is an all-in-one solution that contains a schema registry that can check for breaking changes and composition errors, a blazingly fast Federation V1/V2 compatible Router, and an analytics/distributed tracing platform for federated GraphQL.
Key Components
The Cosmo stack includes:
- the Studio (GUI web interface) and the
wgc(command-line tool) for managing the platform as a whole — schemas, users, and projects — and accessing analytics/traces. - the Router as the component that actually implements GraphQL Federation, routing requests and aggregating responses.
- the Control Plane, the heart of the platform, providing the core APIs that both the Studio/CLI and the Router consume.
For hosting, you can run the entire platform on-prem on any Kubernetes service (AWS, Azure, Google for production, and Minikube for local dev), or use the managed Cosmo Cloud for all stateful components while you host the stateless router yourself.
The Cosmo Router
The Cosmo Router ( which you can find in the Cosmo monorepo) is an open source (Apache 2.0 license) alternative to the Apollo Gateway or Router. It is a HTTP server written in Golang that is the central entry point for your federated GraphQL architectures, responsible for routing queries and aggregating responses.
1. How it works
Clients make GraphQL requests to the Router’s endpoint, and it intelligently routes these requests to services that can resolve them. Here’s the process:
- It needs access to the Federated graph’s schema, periodically fetched from a high-availability CDN to ensure the Router has the latest config.
- An optimized Query Plan is generated based on configuration — cached across requests to minimize work done.
- The Router decomposes the client query into multiple subqueries, executes them, and aggregates responses.
- Finally, the Router sends back the assembled response to the client.
2. Performance
The Cosmo Router is powered by graphql-go-tools, designed for performance, with significant optimizations.
Batching
Instead of making separate requests for each User's Posts, the Router utilizes a customized DataLoader pattern to fetch all Users and batch the Posts retrieval for all users into a single query, significantly improving efficiency.
Ludicrous Mode
When multiple identical requests are processed, it intelligently sends only one request to the origin server, optimizing network traffic and reducing load.
3. ‘Stateless’
The Router’s stateless design ensures that each request handled is independent, allowing horizontal scaling to handle large numbers of incoming requests without session state preservation.
4. Customization
You can extend the Cosmo Router by creating custom modules, written in Go, offering extensive customization options.
5. Analytics — OpenTelemetry, Prometheus, and RED Metrics
The Cosmo Router has been instrumented with OpenTelemetry to collect, process, and export metrics for detailed performance insights. Integration with multiple monitoring systems (like Jaeger, DataDog) is also supported.
6. Forwarding client headers to subgraphs
The Cosmo Router facilitates the forwarding of specific client headers to subgraphs for contextual information handling, enhancing the decision-making of subgraphs based on client data.
Testing and Deployment
The Cosmo Router fetches the latest config from the CDN. Local testing can be set up by loading a config from a local file. The system is designed to work as a self-contained Docker container.
Conclusion
For many, traditional solutions like Apollo will suffice. However, for enterprise scenarios requiring flexibility, compliance, and scalability, the open-source, fully compatible Cosmo Router is a superior choice. To learn more, check out their docs here.