Overview - WunderGraph

Cosmo Connect

Cosmo Connect is the high-level framework for extending your federated graph with external implementations. This section introduces the internal model behind Connect and explains how it works, before going deeper into Plugins and gRPC Services as the two deployment approaches.

Introduction

The Cosmo Router supports integration with gRPC through a schema-first approach. You define a GraphQL schema that represents the interface to your gRPC implementation, and the Cosmo tooling generates the corresponding Protocol Buffer definitions and mappings that enable the router to establish communication. This approach allows you to bridge any service - whether it’s gRPC, REST, SOAP, or legacy systems - into your GraphQL Federation Supergraph by creating a protocol translation layer. The router handles the communication with your implementations based on the generated mappings, making it easy to modernize your architecture while preserving existing investments.

What is gRPC?

gRPC is a modern, open-source, high-performance RPC framework that enables communication between services using a lightweight binary protocol. It provides a robust foundation for building distributed systems and is widely adopted in the industry.Key characteristics include:

• Language and platform agnostic - allows you to define service interfaces in a language-neutral way
• Protocol Buffers - uses protobuf as the interface definition language for type-safe communication
• High performance - binary protocol enables efficient data serialization and transmission
• Industry standard - widely adopted across microservices architectures

You can find more information about gRPC here.

What is gRPC Integration in Cosmo?

gRPC integration in Cosmo allows you to incorporate gRPC-based functionality into your GraphQL Federation through a code generation workflow:

• Schema-driven integration where you define GraphQL schemas that represent your gRPC interfaces
• Automatic protobuf generation from your GraphQL schema definitions
• Router-managed communication where the Cosmo Router handles gRPC communication
• Protocol translation between GraphQL requests and gRPC calls
• Type-safe mappings ensuring consistency between GraphQL and protobuf definitions
• Flexible deployment models supporting both local and remote gRPC implementations

Core Workflow

1. Define GraphQL Schema
   Create a GraphQL schema that represents the interface to your gRPC implementation. This schema defines the types, queries, mutations, and inputs that will be exposed through your GraphQL API.
2. Generate Protobuf Files
   Use the Cosmo CLI to automatically generate protobuf service definitions and mapping configurations from your GraphQL schema. This creates the bridge between GraphQL and gRPC protocols.
3. Implement gRPC Logic
   Build your gRPC implementation using the generated protobuf definitions. This implements the business logic for your GraphQL operations.
4. Configure Router
   Configure the Cosmo Router to understand how to communicate with your gRPC implementation.
5. Deploy and Test
   Deploy your setup and test the integration by making GraphQL queries that are translated to gRPC calls.

Motivation

Many companies see the value of GraphQL Federation but are hesitant to adopt it because they have existing systems that are incompatible, like legacy systems, REST APIs, SOAP, etc. gRPC integration solves this problem by making it easy to generate adapters between your Supergraph and existing systems. The system is designed with modern development tools in mind - define a GraphQL schema, provide an OpenAPI document, a SOAP WSDL, or even just some curl commands, and AI coding assistants can generate adapter code and tests in minutes. Thanks to the strongly-typed proto definition and built-in tooling, development becomes faster and more reliable.

Core Benefits

Simplify GraphQL Implementation

While everyone understands the value of “one schema, one query,” building and maintaining production-grade subgraphs across diverse environments remains challenging. Spec support, runtime performance, and type safety depend on your implementation quality.

Design with GraphQL, Implement with gRPC

Our approach combines GraphQL’s schema-first flexibility with gRPC’s performance and type safety. You can develop implementations in any language that supports gRPC while maintaining GraphQL’s benefits.

Proto-Based Code Generation

The strict typing and automatic code generation from Protocol Buffers (proto) definitions provides an immense productivity boost, especially in the era of generative AI. The generated proto-based gRPC code creates a strongly-typed foundation that AI tools can effectively understand and extend.

Strongly-Typed Integration

With gRPC integration, there’s no way to get around the proto definition. If the implementation compiles against the proto definition, you know it’s correct. This eliminates a whole class of integration issues.

Apollo Federation Compatibility

gRPC implementations are 100% compatible with existing Apollo Federation Subgraph implementations. You can use gRPC alongside existing subgraphs seamlessly.

No N+1 Problems

gRPC implementations leverage Cosmo Router’s DataLoader capabilities which batch requests by default, avoiding common performance pitfalls.

No Framework Lag

