Configure Subgraph Error handling (#997)

ardatan · web-flow · commit 4cf75cbf1f14 · 2025-04-09T13:36:53.000+03:00
diff --git a/.changeset/quick-buses-obey.md b/.changeset/quick-buses-obey.md
@@ -0,0 +1,17 @@
+---
+'@graphql-tools/executor-http': major
+'@graphql-mesh/transport-http-callback': minor
+'@graphql-hive/gateway-runtime': minor
+'@graphql-tools/federation': patch
+---
+
+- **BREAKING**: HTTP Executor no longer takes `serviceName` as an option.
+- Both HTTP executor and `@graphql-mesh/transport-http-callback` no longer handle `DOWNSTREAM_SERVICE_ERROR` error code with `serviceName`.
+- Gateway runtime handles subgraph errors on its own with `DOWNSTREAM_SERVICE_ERROR` error code and `serviceName` as a property. This behavior can be configured with `subgraphErrors` option of the `createGatewayRuntime` function or CLI config.
+
+```ts
+subgraphError: {
+   errorCode: 'DOWNSTREAM_SERVICE_ERROR', // or `false` to remove this code completely
+   subgraphNameProp: 'serviceName' // or `false` to remove this prop completely
+}
+```
diff --git a/packages/executors/http/src/index.ts b/packages/executors/http/src/index.ts
@@ -57,10 +57,6 @@ export type AsyncImportFn = (moduleName: string) => PromiseLike<any>;
 export type SyncImportFn = (moduleName: string) => any;
 
 export interface HTTPExecutorOptions {
-  /**
-   * The name of the service
-   */
-  serviceName?: string;
   /**
    * The endpoint to use when querying the upstream API
    * @default '/graphql'
@@ -163,7 +159,6 @@ export function buildHTTPExecutor(
 ): DisposableExecutor<any, HTTPExecutorOptions> {
   const printFn = options?.print ?? defaultPrintFn;
   let disposeCtrl: AbortController | undefined;
-  const serviceName = options?.serviceName;
   const baseExecutor = (
     request: ExecutionRequest<any, any, any, HTTPExecutorOptions>,
     excludeQuery?: boolean,
@@ -237,8 +232,6 @@ export function buildHTTPExecutor(
     const signal = abortSignalAny(signals);
 
     const upstreamErrorExtensions: UpstreamErrorExtensions = {
-      code: 'DOWNSTREAM_SERVICE_ERROR',
-      serviceName,
       request: {
         method,
       },
@@ -442,15 +435,7 @@ export function buildHTTPExecutor(
                             }: {
                               message: string;
                               extensions: Record<string, unknown>;
-                            }) =>
-                              createGraphQLError(message, {
-                                ...options,
-                                extensions: {
-                                  code: 'DOWNSTREAM_SERVICE_ERROR',
-                                  serviceName,
-                                  ...(options.extensions || {}),
-                                },
-                              }),
+                            }) => createGraphQLError(message, options),
                           ),
                         };
                       }
diff --git a/packages/executors/http/tests/buildHTTPExecutor.test.ts b/packages/executors/http/tests/buildHTTPExecutor.test.ts
@@ -285,14 +285,7 @@ describe('buildHTTPExecutor', () => {
       `),
     });
     expect(res).toMatchObject({
-      errors: expect.arrayContaining([
-        expect.any(GraphQLError),
-        expect.objectContaining({
-          extensions: {
-            code: 'DOWNSTREAM_SERVICE_ERROR',
-          },
-        }),
-      ]),
+      errors: expect.arrayContaining([expect.any(GraphQLError)]),
     });
   });
 
diff --git a/packages/federation/src/supergraph.ts b/packages/federation/src/supergraph.ts
@@ -1053,7 +1053,6 @@ export function getStitchingOptionsFromSupergraphSdl(
     }
     let executor: Executor = buildHTTPExecutor({
       endpoint,
-      serviceName: subgraphName,
       ...httpExecutorOpts,
     });
     if (globalThis.process?.env?.['DEBUG']) {
diff --git a/packages/federation/tests/unavailable-subgraph.test.ts b/packages/federation/tests/unavailable-subgraph.test.ts
@@ -187,12 +187,10 @@ describe('Yoga gateway - subgraph unavailable', () => {
             {
               message: expect.stringContaining('connect'),
               extensions: {
-                code: 'DOWNSTREAM_SERVICE_ERROR',
                 request: {
                   body: '{"query":"{__typename testNestedField{subgraph2{testSuccessQuery{id email sub2}}}}"}',
                   method: 'POST',
                 },
-                serviceName: 'SUBGRAPH2',
               },
               path: ['testNestedField'],
             },
@@ -230,12 +228,10 @@ describe('Yoga gateway - subgraph unavailable', () => {
             {
               message: expect.stringContaining('connect'),
               extensions: {
-                code: 'DOWNSTREAM_SERVICE_ERROR',
                 request: {
                   body: '{"query":"{__typename testNestedField{subgraph2{testErrorQuery{id email sub2}}}}"}',
                   method: 'POST',
                 },
-                serviceName: 'SUBGRAPH2',
               },
               path: ['testNestedField'],
             },
diff --git a/packages/runtime/src/createGatewayRuntime.ts b/packages/runtime/src/createGatewayRuntime.ts
@@ -98,6 +98,7 @@ import useHiveConsole from './plugins/useHiveConsole';
 import { usePropagateHeaders } from './plugins/usePropagateHeaders';
 import { useRequestId } from './plugins/useRequestId';
 import { useRetryOnSchemaReload } from './plugins/useRetryOnSchemaReload';
+import { useSubgraphErrorPlugin } from './plugins/useSubgraphErrorPlugin';
 import { useSubgraphExecuteDebug } from './plugins/useSubgraphExecuteDebug';
 import { useUpstreamCancel } from './plugins/useUpstreamCancel';
 import { useUpstreamRetry } from './plugins/useUpstreamRetry';
@@ -991,6 +992,16 @@ export function createGatewayRuntime<
     useRetryOnSchemaReload({ logger }),
   ];
 
+  if (config.subgraphErrors !== false) {
+    basePlugins.push(
+      useSubgraphErrorPlugin(
+        typeof config.subgraphErrors === 'object'
+          ? config.subgraphErrors
+          : undefined,
+      ),
+    );
+  }
+
   if (config.requestId !== false) {
     const reqIdPlugin = useRequestId(
       typeof config.requestId === 'object' ? config.requestId : undefined,
diff --git a/packages/runtime/src/plugins/useSubgraphErrorPlugin.ts b/packages/runtime/src/plugins/useSubgraphErrorPlugin.ts
@@ -0,0 +1,64 @@
+import { isAsyncIterable } from '@graphql-tools/utils';
+import { GraphQLError } from 'graphql';
+import { GatewayPlugin } from '../types';
+
+export interface SubgraphErrorPluginOptions {
+  /**
+   * The error code for the error that occurred in the subgraph.
+   *
+   * If set to `false`, the error code will not be included in the error.
+   *
+   * @default 'DOWNSTREAM_SERVICE_ERROR'
+   */
+  errorCode?: string | false;
+
+  /**
+   * The name of the extension field for the name of the subgraph
+   *
+   * If set to `false`, the subgraph name will not be included in the error.
+   *
+   * @default 'serviceName'
+   */
+  subgraphNameProp?: string | false;
+}
+
+export function useSubgraphErrorPlugin<
+  TContext extends Record<string, unknown>,
+>({
+  errorCode = 'DOWNSTREAM_SERVICE_ERROR',
+  subgraphNameProp = 'serviceName',
+}: SubgraphErrorPluginOptions = {}): GatewayPlugin<TContext> {
+  function extendError(error: GraphQLError, subgraphName: string) {
+    // @ts-expect-error - we know "extensions" is a property of GraphQLError
+    const errorExtensions = (error.extensions ||= {});
+    if (errorCode) {
+      errorExtensions.code ||= errorCode;
+    }
+    if (subgraphNameProp) {
+      errorExtensions[subgraphNameProp] ||= subgraphName;
+    }
+  }
+  return {
+    onSubgraphExecute({ subgraphName }) {
+      return function ({ result }) {
+        if (isAsyncIterable(result)) {
+          return {
+            onNext({ result }) {
+              if (result.errors) {
+                for (const error of result.errors) {
+                  extendError(error, subgraphName);
+                }
+              }
+            },
+          };
+        }
+        if (result.errors) {
+          for (const error of result.errors) {
+            extendError(error, subgraphName);
+          }
+        }
+        return;
+      };
+    },
+  };
+}
diff --git a/packages/runtime/src/types.ts b/packages/runtime/src/types.ts
@@ -42,6 +42,7 @@ import { DemandControlPluginOptions } from './plugins/useDemandControl';
 import { HiveConsolePluginOptions } from './plugins/useHiveConsole';
 import { PropagateHeadersOpts } from './plugins/usePropagateHeaders';
 import { RequestIdOptions } from './plugins/useRequestId';
+import { SubgraphErrorPluginOptions } from './plugins/useSubgraphErrorPlugin';
 import { UpstreamRetryPluginOptions } from './plugins/useUpstreamRetry';
 import { UpstreamTimeoutPluginOptions } from './plugins/useUpstreamTimeout';
 
@@ -661,6 +662,11 @@ interface GatewayConfigBase<TContext extends Record<string, any>> {
    * @experimental
    */
   __experimental__batchDelegation?: boolean;
+
+  /**
+   * Subgraph error handling
+   */
+  subgraphErrors?: SubgraphErrorPluginOptions | false;
 }
 
 interface DisableIntrospectionOptions {
diff --git a/packages/transports/http-callback/src/index.ts b/packages/transports/http-callback/src/index.ts
@@ -275,31 +275,10 @@ export default {
                 break;
               case 'complete':
                 if (message.errors) {
-                  if (message.errors.length === 1 && message.errors[0]) {
-                    const error = message.errors[0];
-                    stopSubscription(
-                      createGraphQLError(error.message, {
-                        ...error,
-                        extensions: {
-                          ...error.extensions,
-                          code: 'DOWNSTREAM_SERVICE_ERROR',
-                        },
-                      }),
-                    );
+                  if (message.errors.length === 1) {
+                    stopSubscription(message.errors[0]);
                   } else {
-                    stopSubscription(
-                      new AggregateError(
-                        message.errors.map((err) =>
-                          createGraphQLError(err.message, {
-                            ...err,
-                            extensions: {
-                              ...err.extensions,
-                              code: 'DOWNSTREAM_SERVICE_ERROR',
-                            },
-                          }),
-                        ),
-                      ),
-                    );
+                    stopSubscription(new AggregateError(message.errors));
                   }
                 } else {
                   stopSubscription();
diff --git a/packages/transports/http/src/index.ts b/packages/transports/http/src/index.ts
@@ -56,7 +56,6 @@ export default {
         : undefined,
       ...payload.transportEntry.options,
       getDisposeReason: payload.getDisposeReason,
-      serviceName: payload.subgraphName,
       // @ts-expect-error - TODO: Fix this in executor-http
       fetch: payload.fetch,
     });

Original file line number	Diff line number	Diff line change
`@@ -1053,7 +1053,6 @@ export function getStitchingOptionsFromSupergraphSdl(`
`1053`	`1053`	`}`
`1054`	`1054`	`let executor: Executor = buildHTTPExecutor({`
`1055`	`1055`	`endpoint,`
`1056`		`- serviceName: subgraphName,`
`1057`	`1056`	`...httpExecutorOpts,`
`1058`	`1057`	`});`
`1059`	`1058`	`if (globalThis.process?.env?.['DEBUG']) {`