Add support for newer incremental delivery format

.changeset/fruity-ways-tell.md

@@ -0,0 +1,5 @@
+---
+'@apollo/server': minor
+---
+
+Add 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`, an error is returned to the client.

.changeset/yellow-worlds-start.md

@@ -0,0 +1,38 @@
+---
+'@apollo/server': minor
+---
+
+Add `[email protected]` incremental delivery types and rename the existing incremental delivery types by adding 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';
+```

.circleci/config.yml

@@ -80,6 +80,7 @@ jobs:
     docker:
     - image: cimg/base:stable
     environment:
+      INCREMENTAL_DELIVERY_TESTS_ENABLED: t
       GRAPHQL_JS_VERSION: 17.0.0-alpha.9
     steps:
       - setup-node:

docs/source/workflow/requests.md

@@ -91,7 +91,7 @@ For more details, see [the CSRF prevention documentation](../security/cors#preve
 
 ## Incremental delivery (experimental)
 
-Incremental delivery is a [Stage 2: Draft Proposal](https://github.com/graphql/graphql-spec/pull/742) to the GraphQL specification which adds `@defer` and `@stream` executable directives. These directives allow clients to specify that parts of an operation can be sent after an initial response, so that slower fields do not delay all other fields. As of June 2025, the `graphql` library (also known as `graphql-js`) upon which Apollo Server is built implements incremental delivery only in the unreleased major version 17. If a pre-release of `[email protected]` is installed in your server, Apollo Server can execute these incremental delivery directives and provide streaming [`multipart/mixed`](https://github.com/graphql/graphql-over-http/blob/main/rfcs/IncrementalDelivery.md) responses.
+Incremental delivery is a [Stage 1: Proposal](https://github.com/graphql/graphql-spec/pull/1110) to the GraphQL specification which adds `@defer` and `@stream` executable directives. These directives allow clients to specify that parts of an operation can be sent after an initial response, so that slower fields do not delay all other fields. As of June 2025, the `graphql` library (also known as `graphql-js`) upon which Apollo Server is built implements incremental delivery only in the unreleased major version 17. If a pre-release of `[email protected]` or `[email protected]` is installed in your server, Apollo Server can execute these incremental delivery directives and provide streaming [`multipart/mixed`](https://github.com/graphql/graphql-over-http/blob/main/rfcs/IncrementalDelivery.md) responses.
 
 Support for incremental delivery in graphql version 17 is [opt-in](https://github.com/robrichard/defer-stream-wg/discussions/12), meaning the directives are not defined by default. In order to use `@defer` or `@stream`, you must provide the appropriate definition(s) in your SDL. The definitions below can be pasted into your schema as-is:
 
@@ -119,8 +119,8 @@ const schema = new GraphQLSchema({
 });
 ```
 
-Clients sending operations with incremental delivery directives need to explicitly indicate that they are expecting to receive `multipart/mixed` responses in an `accept` header. Moreover, because incremental delivery has not yet been finalized in the GraphQL spec and may change before the final version, they need to specify that they expect the particular response format that Apollo Server produces today via a `deferSpec` parameter. Specifically, clients prepared to accept incremental delivery responses should send an `accept` header like `multipart/mixed; deferSpec=20220824`. Note that this header implies that *only* multipart responses should be accepted; typically, clients will send an accept header like `multipart/mixed; deferSpec=20220824, application/json` indicating that either multipart or single-part responses are acceptable.
+Clients sending operations with incremental delivery directives need to explicitly indicate that they are expecting to receive `multipart/mixed` responses in an `accept` header. Moreover, because incremental delivery has not yet been finalized in the GraphQL spec and may change before the final version, they need to specify that they expect the particular response format that Apollo Server produces today via a `deferSpec` parameter (for `17.0.0-alpha.2`) or `incrementalDeliverySpec` parameter (for `17.0.0-alpha.9`). Specifically, clients prepared to accept incremental delivery responses should send an `accept` header like `multipart/mixed; deferSpec=20220824` or `multipart/mixed; incrementalDeliverySpec=3283f8a`. Note that this header implies that *only* multipart responses should be accepted; typically, clients will send an accept header like `multipart/mixed; deferSpec=20220824, application/json` indicating that either multipart or single-part responses are acceptable.
 
-> Apollo Server *only* supports the specific pre-release `[email protected]`. Newer alpha versions of `graphql` v17 support a slightly different format for incremental delivery, which Apollo Server does not yet support. Apollo Server 5 checks the version of `graphql` you have installed and will not attempt to support incremental delivery unless it is precisely `17.0.0-alpha.2`. We hope to support the newer incremental delivery protocol in a future release, using a different `deferSpec` value.
+> Apollo Server *only* supports the specific pre-release `[email protected]` or `graphql@17.0.0-alpha.9`. Apollo Server 5 checks the version of `graphql` you have installed and will not attempt to support incremental delivery unless it is precisely `17.0.0-alpha.2` or `17.0.0-alpha.9`.
 
 You cannot combine [batching](#batching) with incremental delivery in the same request.

packages/integration-testsuite/src/apolloServerTests.ts

@@ -16,6 +16,7 @@ import {
   type FieldNode,
   type GraphQLFormattedError,
   GraphQLScalarType,
+  version as graphqlVersion,
 } from 'graphql';
 
 // Note that by doing deep imports here we don't need to install React.
@@ -1178,8 +1179,11 @@ export function defineIntegrationTestSuiteApolloServerTests(
             expect(Object.keys(reports[0].tracesPerQuery)[0]).toMatch(/^# -\n/);
           });
 
-          (process.env.INCREMENTAL_DELIVERY_TESTS_ENABLED ? it : it.skip)(
-            'includes all fields with defer',
+          (process.env.INCREMENTAL_DELIVERY_TESTS_ENABLED &&
+            graphqlVersion === '17.0.0-alpha.2'
+            ? it
+            : it.skip)(
+            'includes all fields with defer [email protected]',
             async () => {
               await setupApolloServerAndFetchPair({}, {}, [], true);
               const response = await fetch(uri, {
@@ -1199,18 +1203,68 @@ export function defineIntegrationTestSuiteApolloServerTests(
                 `"multipart/mixed; boundary="-"; deferSpec=20220824"`,
               );
               expect(await response.text()).toMatchInlineSnapshot(`
-                "
-                ---
-                content-type: application/json; charset=utf-8
-
-                {"hasNext":true,"data":{"justAField":"a string"}}
-                ---
-                content-type: application/json; charset=utf-8
+                                  "
+                                  ---
+                                  content-type: application/json; charset=utf-8
+
+                                  {"hasNext":true,"data":{"justAField":"a string"}}
+                                  ---
+                                  content-type: application/json; charset=utf-8
+
+                                  {"hasNext":false,"incremental":[{"path":[],"data":{"delayedFoo":{"bar":"hi"}}}]}
+                                  -----
+                                  "
+                              `);
+              const reports = await reportIngress.promiseOfReports;
+              expect(reports.length).toBe(1);
+              expect(Object.keys(reports[0].tracesPerQuery)).toHaveLength(1);
+              const trace = Object.values(reports[0].tracesPerQuery)[0]
+                .trace?.[0] as Trace;
+              expect(trace).toBeDefined();
+              expect(trace?.root?.child?.[0].responseName).toBe('justAField');
+              expect(trace?.root?.child?.[1].responseName).toBe('delayedFoo');
+              expect(trace?.root?.child?.[1].child?.[0].responseName).toBe(
+                'bar',
+              );
+            },
+          );
 
-                {"hasNext":false,"incremental":[{"path":[],"data":{"delayedFoo":{"bar":"hi"}}}]}
-                -----
-                "
-              `);
+          (process.env.INCREMENTAL_DELIVERY_TESTS_ENABLED &&
+            graphqlVersion === '17.0.0-alpha.9'
+            ? it
+            : it.skip)(
+            'includes all fields with defer [email protected]',
+            async () => {
+              await setupApolloServerAndFetchPair({}, {}, [], true);
+              const response = await fetch(uri, {
+                method: 'POST',
+                headers: {
+                  'content-type': 'application/json',
+                  accept: 'multipart/mixed; incrementalDeliverySpec=3283f8a',
+                },
+                body: JSON.stringify({
+                  query: '{ justAField ...@defer { delayedFoo { bar} } }',
+                }),
+              });
+              expect(response.status).toBe(200);
+              expect(
+                response.headers.get('content-type'),
+              ).toMatchInlineSnapshot(
+                `"multipart/mixed; boundary="-"; incrementalDeliverySpec=3283f8a"`,
+              );
+              expect(await response.text()).toMatchInlineSnapshot(`
+                  "
+                  ---
+                  content-type: application/json; charset=utf-8
+
+                  {"hasNext":true,"data":{"justAField":"a string"},"pending":[{"id":"0","path":[]}]}
+                  ---
+                  content-type: application/json; charset=utf-8
+
+                  {"hasNext":false,"incremental":[{"id":"0","data":{"delayedFoo":{"bar":"hi"}}}],"completed":[{"id":"0"}]}
+                  -----
+                  "
+                `);
               const reports = await reportIngress.promiseOfReports;
               expect(reports.length).toBe(1);
               expect(Object.keys(reports[0].tracesPerQuery)).toHaveLength(1);