Subscriptions
Enable Real-time capabilities for your client applications.
Last updated
Enable Real-time capabilities for your client applications.
Last updated
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.
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.
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.
Install wscat globally through npm:
Run the following steps in order:
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 initial payload. The feature in enabled by default, here's an example on how to use it:
When establishing a connection from the Router to the Subgraph, we will automatically include the "extensions" field from the initial payload. More specifically, the Router will include this "extensions" field in all (subsequent) Subgraph requests. E.g. if a Subscription depends on a nested entity field that will be resolved through a GraphQL Query, the extensions field will be included as well.
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.