Streams · Event-Driven (EDFS)

Stateless subgraphs, event-driven subscriptions, any scale

Connect the Router to Kafka, NATS, or Redis. Subgraphs publish events and serve HTTP. The Router handles all subscription state.

Kafka, NATS JetStream, and Redis Pub/Sub. Serverless compatible.

Available onFreeProEnterprise

The problem

Traditional GraphQL subscriptions push state into every subgraph

WebSocket connections, subscription loops, heartbeat handling: all of this ends up in subgraphs that should be stateless services.

WebSocket connections make subgraphs stateful

Each active subscription requires a long-lived connection in subgraph memory. Lambda functions and Cloud Run containers cannot maintain these connections. Serverless deployments become impossible.

Three connections per client

Client to Router, Router to Subgraph, and internal subgraph connection state. At scale, this connection overhead consumes memory that should go to actual workloads.

Subscription logic in every subgraph

WebSocket servers, subscription loops, heartbeat handling, reconnection logic: each subgraph must implement and maintain all of this independently.

Our solution

The Router subscribes. Subgraphs stay stateless.

Cosmo Streams connects the Router directly to your message broker. Subgraphs publish events when data changes. The Router determines which client subscriptions are affected, deduplicates fetch work, and pushes updates over WebSocket, SSE, or Multipart HTTP.

How Cosmo Streams works

  1. Add EDFS directives to your subgraph schema. Map subscription fields to Kafka topics, NATS subjects, or Redis channels using @edfs__kafkaSubscribe, @edfs__natsSubscribe, or @edfs__redisSubscribe.

  2. Configure the Router with your message broker connection. The Router subscribes to the configured topics.

  3. Backend services publish events to the message broker when data changes. Subgraphs handle only plain HTTP requests.

  4. When an event arrives, the Router identifies affected client subscriptions and deduplicates fetch requests.

  5. The Router fetches updated data from subgraphs via plain HTTP and broadcasts results to clients.

  6. Clients receive updates over WebSocket, SSE, or Multipart HTTP. Subgraphs never hold WebSocket connections.

Subgraphs emit events. The Router does the rest.

Cosmo Streams (EDFS)

Before & After

Before Cosmo StreamsWith Cosmo Streams
3 WebSocket connections per client1 client connection, HTTP to subgraphs
Subgraphs must be statefulSubgraphs are completely stateless
No serverless deployment optionFull serverless compatibility
Subscription logic in every subgraphZero subscription code in subgraphs

Directives

Schema-level event source mapping

Map subscription fields to message broker topics directly in your subgraph schema:

  • @edfs__kafkaSubscribe — subscribe to an Apache Kafka topic
  • @edfs__natsSubscribe — subscribe to a NATS subject or JetStream stream
  • @edfs__redisSubscribe — subscribe to a Redis Pub/Sub channel
  • Topic templating with argument interpolation: e.g., employeeUpdated.{{ args.id }}
  • Subscription filtering with @openfed__subscriptionFilter using AND, OR, NOT, and IN conditions

How Cosmo Streams works

01
Directives map subscriptions to topics.

Define

Add EDFS directives to your subgraph schema. Map subscription fields to Kafka topics, NATS subjects, or Redis channels. Topic templates support argument interpolation.

02
Events go to broker. Not to subgraphs.

Publish

Backend services emit events to the configured message broker when data changes. Subgraphs handle only plain HTTP requests. No WebSocket servers, no subscription loops.

03
Router deduplicates. Efficient I/O.

Receive

The Router subscribes to broker topics. When events arrive, it identifies affected client subscriptions, deduplicates fetch requests, and minimizes upstream HTTP calls.

04
WebSocket, SSE, or Multipart.

Broadcast

The Router fetches updated data from subgraphs via plain HTTP and pushes results to clients over WebSocket, SSE, or Multipart HTTP.

Capabilities

What Cosmo Streams provides

Event-driven subscriptions, stateless subgraphs, and native message broker integration.

Kafka, NATS, and Redis Pub/Sub

Native integration with Apache Kafka clusters, NATS servers, and Redis Pub/Sub. Connect to existing infrastructure without additional middleware.

NATS JetStream

Persistent, replayable event streams via NATS JetStream for event data that must survive restarts.

Topic templating

Use argument interpolation in topic names: employeeUpdated.{{ args.id }} routes events to the right clients without custom code.

Subscription filtering

Use @openfed__subscriptionFilter with AND, OR, NOT, and IN conditions to control which events reach which subscribers.

Automatic subscription deduplication

The Router deduplicates fetch requests across clients subscribed to the same event. Each unique update fetches once regardless of subscriber count.

Serverless compatible

Subgraphs handle only plain HTTP requests. Deploy on Lambda, Cloud Run, or any serverless platform.

Move to event-driven subscriptions

Connect the Router to your message broker. Keep subgraphs stateless.

FAQ

Cosmo Streams questions

Deep dive in the Cosmo Streams documentation.