Subscriptions

A GraphQL subscription is essentially a query where the client receives an event whenever the value of any field changes upstream. The Hasura GraphQL engine supports subscriptions for all kinds of queries. All the concepts of queries hold true for subscriptions as well.

Convert a query to a subscription

You can turn any query into a subscription by simply replacing query with subscription as the operation type.

Caveat

Hasura follows the GraphQL spec which allows for only one root field in a subscription.

Communication protocol

Hasura GraphQL engine uses the GraphQL over WebSocket Protocol by the apollographql/subscriptions-transport-ws library for sending and receiving events.

Setting headers for subscriptions with Apollo client

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).

  1. When it is *, the cookie is read and the CORS check is not enforced.
  2. When there are explicit domains, the cookie will only be read if the request originates from one of the listed domains.
  3. If CORS is disabled, the default behaviour is that the cookie won’t be read (because of potential security issues). To override the behaviour, you can use the flag --ws-read-cookie or the environment variable HASURA_GRAPHQL_WS_READ_COOKIE. See GraphQL engine server flags reference for the setting.
« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2019 Hasura.