<article><h2>TLDR</h2><p>Cosmo Streams extends EDFS by moving subscription authorization, per subscriber event filtering, and mutation side validation into the router itself. Instead of building custom subscription services, Streams adds three lifecycle handlers that run when a subscription starts, while events are in flight, and when mutations publish events.</p><p>This gives teams control over who can subscribe, what data each subscriber receives, and what events are allowed into the system, without changing schemas or event infrastructure. The result is a policy-aware GraphQL subscription system that scales without extra services.</p><p>WunderGraph Hub is our new collaborative platform for designing, evolving, and shipping APIs together. It’s a design-first workspace that brings schema design, mocks, and workflows into one place.</p><h2>Why Cosmo Streams Exists</h2><p>EDFS solved a basic problem: connecting your internal event driven architecture to GraphQL subscriptions without building a separate translation layer. The router connects to your message broker, listens for events, and publishes them as subscriptions. That flow works and remains the foundation of how Cosmo Streams operates.</p><p>Cosmo Streams extends that model by letting you run subscription authorization, per-subscriber event filtering, and mutation side validation directly inside the router. Instead of pushing this logic into custom subscription services or resolver layers, Streams introduces controlled extension points in the event flow itself.</p><p>But as customers started using EDFS, they ran into limitations. Three problems in particular were identified. They all revolve around the need for more flexibility when dealing with events on the router. Cosmo Streams addresses these by adding three new handlers to the custom module system.</p><p>You can think of these handlers as three stages in the event lifecycle: logic that runs when a subscription starts, logic that runs while events are in flight to subscribers, and logic that runs when mutations publish new events.</p><h2><strong>Problem 1: &quot;You Can Subscribe to Everything or Nothing&quot;</strong></h2><p>With EDFS, subscription access was all-or-nothing. A user who passed authentication could subscribe to any available topic, with no way to scope or restrict access to individual subscriptions or events.</p><p>You could try to solve this outside the router by introducing custom subscription services, resolver-level checks, or post-processing layers. In practice, this means managing connection state, duplicating authorization logic, and fanning out events manually, all while keeping performance under control.</p><p>Cosmo Streams moves this logic into the router itself, where subscription context, connection details, and event flow already exist.</p><p>The problem is that many teams need finer-grained control. Different users should see different streams, even if they're authenticated in the same way. An admin might need access to all <code>order</code> updates. A regular user should only see their own orders. With EDFS, that kind of role-based access control on subscriptions wasn't possible.</p><h3><strong>The Solution: SubscriptionOnStart Handler</strong></h3><p>With Cosmo Streams, the router can run custom logic when a client subscribes using the <code>SubscriptionOnStart</code> handler.</p><p>This means you can grant access to specific streams based on custom logic. You have access to the token data, HTTP headers, connection details, and GraphQL operation variables. Basically, all the context you need to make authorization decisions.</p><p>In the demo example, users can create orders and subscribe to order updates. When a client subscribes, the <code>SubscriptionOnStart</code> handler validates the JWT and its issuer to decide whether the subscription should be allowed.</p><p>Once the subscription is established, the <code>OnReceiveEvent</code> handler determines which events each subscriber actually receives. Two users can subscribe to the same GraphQL subscription but receive different events based on their permissions. This kind of per-subscriber event filtering was not possible with EDFS alone.</p><h2><strong>Problem 2: &quot;New Subscribers See Nothing Until the Next Event&quot;</strong></h2><p>EDFS is purely event driven. A client subscribes, then receives future events as they occur. This is efficient and straightforward, but in some scenarios it can create a UX problem.</p><p>Imagine a user joining a live soccer match stream. The game is already 1-0. With the old EDFS approach, they see nothing until the next goal drops, which could be 30 minutes away. The client is connected, but they have no context about the current state of the game.</p><h3><strong>The Solution: SubscriptionOnStart Handler (Again)</strong></h3><p>The same <code>SubscriptionOnStart</code> handler that handles authorization can also send data immediately when a subscription starts.</p><p>When a client subscribes to a soccer match that is already in progress with a score of 1-0, the router can query the current score and update the client immediately. The client sees the correct score, then continues receiving updates as future goals occur. They get the initial state first, then the event stream.</p><p>That same handler solves two different problems. It runs when someone subscribes, and you can use it for access control, for sending initial data, or both.</p><h2><strong>Problem 3: &quot;All Subscribers Get Identical Events&quot;</strong></h2><p>With EDFS, when an event arrived from the broker, it was fanned out to all subscribers in the same way. Everyone got the same event with the same data. This kept the system simple and performant, but some teams needed to filter or modify events based on individual subscriber permissions.</p><p>The challenge appears when you have two users subscribed to the same topic, but they should receive different data. Maybe one is an admin who should see everything. The other is a regular user who should only see events they're allowed to see.</p><h3><strong>The Solution: OnReceiveEvent Handler</strong></h3><p>The <code>OnReceiveEvent</code> handler runs whenever a new event is received from the message broker, before the router resolves it. It executes once per subscriber, which means you can make decisions per subscriber about what gets delivered.</p><p>In the demo, when a user subscribes to order updates, they only receive events from orders they created. The handler filters events based on the user's token. It matches the customer ID from the token against the customer ID in the order event. Two users subscribe to the same subscription but receive different events.</p><p>This filtering happens for each subscriber. If you have 30,000 subscribers, the handler runs 30,000 times, once for each subscriber. The router executes these handlers asynchronously by default, with configurable concurrency limits to avoid memory spikes when processing large numbers of subscribers.</p><h2><strong>The Mutation Side: OnPublishEvent Handler</strong></h2><p>Subscription filtering controls what leaves the system. Mutation side validation controls what enters it. <code>OnPublishEvent</code> completes the loop by enforcing rules before events are emitted into your event driven architecture.</p><p>The <code>OnPublishEvent</code> handler runs when a mutation explicitly publishes an event through Cosmo Streams, before the router emits that event to the message system. This lets you validate or enrich data before it enters your internal event flow.</p><p>In the demo, a user can create an order through a mutation. The handler inspects the mutation data and validates that the user is creating an order for themselves, not for another user. It matches the customer ID from the token against the customer ID in the mutation input.</p><p>Without this handler, it was very hard to do these kinds of checks at the router level. EDFS just took the mutation data, transformed it into an event, and sent it out. Now you have an additional layer of validation before events get emitted into your system.</p><h2><strong>How the Handlers Work</strong></h2><p>These three handlers are implemented through the <a href="https://cosmo-docs.wundergraph.com/router/cosmo-streams/custom-modules">Custom Module</a> system. Custom modules aren't new on the router; they already exist for other things. What we did with Cosmo Streams was add three new handler types to help tackle customization and compliance needs.</p><p>All handlers are optional. If a handler is not defined, the router falls back to standard EDFS behavior with no additional logic applied.</p><p>You write this logic in Go as custom modules that compile with the router itself. The router processes your custom code at three extension points in the event flow:</p><ul><li>When subscriptions start: <code>SubscriptionOnStart</code></li><li>When events are received from the broker: <code>OnReceiveEvent</code></li><li>When mutations publish events: <code>OnPublishEvent</code></li></ul><p>The handlers run inside the router. You're not building a separate service; you're shaping the router's behavior at specific points where you need custom logic.</p><h2><strong>Building on EDFS</strong></h2><p>Streams does not require changes to your GraphQL schema or subscription configuration. Existing EDFS setups continue to work as before, with handlers applied only where additional control is needed.</p><p>What Streams adds is flexibility. Instead of requiring teams to move logic into separate services, Streams allows custom logic to run inside the router itself at these three extension points.</p><h2><strong>Performance Considerations</strong></h2><p>Every subscriber needs to be processed individually on the <code>OnReceiveEvent</code> handler. So if you have 30,000 subscribers, this handler runs 30,000 times per received event batch.</p><p>If you do an API call per handler run, that's 30K API calls with 30K subscribers for each event the handler processes. As Cosmo Streams uses Custom Modules, which are essentially Go functions, handlers can use in-process caches or external caches. This lets you run asynchronous routines and look up pre-computed data instead of calling upstream systems for every subscriber.</p><p>From the above, it should be clear that your handlers need to stay performant. Don’t do expensive or potentially blocking operations per subscriber. We already handle concurrency and memory management, but the handler logic itself must be efficient. Where additional data is required, use caching or move API calls out of the hot path.</p><p>For example, performing external network calls inside <code>OnReceiveEvent</code> can quickly become expensive at scale. With thousands of subscribers, a single event could trigger thousands of outbound requests.</p><h2><strong>Getting Started</strong></h2><p>The <a href="https://github.com/wundergraph/cosmo-streams-demo/tree/initial">demo repository</a> shows all three handlers in action with a working example of the order system I mentioned. You can see how <code>SubscriptionOnStart</code> validates JWTs, how <code>OnPublishEvent</code> ensures users can only create orders for themselves, and how <code>OnReceiveEvent</code> filters events so each customer only sees their own orders.</p><p>The documentation explains how to configure Streams and highlights patterns for authentication, filtering, and initial data handling.</p><p>For teams with existing event driven architectures, Cosmo Streams offers a way to expose those events through GraphQL subscriptions without building translation infrastructure around the router. You connect the router directly to your message broker and add custom logic where you need it.</p><p>Cosmo Streams turns GraphQL subscriptions from a broadcast pipe into a policy-aware event system, with control at subscribe time, in-flight, and at publish time.</p><hr><hr></article>

