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.