feat: export the mask error function + gateway notes (#2364)

Co-authored-by: Arda TANRIKULU <ardatanrikulu@gmail.com>

.changeset/old-spiders-perform.md

@@ -0,0 +1,21 @@
+---
+'graphql-yoga': minor
+---
+
+export the yoga default format error function.
+
+```ts
+import { maskError, createYoga } from 'graphql-yoga'
+
+const yoga = createYoga({
+  maskedErrors: {
+    maskError(error, message, isDev) {
+      if (error?.extensions?.code === 'DOWNSTREAM_SERVICE_ERROR') {
+        return error
+      }
+
+      return maskError(error, message, isDev)
+    }
+  }
+})
+```

examples/apollo-federation/__integration-tests__/apollo-federation.spec.ts

@@ -51,4 +51,27 @@ describe('apollo-federation example integration', () => {
       },
     })
   })
+
+  it('pass through errors', async () => {
+    const response = await fetch(
+      `http://localhost:${gatewayPort}/graphql?query=query{throw}`,
+    )
+    const body = await response.json()
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "data": {
+          "throw": null,
+        },
+        "errors": [
+          {
+            "extensions": {
+              "code": "DOWNSTREAM_SERVICE_ERROR",
+              "serviceName": "accounts",
+            },
+            "message": "This should throw.",
+          },
+        ],
+      }
+    `)
+  })
 })

examples/apollo-federation/gateway/gateway.js

@@ -1,9 +1,9 @@
 /* eslint-disable */
-const { createYoga } = require('graphql-yoga')
+const { createYoga, maskError } = require('graphql-yoga')
 const { ApolloGateway, RemoteGraphQLDataSource } = require('@apollo/gateway')
 const { useApolloFederation } = require('@envelop/apollo-federation')
 
-export async function gateway(config) {
+module.exports.gateway = async function gateway(config) {
   // Initialize the gateway
   const gateway = new ApolloGateway(config)
 
@@ -16,6 +16,15 @@ export async function gateway(config) {
         gateway,
       }),
     ],
+    maskedErrors: {
+      maskError(error, message, isDev) {
+        // Note: it seems like the "useApolloFederation" plugin should do this by default?
+        if (error?.extensions?.code === 'DOWNSTREAM_SERVICE_ERROR') {
+          return error
+        }
+        return maskError(error, message, isDev)
+      },
+    },
   })
 
   return yoga
@@ -27,7 +36,7 @@ export async function gateway(config) {
  * By default Yoga uses `application/graphql-response+json` content type as per the GraphQL over HTTP spec
  * https://github.com/apollographql/federation/issues/2161
  */
-export class DataSource extends RemoteGraphQLDataSource {
+module.exports.DataSource = class DataSource extends RemoteGraphQLDataSource {
   willSendRequest({ request }) {
     request.http.headers.set('accept', 'application/json')
   }

examples/apollo-federation/service/yoga.js

@@ -1,11 +1,12 @@
 /* eslint-disable */
-const { parse } = require('graphql')
+const { parse, GraphQLError } = require('graphql')
 const { buildSubgraphSchema } = require('@apollo/subgraph')
 const { createYoga } = require('graphql-yoga')
 
 const typeDefs = parse(/* GraphQL */ `
   type Query {
     me: User
+    throw: String
   }
 
   type User @key(fields: "id") {
@@ -19,6 +20,9 @@ const resolvers = {
     me() {
       return { id: '1', username: '@ava' }
     },
+    throw() {
+      throw new GraphQLError('This should throw.')
+    },
   },
   User: {
     __resolveReference(user, { fetchUserById }) {
@@ -27,6 +31,6 @@ const resolvers = {
   },
 }
 
-export const yoga = createYoga({
+module.exports.yoga = createYoga({
   schema: buildSubgraphSchema([{ typeDefs, resolvers }]),
 })

packages/graphql-yoga/src/index.ts

@@ -10,6 +10,7 @@ export * from './schema.js'
 export * from './server.js'
 export * from './subscription.js'
 export * from './types.js'
+export { maskError } from './utils/mask-error.js'
 export type {
   // Handy type utils
   Maybe,

packages/graphql-yoga/src/server.ts

@@ -70,7 +70,7 @@ import {
   YogaInitialContext,
   YogaMaskedErrorOpts,
 } from './types.js'
-import { yogaDefaultFormatError } from './utils/yoga-default-format-error.js'
+import { maskError } from './utils/mask-error.js'
 
 /**
  * Configuration options for the server
@@ -219,7 +219,7 @@ export class YogaServer<
       }
     }
 
-    const logger = options?.logging != null ? options.logging : true
+    const logger = options?.logging == null ? true : options.logging
     this.logger =
       typeof logger === 'boolean'
         ? logger === true
@@ -232,7 +232,7 @@ export class YogaServer<
     const maskErrorFn: MaskError =
       (typeof options?.maskedErrors === 'object' &&
         options.maskedErrors.maskError) ||
-      yogaDefaultFormatError
+      maskError
 
     const maskedErrorSet = new WeakSet()
 
@@ -265,7 +265,7 @@ export class YogaServer<
           }
 
     const maskedErrors =
-      this.maskedErrorsOpts != null ? this.maskedErrorsOpts : null
+      this.maskedErrorsOpts == null ? null : this.maskedErrorsOpts
 
     let batchingLimit = 0
     if (options?.batching) {

packages/graphql-yoga/src/utils/yoga-default-format-error.ts → packages/graphql-yoga/src/utils/mask-error.ts

@@ -4,7 +4,7 @@ import { createGraphQLError } from '@graphql-tools/utils'
 import { isGraphQLError } from '../error.js'
 import { MaskError } from '../types.js'
 
-export const yogaDefaultFormatError: MaskError = (
+export const maskError: MaskError = (
   error: unknown,
   message: string,
   isDev = globalThis.process?.env?.NODE_ENV === 'development',

website/src/pages/docs/features/apollo-federation.mdx

@@ -68,6 +68,31 @@ server.listen(4000, () => {
 })
 ```
 
+### Handling Subgraph Errors
+
+By default, GraphQL Yoga masks any unexpected GraphQL Errors. This is done to prevent leaking internal errors to the client.
+If you know that your subgraph is safe and you want to expose the errors to the client, you can customize the error masking bahviour.
+
+[Learn more about error masking](/docs/features/error-masking)
+
+```ts filename="Expose subgraph errors to the client"
+import { maskError, createYoga } from 'graphql-yoga'
+import { schema } from './schema.js'
+
+const yoga = createYoga({
+  schema,
+  maskedErrors: {
+    maskError(error, message, isDev) {
+      if (error?.extensions?.code === 'DOWNSTREAM_SERVICE_ERROR') {
+        return error
+      }
+
+      return maskError(error, message, isDev)
+    }
+  }
+})
+```
+
 ## Federation Service
 
 You don't need any extra plugins for Yoga for Federation Service.

website/src/pages/docs/features/error-masking.mdx

@@ -381,3 +381,28 @@ query {
   "data": null
 }
 ```
+
+## Customize error masking
+
+For advanced use-cases e.g. when using GraphQL Yoga as a Gateway, you might to automatically expose errors that are resolved from the subgraphs as you asume these already take care of hiding sensitive information.
+In this case, you can customize the error masking behavior by providing a custom `maskError` function.
+
+Use the default `maskError` function as a fallback for all other errors.
+
+```ts filename="Custom Mask Error Usage"
+import { maskError, createYoga } from 'graphql-yoga'
+import { schema } from './schema.js'
+
+const yoga = createYoga({
+  schema,
+  maskedErrors: {
+    maskError(error, message, isDev) {
+      if (error?.extensions?.code === 'DOWNSTREAM_SERVICE_ERROR') {
+        return error
+      }
+
+      return maskError(error, message, isDev)
+    }
+  }
+})
+```