Which subscription protocols does Cosmo Router support?

graphql-ws (default), Server-Sent Events (GET and POST), Multipart HTTP, subscriptions-transport-ws (legacy), and Absinthe (Phoenix). All five work between clients and the Router. Between the Router and subgraphs, each subgraph is registered with WebSockets (graphql-ws or subscriptions-transport-ws), SSE, or SSE over POST.

How does connection multiplexing work?

The Router groups multiple client subscriptions that share the same authentication headers into a single upstream connection to the subgraph. When headers match, clients share a connection rather than each opening their own.

Can I use different protocols for different subgraphs?

Yes. Configure the subscription protocol per subgraph using the Cosmo CLI when registering or updating the subgraph.

What happens when the Router updates its configuration at runtime?

Active subscriptions are terminated. Clients should be built to reconnect automatically on disconnect.

What is the extensions field used for?

The extensions field lets you pass additional metadata (such as Bearer tokens) with subscription messages. The Router forwards these to subgraphs in the per-operation subscribe payload. This is enabled by default.

When should I use SSE instead of WebSockets?

Server-Sent Events are more resource efficient than WebSockets and work better through certain proxies. Use SSE when clients only need to receive updates (unidirectional), not send them.

GraphQL Subscriptions | WebSocket, SSE, and Multipart

The problem

One URL, multiple protocols, many clients

Real-time features break when clients, routers, and subgraphs all expect different protocols. Connection overhead grows linearly with client count without multiplexing.

Clients and subgraphs use different protocols

Legacy Apollo clients, modern web clients, and Phoenix (Absinthe) clients each prefer different subscription protocols. Without a router that speaks all of them, each combination requires separate handling.

Each client opens a separate backend connection

Without connection multiplexing, every client subscription opens its own connection to the subgraph. Backend connection count scales 1:1 with subscriber count, which can strain server resources.

Adding subscriptions requires infrastructure work

Protocol negotiation, heartbeat handling, and extension field forwarding all need to be implemented before a single real-time update ships.

Our solution

Protocol translation and multiplexing in the Router

The Cosmo Router accepts five subscription protocols from clients and talks to each subgraph over WebSockets or SSE. It translates between protocols automatically.

How subscriptions work in Cosmo Router

Clients connect using their preferred protocol. graphql-ws is the default. SSE is recommended for unidirectional updates.
The Router accepts graphql-ws, SSE (GET and POST), Multipart HTTP, subscriptions-transport-ws, and Absinthe from clients.
The Router communicates with each subgraph using the protocol configured for that subgraph. Set per-subgraph protocol via the CLI.
Protocol translation is automatic. A legacy client using subscriptions-transport-ws can subscribe to a modern graphql-ws subgraph.
Connection multiplexing groups subscriptions with matching authentication headers into shared upstream connections.
The Router forwards extension field data (such as Bearer tokens) to subgraphs in the per-operation subscribe payload.

Clients use what they support. The Router handles the rest.

GraphQL Subscriptions

Before & After

Before Cosmo	With Cosmo
Limited to one subscription protocol	Choose from five protocols: graphql-ws, SSE, Multipart HTTP, subscriptions-transport-ws, or Absinthe
Each client opens a new backend connection	Multiplexed connections share resources
Manual protocol negotiation logic	Automatic protocol translation between clients and subgraphs (WebSockets or SSE to subgraphs)
Legacy clients break on protocol updates	subscriptions-transport-ws and Absinthe supported alongside modern protocols

Supported protocols

Five client protocols

graphql-ws: default and recommended. The protocol of the graphql-ws library.
SSE (GET and POST): Server-Sent Events. Unidirectional. More resource efficient than WebSockets. Works better through certain proxies.
Multipart HTTP: Chunked subscription responses over HTTP.
subscriptions-transport-ws: Legacy Apollo WebSocket protocol. For existing clients that have not migrated.
Absinthe: Phoenix (Elixir) protocol. For Elixir/Phoenix ecosystems.

How GraphQL Subscriptions work in Cosmo Router

01

All 5 protocols from clients.

Connect

Clients connect using graphql-ws, SSE, Multipart HTTP, subscriptions-transport-ws, or Absinthe. The Router accepts all five protocols from clients.

02

Shared upstream connections.

Multiplex

The Router groups client subscriptions with matching authentication headers into single upstream connections to subgraphs. Multiple clients share the same backend connection when their headers match.

03

Automatic protocol translation.

Translate

If the client protocol differs from the subgraph protocol, the Router translates automatically. Configure the subgraph protocol per-subgraph via the Cosmo CLI.

04

Config reload ends subscriptions.

Stream

The Router streams updates to each client over its chosen protocol. When the Router configuration updates at runtime, it terminates all active subscriptions, so clients should reconnect automatically on disconnect.

Capabilities

What GraphQL Subscriptions provides

Five protocols, automatic translation, and connection multiplexing.

graphql-ws (default)

The recommended WebSocket subprotocol. Widely supported by GraphQL client libraries. Enabled by default with no configuration required.

Server-Sent Events (GET and POST)

One-way event streaming over HTTP. More resource efficient than WebSockets and works better through certain proxies. Recommended for notification streams.

Multipart HTTP

Chunked subscription responses over standard HTTP. Send the subscription as a POST with Accept: multipart/mixed.

Legacy protocol support

subscriptions-transport-ws for existing Apollo clients. Absinthe for Phoenix/Elixir ecosystems. Migrate backend services without breaking existing clients.

Extension field forwarding

Pass additional metadata (such as Bearer tokens) in the GraphQL extensions field with subscription messages. The Router forwards extensions to subgraphs in the per-operation subscribe payload.

Per-subgraph protocol configuration

Configure the subscription protocol per subgraph via the Cosmo CLI. Modernize backend services gradually without changing client protocols.

Enable real-time subscriptions

Subscriptions work out of the box. Customize protocols per subgraph as needed.

Start Free Read the Docs

Five subscription protocols and automatic connection multiplexing