Do I have to fork Cosmo Router to add custom logic?

No. You write Go code implementing the extension interfaces, then compile it into a custom router binary with a single build command.

How many lifecycle hooks can a single Cosmo Router module implement?

Up to six: RouterOnRequestHandler, RouterMiddlewareHandler, EnginePreOriginHandler, EnginePostOriginHandler, Provisioner, and Cleaner.

Can a custom module reject or short-circuit a request?

Yes. Implement RouterOnRequestHandler to either pass the request through or return an early error response.

Where does custom module configuration live in the router config?

In the router's YAML config file, mapped via struct tags.

When should I use custom Go modules vs. router header rules?

Use header rules for standard forwarding, renaming, and static values. Use custom modules when you need logic YAML can't express — custom authentication, caching, rate limiting, cost-based policies, or integration with internal systems.

Custom Go Modules for GraphQL Router | Cosmo by WunderGraph

The problem

Why teams bolt on proxies, scripting, or forks

Federated GraphQL needs gateway logic that talks to the rest of your platform. That rarely fits in a single hop, a sandboxed script, or a one-off fork.

External proxies add a network hop

A sidecar or Envoy filter in front of the router handles the custom logic, at the cost of an extra hop, another process to run, and metrics that live in two places.

Scripting languages limit what you can reach for

Lua, JavaScript, or sandboxed WASM filters cover basic shape-shifting, but they can't call your company's Go client library, your internal gRPC service, or the cache SDK your platform team already ships.

Forked gateways drift

Copying the router source to add a few hooks means inheriting every merge conflict forever. Upstream fixes stop being free.

Our solution

Add custom gateway logic without running a second process

Custom modules are Go packages linked into the router binary. Your code runs in the same process as routing and federation, so you can reuse internal clients and observability without adding another network hop or maintaining a fork.

Each interface hooks into a specific point

One module can implement several interfaces at once, and multiple modules can coexist; set priority when their relative order matters.
RouterOnRequestHandler runs as early as possible, before built-in auth and parsing.
RouterMiddlewareHandler runs after the operation is parsed, with access to the GraphQL operation and query plan stats.
EnginePreOriginHandler and EnginePostOriginHandler wrap each subgraph fetch and response.
Provisioner and Cleaner run at router start and shutdown for module lifecycle.
At request time, handlers fire in-process in the same goroutine as the request, with access to the full request context.

One binary. Native performance. Your libraries, in-process.

Custom modules

Before & After

Before Cosmo	With Cosmo
External proxy layer for custom logic	In-process Go module, zero network hop
Scripting language with limited reach	Full Go ecosystem and compiled performance
A single "on request" hook, workarounds for the rest	Six distinct hooks for precise lifecycle control
Hard to test: proxy plus router plus test harness	Plain Go: go test, pprof, delve all apply

Router extensibility

The six interfaces

Interface	When it runs
`RouterOnRequestHandler`	Earliest intercept, before auth and parsing
`RouterMiddlewareHandler`	After the operation is known, with query plan stats
`EnginePreOriginHandler`	Before each subgraph fetch
`EnginePostOriginHandler`	After each subgraph response
`Provisioner`	Module setup on router start
`Cleaner`	Module teardown on router shutdown

What a module can see

GraphQL operation name, type, hash, content
Query plan stats (subgraph fetch count, etc.)
Request context and per-request store
Subgraph name, ID, and URL (for pre/post origin hooks)
Authentication info (readable and modifiable)

How custom Go modules work

01

Compose behavior like middleware, but native Go.

Implement interfaces

Pick the hook point(s) needed. A module can implement more than one interface.

02

Config lives in router YAML, not scattered env vars.

Register the module

Register with the router. Set priority if order relative to other modules matters. Map YAML config values to struct fields with tags.

03

Ship one artifact, no sidecar fleet.

Build the router binary

Compile the router with your modules included. Output is a single binary.

04

pprof and delve see your code.

Handlers fire in-process

At runtime, each hook fires at its point in the request lifecycle in the same goroutine as the request, with access to the full request context.

Use cases

Patterns teams ship first

Auth, cache, cost controls, and headers at the gateway, without subgraph changes.

Custom authentication

Earliest stage

RouterOnRequestHandler runs before the router's built-in auth. Extract credentials, validate against the internal system, either let the request continue or return an early error.

Gateway-level caching

Pre / Post origin

EnginePreOriginHandler checks cache using the operation hash and query plan stats; on a hit it returns early and skips the subgraph fetch. EnginePostOriginHandler populates the cache after a miss.

Per-tenant rate limiting

After parse

RouterMiddlewareHandler reads operation details and QueryPlanStats, estimates cost based on subgraph fetch count, and enforces per-tenant budgets.

Destination-aware header transformation

Per subgraph

EnginePreOriginHandler reads ctx.ActiveSubgraph() and adds or rewrites headers on the outgoing request. No subgraph code changes.

Request header operations cover declarative cases; modules cover dynamic logic.

Requirements & operations

Build-time

Requirements

Go development environment
Router source access for building the custom binary
Familiarity with Go interfaces and the standard http.Handler pattern

Ops notes

Modules compile in; plan releases when router versions bump.
Use priorities to keep cross-module ordering predictable.

Prefer YAML and header rules when they suffice; reach for Go when you need real code paths.

Extend the router in Go today

Six hooks, one binary, zero extra hop. Free tier included.

Start Free Read the Docs

GraphQL Router Middleware in Go