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=3283f8a 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: 267623d3d32c2c5b9f02e1b2
Build Logs: View logs

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

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

glasser · 2025-10-01T00:12:40Z

packages/server/src/externalTypes/incrementalDeliveryPolyfillAlpha2.ts

 interface ObjMap<T> {
  [key: string]: T;
 }



Yeah, I don't know much about TS namespaces and we haven't used them in this project to my knowledge.

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

glasser · 2025-10-01T22:35:14Z

packages/server/src/externalTypes/incrementalDeliveryPolyfillAlpha9.ts

@@ -0,0 +1,82 @@
+import type { FormattedExecutionResult, GraphQLFormattedError } from 'graphql';


General question — now that we're not reordering fields, is it possible we can drop a lot of these types (and just have some higher-up field be unknown or something)?

Definitely! I'll look through this and see if there are any that are used outside of ordering, but I would definitely love to remove as much as we can.

Discussed over slack. Since it's used by GraphQLResponse, we're going to leave these so that they are usable. Eventually we'll be able to deprecate these types once graphql v17 is released and the types can be imported directly from there.

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]>

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 2 commits September 28, 2025 22:21

Update smoke test to check both versions

025d292

Fix ref in circle config

a17ffff

jerelmiller force-pushed the jerel/newer-incremental-spec branch from 7caea09 to a17ffff Compare September 29, 2025 04:29

jerelmiller marked this pull request as draft September 29, 2025 04:32

jerelmiller force-pushed the jerel/newer-incremental-spec branch from 8478c9e to a17ffff Compare September 29, 2025 14:53

jerelmiller added 10 commits September 29, 2025 08:55

Add ts-ignore

1ad2066

Throw if old format requested but not supported

6f1e3e6

Install @yaacovcr/transform in prepare.sh

b7e1661

Add yaacovcr to cspell dict

0f8d32d

Fix typo

1d101dc

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 6 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

		@@ -0,0 +1,82 @@
		import type { FormattedExecutionResult, GraphQLFormattedError } from 'graphql';

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!

Choose a reason for hiding this comment

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!

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!

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!

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