feat: @defer support

index.js

@@ -18,10 +18,10 @@ const {
   extendSchema,
   validate,
   validateSchema,
-  specifiedRules,
-  execute
+  specifiedRules
 } = require('graphql')
 const { buildExecutionContext } = require('graphql/execution/execute')
+const { Readable } = require('stream')
 const queryDepth = require('./lib/queryDepth')
 const buildFederationSchema = require('./lib/federation')
 const { initGateway } = require('./lib/gateway')
@@ -37,7 +37,8 @@ const {
   MER_ERR_GQL_VALIDATION,
   MER_ERR_INVALID_OPTS,
   MER_ERR_METHOD_NOT_ALLOWED,
-  MER_ERR_INVALID_METHOD
+  MER_ERR_INVALID_METHOD,
+  MER_ERR_INVALID_MULTIPART_ACCEPT_HEADER
 } = require('./lib/errors')
 const { Hooks, assignLifeCycleHooksToContext } = require('./lib/hooks')
 const { kLoaders, kFactory, kSubscriptionFactory, kHooks } = require('./lib/symbols')
@@ -47,6 +48,7 @@ const {
   preExecutionHandler,
   onResolutionHandler
 } = require('./lib/handlers')
+const { executeGraphql, MEDIA_TYPES } = require('./lib/util')
 
 // Required for module bundlers
 // istanbul ignore next
@@ -187,6 +189,20 @@ const plugin = fp(async function (app, opts) {
     })
   }
 
