Documentation incorrectly states HTTP Multipart supports subscription operations
Hi, I have spent a few days trying to understand the state of support for HTTP Multipart with subscriptions in @apollo/server.
In this issue, I am looking to get clarity on two things
- Understanding exactly what methods of streaming content can be used with HTTP Multipart
- Confirm if the documentation is misleading or needs updating
I am going to start with the following assertion, if this is incorrect, then please let me know as it changes the content of suggestions.
@apollo/server supports two different ways to stream content to a client. WebSockets and HTTP Multipart. HTTP Multipart can only be used to stream content using the @defer and @stream directives, it does not support
subscriptionoperation type, that is only supported with WebSockets.
If that assertion is correct, then I struggled to understand that distinction by reading the documentation. Specifically this page.
Here are some notes as where I was confused.
- This page is called
subscriptions, and the first line defines asubscriptionas a third operation type, in addition toQueryandMutation - The page states that
HTTP, using chunked multipart responsesis aSupported subscription protocol - The page states that
@apollo/clienthas out-of-the-box support for multipart subscriptions, however when clicking through to the linked documentation, nowhere on that page does it say that multipart HTTP can be used withsubscriptions, only@deferor@streamdirectives - The
Usage with Relayexample uses the variablefetchQuerybut that is not defined in the code snippet - The
Subscriptions via multipart HTTPagain states that you can use multipart HTTP for asubscriptionoperation type, that is not the case
In summary, this page makes it seem like WebSocket and HTTP Multipart are interchangable, and both protocols and equally capabable to use the subscription operation type, in my testing and debugging that does seem to be the case.
If you have a resolver that looks like this
const resolvers = {
Subscription: {
numberIncremented: {
subscribe: () => pubsub.asyncIterableIterator(['NUMBER_INCREMENTED']),
}
}
};And you perform a GraphQL operation like this, using HTTPLink (which the documentation explictly states supports subscription out-of-the-box)
subscription Test {
numberIncremented
}It does not work, and in fact it will try and find a resolve property in the numberIncremented object instead.
Here is a POC repository https://github.com/connorjburton/apollo-server-http-multipart-poc, modified from this example (but made non-Websocket)
Again, if my assertion is wrong, then please let me know, but I could not get subscription operation type to work over HTTP Multipart.
Thanks for your time!
Source: apollographql/apollo-server