streams-handlers-and-solutions-banner.png

Cosmo Streams adds three router handlers to enable subscription authorization, initial state delivery, and per-subscriber event filtering without building custom infrastructure.

Three Handlers for Event Driven GraphQL Subscriptions

<article><h2>TLDR</h2><p>Cosmo Streams lets teams expose events from their event driven systems through GraphQL subscriptions without building or operating a separate translation layer. The Cosmo Router connects directly to the message broker. When an event arrives, it fetches the required data from subgraphs, handles subscription delivery, and provides router level hooks for authorization, filtering, and event handling.</p><h2>Why GraphQL Subscriptions Usually Require a Translation Service</h2><p>Many teams already run event driven systems internally. When something happens, an event is emitted into that system, and other parts of the infrastructure react to it.</p><p>The challenge appears when the same internal events need to be exposed to clients over GraphQL.</p><p>In these setups, you're using a message broker or event store (like <a href="https://kafka.apache.org/">Kafka</a>, <a href="https://nats.io/">NATS</a>, or <a href="https://redis.io/">Redis</a>) to collect and redistribute events. Cosmo Streams is designed to integrate with the same brokers you're already using.</p><p>In GraphQL, streaming updates to clients is most commonly handled with subscriptions. A client subscribes to an entity in the schema and selects one or more fields on it, then receives updates when relevant events occur.</p><p>When those events already exist internally, subscriptions are an obvious way to expose them. In practice, however, teams often introduce an additional layer to handle subscriptions.</p><h2>Why Subscriptions Are Hard</h2><p>Classic GraphQL subscriptions require a translation layer to manage connections and fan out. Cosmo Streams handles this at the router.</p><p>The root issue is that classic GraphQL <a href="https://graphql.org/learn/subscriptions/">subscriptions</a> introduce a GraphQL specific translation layer between event driven systems and consumers. This layer must manage connections, execution, and fan out, forcing teams to adapt their event streams to GraphQL’s subscription model rather than letting GraphQL integrate directly with existing event infrastructure.</p><p>To work around this mismatch, teams often build a separate service whose role is to consume internal events, translate them into GraphQL subscription payloads, and push updates to connected clients. This bridge service becomes its own codebase that you have to build, deploy, scale, and maintain.</p><p>In a classic GraphQL federation setup, a subgraph must implement the subscription itself. That means the subgraph service is responsible for managing stateful, long running client connections, dealing with WebSockets and subprotocols, fetching and merging data from various sources to form correct responses, handling fan out, and managing timeouts and network issues. All of this makes GraphQL subscriptions notoriously difficult to build and operate at scale.</p><p>Cosmo Streams removes this responsibility from subgraphs entirely by handling connections, subscription state, data fetching, merging, and delivery at the router level. Subgraphs do not need to implement subscriptions, WebSockets, or long running connections.</p><h2>What Cosmo Streams Is and How It Works</h2><p>Cosmo Streams runs in the <a href="https://wundergraph.com/router-gateway">Cosmo Router</a>.</p><p>Instead of placing a separate service between the event system and GraphQL subscriptions, the router connects directly to the message broker. It listens for events and publishes them through the GraphQL API as subscriptions.</p><p>In addition to consuming events, Cosmo Streams can also publish them. Events can be emitted through GraphQL mutations backed by Cosmo Streams, allowing GraphQL to act as both a consumer and a producer in an event driven architecture.</p><p>The router resolves client GraphQL queries by fetching the required data from subgraphs via GraphQL HTTP requests. Subgraphs remain completely stateless while the router owns connection management, subscription state, and delivery to clients.</p><p>To improve efficiency, the router deduplicates client connections, broker connections, and subgraph fetches. It also uses <a href="https://cosmo-docs.wundergraph.com/router/cosmo-streams#efficiency,-cpu-&amp;-memory-consumption-epoll/kqueue">kqueue and epoll</a> to optimize resource handling.</p><h2>Cosmo Streams Customization</h2><p>Cosmo Streams can be customized using router hooks implemented as <a href="https://cosmo-docs.wundergraph.com/router/cosmo-streams/custom-modules">Custom Modules</a>. These modules are written in Go and compiled directly into the Cosmo Router, allowing teams to add custom behavior without introducing a separate service.</p><h3><a href="https://cosmo-docs.wundergraph.com/router/cosmo-streams/custom-modules/subscription-on-start">SubscriptionOnStart</a></h3><p>This runs custom logic when a client starts a subscription. This is primarily used for authorization, ensuring the client is allowed to open a long-running stream before any events are delivered. The handler can reject a subscription during connection initialization based on information such as HTTP request details or authentication token data.</p><p>It can also send the initial state. For example, when a user joins the stream for a live football match that is already 1–0, the router can immediately send the current score without waiting for the next event.</p><h3><a href="https://cosmo-docs.wundergraph.com/router/cosmo-streams/custom-modules/on-receive-event">OnReceiveEvent</a></h3><p>When an event arrives from the broker, this handler runs per subscriber to filter or modify what each receives. Two users subscribing to the same stream can receive different data, for example, based on their permissions. An admin might see all order updates while a regular user sees only their own orders.</p><h3><a href="https://cosmo-docs.wundergraph.com/router/cosmo-streams/custom-modules/on-publish-event">OnPublishEvent</a></h3><p>This handler runs custom logic when a Cosmo Streams-backed mutation publishes an event. It executes before the event is emitted to the underlying message system, allowing validation or enrichment as part of the publish flow.</p><p>For example, you can validate that a user is creating an order for themselves, not on behalf of another user, before the event enters your internal event stream.</p><h2>What Cosmo Streams Means for Platform Teams</h2><p>For platform teams, the event system is already in place and is a natural fit for sending events via GraphQL subscriptions. However, adding another service solely to translate events into GraphQL subscriptions means owning an additional service and managing long running, stateful connections with all their drawbacks, along with everything else required to bridge the gap between an internal event and a working GraphQL subscription.</p><p>Cosmo Streams uses the router, which already hosts the GraphQL API, as the integration point. Instead of building and maintaining a separate bridge, you connect the router directly to the event system and add custom logic where you need it.</p><p>When subscriptions run at scale, things like concurrency, performance optimizations, GraphQL over WebSockets, and event translation become your responsibility. By keeping subgraphs stateless, Cosmo Streams works cleanly with serverless and short lived runtimes where long running connections are impractical.</p><p>These are hard problems that Cosmo Streams already accounts for, so you do not have to build and operate that layer yourself.</p><h2>From Event Driven Federated Subscriptions to Streams</h2><p>Cosmo Streams builds on <a href="https://cosmo-docs.wundergraph.com/router/cosmo-streams">Event Driven Federated Subscriptions (EDFS)</a>. EDFS established the core flow: router connects to broker, listens for events, delivers them via GraphQL subscriptions. The main limitation of EDFS was coarse grained control. The available options for customizing authorization and filtering were limited.</p><p>That same broker-to-router-to-subscription flow remains the basis of how Streams works. What Cosmo Streams adds is the three handlers described above. This gives you control over subscription behavior without moving logic into separate services.</p><p>For teams already using EDFS, Streams preserves the same schema and EDFS directive model and extends it with handlers at the router level. Teams already using EDFS can upgrade to Streams and add handlers without changing their existing GraphQL schema.</p><h2>Getting started</h2><p>The <a href="https://github.com/wundergraph/cosmo-streams-demo/">demo repository</a> shows how the three handlers work together in a simplified order management system with authentication and filtering.</p><p><a href="https://cosmo-docs.wundergraph.com/router/cosmo-streams">Documentation</a> explains how to configure Streams and highlights patterns for authentication, filtering, and initial data handling.</p><p>For teams with existing event driven architectures, Cosmo Streams offers a way to expose those events through GraphQL subscriptions without needing to deal with the technical hurdles that come with them.</p></article>

