GraphQL WebSocket Network Interface for Apollo Client

This is a GraphQL WebSocket based NetworkInterface layer for the JavaScript GraphQL client library Apollo Client. It was developed for and is intended to be used with the HAPI server framework and its seamless WebSocket protocol integration module HAPI-Plugin-WebSocket, although it could be used with any GraphQL server speaking plain (JSON-encoded) GraphQL request/response messages over WebSocket connections. It has deferred connection establishment and connection keepalive support and can reconnect automatically.

$ npm install graphql-tag apollo-client apollo-client-ws

const gql            = require("graphql-tag")
const ApolloClient   = require("apollo-client")
const ApolloClientWS = require("apollo-client-ws")

const networkInterface = ApolloClientWS.createNetworkInterface({
    uri: "ws://127.0.0.1:12345/api",
    opts: {
        /*  (all options and their default values)  */
        debug:             false,
        log:               (msg) => { console.log(msg) },
        protocols:         [],
        compress:          false,
        encoding:          "json",
        keepalive:         0,
        reconnectattempts: 10,
        reconnectdelay:    2 * 1000
    }
})

const apolloClient = new ApolloClient.ApolloClient({
    networkInterface: networkInterface
})

apolloClient.query({ query: gql`{ ... }` })
    .then((response) => { ...  })
    .catch((err)     => { ...  })

There is also the alternative module Subscriptions-Transport-WS for Apollo Client. While Apollo-Client-WS transfers plain GraphQL request/response messages over WebSocket connections and intentionally has no direct built-in subscription support, the Subscriptions-Transport-WS module uses an own protocol on top of WebSockets to support the subscription notification and unfortunately, but by design, uses an opinionated way of implementing GraphQL subscriptions on the GraphQL engine side.

The Apollo-Client-WS instead provides plain GraphQL over WebSocket communication, without any additional subscription protocol, and hence does not need any special support on the server side.

For implementing a subscription or similar add-on protocol on top of Apollo-Client-WS, use the send method to send non-GraphQL request messages to the server, use the receive event for receiving non-GraphQL response messages from the server and use the query:request and query:response hooks to optionally wrap/unwrap regular GraphQL request/response messages.

For example, assume your custom protocol is based on messages of the form { cmd: "...", args: [ ... ] }, then you could implement it with Apollo-Client-WS the following way (ignoring error handling for illustration purposes):

/*  send a subscribe command  */
networkInterface.send({ cmd: "SUBSCRIBE", args: [ 42 ] })

/*  receive a notification command  */
networkInterface.on("receive", ({ cmd, args }) => {
    if (cmd === "NOTIFY")
        notify(...args)
})

/*  wrap GraphQL request into a request command  */
networkInterface.latch("query:request", (request) => {
    return { cmd: "REQUEST", args: [ request ] }
})

/*  unwrap GraphQL response from a response command  */
networkInterface.latch("query:response", (response) => {
    if (response.cmd === "RESPONSE")
         response = response.args[0]
    return response
})

Copyright (c) 2017 Ralf S. Engelschall (http://engelschall.com/)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.