Cosmo Streams (EDFS)

Stateless subgraphs, event-driven subscriptions

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

Kafka, NATS (including JetStream), and Redis. Serverless compatible.

Available onEvery Cosmo plan

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. Serverless platforms such as Lambda and Cloud Run usually limit request length, which makes serverless deployments difficult or 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 that serves subscriptions 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 Cosmo Streams directives to an Event-Driven Graph, a schema-only subgraph that is never implemented. 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. When a client subscribes, the Router subscribes to the matching topic, subject, or channel.

  3. Backend services publish events to the message broker when data changes. Each event carries the entity __typename and its key fields. 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 graphql-ws, Server-Sent Events, multipart HTTP, or the legacy subscriptions-transport-ws and absinthe. Subgraphs never hold WebSocket connections.

Subgraphs emit events. The Router does the rest.

Cosmo Streams

Before & After

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

Directives

Schema-level event source mapping

Map subscription fields to message broker topics in an Event-Driven Graph schema:

  • @edfs__kafkaSubscribe: subscribe to one or more Apache Kafka topics
  • @edfs__natsSubscribe: subscribe to NATS subjects, optionally through a JetStream stream
  • @edfs__redisSubscribe: subscribe to one or more Redis channels
  • 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 Cosmo Streams directives to an Event-Driven Graph, a schema-only subgraph that is never implemented. 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

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

NATS JetStream

Configure a JetStream stream and consumer so messages sent while a subscription is inactive can be consumed when it restarts. The consumer is deleted after 30 seconds of inactivity by default; consumerInactiveThreshold changes that.

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. Subscriptions on the same topic share one trigger.

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.