GraphQL over WebSocket

To perform GraphQL over WebSocket, there need to be a sub protocol to define operations clearly. No "official" sub-protocol nor implementation details on handling subscription given in the GraphQL Spec. However, there are many implementations by the community that have become de facto standards like subscriptions-transport-ws and graphql-ws.

Websocket Subprotocol

graphql-ws

The newer sub-protocol is graphql-ws (opens in a new tab). Aimed mostly on solving most of the problem with the subscriptions-transport-ws.

Usage

You can to use this sub-protocol by specifying when initializing Pioneer. This is the default option.

let server = Pioneer(
    ...,
    websocketProtocol: .graphqlWs
)

Consideration

Even though the sub-protocol is the recommended and default option, there are still some consideration to take account of. Adoption for this sub-protocol are somewhat limited outside the Node.js / Javascript ecosystem or major GraphQL client libraries.

A good amount of other server implementations on many languages have also yet to support this sub-protocol. So, make sure that libraries and frameworks you are using already have support for graphql-ws (opens in a new tab).

subscriptions-transport-ws

The older standard is subscriptions-transport-ws (opens in a new tab). This is a sub-protocol from the team at Apollo GraphQL, that was created along side apollo-server (opens in a new tab) and apollo-client (opens in a new tab). Some clients and servers still use this to perform operations through websocket especially subscriptions.

Usage

You can to use this sub-protocol by specifying when initializing Pioneer.

let server = Pioneer(
    ...,
    websocketProtocol: .subscriptionsTransportWs
)

Consideration

Despite being used by most clients and servers, there are problems with this sub-protocol. Notably, the fact that the package wasn't actively maintained with many issues unresolved and pull request un-reviewed and unmerged, the maintainers themselves also recommend most people to opt for a newer sub-protocol if possible.

Most of the problems (mostly for the implementation) are described in this issue (opens in a new tab) and this blog post (opens in a new tab).

We also recommend using the newer sub-protocol graphql-ws when possible unless you have to support a legacy client.

Disabling

You can also choose to disable GraphQL over WebSocket all together, which you can do by specifiying in the Pioneer initializer.

let server = Pioneer(
    ...,
    websocketProcotol: .disable
)

Queries and Mutation over Websocket

While the primary operation going through websocket is Subscription, Queries and Mutation can be accepted through WebSocket and process properly as long as it follows the sub-protocol above.

This also include introspection query.