Add support for newer incremental delivery format #8148

jerelmiller · 2025-09-25T01:21:32Z

Adds support for the [email protected] @defer and @stream incremental delivery protocol.

When [email protected] is installed, clients must send the Accept header with a value of multipart/mixed; incrementalDeliverySpec=graphql/incremental/v0.1 to specify the new format. If the Accept header is not compatible with the installed version of graphql (such as sending deferSpec=20220824 when ``17.0.0-alpha.9` is installed), an error is returned to the client.

apollo-librarian · 2025-09-25T01:21:40Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 1 changed, 0 removed

* (developer-tools)/apollo-server/(latest)/workflow/requests.md

Build ID: afe05c62ab65b9d1a52c8666
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/afe05c62ab65b9d1a52c8666

codesandbox-ci · 2025-09-25T01:22:18Z

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.

jerelmiller · 2025-09-29T20:25:52Z

Ok I think I have this implemented working as I had hoped. 5.1 will now require 17.0.0-alpha.9 and will be able to support the legacy format if the @yaacovcr/transform package is installed. This allows Apollo Server to simultaneously support both the old and new formats (which means clients can switch over whenever).

The only unanswered questions remaining before I think this is 100% ready:

What do we want the accept header paramter value to be? (Add support for newer incremental delivery format #8148 (comment))
How do we want to change/expose the types? Do we want to use a namespace, use the Alpha<n> naming scheme, or something else? (Add support for newer incremental delivery format #8148 (comment))
Do we want to get rid of field ordering? (Add support for newer incremental delivery format #8148 (comment))

.changeset/wild-candies-deny.md

glasser · 2025-10-01T00:11:58Z

packages/server/src/ApolloServer.ts

+  MULTIPART_MIXED_EXPERIMENTAL_ALPHA_2: 'multipart/mixed; deferSpec=20220824',
+  // spec version represents the commit hash of 17.0.0-alpha.9
+  MULTIPART_MIXED_EXPERIMENTAL_ALPHA_9:
+    'multipart/mixed; incrementalDeliverySpec=3283f8a',


I lean towards @BoD 's preference from last week of just using deferSpec with a date again. While it might not have been the best design in the first place, it does kinda feel like using the same mechanism twice for the same exact thing ("representing an unreleased incremental delivery format") would be better than changing it? (And then once it's fully standardized, we can drop it.)

packages/server/src/externalTypes/incrementalDeliveryPolyfillAlpha2.ts

packages/server/src/runHttpQuery.ts

docs/source/workflow/requests.md

glasser · 2025-10-01T22:32:50Z

packages/server/package.json

  },
  "peerDependencies": {
-    "graphql": "^16.11.0"
+    "graphql": "^16.11.0 || 17.0.0-alpha.9",


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?)

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.

Updated in bd5cd63

packages/server/src/externalTypes/incrementalDeliveryPolyfillAlpha9.ts

glasser · 2025-10-01T22:38:56Z

.changeset/fruity-ways-tell.md

+'@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`.


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"?

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" 🙂

Updated in 3c0a88e

I think the term is also used in errors?

Oops, you're right! Updated in 5d15554

Co-authored-by: David Glasser <[email protected]>

docs/source/workflow/requests.md

glasser

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.

jerelmiller · 2025-10-14T18:52:37Z

🙌

I'm not really sure what the v0.1 refers to but it's as good as anything else.

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.

Have you tested what happens when both deferSpec and incrementalDeliverySpec are sent?

Actually no! I'll try this out. I believe it will return the newer version of the spec (since it uses Negotiator and prefers that version), but wouldn't hurt to add an explicit test.

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.

Good call. I'll see if I can update the docs page and include that.

jerelmiller added 28 commits September 23, 2025 18:07

DeMorgan's Law

9274bb7

Compare against no defer spec

922da17

Add new multipart mixed header

0bb58a0

Update request error message to suggest new format

9b63f24

Add Alpha2 suffix to existing incremental types

7a8292c

Add Alpha2 suffix to polyfill file

852a6a6

Add polyfill types for alpha9

8ac5c71

Export alpha9 types

96112c0

Remove ordering of incremental fields

56245aa

Add type for GraphQLResponseBody with alpha 9 format

92fa99b

Update writeMultipartBody signature

fbfa0df

Update payload type for willSendSubsequentPayload

c7abd87

Load from alpha 9

4d3beb0

Add alpha2 suffix to existing execute types and add alpha9 types

d6e19f6

Update ApolloServer types

ddddd79

Update constructor types

bb827ce

Ensure executeIncrementally returns alpha9 types

0da6d92

Handle formatting alpha9 errors

d8fa3ec

Throw if version mismatch from header

bd8d0c3

Simplify check

1916a46

Rename media types

5ec9b5e

Change value of alpha9 spec version

5aa7578

Change output header depending on graphql version

48e2572

Swap order of conditional

c2403d5

Enable incremental delivery tests for alpha9

b7ce974

Wrap existing tests in check for alpha2

5c7bed1

Add back field ordering

7df7889

Enable incremental delivery tests for alpha9

758f50f

jerelmiller added 5 commits September 29, 2025 13:49

Update changeset

13f005c

Add another changeset

a7cbae6

Update documentation

f697a2c

Fix typo

ef1938d

Use && instead of ||

18a9868

jerelmiller marked this pull request as ready for review September 29, 2025 20:22

glasser reviewed Oct 1, 2025

View reviewed changes

jerelmiller added 3 commits October 1, 2025 15:04

Remove ordering on incremental fields

fc889d8

Allow v17.0.0-alpha.9

ce4d8d1

Combine all changesets

c9c8c78

glasser reviewed Oct 1, 2025

View reviewed changes

docs/source/workflow/requests.md Outdated Show resolved Hide resolved

glasser reviewed Oct 1, 2025

View reviewed changes

jerelmiller and others added 7 commits October 1, 2025 16:41

Fix typo

28e9d9c

Co-authored-by: David Glasser <[email protected]>

Grammar

b32394a

Remove use of "modern" in changeset

3c0a88e

Revert changes to peer deps

bd5cd63

Don't export unneeded types

96af552

Update error messages

5d15554

Update incrementalDeliverySpec header value

79fb340

jerelmiller commented Oct 14, 2025

View reviewed changes

docs/source/workflow/requests.md Outdated Show resolved Hide resolved

Fix typo

77b57de

jerelmiller requested review from BoD, glasser, martinbonnin and phryneas October 14, 2025 18:22

jerelmiller mentioned this pull request Oct 14, 2025

Update accept header used with GraphQL17Alpha9Handler apollographql/apollo-client#12973

Open

glasser approved these changes Oct 14, 2025

View reviewed changes

Add support for newer incremental delivery format #8148

Are you sure you want to change the base?

Add support for newer incremental delivery format #8148

Conversation

jerelmiller commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apollo-librarian bot commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

Uh oh!

codesandbox-ci bot commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jerelmiller commented Sep 29, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

glasser left a comment

Choose a reason for hiding this comment

Uh oh!

jerelmiller commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jerelmiller commented Sep 25, 2025 •

edited

Loading

apollo-librarian bot commented Sep 25, 2025 •

edited

Loading

codesandbox-ci bot commented Sep 25, 2025 •

edited

Loading

jerelmiller commented Oct 14, 2025 •

edited

Loading