Skip to main content

Documentation Index

Fetch the complete documentation index at: https://cosmo-docs.wundergraph.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What are subscriptions for?

GraphQL subscriptions are a feature of the GraphQL query language that allows clients to receive real-time updates from a server when specific events or data changes occur. They are useful for building interactive and responsive applications, as they eliminate the need for clients to continuously poll the server for updates. Subscriptions work by establishing a long-lived connection between the client and server, enabling the server to push data to the client as soon as it becomes available, making them a more efficient and scalable way to handle real-time data synchronization in applications. The Cosmo Router comes with subscription support out of the box without any limitations. We support multiple different protocols to enable the most versatile and efficient real-time data synchronization for your applications: WebSockets, Server-Sent Events, and Multipart HTTP Protocol, among others.
  • graphql-ws: (default) Coherent, zero-dependency, lazy, simple, GraphQL over WebSocket Protocol compliant server and client.
  • Server-Sent Events (SSE): One-Way Messaging. Both with GET and POST requests. Recommended for unidirectional updates. More resource efficient than WebSockets.
  • Multipart HTTP: Multi-part GraphQL subscriptions allow data to be delivered in chunks over time, enabling efficient streaming of large or frequently updated data in real-time applications.
  • subscriptions-transport-ws: Legacy transport to WebSocket-based GraphQL subscriptions. Please use graphql-ws or SSE if you have the choice.
  • absinthe: Legacy transport for Clients that still use the Absinthe (Phoenix) protocol.
GraphQL subscription architecture showing Cosmo Router with protocol translator and multiplexer connecting to multiple backend APIs.
These protocols are both supported between the client and the router as well as between the router and each subgraph. The supported transport depends on the support of your client or subgraph. By default, graphql-ws is used which is widely adopted. The protocol to be used to subscribe for each subgraph can be configured while registering the subgraph on the control plane. See Create and Update for more information.

​
Multiplexing

Diagram showing Cosmo Router multiplexing client subscriptions into shared connections to backend APIs or services.
The Cosmo router multiplexes long-lived connections to the subgraphs when possible. Multiple client requests with the same authentication information are routed to the subgraph over a single connection.
Whenever your router updates its config at runtime, it terminates all active subscriptions. Clients should be built in a way that reconnects automatically on disconnect.

​
Test WebSockets

Install wscat globally through npm: 
npm install -g wscat
Run the following steps in order: 
# 1. Establish a secure WebSocket connection with our demo Router.
wscat -c wss://demo-router.fly.dev/graphql --subprotocol graphql-transport-ws
# 2. Paste the initial init message and press ENTER.
{"type":"connection_init","payload":{}}
# 3. Paste the GraphQL subscription and press ENTER to get updates.
{"id":"6e6f71d0-2729-4db5-baee-8b6fc88721a7","type":"subscribe","payload":{"query":"subscription {\n  currentTime {\n    unixTime\n  }\n}"}}

​
Using the extensions field

Cosmo Router allows you to leverage the “extensions” field of a GraphQL Request JSON to add additional meta information to the subscription message. This is useful, e.g. if you’re trying to send an additional parameter, like a Bearer token with the subscription. The feature is enabled by default, here’s an example on how to use it: 
# 1. Establish a secure WebSocket connection with our demo Router.
wscat -c wss://demo-router.fly.dev/graphql --subprotocol graphql-transport-ws
# 2. Paste the initial init message and press ENTER.
{"type":"connection_init","payload":{}}
# 3. Paste the GraphQL subscription and press ENTER to get updates.
{"id":"1","type":"subscribe","payload":{"extensions":{"token":"asd"},"query":"subscription {\n  currentTime {\n    unixTime\n  }\n}"}}
The router forwards each subscribe message’s extensions to the subgraph in the per-operation subscribe.payload.extensions field, where the graphql-transport-ws spec places them. Subsequent subgraph requests that resolve nested fields for the same subscription also include the extensions. The router does not merge subscribe-message extensions into connection_init.payload. The connection_init.payload carries only the downstream client’s initial payload, unchanged.
Prior to the router@0.313.0 subscription overhaul release, the router merged subscribe-message extensions into connection_init.payload.extensions, overriding any initial_payload extensions. Subgraphs that read extensions from connection_init must now read them from subscribe.payload.extensions.

​
Header forwarding

Headers in subscriptions can be forwarded through the router to the subgraphs using the proxy capabilities for the router. See #forward-http-headers-to-subgraphs for more information. When multiplexing subscriptions over a single WebSocket connection, only subscriptions with the same forwarded header names and values are grouped into a single connection.