Which languages can I use for Router Plugins?

Go and TypeScript via Bun. The CLI installs the Go compiler, protobuf compiler, and protoc plugins automatically. The Bun runtime (v1.2.15+) is a separate prerequisite for TypeScript plugins.

What happens if a plugin crashes?

Plugins run as separate processes with fault isolation. A plugin crash does not bring down the Router.

How do I update a plugin without downtime?

The Router supports hot-reload. Update the plugin binary and the Router reloads it without service interruption.

What does the Go SDK provide?

HTTP client with middleware support (auth, user-agent, custom headers), automatic OpenTelemetry tracing propagation from the Router through the plugin to downstream services, structured logging with context injection (surfaced through the Router's logger), and built-in gRPC health check support.

When should I use Router Plugins instead of gRPC Services?

Use Router Plugins for simple integrations where minimal latency and unified deployment matter. Use gRPC Services when you need language flexibility beyond Go and TypeScript, independent scaling, or distributed deployments.

Does the Go SDK handle distributed tracing automatically?

Yes. The Go SDK propagates OpenTelemetry trace context from the Router through the plugin to downstream HTTP calls without additional configuration.

Router Plugins | In-Process gRPC Extensions for Cosmo

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.

One deployment unit. No extra infrastructure.

Router Plugins

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

CLI scaffolds proto and project.

Scaffold

Run `wgc router plugin init` to generate the plugin project. The CLI creates the protobuf definitions, SDK wiring, and project structure.

02

Go or TypeScript (Bun).

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

Fault isolation, hot-reload.

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

Cloud registry or local.

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.

Start Free Read the Docs

Run integrations in-process with no extra infrastructure