When new features are added to the GraphQL Federation specification, gRPC implementations can immediately take advantage of them since federation logic is handled within the Router.

LLM-Friendly

gRPC integration is a great fit for LLM-based applications. From a generated proto definition, an LLM can generate a gRPC service implementation in any supported language.

Benefits Over Traditional REST Integration

When compared to integrating REST APIs into GraphQL Federation, gRPC offers several advantages:

Efficient Communication

Binary protocol and HTTP/2 multiplexing provide better performance than traditional REST over HTTP/1.1, especially for high-frequency communication.

Automatic Code Generation

Generate protobuf definitions and mappings directly from your GraphQL schema, reducing development time and ensuring consistency.

Streaming Support

Native support for streaming data enables real-time capabilities and efficient handling of large datasets.

Contract-First Development

GraphQL schemas serve as the single source of truth for service contracts, with protobuf definitions generated automatically to ensure compatibility.

Streaming support is currently not yet supported for gRPC services in the router.

Architecture Overview

Development Workflow

This diagram shows how the wgc CLI generates the necessary artifacts for gRPC integration:

Explanation

As a developer, you start by defining a GraphQL Schema with your types and operations. The CLI uses this schema to generate the necessary protobuf definitions, mapping files and language-specific service implementations. You can then use the generated skeleton to implement your gRPC service. If you want to see how to get started, check out our Tutorial.

Runtime Execution

This diagram shows how the router processes GraphQL requests and communicates with gRPC services:

Explanation

At runtime, clients send GraphQL requests to the Cosmo Router. The router’s engine plans the operation and translates GraphQL into gRPC calls using the generated mapping files. The data loader batches requests to your gRPC services for optimal performance. Responses are translated back from protobuf to GraphQL format and assembled into the final client response.

In Short

gRPC integration into GraphQL Federation follows this pattern:

1. Schema Definition: You define GraphQL schemas that represent your gRPC interfaces
2. Code Generation: Cosmo tooling generates protobuf definitions and mappings from your GraphQL schemas
3. Router Configuration: The router is configured with the generated mappings to understand how to communicate with your gRPC implementations
4. Request Processing: When GraphQL queries are received, the router translates relevant portions into gRPC calls
5. Protocol Translation: The router handles the translation between GraphQL and gRPC protocols
6. Response Assembly: Results from gRPC calls are translated back to GraphQL and assembled into the final response

Implementation Options

Cosmo provides two main approaches for gRPC integration:

Router Plugins

• Local execution: Run as separate processes managed by the router
• Simplified deployment: Deployed alongside the router
• Lower latency: Direct inter-process communication
• Currently Go-only: Implementation language is limited to Go

gRPC Services

• Remote execution: Run as independent services anywhere in your infrastructure
• Language flexibility: Implement in any language that supports gRPC
• Independent scaling: Scale services based on their specific requirements
• Distributed architecture: Services can be deployed across different environments

Choosing Between gRPC Services and Plugins

This choice between gRPC Services and Router Plugins is central to Cosmo Connect’s design, giving you flexibility between simplicity and full control. When implementing gRPC integration in your GraphQL Federation, you have two main options: gRPC Services and Router Plugins. Each approach has distinct advantages that make them suitable for different scenarios.

When to Choose gRPC Services

• Language Flexibility: Implement services in any language that supports gRPC - Python, Java, C#, Node.js, Rust, and many others.
• Team Independence: Different teams can own and operate their services independently with their preferred technologies.
• Independent Scaling: Scale services based on their specific load patterns and resource requirements.
• Distributed Architecture: Deploy services across different environments, datacenters, or cloud regions.
• Microservices Pattern: Maintain existing microservices architecture and deployment practices.
• Independent Release Cycles: Services can have different release schedules and deployment pipelines.

When to Choose Router Plugins

• Simple Deployment: Deploy plugins alongside the router with minimal infrastructure complexity.
• High Performance: Achieve lower latency through direct inter-process communication.
• Go Development: Leverage Go’s performance and ecosystem for plugin development.
• Unified Operations: Manage deployment, monitoring, and lifecycle in a unified manner.

Decision Matrix

Roadmap

We’re actively working on addressing these limitations. Future releases will include:

• Enhanced Federation feature support
• Subscription support for real-time data
• Deep integration with the cosmo observability stack

For the most up-to-date information, check our GitHub repository.

Next Steps

gRPC Services

Router Plugins

gRPC Tutorial

Plugins Tutorial