streams-without-hurdle-banner.png

Cosmo Streams lets teams expose events through GraphQL subscriptions without the need to bring their own code. Events flow directly from the message broker through the Cosmo Router to clients.

Cosmo Streams: GraphQL Subscriptions Without the Hurdle

<article><h2>TLDR;</h2><p>Cosmo Connect now lets you extend the router entirely in TypeScript. If you already work in a TypeScript-heavy codebase, you no longer need to introduce Go or maintain a separate microservice just to add custom logic to your graph. The plugin runs inside the router, is published through Cosmo Cloud, and participates in schema checks like any other subgraph.</p><h2>Getting Started with TypeScript Plugins</h2><p>We’ve released <a href="https://cosmo-docs.wundergraph.com/router/gRPC/plugins/ts-plugin/overview">TypeScript plugin</a> support for Cosmo Connect. You can now write plugins in TypeScript and load them directly into the router instead of running a separate service. This makes it easier to expose small pieces of logic, legacy API calls, or internal service integrations behind your GraphQL contract.</p><p>Until now, Cosmo Connect router plugins were only available in Go. That’s fine if your team already writes Go, but it can be a blocker if you don’t. Most teams already have people writing TypeScript every day, so adding TS support makes the plugin workflow accessible to a lot more users.</p><p>A common pattern we see is teams wanting to expose a small piece of logic or wrap a legacy REST API without spinning up another service. With a TypeScript plugin, you can model a GraphQL type, call the internal API, transform the response, and expose it through the router with minimal overhead. It behaves like a subgraph but without the operational cost of deploying one.</p><h2>Why TypeScript Plugins Matter</h2><p>TypeScript plugins don’t introduce new capabilities on top of Go plugins. They make the same plugin workflow available to more teams. From the platform’s point of view, this feature is mainly about adoption and accessibility: if your engineers are already comfortable in TypeScript, they can start using plugins immediately without needing to learn Go first.</p><p>In a typical federated setup, each subgraph is its own service with its own deployment. With router plugins, you can move some of that logic into the router itself. This is especially useful if you want to create a new &quot;subgraph&quot; but don't want to deploy an entire service just to do it, or if you have a legacy system that does not speak GraphQL and you want to use router plugins to bridge that gap.</p><p>When initializing a plugin, you can now pass in <code>ts</code> as a language option, for example <code>wgc router plugin init planets --language ts</code>.</p><p>When you publish the plugin and update the subgraph, it goes through the same composition and schema checks as everything else in Cosmo. There are no extra checks specific to TypeScript plugins.</p><p>Like with Go plugins, TypeScript plugins are supported in the Cosmo Cloud Plugin Registry, which means you can push plugins directly to Cosmo Cloud, and it will be pulled by all of your running router instances.</p><h2>Why TypeScript shipped after Go</h2><p>Cosmo Connect's plugin story started in Go. The router itself is written in Go, and we use HashiCorp's <code>go-plugin</code> library under the hood to load and manage plugins. That setup is very &quot;batteries included&quot; for Go: most of the low-level mechanics are already handled for us.</p><p>TypeScript support took longer because there’s no equivalent, fully packaged runtime for TS plugins. We did more of the plumbing ourselves to make TypeScript plugins feel as integrated as Go plugins, which is why Go shipped first.</p><p>If you're curious, our CEO Jens wrote about the choice to use HashiCorp's <code>go-plugin</code> in <a href="https://wundergraph.com/blog/generative-api-orchestration">REST in Peace-Connectors Were Never the Right Supergraph Abstraction</a>.</p><h2>Initializing a TypeScript plugin</h2><p>Here is a quick example of what it might look like to implement a TypeScript plugin. For a more in-depth walkthrough, see the <a href="https://cosmo-docs.wundergraph.com/tutorial/using-grpc-plugins">full plugin tutorial in our docs</a>.</p><p>You start by initializing a Cosmo Connect TypeScript plugin using our CLI. This sets up the basic scaffolding which you can build upon.</p><pre>wgc router plugin init planets --language ts
</pre><p>Cosmo Connect works by generating protobuf definitions from your GraphQL schema. Upon scaffolding the plugin, you still need to generate the protobuf definitions. You can run the following command to generate the protobuf definitions from the GraphQL schema as well as generate the protobuf code.</p><pre>wgc router plugin generate planets
</pre><p>After this, you have a minimal plugin project with a basic TypeScript plugin server. You can now start editing the GraphQL schema inside the plugin directory.</p><p>After running the above two commands, you should have the following project structure:</p><pre>plugin
├── Dockerfile
├── generated
│   ├── mapping.json
│   ├── service.pb.ts
│   ├── service.proto
│   ├── service.proto.lock.json
│   └── service_grpc.pb.ts
├── package.json
├── tsconfig.json
├── Makefile
├── README.md
├── patches
└── src
	  ├── plugin.ts
	  ├── plugin.test.ts
	  ├── plugin-server.ts
	  └── schema.graphql
