Experimental support for incremental delivery (`@defer`/`@stream`) #6827

glasser · 2022-08-18T06:05:00Z

Also provides improved compatibility with the graphql-over-http spec by
supporting content-type: application/graphql-response+json if requested via
accept header, and adds ; charset=utf-8 to content-types.

Executing @defer and @stream directives requires you to install pre-release
of graphql@17 in your server. This PR does not update package.json to
install that prerelease (nor does it even broaden peer deps, which would be
inadequate as many of its dependencies have peer deps that won't include v17).
However, it does add a new CI step that installs a particular v17 pre-release
and runs the test suite and smoke test (including running some
otherwise-disabled tests that exercise the execution of these directives). We
also add a new __testing_incrementalExecutionResults option that lets us test
transport-level behavior without installing the prerelease.

This change reworks GraphQLResponse and HTTPGraphQLResponse to allow
responses to be single- or multi-part. GraphQLResponse had previously (in v4)
moved most of its fields onto result; we now instead of body with two
kinds determining the structure of the rest of the response.
HTTPGraphQLResponse (new in v4) had tried to anticipate this change, but now
the structure is a bit different.

A few other changes were made for compatibility with graphql@17 such as
removing some uses of the non-options multi-argument GraphQLError constructor.

Add two new plugin APIs: didEncounterSubsequentErrors and
willSendSubsequentPayload.

Updates to plugins:

Usage reporting waits until all payloads are ready before it's done with
a given operation.
The response cache does not cache incremental responses (although that would
likely be quite helpful).
No cache-control HTTP headers are written with incremental responses (since we
don't know all the fields that will be executed yet).
Inline traces are not added to incremental delivery responses (though it might
make sense to add them to the last payload or something).

Fixes #6671.

netlify · 2022-08-18T06:05:12Z

✅ Deploy Preview for apollo-server-docs ready!

Name	Link
🔨 Latest commit	`93c14b9`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-server-docs/deploys/632e3f476d67ed0008eb6e2f
😎 Deploy Preview	https://deploy-preview-6827--apollo-server-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

glasser · 2022-08-18T17:32:29Z

packages/server/src/express4/index.ts

+        // FIXME double check that this will always lead to chunked.
+        // FIXME error handling? is `then async` above legit?
+        for await (const chunk of httpGraphQLResponse.body.asyncIterator) {
+          res.write(chunk);


maybe have some sort of flush here?

I think this is still a thing, if using compression.

glasser · 2022-08-18T17:38:51Z

packages/server/src/externalTypes/graphql.ts

@@ -23,9 +23,9 @@ export interface GraphQLRequest {
 export type VariableValues = { [name: string]: any };

 export interface GraphQLResponse {
-  // TODO(AS4): for incremental delivery, maybe we'll have an iterator here
-  // instead of a single result?
  result: FormattedExecutionResult;


FormattedExecutionResult | FormattedFirstAsyncExecutionResult

glasser · 2022-08-18T17:39:05Z

packages/server/src/externalTypes/graphql.ts

  result: FormattedExecutionResult;
+  // FIXME doc
+  subsequentResults: AsyncIterable<FormattedExecutionResult> | null;


AsyncIterable<FormattedSubsequentAsyncExecutionResult> | null

codesandbox-ci · 2022-09-22T20:26:25Z

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.

Latest deployment of this branch, based on commit 93c14b9:

Sandbox	Source
Apollo Server Typescript	Configuration
Apollo Server	Configuration

Also provides improved compatibility with the graphql-over-http spec by supporting `content-type: application/graphql-response+json` if requested via `accept` header, and adds `; charset=utf-8` to content-types. Executing `@defer` and `@stream` directives requires you to install pre-release of `graphql@17` in your server. This PR does not update `package.json` to install that prerelease (nor does it even broaden peer deps, which would be inadequate as many of its dependencies have peer deps that won't include v17). However, it does add a new CI step that installs a particular v17 pre-release and runs the test suite and smoke test (including running some otherwise-disabled tests that exercise the execution of these directives). We also add a new `__testing_incrementalExecutionResults` option that lets us test transport-level behavior without installing the prerelease. This change reworks `GraphQLResponse` and `HTTPGraphQLResponse` to allow responses to be single- or multi-part. `GraphQLResponse` had previously (in v4) moved most of its fields onto `result`; we now instead of `body` with two `kind`s determining the structure of the rest of the response. `HTTPGraphQLResponse` (new in v4) had tried to anticipate this change, but now the structure is a bit different. A few other changes were made for compatibility with `graphql@17` such as removing some uses of the non-options multi-argument GraphQLError constructor. Add two new plugin APIs: `didEncounterSubsequentErrors` and `willSendSubsequentPayload`. Updates to plugins: - Usage reporting waits until all payloads are ready before it's done with a given operation. - The response cache does not cache incremental responses (although that would likely be quite helpful). - No cache-control HTTP headers are written with incremental responses (since we don't know all the fields that will be executed yet). - Inline traces are not added to incremental delivery responses (though it might make sense to add them to the last payload or something). Fixes #6671.

docs/source/integrations/building-integrations.md

docs/source/migration.mdx

trevor-scheer · 2022-09-23T21:27:41Z

docs/source/migration.mdx

@@ -1127,7 +1130,7 @@ const server = new ApolloServer({
  context: async ({ req }) => ({ name: req.headers.name }),
 });

-const { result } = await server.executeOperation({
+const result = await server.executeOperation({


This was just incorrect before, right?

No, GraphQLResponse in version-4 previously had a result field (new in 4).

docs/source/migration.mdx

trevor-scheer · 2022-09-23T21:35:56Z

packages/integration-testsuite/src/apolloServerTests.ts

+                  if (!('singleResult' in response.body)) {
+                    throw Error('expected single result');
+                  }


Good use for assert like you demonstrated above?

Well, I did it in one place instead of calling the function, but the function seems a little easy to use than the same repeated two lines each time.

Co-authored-by: Trevor Scheer <trevor.scheer@gmail.com>

@glasser

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 version-4, this PR will be updated. ⚠️

⚠️

⚠️ `version-4` 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 `version-4`. ⚠️

⚠️

⚠️ # Releases ## @apollo/server-integration-testsuite@4.0.0-alpha.12 ### Patch Changes - [#6827](#6827) [`0c2909aa1`](0c2909a) Thanks [@glasser](https://github.com/glasser)! - Experimental support for incremental delivery (`@defer`/`@stream`) when combined with a prerelease of `graphql-js`. - [#6850](#6850) [`256f2424b`](256f242) Thanks [@renovate](https://github.com/apps/renovate)! - Expand jest peer deps to include v29 - [#6910](#6910) [`6541f92c9`](6541f92) Thanks [@trevor-scheer](https://github.com/trevor-scheer)! - Update snapshot format to future jest v29 default - [#6827](#6827) [`0c2909aa1`](0c2909a) Thanks [@glasser](https://github.com/glasser)! - Support application/graphql-response+json content-type if requested via Accept header, as per graphql-over-http spec. Include `charset=utf-8` in content-type headers. - Updated dependencies \[[`0c2909aa1`](0c2909a), [`0c2909aa1`](0c2909a)]: - @apollo/server@4.0.0-alpha.12 ## @apollo/server-plugin-response-cache@4.0.0-alpha.5 ### Patch Changes - [#6827](#6827) [`0c2909aa1`](0c2909a) Thanks [@glasser](https://github.com/glasser)! - Experimental support for incremental delivery (`@defer`/`@stream`) when combined with a prerelease of `graphql-js`. - Updated dependencies \[[`0c2909aa1`](0c2909a), [`0c2909aa1`](0c2909a)]: - @apollo/server@4.0.0-alpha.12 ## @apollo/server@4.0.0-alpha.12 ### Patch Changes - [#6827](#6827) [`0c2909aa1`](0c2909a) Thanks [@glasser](https://github.com/glasser)! - Experimental support for incremental delivery (`@defer`/`@stream`) when combined with a prerelease of `graphql-js`. - [#6827](#6827) [`0c2909aa1`](0c2909a) Thanks [@glasser](https://github.com/glasser)! - Support application/graphql-response+json content-type if requested via Accept header, as per graphql-over-http spec. Include `charset=utf-8` in content-type headers. Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

glasser commented Aug 18, 2022

View reviewed changes

glasser force-pushed the glasser/experimental-incremental-delivery branch from 1cf6807 to 9f1e4ef Compare August 24, 2022 01:12

glasser force-pushed the glasser/experimental-incremental-delivery branch 2 times, most recently from 077cadc to bf5a3cc Compare September 22, 2022 20:22

glasser force-pushed the glasser/experimental-incremental-delivery branch 2 times, most recently from 6d7ccf6 to 9c5b20a Compare September 23, 2022 16:31

glasser changed the title ~~Checkpoint for experimental incremental delivery support~~ Experimental support for incremental delivery (@defer/@stream) Sep 23, 2022

glasser force-pushed the glasser/experimental-incremental-delivery branch 5 times, most recently from d1f9878 to c1d052b Compare September 23, 2022 22:03

glasser marked this pull request as ready for review September 23, 2022 22:21

glasser force-pushed the glasser/experimental-incremental-delivery branch from c1d052b to f29eae4 Compare September 23, 2022 22:47

trevor-scheer reviewed Sep 23, 2022

View reviewed changes

glasser and others added 5 commits September 23, 2022 16:05

Update docs/source/integrations/building-integrations.md

5cf0b21

Co-authored-by: Trevor Scheer <trevor.scheer@gmail.com>

Update docs/source/migration.mdx

2ceec88

Co-authored-by: Trevor Scheer <trevor.scheer@gmail.com>

Update docs/source/migration.mdx

e97ee40

Co-authored-by: Trevor Scheer <trevor.scheer@gmail.com>

Update docs/source/migration.mdx

e5b7528

Co-authored-by: Trevor Scheer <trevor.scheer@gmail.com>

add more application/json to match recommendations

93c14b9

trevor-scheer approved these changes Sep 23, 2022

View reviewed changes

glasser merged commit 0c2909a into version-4 Sep 23, 2022

glasser deleted the glasser/experimental-incremental-delivery branch September 23, 2022 23:42

github-actions bot mentioned this pull request Sep 23, 2022

Version Packages (alpha) #6908

Merged

github-actions bot mentioned this pull request Oct 10, 2022

Version Packages #7017

Merged

igrlk mentioned this pull request Oct 25, 2022

feat: @defer support mercurius-js/mercurius#898

Open

1 task

Banou26 mentioned this pull request Jan 1, 2023

@defer & @stream experimental usage & docs #7279

Closed

github-actions bot locked as resolved and limited conversation to collaborators Apr 20, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Experimental support for incremental delivery (`@defer`/`@stream`) #6827

Experimental support for incremental delivery (`@defer`/`@stream`) #6827

glasser commented Aug 18, 2022 •

edited

Loading

netlify bot commented Aug 18, 2022 •

edited

Loading

glasser Aug 18, 2022

glasser Sep 23, 2022

glasser Aug 18, 2022

glasser Aug 18, 2022

codesandbox-ci bot commented Sep 22, 2022 •

edited

Loading

trevor-scheer Sep 23, 2022

glasser Sep 23, 2022

trevor-scheer Sep 23, 2022

glasser Sep 23, 2022

Experimental support for incremental delivery (@defer/@stream) #6827

Experimental support for incremental delivery (@defer/@stream) #6827

Conversation

glasser commented Aug 18, 2022 • edited Loading

netlify bot commented Aug 18, 2022 • edited Loading

✅ Deploy Preview for apollo-server-docs ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codesandbox-ci bot commented Sep 22, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Experimental support for incremental delivery (`@defer`/`@stream`) #6827

Experimental support for incremental delivery (`@defer`/`@stream`) #6827

glasser commented Aug 18, 2022 •

edited

Loading

netlify bot commented Aug 18, 2022 •

edited

Loading

codesandbox-ci bot commented Sep 22, 2022 •

edited

Loading