apollographql / apollographql/apollo-server
Documentation incorrectly states HTTP Multipart supports subscription operations
- Dominant language
- TypeScript
- Stars
- 14k
- Forks
- 2k
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 2
Description
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](https://www.apollographql.com/docs/react/data/subscriptions).
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](https://github.com/graphql/graphql-over-http/blob/main/rfcs/IncrementalDelivery.md), 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](https://github.com/apollographql/docs-examples/blob/main/apollo-server/v5/subscriptions-graphql-ws/src/index.ts) (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!
Contributor guide
Research direction
Start with the Apollo Client subscriptions page linked in the issue and compare its HTTP multipart claims with the linked IncrementalDelivery.md RFC. Review the “Usage with Relay” and “Subscriptions via multipart HTTP” sections, plus the HTTPLink example and the provided POC; done means the documentation accurately distinguishes subscription operations from @defer/@stream support and fixes the undefined fetchQuery example.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100