</pre><p>As mentioned earlier, the <code>hashicorp-go</code> library provides helpers for initializing a plugin server. We implemented similar helpers ourselves in <code>plugin-server.ts</code>, which includes:</p><ul><li>Initializing gRPC health checks</li><li>Initializing the handshake between the router and plugin</li></ul><p>The <code>plugin.ts</code> file serves as the entrypoint for your plugin. This is also where you will implement the RPC handlers like <code>queryHello</code> and the new <code>queryPlanet</code> method.</p><h2>Adding a GraphQL schema</h2><p>Next, update the schema inside the plugin directory:</p><pre>type World {
  &quot;&quot;&quot;
  The ID of the world
  &quot;&quot;&quot;
  id: ID!
  &quot;&quot;&quot;
  The name of the world
  &quot;&quot;&quot;
  name: String!
}

type Planet {
  name: String!
  hasHumans: Boolean!
  hasDogs: Boolean!
}
</pre><p>Any time you change these types, you need to regenerate the protobuf definitions so the plugin code has access to the new fields and operations.</p><h2>Generating Protobuf Types</h2><p>After updating the schema, we need to regenerate the protobuf types:</p><pre>wgc router plugin generate planets
</pre><p>This uses our internal tool <code>protographic</code> to compile the schema into protobuf definitions the router understands.</p><p>You can see this by opening <code>service.proto</code> in the generated proto directory before and after running the command.</p><p>Before running <code>generate</code>, the proto file only contains the original <code>World</code> and <code>hello</code> RPC definitions. After running it, the new <code>Planet</code> message and RPC (<code>QueryPlanet</code>) appear in <code>service.proto</code>.</p><h2>Implementing the Plugin Logic</h2><p>You implement both of these RPC handlers inside <code>src/plugin-server.ts</code>, alongside the existing <code>QueryHello</code> handler.</p><p>The existing hello RPC:</p><pre>QueryHello: (call, callback) =&gt; {
  const name = call.request.getName();
  const currentCounter = Atomics.add(counterArray, 0, 1) + 1;

  const world = new World();
  world.setId(&quot;&quot; + currentCounter);
  world.setName(&quot;Hello from PlanetsService plugin &quot; + name);

  const response = new QueryHelloResponse();
  response.setHello(world);

  callback(null, response);
},
</pre><p>Then add the new planet RPC for <code>planet: Planet!</code>:</p><pre>queryPlanet: (call, callback) =&gt; {
  const planet = new Planet();
  planet.setName(&quot;Jupiter&quot;);
  planet.setHasHumans(true);
  planet.setHasDogs(false);

  const response = new QueryPlanetResponse();
  response.setPlanet(planet);

  callback(null, response);
}
</pre><p>This is all the business logic. The router will convert the protobuf response back into GraphQL automatically.</p><p>In a real application, this is where you'd call an internal HTTP service, legacy API, or database.</p><h2>Building the Plugin</h2><p>Build the plugin:</p><pre>wgc router plugin build planets
</pre><p>A successful build produces a plugin artifact, which you can verify by looking in the <code>bin</code> folder of the plugin. It should contain a binary, whose name will depend on your OS and architecture. For example, if you ran the <code>build</code> command on an M1 Mac, the binary name would be <code>darwin-arm64</code>.</p><h2>Publishing the plugin</h2><p>The next step is to publish the plugin to Cosmo Cloud so that your router can pull and use it.</p><p>Publish it to Cosmo Cloud:</p><pre>wgc router plugin publish planets -n &lt;yourNamespace&gt;
</pre><p>This uploads the plugin to Cosmo Cloud for the specified namespace.</p><p>Then update the subgraph metadata:</p><pre>wgc subgraph update planets -n &lt;yourNamespace&gt; --label team=A
</pre><p>Updating the subgraph metadata triggers routers in the namespace to reload and pull the new plugin, so the new <code>planet</code> field becomes part of the schema they serve.</p><h2>Querying the router</h2><p>Once the router reloads and pulls the updated plugin after the subgraph update, the <code>planet</code> field appears in the playground schema.</p><pre>{
  planet {
    name
    hasDogs
    hasHumans
  }
}
</pre><p>It returns:</p><pre>{
  &quot;data&quot;: {
    &quot;planet&quot;: {
      &quot;name&quot;: &quot;Jupiter&quot;,
      &quot;hasDogs&quot;: false,
      &quot;hasHumans&quot;: true
    }
  }
}
</pre><h2>Schema Checks and Observability</h2><p>When you publish the plugin and update the subgraph:</p><ul><li>Normal composition rules apply</li><li>No extra checks are required for TypeScript plugins</li></ul><p>For observability:</p><ul><li>You can test your plugin logic directly in the Playground</li><li>TypeScript plugins currently don’t have built-in tracing</li></ul><h2>Conclusion</h2><p>A good first experiment is to create a TypeScript plugin that wraps a single REST endpoint. Define the GraphQL type, map it in your handler, publish the plugin through Cosmo Cloud, update the subgraph metadata, and query it in the Playground. This gives you end-to-end familiarity with the workflow in a real environment.</p><p>That’s the full flow: define the schema, generate the protobufs, implement the handlers in TypeScript, build, publish, and the router reloads automatically once the update completes. This makes it much easier to fold small pieces of logic or legacy services into your graph without standing up another subgraph.</p><p>For a more in-depth look at building plugins, check out the <a href="https://cosmo-docs.wundergraph.com/tutorial/using-grpc-plugins">full plugin tutorial</a> in our docs.</p><hr><hr></article>