+  if (opts.defer) {
+    app.register(require('@fastify/accepts'))
+
+    schema = extendSchema(
+      schema,
+      parse(`
+        directive @defer(
+          if: Boolean! = true
+          label: String
+        ) on FRAGMENT_SPREAD | INLINE_FRAGMENT
+      `)
+    )
+  }
+
   fastifyGraphQl.schema = schema
 
   app.addHook('onReady', async function () {
@@ -546,7 +562,7 @@ const plugin = fp(async function (app, opts) {
       return maybeFormatErrors(execution, context)
     }
 
-    const execution = await execute({
+    const execution = await executeGraphql({
       schema: modifiedSchema || fastifyGraphQl.schema,
       document: modifiedDocument || document,
       rootValue: root,
@@ -555,9 +571,85 @@ const plugin = fp(async function (app, opts) {
       operationName
     })
 
+    /* istanbul ignore next */
+    if (execution.initialResult) {
+      const accept = reply.request.accepts() // Accepts object
+
+      if (
+        !(
+          accept.negotiator.mediaType([
+            // mediaType() will return the first one that matches, so if the client
+            // doesn't include the deferSpec parameter it will match this one here,
+            // which isn't good enough.
+            MEDIA_TYPES.MULTIPART_MIXED_NO_DEFER_SPEC,
+            MEDIA_TYPES.MULTIPART_MIXED_EXPERIMENTAL
+          ]) === MEDIA_TYPES.MULTIPART_MIXED_EXPERIMENTAL
+        )
+      ) {
+        // The client ran an operation that would yield multiple parts, but didn't
+        // specify `accept: multipart/mixed`. We return an error.
+        throw new MER_ERR_INVALID_MULTIPART_ACCEPT_HEADER()
+      }
+
+      reply.header('content-type', 'multipart/mixed; boundary="-"; deferSpec=20220824')
+
+      return Readable.from(
+        writeMultipartBody(
+          execution.initialResult,
+          execution.subsequentResults
+        )
+      )
+    }
+
     return maybeFormatErrors(execution, context)
   }
 
+  /* istanbul ignore next */
+  async function * writeMultipartBody (initialResult, subsequentResults) {
+    yield `\r\n---\r\ncontent-type: application/json; charset=utf-8\r\n\r\n${JSON.stringify(
+      orderInitialIncrementalExecutionResultFields(initialResult)
+    )}\r\n---${initialResult.hasNext ? '' : '--'}\r\n`
+
+    for await (const result of subsequentResults) {
+      yield `content-type: application/json; charset=utf-8\r\n\r\n${JSON.stringify(
+        orderSubsequentIncrementalExecutionResultFields(result)
+      )}\r\n---${result.hasNext ? '' : '--'}\r\n`
+    }
+  }
+
+  /* istanbul ignore next */
+  function orderInitialIncrementalExecutionResultFields (result) {
+    return {
+      hasNext: result.hasNext,
+      errors: result.errors,
+      data: result.data,
+      incremental: orderIncrementalResultFields(result.incremental),
+      extensions: result.extensions
+    }
+  }
+
+  /* istanbul ignore next */
+  function orderSubsequentIncrementalExecutionResultFields (result) {
+    return {
+      hasNext: result.hasNext,
+      incremental: orderIncrementalResultFields(result.incremental),
+      extensions: result.extensions
+    }
+  }
+
+  /* istanbul ignore next */
+  function orderIncrementalResultFields (incremental) {
+    return incremental?.map((i) => ({
+      hasNext: i.hasNext,
+      errors: i.errors,
+      path: i.path,
+      label: i.label,
+      data: i.data,
+      items: i.items,
+      extensions: i.extensions
+    }))
+  }
+
   async function maybeFormatErrors (execution, context) {
     execution = addErrorsToExecutionResult(execution, context.errors)
 

lib/errors.js

@@ -35,12 +35,14 @@ function toGraphQLError (err) {
 
   const gqlError = new GraphQLError(
     err.message,
-    err.nodes,
-    err.source,
-    err.positions,
-    err.path,
-    err,
-    err.extensions
+    {
+      nodes: err.nodes,
+      source: err.source,
+      positions: err.positions,
+      path: err.path,
+      originalError: err,
+      extensions: err.extensions
+    }
   )
 
   gqlError.locations = err.locations
@@ -137,6 +139,10 @@ const errors = {
     'Method not allowed',
     405
   ),
+  MER_ERR_INVALID_MULTIPART_ACCEPT_HEADER: createError(
+    'MER_ERR_INVALID_MULTIPART_ACCEPT_HEADER',
+    'Server received an operation that uses incremental delivery (@defer or @stream), but the client does not accept multipart/mixed HTTP responses. To enable incremental delivery support, add the HTTP header "Accept: multipart/mixed; deferSpec=20220824".'
+  ),
   /**
    * General graphql errors
    */

lib/util.js

@@ -1,5 +1,8 @@
 'use strict'
 
+const { execute } = require('graphql')
+const { experimentalExecuteIncrementally } = require('graphql/execution')
+
 function hasDirective (directiveName, node) {
   if (!node.directives || node.directives.length < 1) {
     return false
@@ -23,7 +26,26 @@ function hasExtensionDirective (node) {
   }
 }
 
+const canUseIncrementalExecution = !!require('graphql/execution').experimentalExecuteIncrementally
+
+// istanbul ignore next
+function executeGraphql (args) {
+  if (canUseIncrementalExecution) {
+    return experimentalExecuteIncrementally(args)
+  }
+
+  return execute(args)
+}
+
+const MEDIA_TYPES = {
+  MULTIPART_MIXED_NO_DEFER_SPEC: 'multipart/mixed',
+  MULTIPART_MIXED_EXPERIMENTAL: 'multipart/mixed; deferSpec=20220824'
+}
+
 module.exports = {
   hasDirective,
-  hasExtensionDirective
+  hasExtensionDirective,
+  canUseIncrementalExecution,
+  executeGraphql,
+  MEDIA_TYPES
 }

package.json

@@ -27,7 +27,7 @@
   },
   "homepage": "https://mercurius.dev",
   "peerDependencies": {
-    "graphql": "^16.0.0"
+    "graphql": "^17.0.0-alpha.2"
   },
   "devDependencies": {
     "@graphql-tools/merge": "^8.0.0",
@@ -56,12 +56,13 @@
     "wait-on": "^6.0.0"
   },
   "dependencies": {
+    "@fastify/accepts": "^4.0.1",
     "@fastify/error": "^3.0.0",
     "@fastify/static": "^6.0.0",
     "@fastify/websocket": "^7.0.0",
     "events.on": "^1.0.1",
     "fastify-plugin": "^4.2.0",
-    "graphql": "^16.0.0",
+    "graphql": "^17.0.0-alpha.2",
     "graphql-jit": "^0.7.3",
     "mqemitter": "^5.0.0",
     "p-map": "^4.0.0",