@barejs/graphql-client

This is a collection of GraphQL clients which support queries, mutations and subscriptions.

It specifically targets the bareASGI GraphQL module from the bareASGI python web framework. This framework provides two novel features.

• Server side identification of subscriptions (by returning a 201 if the query was a subscription),
• Multiple subscription transports (WebSocket, EventSource (server sent events), and fetch with ReadableStream.

Because the ReadableStream api is a feature of fetch, it can provide headers to the server, allowing CORS and authentication to be maintained. This is a relatively new feature; in particular the pipeThrough and pipeTo methods (which are used by the client) are still marked as "experimental". At the time of writing this is supported by most common browsers with the notable exception of FireFox (and Internet Explorer, obviously).

Usage

Queries and mutations

The graphqlFetchClient function is a thin wrapper around fetch. It can be used for queries and mutations.

import { graphqlFetchClient } from '@barejs/graphql-client'

const url = 'http://www.example.com/graphql'
const init {}

const query = 'query { someQuery { someField someOtherField } }'
const variables = null
const operationName = null

graphqlFetchClient(
  url,
  init,
  query,
  variables,
  operationName,
  error => console.error(error),
  data => console.log(data))

Subscriptions

There are three mechanisms provided for subscriptions:

• Over WebSockets (widely supported),
• Using server sent events (only supported by bareASGI)
• Using readable streams (only supported by bareASGI)

WebSockets

This follows the Apollo websocket protocol, which appears to be the most widely used and compatible transport. The main issue with the websocket transport is that authentication is must be implemented separately, as headers and cookie are not available.

import { graphqlWsSubscriber } from '@barejs/graphql-client'

const url = 'http://www.example.com/sse-subscription'

const query = 'subscription { someSubscription { someField someOtherField } }'
const variables = null
const operationName = null

graphqlWsSubscriber(
  url,
  query,
  variables,
  operationName,
  error => console.error(error),
  data => console.log(data))

The maximum number of web sockets is browser dependent, and is in the order of 30 per host, and 256 in total.

Server Sent Events

This sends the subscription as JSON messages over and EventSource. This is a widely supported protocol. Under the hood this is implemented as a streaming GET. This means things like headers are valid, which allows for consistent authentication.

import { graphqlEventSourceSubscriber } from '@barejs/graphql-client'

const url = 'http://www.example.com/sse-subscription'
init = {
  withCredentials: true // This controls CORS behaviour.
}

const query = 'subscription { someSubscription { someField someOtherField } }'
const variables = null
const operationName = null

graphqlEventSourceSubscriber(
  url,
  init,
  query,
  variables,
  operationName,
  error => console.error(error),
  data => console.log(data))

Under http/1.1 most browsers allow up to 6 concurrent connections per session. This is not an issue with http/2 as all http traffic to a host is multiplexed over a single connection.

Readable Streams

Readable streams are essentially a long running fetch. This means they have similar characteristics to server sent events, without the slightly arcane protocol.

The key advantage to this approach is that it works for query and mutation as well as subscription. This means everything works from a single client, which is attractive.

import { graphqlStreamClient } from '@barejs/graphql-client'

const url = 'http://www.example.com/sse-subscription'
init = {} // Anything the fetch takes.

const query = 'subscription { someSubscription { someField someOtherField } }'
const variables = null
const operationName = null

graphqlStreamClient(
  url,
  init,
  query,
  variables,
  operationName,
  error => console.error(error),
  data => console.log(data))

As with server sent events the 6 connection limitation with http/1.1 is an issue.

Clients

By using one of the three "client" functions, queries, mutations and subscriptions can be handled transparently. For web sockets and server sent events this is achieved by the server responding to a subscription with the location of the web socket or SSE endpoint. For readable streams, no redirection is necessary.

The graphqlWsClient can be used for queries, mutations, or subscriptions when using the bareASGI-graphql-next server server, using web sockets as the underlying subscription transport.

import { graphqlWsClient } from '@barejs/graphql-client'

const url = 'http://www.example.com/graphql'
const init = {}

// This could be a query, mutation or subscription.
const query = 'subscription { someSubscription { someField someOtherField } }'
const variables = null
const operationName = null

const unsubscribe = graphqlWsClient(
  url,
  init,
  query,
  variables,
  operationName,
  data => console.log(data),
  error => console.log(error),
  () => console.log('complete'))

// Later ...
unsubscribe()

There are three client functions:

• graphqlWsClient
• graphqlEventSourceClient
• graphqlStreamClient

They take the same arguments as graphqlWsClient.

graphqlWsClient

The graphqlWsClient function uses a WebSocket as the subscription transport. This implements the appolo protocol which is supported by all major GraphQL web servers.

graphqlEventSourceClient

The graphqlEventSourceClient function uses an EventSource as the subscription transport. It is more efficient than the WebSocket transport, but is only supported by the bareASGI-graphql-next server server. The underlying EventSource transport requires the subscription query and parameters to be passed in the url as a query string which can be problematic for large queries.

graphqlStreamClient

The graphqlStreamClient uses a streaming fetch with ReadableStreams as the subscription transport. This is the most efficient transport, but is only supported by the bareASGI-graphql-next server server. The request method is POST so large queries are not a problem.

Installation

npm install @barejs/graphql-client