typescript-plugins-banner.png

Cosmo Connect now supports TypeScript router plugins, allowing developers to write plugin logic in TypeScript and load it directly into the GraphQL federation router without deploying separate services.

TypeScript Plugin Support for Cosmo Connect

<article><p>Cosmo already supports subgraph checks. They help you catch breaking changes and see lint issues before you publish a subgraph. But several customers asked for something more. They wanted to run their own checks with rules that aren't included by default.</p><p>That is why we added subgraph check extensions as an add-on to the normal checks. Cosmo keeps doing what it already does, and your service adds its own logic.</p><h2>Where the Idea Came From</h2><p>This began because customers wanted the ability to run their own checks. Our built-in lint rules don't always include everything a team cares about. This includes naming conventions, casing rules, or patterns for object and enum names that are not included by default.</p><p>Previously, teams had to ask us to implement those rules, but now they can implement that logic on their own systems.</p><p>Cosmo already has all the data that is necessary for this. The subgraph check knows the composed schema and the context for the run. However, what we were missing was a clean way to send that information to an external service. Extensions provide that.</p><p>That’s what led us to build subgraph check extensions as an add-on to the existing checks.</p><p>This feature is part of Cosmo and is available under the enterprise license.</p><h2>What Subgraph Check Extensions Do</h2><p>When a subgraph check runs, Cosmo sends a request to your configured endpoint. Your service then receives the data, runs its own rules, and returns a response.</p><p>The request happens in <strong>two</strong> stages.</p><p><strong>Stage one sends metadata for the check.</strong> This includes the organization, namespace, subgraph, who triggered the check, and a temporary URL. That URL points to a file with the SDL and is available for five minutes. This is helpful for large schemas.</p><p>Your service downloads the file, performs its checks, and prepares the result.</p><p><strong>Stage two is Cosmo displaying that result.</strong> If your service returns errors, they will appear alongside the normal lint issues. If something goes wrong - an incorrect endpoint, invalid response, or wrong status code - it will be shown in the check details.</p><p>Cosmo is expecting a <code>200</code> or <code>204</code> status code.</p><ul><li>A <code>200</code> code is validated against the expected response shape.</li><li>A <code>204</code> code means the check succeeded and no further action is required.</li></ul><p>Any other status code is considered a failure.</p><p>You can find the full <a href="https://cosmo-docs.wundergraph.com/studio/sce/request-payload-structure">request</a> and <a href="https://cosmo-docs.wundergraph.com/studio/sce/response-structure">response</a> structure in the documentation.</p><h2>Configuring an Extension in Cosmo Studio</h2><p>Below is an example of how the feature looks when enabled for a namespace:</p><p>The configuration includes:</p><h3>Endpoint</h3><p>The URL where Cosmo sends <code>POST</code> requests.</p><h3>Secret Key</h3><p>This is used to generate an HMAC signature (<code>X-Cosmo-Signature-256</code>) so you can verify the request came from Cosmo.</p><h3>Included Fields</h3><p>You will choose what information gets sent:</p><ul><li>Composed SDL</li><li>Lint warnings and errors</li><li>Graph pruning warnings and errors</li><li>Schema changes</li><li>Affected operations</li></ul><p>These match the data options shown in the UI.</p><h2>How It Works in Practice</h2><p>The flow works as follows:</p><ol><li>Register an endpoint.</li><li>Choose what data Cosmo sends.</li><li>Run a subgraph check as usual.</li><li>Cosmo triggers the extension and displays the result.</li></ol><p>If the file is incorrect, the check fails. After correcting it, the extension runs normally. If there is an error, Cosmo displays that error as a lint issue.</p><p>If the endpoint is not configured correctly, the check details show the metadata, the URL, the response, and any failure information. You can see the same error message in both the CLI output and the checks page.</p><h2>Real Examples</h2><p>Below are examples of rules your team can implement:</p><h3>Naming and casing rules</h3><p>For example:</p><ul><li>A field name matches a specific case.</li><li>A type name ends with <code>Object</code>.</li><li>An enum ends with <code>Enum</code>.</li></ul><p>These are not included by default, so a team would implement these checks in their own service and return an error when something doesn't match.</p><h3>LLM-based rules</h3><p>Because the composed SDL file is provided, a team can send it to an LLM, and if the model finds something they consider wrong, their service can fail the check based on that.</p><h3>Any backend</h3><p>Teams can use TypeScript, ASP, C, PHP, Go, or whatever backend they already run. Cosmo sends an HTTP request and waits for the response.</p><h2>Verifying the Request</h2><p>To ensure the data comes from a trusted source, an HMAC signature is included in the <code>X-Cosmo-Signature-256</code> header.</p><p>When you configure the extension, you need to provide a secret key. Your server computes the signature and compares it with the header.</p><p>Here is an example from the docs:</p><pre data-language="javascript">import crypto from 'crypto'

