Documentation incorrectly states HTTP Multipart supports subscription operations

[connorjburton]

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

1. Understanding exactly what methods of streaming content can be used with HTTP Multipart
2. 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 subscription operation 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.

1. This page is called subscriptions, and the first line defines a subscription as a third operation type, in addition to Query and Mutation
2. The page states that HTTP, using chunked multipart responses is a Supported subscription protocol
3. The page states that @apollo/client has 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 with subscriptions, only @defer or @stream directives
4. The Usage with Relay example uses the variable fetchQuery but that is not defined in the code snippet
5. The Subscriptions via multipart HTTP again states that you can use multipart HTTP for a subscription operation 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!

[phryneas]

Hi @connorjburton!

We do support the Multipart HTTP protocol for GraphQL Subscriptions .

That said, there is no official standardized protocol for subscriptions over Http Multipart in GraphQL in general - this is just the protocol that we support with GraphOS Router. A downstream GraphQL server would then implement this Callback Protocol and GraphOS Router would expose it as Http Multipart then.
I'm not aware of any other implementations of Multipart HTTP for GraphQL subscriptions.

[connorjburton]

@phryneas Thanks for the speedy response.

To confirm, would it be accurate to say that @apollo/server cannot, on it's own, support subscription over multipart HTTP? Only if fronted by a router layer that supports this "translation", such as GraphOS?

I can see that the documentation I referenced was the @apollo/client documentation, which I presume works just fine, if the destination you point to supports subscription over HTTP Multipart, which is up to the server to implement, as there is no standard protocol.

This makes sense to me, if that is the case.

[phryneas]

To confirm, would it be accurate to say that @apollo/server cannot, on it's own, support subscription over multipart HTTP? Only if fronted by a router layer that supports this "translation", such as GraphOS?

Yes, to my knowledge that about sums it up. Sorry for the confusion!

[connorjburton]

Thanks for the confirmation. I think the issue can probably be closed if you want, though one piece of feedback for the @apollo/client documentation is to call out that you need a server component that supports subscription over HTTP Multipart such as GraphOS.

As of now, it seems too easy to interpet that @apollo/sever can serve these needs.

Appreciate your responses.