Sub-protocols
To perform GraphQL over Websockets, 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.
subscriptions-transport-ws#
The current standard is subscriptions-transport-ws. This was a sub-protocol from the team at Apollo GraphQL, that was created along side apollo-server and apollo-client. Most clients and other server implementations still use this to perform subscriptions.
Usage#
By default, OverLayer will already use this sub-protocol to perform subscription operations through websocket. Given that, you can still explicitly declare that you are using this sub-protocol through the protocol option when constructing the OverTransportLayer.
val transport = OverTransportLayer( schema = Schema.t, root = (), protocol = OverWebsocket.subscriptionsTransportWs // <- Explicitly declare sub protocol)
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 the implementation) are described in this issue and blog post.
We also recommend using the newer sub-protocol graphql-ws when possible. However, subscriptions-transport-ws will stay as the default sub protocol until most clients on all major platforms supported the newer sub protocol.
graphql-ws#
The newer sub-protocol is graphql-ws. Aimed mostly on solving most of the problem with the subscriptions-transport-ws.
development limitation
A number of clients and most GraphQL Browser IDE (like graphql-playground, apollo sandbox, etc) has yet to support subscriptions over this protocol.
Due to this, development testing can be difficult. Recommended to have good understanding of how the protocol work on the raw websocket communication level.
Usage#
Using this sub-protocol is as easy as explicitly changing the protocol option when constructing OverTransportLayer.
val transport = OverTransportLayer( schema = Schema.t, root = (), protocol = OverWebsocket.graphqlWs // <- Explicitly declare sub protocol)
Consideration#
Even though the sub-protocol is the recommended option, there are still some consideration to take account of. Adoption for this sub-protocol are somewhat limited outside the Node.js / Javascript ecosystem.
Here are some notable clients and tools that has yet to support graphql-ws as of Sep 27th, 2021:
- graphql-kotlin, no issue mentioning the new protocol yet.
- graphql-flutter, already an issue but not yet resolved.
- apollo sandbox.
- No proper GraphQL Browser IDE that can use this protocol for subscriptions especially one that can split operations to HTTP and Websocket.
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. If in doubt, it's best to understand how both sub-protocols work and have options to swap between both options.