Add support for newer incremental delivery format #8148
Conversation
✅ Docs preview readyThe preview is ready to be viewed. View the preview File Changes 0 new, 1 changed, 0 removedBuild ID: dc85da527b6ca91985ac90df URL: https://www.apollographql.com/docs/deploy-preview/dc85da527b6ca91985ac90df |
|
This pull request is automatically built and testable in CodeSandbox. To see build info of the built libraries, click here or the icon next to each commit SHA. |
packages/server/package.json
Outdated
| }, | ||
| "peerDependencies": { | ||
| "graphql": "^16.11.0" | ||
| "graphql": "^16.11.0 || 17.0.0-alpha.9", |
There was a problem hiding this comment.
As discussed on Slack, I am somewhat paranoid that this may lead in some cases to npm i @apollo/server installing [email protected] by default (because it's the dependency of @yaacovr/transform. I still lean towards us just saying that to support this experimental feature you need to do a manual npm i --legacy-peer-deps. (What exactly does declaring an optional peer dep win us anyway — enforcement of its version constraint?)
There was a problem hiding this comment.
What exactly does declaring an optional peer dep win us anyway — enforcement of its version constraint?
I think precisely that. Though its a very niche tool so maybe there are more downsides to declaring it as a peer dependency vs not.
.changeset/fruity-ways-tell.md
Outdated
| '@apollo/server': minor | ||
| --- | ||
|
|
||
| Apollo Server now supports the modern incremental delivery protocol (`@defer` and `@stream`) that ships with `[email protected]`. To use the modern protocol, clients must send the `Accept` header with a value of `multipart/mixed; incrementalDeliverySpec=3283f8a`. |
There was a problem hiding this comment.
I wonder if "modern" is an overly optimistic term to use throughout this PR. If we come up with a third protocol later, it won't age well. Would "current" work better than "modern"?
There was a problem hiding this comment.
This is why I hate naming 😂. I just picked something to differentiate from it and the legacy version. I didn't really find a good name for the "now" version, but I'd be ok with "current" 🙂
There was a problem hiding this comment.
I think the term is also used in errors?
There was a problem hiding this comment.
Oops, you're right! Updated in 5d15554
There was a problem hiding this comment.
I think you've addressed all my concerns from last time.
I'm not really sure what the v0.1 refers to but it's as good as anything else. Have you tested what happens when both deferSpec and incrementalDeliverySpec are sent? Would be good to make that well-defined, but not necessary.
This isn't a regression, but it might be nice to be explicit somewhere that --legacy-peer-deps is required for installing the alpha and transform.
|
🙌
We're going to document the spec as it exists today in specs.apollo.dev. @calvincestari has a PR up right now to add this: apollographql/specs#67 That v0.1 refers to the version in that PR. We figure this is a good way to reference the spec as implemented in that version. If new ones come along, we can add v0.2, 0.3, etc for as long as we need until the spec is stable. But we plan to have those versions documented to capture the spec as it exists at the time we add support for the version.
Actually no! I'll try this out. I believe it will return the newer version of the spec (since it uses
Good call. I'll see if I can update the docs page and include that. |
Updates the header based on changes in apollographql/apollo-server#8148
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ `main` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `main`.⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ # Releases ## @apollo/[email protected] ### Minor Changes - [#8148](#8148) [`80a1a1a`](80a1a1a) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Apollo Server now supports the incremental delivery protocol (`@defer` and `@stream`) that ships with `[email protected]`. To use the current protocol, clients must send the `Accept` header with a value of `multipart/mixed; incrementalSpec=v0.2`. Upgrading to 5.1 will depend on what version of `graphql` you have installed and whether you already support the incremental delivery protocol. ## I use `graphql@16` without incremental delivery Continue using `graphql` v16 with no additional changes. Incremental delivery won't be available. ## I use `graphql@16` but would like to add support for incremental delivery Install `[email protected]` and follow the ["Incremental delivery" guide](https://www.apollographql.com/docs/apollo-server/workflow/requests#incremental-delivery-experimental) to add the `@defer` and `@stream` directives to your schema. Clients should send the `Accept` header with a value of `multipart/mixed; incrementalSpec=v0.2` to get multipart responses. ## I use `[email protected]` and use incremental delivery You must upgrade to `[email protected]` to continue using incremental delivery. If you'd like to continue providing support for the legacy incremental protocol, install the [`@yaacovcr/transform`](https://github.com/yaacovCR/transform) package. Apollo Server will attempt to load this module when the client specifies an `Accept` header with a value of `multipart/mixed; deferSpec=20220824`. If this package is not installed, an error is returned by the server. Because Apollo Server now supports multiple versions of the incremental delivery types, the existing incremental delivery types have been renamed with an `Alpha2` suffix. If you import these types in your code, you will need to add the `Alpha2` suffix. ```diff import type { - GraphQLExperimentalFormattedInitialIncrementalExecutionResult, + GraphQLExperimentalFormattedInitialIncrementalExecutionResultAlpha2, - GraphQLExperimentalFormattedSubsequentIncrementalExecutionResult, + GraphQLExperimentalFormattedSubsequentIncrementalExecutionResultAlpha2, - GraphQLExperimentalFormattedIncrementalResult, + GraphQLExperimentalFormattedIncrementalResultAlpha2, - GraphQLExperimentalFormattedIncrementalDeferResult, + GraphQLExperimentalFormattedIncrementalDeferResultAlpha2, - GraphQLExperimentalFormattedIncrementalStreamResult, + GraphQLExperimentalFormattedIncrementalStreamResultAlpha2, } from '@apollo/server'; ``` Incremental delivery types for the `[email protected]` version are now available using the `Alpha9` suffix: ```ts import type { GraphQLExperimentalFormattedInitialIncrementalExecutionResultAlpha9, GraphQLExperimentalFormattedSubsequentIncrementalExecutionResultAlpha9, GraphQLExperimentalFormattedIncrementalResultAlpha9, GraphQLExperimentalFormattedIncrementalDeferResultAlpha9, GraphQLExperimentalFormattedIncrementalStreamResultAlpha9, GraphQLExperimentalFormattedCompletedResultAlpha9, GraphQLExperimentalPendingResultAlpha9, } from '@apollo/server'; ``` ## @apollo/[email protected] ### Patch Changes - Updated dependencies \[[`80a1a1a`](80a1a1a)]: - @apollo/[email protected] ## @apollo/[email protected] ### Patch Changes - Updated dependencies \[[`80a1a1a`](80a1a1a)]: - @apollo/[email protected] --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jerel Miller <[email protected]>
5 participants
Closes #7932
Adds support for the
[email protected]@deferand@streamincremental delivery protocol.When
[email protected]is installed, clients must send theAcceptheader with a value ofmultipart/mixed; incrementalSpec=v0.2to specify the new format. If theAcceptheader is not compatible with the installed version ofgraphql(such as sendingdeferSpec=20220824when ``17.0.0-alpha.9` is installed), an error is returned to the client.