MS SQL Server: GraphQL Subscriptions
Introduction
A GraphQL subscription is essentially a query where the client receives an update whenever the value of any field changes upstream.
Subscriptions are supported for all kinds of queries. All the concepts of queries hold true for subscriptions as well.
Implementation
The Hasura GraphQL Engine subscriptions are actually live queries, i.e. a subscription will return the latest result of the query being made and not necessarily all the individual events leading up to the result. By default, updates are delivered to clients every 1 sec.
Convert a query to a subscription
You can turn any query into a subscription by simply replacing query
with subscription
as the operation type.
Hasura follows the GraphQL spec which allows for only one root field in a subscription. You also cannot execute multiple separate subscriptions in one query. To have multiple subscriptions running at the same time they must be in separate queries.
Use cases
- Subscribe to the latest value of a particular field
- Subscribe to changes to a table’s entries
- Subscribe to the latest value of some derived data
Communication protocol
Hasura GraphQL Engine uses the
GraphQL over WebSocket Protocol
by the apollographql/subscriptions-transport-ws library
and the GraphQL over WebSocket Protocol by the
graphql-ws library for sending and receiving events. The GraphQL Engine uses
the Sec-WebSocket-Protocol
header to determine the communication protocol that'll be used. By default, the GraphQL
engine will use the apollographql/subscriptions-transport-ws
protocol.
If you are using Apollo Client, headers can be passed to a subscription by setting connectionParams
while
creating the wsLink:
// Create a WebSocket link:
const wsLink = new WebSocketLink({
uri: `<graphql-endpoint>`,
options: {
reconnect: true,
connectionParams: {
headers: {headers-object}
}
}
});
See this for more info on
using connectionParams
.
Cookies and WebSockets
The Hasura GraphQL Engine will read cookies sent by the browser when initiating a WebSocket connection. The browser will
send the cookie only if it is a secure cookie (secure
flag in the cookie) and if the cookie has a HttpOnly
flag.
Hasura will read this cookie and use it as headers when resolving authorization (i.e. when resolving the auth webhook).
Cookies, WebSockets and CORS
As browsers don't enforce Same Origin Policy (SOP) for websockets, the Hasura server enforces the CORS rules when accepting the websocket connection.
It uses the provided CORS configuration (as per Configure Cors).
- When it is
*
, the cookie is read and the CORS check is not enforced. - When there are explicit domains, the cookie will only be read if the request originates from one of the listed domains.
- If CORS is disabled, the default behavior is that the cookie won't be read (because of potential security issues).
To override the behavior, you can use the flag
--ws-read-cookie
or the environment variableHASURA_GRAPHQL_WS_READ_COOKIE
. See GraphQL Engine server config reference for the setting.