feat: @defer support

docs/api/options.md

@@ -52,6 +52,10 @@
 
 - `jit`: Integer. The minimum number of execution a query needs to be
   executed before being jit'ed.
+  - Default: `0`, jit is disabled.
+  - _jit can't be used together with `defer: true`_
+- `defer`: boolean. Default: `false`. Enable @defer directive execution support.
+  - _defer can't be used together with `jit`_
 - `routes`: boolean. Serves the Default: `true`. A graphql endpoint is
   exposed at `/graphql`.
 - `path`: string. Change default graphql `/graphql` route to another one.

index.d.ts

@@ -437,17 +437,52 @@ export interface MercuriusSchemaOptions {
   schemaTransforms?: ((originalSchema: GraphQLSchema) => GraphQLSchema) | Array<(originalSchema: GraphQLSchema) => GraphQLSchema>;
 }
 
+export interface MercuriusGraphiQLOptions {
+  /**
+   * Expose the graphiql app, default `true`
+   */
+  enabled?: boolean;
+  /**
+   * The list of plugin to add to GraphiQL
+   */
+  plugins?: Array<{
+    /**
+     * The name of the plugin, it should be the same exported in the `umd`
+     */
+    name: string;
+    /**
+     * The props to be passed to the plugin
+     */
+    props?: Object;
+    /**
+     * The urls of the plugin, it's downloaded at runtime. (eg. https://unpkg.com/myplugin/....)
+     */
+    umdUrl: string;
+    /**
+     * A function name exported by the plugin to read/enrich the fetch response
+     */
+    fetcherWrapper?: string;
+  }>
+}
+
 export interface MercuriusCommonOptions {
   /**
    * Serve GraphiQL on /graphiql if true or 'graphiql' and if routes is true
    */
-  graphiql?: boolean | 'graphiql';
-  ide?: boolean | 'graphiql';
+  graphiql?: boolean | 'graphiql' | MercuriusGraphiQLOptions;
+  ide?: boolean | 'graphiql' | MercuriusGraphiQLOptions;
   /**
    * The minimum number of execution a query needs to be executed before being jit'ed.
+   * Can't be enabled with MercuriusCommonOptions.defer
    * @default 0 - disabled
    */
   jit?: number;
+  /**
+   * Enable @defer directive execution support.
+   * Can't be enabled with MercuriusCommonOptions.jit
+   * @default false
+   */
+  defer?: boolean;
   /**
    * A graphql endpoint is exposed at /graphql when true
    * @default true

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,24 @@ const plugin = fp(async function (app, opts) {
     })
   }
 
+  if (opts.defer) {
+    if (opts.jit) {
+      throw new MER_ERR_INVALID_OPTS("@defer and JIT can't be used together")
+    }
+
+    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 +566,7 @@ const plugin = fp(async function (app, opts) {
       return maybeFormatErrors(execution, context)
     }
 
-    const execution = await execute({
+    const execution = await executeGraphql(opts.defer, {
       schema: modifiedSchema || fastifyGraphQl.schema,
       document: modifiedDocument || document,
       rootValue: root,
@@ -555,9 +575,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/federation.js

@@ -92,7 +92,7 @@ function getStubTypes (schemaDefinitions, isGateway) {
   const directiveDefinitions = []
 
   for (const definition of schemaDefinitions) {
-    if (definition.kind === 'SchemaDefinition') {
+    if (definition.kind === 'SchemaDefinition' || definition.kind === 'SchemaExtension') {
       continue
     }
 

lib/gateway/build-gateway.js

@@ -313,7 +313,7 @@ async function buildGateway (gatewayOpts, app) {
     throw new MER_ERR_GQL_GATEWAY_INIT('No valid service SDLs were provided')
   }
 
-  const schema = buildFederatedSchema(serviceSDLs.join(''), true)
+  const schema = buildFederatedSchema(serviceSDLs.join(' '), true)
 
   const typeToServiceMap = {}
   const typeFieldsToService = {}
@@ -419,7 +419,7 @@ async function buildGateway (gatewayOpts, app) {
     async refresh (isRetry) {
       const failedMandatoryServices = []
       if (this._serviceSDLs === undefined) {
-        this._serviceSDLs = serviceSDLs.join('')
+        this._serviceSDLs = serviceSDLs.join(' ')
       }
 
       const $refreshResult = await Promise.allSettled(
@@ -458,7 +458,7 @@ async function buildGateway (gatewayOpts, app) {
 
       const _serviceSDLs = Object.values(serviceMap)
         .map((service) => service.schemaDefinition)
-        .join('')
+        .join(' ')
 
       if (this._serviceSDLs === _serviceSDLs) {
         return null

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,23 @@ function hasExtensionDirective (node) {
   }
 }
 
+// istanbul ignore next
+function executeGraphql (isDeferEnabled, args) {
+  if (isDeferEnabled) {
+    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,
+  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",