Add support for newer incremental delivery format (#8148)

Closes #7932

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; incrementalSpec=v0.2`
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.

---------

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

Author: jerelmiller

.changeset/fruity-ways-tell.md

@@ -0,0 +1,54 @@
+---
+'@apollo/server': minor
+---
+
+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';
+```

.circleci/config.yml

@@ -60,37 +60,22 @@ jobs:
       - setup-node
       - run: npm run test:smoke
 
-  Full incremental delivery tests with graphql 17 alpha 2:
+  Full incremental delivery tests with graphql 17 alpha 9:
     docker:
     - image: cimg/base:stable
     environment:
       INCREMENTAL_DELIVERY_TESTS_ENABLED: t
-      GRAPHQL_JS_VERSION: 17.0.0-alpha.2
+      GRAPHQL_JS_VERSION: 17.0.0-alpha.9
     steps:
       - setup-node:
           node-version: "20"
       # Install a prerelease of graphql-js 17 with incremental delivery support.
       # --legacy-peer-deps because nothing expects v17 yet.
-      - run: npm i --legacy-peer-deps "graphql@${GRAPHQL_JS_VERSION}"
+      - run: npm i --legacy-peer-deps "graphql@${GRAPHQL_JS_VERSION}" @yaacovcr/transform
       - run: npm run test:ci
       - maybe-upload-coverage
       - run: npm run test:smoke
 
-  Test with recent graphql-js alpha:
-    docker:
-    - image: cimg/base:stable
-    environment:
-      GRAPHQL_JS_VERSION: 17.0.0-alpha.9
-    steps:
-      - setup-node:
-          node-version: "20"
-      # Install a newer prerelease of graphql-js 17; we do not yet support
-      # its incremental delivery format.
-      # --legacy-peer-deps because nothing expects v17 yet.
-      - run: npm i --legacy-peer-deps "graphql@${GRAPHQL_JS_VERSION}"
-      - run: npm run test:ci
-      - run: npm run test:smoke
-
   Prettier:
     docker:
     - image: cimg/base:stable
@@ -172,8 +157,7 @@ workflows:
       - Spell check
       - Codegen check
       - Smoke test built package
-      - Full incremental delivery tests with graphql 17 alpha 2
-      - Test with recent graphql-js alpha
+      - Full incremental delivery tests with graphql 17 alpha 9
       - Changesets
   security-scans:
     jobs:

cspell-dict.txt

@@ -221,4 +221,5 @@ whatwg
 Wheelock's
 withrequired
 xorby
+yaacovcr
 YOURNAME

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].2` 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].9` 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,30 @@ 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 `incrementalSpec` parameter. Specifically, clients prepared to accept incremental delivery responses should send an `accept` header like `multipart/mixed; incrementalSpec=v0.2`. Note that this header implies that *only* multipart responses should be accepted; typically, clients will send an accept header like `multipart/mixed; incrementalSpec=v0.2, application/json` indicating that either multipart or single-part responses are acceptable.
 
-> Apollo Server *only* supports the specific pre-release `[email protected].2`. 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].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.9`.
 
 You cannot combine [batching](#batching) with incremental delivery in the same request.
+
+<Note>
+
+Apollo Server 5.1 changed the required pre-release `graphql` version from `17.0.0-alpha.2` to `17.0.0-alpha.9`. If you are using 5.0 or below, use `graphql` version `17.0.0-alpha.2` instead.
+
+</Note>
+
+<MinVersion version="5.1.0">
+
+### Add support for the legacy incremental delivery protocol
+
+</MinVersion>
+
+Clients may request the legacy incremental delivery protocol by specifying an `accept` header with a value of `multipart/mixed; deferSpec=20220824`. Apollo Server does not support the legacy incremental delivery protocol by default and an error will be returned to the client.
+
+You may choose to support the legacy incremental delivery protocol by installing the [`@yaacovcr/transform` package](https://github.com/yaacovCR/transform) which provides the needed utilities to format the incremental result using the legacy protocol.
+
+```sh
+npm install @yaacovcr/transform
+```
+
+There is nothing else to configure. Apollo Server will load the necessary utility if this package is installed.

packages/integration-testsuite/src/apolloServerTests.ts

@@ -1179,7 +1179,7 @@ export function defineIntegrationTestSuiteApolloServerTests(
           });
 
           (process.env.INCREMENTAL_DELIVERY_TESTS_ENABLED ? it : it.skip)(
-            'includes all fields with defer',
+            'includes all fields with defer legacy',
             async () => {
               await setupApolloServerAndFetchPair({}, {}, [], true);
               const response = await fetch(uri, {
@@ -1203,11 +1203,58 @@ export function defineIntegrationTestSuiteApolloServerTests(
                 ---
                 content-type: application/json; charset=utf-8
 
-                {"hasNext":true,"data":{"justAField":"a string"}}
+                {"data":{"justAField":"a string"},"hasNext":true}
                 ---
                 content-type: application/json; charset=utf-8
 
-                {"hasNext":false,"incremental":[{"path":[],"data":{"delayedFoo":{"bar":"hi"}}}]}
+                {"hasNext":false,"incremental":[{"data":{"delayedFoo":{"bar":"hi"}},"path":[]}]}
+                -----
+                "
+              `);
+              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',
+              );
+            },
+          );
+
+          (process.env.INCREMENTAL_DELIVERY_TESTS_ENABLED ? it : it.skip)(
+            'includes all fields with defer modern',
+            async () => {
+              await setupApolloServerAndFetchPair({}, {}, [], true);
+              const response = await fetch(uri, {
+                method: 'POST',
+                headers: {
+                  'content-type': 'application/json',
+                  accept: 'multipart/mixed; incrementalSpec=v0.2',
+                },
+                body: JSON.stringify({
+                  query: '{ justAField ...@defer { delayedFoo { bar} } }',
+                }),
+              });
+              expect(response.status).toBe(200);
+              expect(
+                response.headers.get('content-type'),
+              ).toMatchInlineSnapshot(
+                `"multipart/mixed; boundary="-"; incrementalSpec=v0.2"`,
+              );
+              expect(await response.text()).toMatchInlineSnapshot(`
+                "
+                ---
+                content-type: application/json; charset=utf-8
+
+                {"data":{"justAField":"a string"},"pending":[{"id":"0","path":[]}],"hasNext":true}
+                ---
+                content-type: application/json; charset=utf-8
+
+                {"hasNext":false,"incremental":[{"data":{"delayedFoo":{"bar":"hi"}},"id":"0"}],"completed":[{"id":"0"}]}
                 -----
                 "
               `);