function verifySignature(body, receivedSignature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')

  return computedSignature === receivedSignature
}

// Usage:
const isVerified = verifySignature(
  JSON.stringify(req.body),
  req.headers['x-cosmo-signature-256'],
  YOUR_SECRET
)
</pre><p>A matching signature confirms the request was generated by Cosmo and not altered in transit.</p><h2>Permissions and Scope</h2><p>To set up an extension, you need to be an admin, a developer admin, or a namespace admin. To see the results, you only need access to the graph or subgraph.</p><p>This keeps teams separated from each other. If someone cannot see a graph, they cannot see its checks.</p><p>Extensions do not change permissions, they only add a way for your own logic to run during a subgraph check.</p><h2>Final Thoughts</h2><p>Subgraph check extensions let teams add checks that Cosmo does not include by default. Cosmo keeps doing its normal work, and your service adds whatever rules you need.</p><p>For more details, see the documentation on <a href="https://cosmo-docs.wundergraph.com/studio/subgraph-check-extensions">subgraph check extensions</a></p><hr><hr></article>

subgraph-check-extensions-banner.png

Cosmo now supports subgraph check extensions, allowing teams to add custom validation rules to their subgraph checks. Cosmo runs its normal linting and schema checks, and your service adds any additional logic through a secure external endpoint.

Blog

Three Handlers for Event Driven GraphQL Subscriptions

Cosmo Streams: GraphQL Subscriptions Without the Hurdle

TypeScript Plugin Support for Cosmo Connect

Extending Subgraph Checks in Cosmo