Router Plugins | In-Process gRPC Extensions for Cosmo | WunderGraph - WunderGraph
Run integrations in-process with no extra infrastructure
Router Plugins run as local processes managed by the Router. The Go SDK includes an HTTP client, distributed tracing, and structured logging; TypeScript runs on Bun.
The problem
Separate subgraph services add overhead and latency
Every integration needs its own deployment pipeline, its own infrastructure, and its own network hop. That cost adds up before the first query runs.
Separate services mean separate deployments
Each integration needs its own CI/CD pipeline, container image, service mesh entry, and monitoring setup. That is significant overhead for what may be a thin adapter.
Network hops add latency
Every request from the Router to a remote subgraph crosses a network boundary. For latency-sensitive operations, that cost adds up per hop.
Observability requires manual wiring
Connecting distributed tracing and structured logging across custom subgraph implementations takes engineering time. Each service needs its own instrumentation.
Our solution
Plugins that run beside the Router
Router Plugins are separate processes that communicate with the Router via gRPC over IPC using HashiCorp's go-plugin framework. They run alongside the Router, not on the network. If a plugin crashes, the Router continues operating.
How Router Plugins integrate
- Scaffold the plugin with
wgc router plugin init. The CLI generates the project with proto definitions and SDK wiring. - Implement the plugin in Go or TypeScript (Bun). The Go SDK includes an HTTP client with middleware support, OpenTelemetry tracing, and structured logging. TypeScript plugins run on Bun without a bundled SDK.
- Build with
wgc router plugin build. The CLI compiles and packages the plugin. - The Router manages plugin lifecycle: startup, health checks, and hot-reload.
- Plugins communicate via gRPC over IPC. No network round trip. No separate deployment target.
- Push to the Cosmo Cloud Plugin Registry to deploy without re-deploying the Router.
Before & After
| Before Cosmo | With Cosmo |
|---|---|
| Deploy separate subgraph services for each integration | Run plugins alongside the Router with unified deployment |
| Manage multiple CI/CD pipelines and infrastructure | Single deployment unit with hot-reload support |
| Network latency between Router and subgraphs | Direct inter-process communication for minimal latency |
| Varying subgraph framework quality and spec compliance | Strongly-typed proto definitions guarantee correctness |
SDK capabilities
Go SDK
- HTTP client: fluent API with middleware support (auth, user-agent, custom headers), generic response handling, and automatic tracing integration.
- Distributed tracing: OpenTelemetry-based with automatic context propagation from Router through plugins to downstream services.
- Structured logging: integration with the Router's zap logger, context injection, and panic recovery with stack traces.
- Health checks: built-in gRPC health check protocol support.
How Router Plugins work in Cosmo Router
01
Scaffold
Run wgc router plugin init to generate the plugin project. The CLI creates the protobuf definitions, SDK wiring, and project structure.
02
Build
Implement the plugin in Go or TypeScript (Bun). The Go SDK provides HTTP client with middleware, OpenTelemetry tracing, and structured logging. TypeScript plugins require the Bun runtime (v1.2.15+).
03
Register
The Router manages plugin lifecycle: startup, health checks, and hot-reload. Plugins communicate over gRPC IPC. If a plugin crashes, the Router continues operating.
04
Deploy
Push to the Cosmo Cloud Plugin Registry or run locally. No additional infrastructure required. The Router handles plugin discovery and activation.
Capabilities
What Router Plugins provide
In-process execution, built-in observability, and zero infrastructure overhead.
HashiCorp go-plugin foundation
Built on the same framework that powers HashiCorp Vault and Terraform. Proven in production at scale.
Go SDK: HTTP client, tracing, logging
HTTP client with middleware support, automatic OpenTelemetry tracing propagation, and structured logging that surfaces through the Router's logger. All in one SDK.
TypeScript (Bun) support
TypeScript plugins run via Bun. Install the Bun runtime (v1.2.15+) to build and run them.
Fault isolation
Plugins run as separate processes. If a plugin crashes, it does not bring down the Router.
Hot-reload without downtime
Update plugins without service interruption. The Router manages the plugin lifecycle including reload.
Cosmo Cloud Plugin Registry
Push plugins directly to the platform. Deploy plugin updates without re-deploying the Router.
Deploy your first Router Plugin
Scaffold with the CLI, implement in Go or TypeScript, run alongside the Router.
FAQ
Router Plugins questions
- Which languages can I use for Router Plugins?
- What happens if a plugin crashes?
- How do I update a plugin without downtime?
- What does the Go SDK provide?
- When should I use Router Plugins instead of gRPC Services?
- Does the Go SDK handle distributed tracing automatically?
Deep dive in the Router Plugins documentation.