feat(diagnostics): throw on re-registration with different dc module

Calling enableDiagnosticsChannel again with the same dc is now a no-op;
a different dc throws to surface the misconfiguration rather than
silently replacing channel references that subscribers already hold.

Author: logaretm

src/__testUtils__/fakeDiagnosticsChannel.ts

@@ -123,6 +123,14 @@ export class FakeDc implements MinimalDiagnosticsChannel {
   }
 }
 
+/**
+ * Shared fake `diagnostics_channel` instance used across all diagnostics
+ * test suites. `enableDiagnosticsChannel` now throws when called with a
+ * different `dc` module than the one previously registered, so all test
+ * files must register the same instance.
+ */
+export const sharedFakeDc: FakeDc = new FakeDc();
+
 export interface CollectedEvent {
   kind: 'start' | 'end' | 'asyncStart' | 'asyncEnd' | 'error';
   ctx: { [key: string]: unknown };

src/__tests__/diagnostics-test.ts

@@ -1,108 +1,55 @@
 import { expect } from 'chai';
 import { describe, it } from 'mocha';
 
+import { sharedFakeDc } from '../__testUtils__/fakeDiagnosticsChannel.js';
+
 import { invariant } from '../jsutils/invariant.js';
 
-import type {
-  MinimalDiagnosticsChannel,
-  MinimalTracingChannel,
-} from '../diagnostics.js';
 import { enableDiagnosticsChannel, getChannels } from '../diagnostics.js';
 
-function fakeTracingChannel(name: string): MinimalTracingChannel {
-  const noop: MinimalTracingChannel['start'] = {
-    hasSubscribers: false,
-    publish: () => {
-      /* noop */
-    },
-    runStores: <T>(
-      _ctx: unknown,
-      fn: (this: unknown, ...args: Array<unknown>) => T,
-    ): T => fn(),
-  };
-  const channel: MinimalTracingChannel & { _name: string } = {
-    _name: name,
-    hasSubscribers: false,
-    start: noop,
-    end: noop,
-    asyncStart: noop,
-    asyncEnd: noop,
-    error: noop,
-    traceSync: <T>(fn: (...args: Array<unknown>) => T): T => fn(),
-  };
-  return channel;
-}
-
-function fakeDc(): MinimalDiagnosticsChannel & {
-  created: Array<string>;
-} {
-  const created: Array<string> = [];
-  const cache = new Map<string, MinimalTracingChannel>();
-  return {
-    created,
-    tracingChannel(name: string) {
-      let existing = cache.get(name);
-      if (existing === undefined) {
-        created.push(name);
-        existing = fakeTracingChannel(name);
-        cache.set(name, existing);
-      }
-      return existing;
-    },
-  };
-}
-
 describe('diagnostics', () => {
-  it('registers the five graphql tracing channels', () => {
-    const dc = fakeDc();
-    enableDiagnosticsChannel(dc);
-
-    expect(dc.created).to.deep.equal([
-      'graphql:execute',
-      'graphql:parse',
-      'graphql:validate',
-      'graphql:resolve',
-      'graphql:subscribe',
-    ]);
+  it('exposes the five graphql tracing channels after registration', () => {
+    enableDiagnosticsChannel(sharedFakeDc);
 
     const channels = getChannels();
     invariant(channels !== undefined);
-    expect(channels.execute).to.not.equal(undefined);
-    expect(channels.parse).to.not.equal(undefined);
-    expect(channels.validate).to.not.equal(undefined);
-    expect(channels.resolve).to.not.equal(undefined);
-    expect(channels.subscribe).to.not.equal(undefined);
+    expect(channels.execute).to.equal(
+      sharedFakeDc.tracingChannel('graphql:execute'),
+    );
+    expect(channels.parse).to.equal(
+      sharedFakeDc.tracingChannel('graphql:parse'),
+    );
+    expect(channels.validate).to.equal(
+      sharedFakeDc.tracingChannel('graphql:validate'),
+    );
+    expect(channels.resolve).to.equal(
+      sharedFakeDc.tracingChannel('graphql:resolve'),
+    );
+    expect(channels.subscribe).to.equal(
+      sharedFakeDc.tracingChannel('graphql:subscribe'),
+    );
   });
 
-  it('re-registration with the same module preserves channel identity', () => {
-    const dc = fakeDc();
-    enableDiagnosticsChannel(dc);
+  it('re-registration with the same module is a no-op', () => {
+    enableDiagnosticsChannel(sharedFakeDc);
     const first = getChannels();
     invariant(first !== undefined);
 
-    enableDiagnosticsChannel(dc);
+    enableDiagnosticsChannel(sharedFakeDc);
     const second = getChannels();
-    invariant(second !== undefined);
 
-    expect(second.execute).to.equal(first.execute);
-    expect(second.parse).to.equal(first.parse);
-    expect(second.validate).to.equal(first.validate);
-    expect(second.resolve).to.equal(first.resolve);
-    expect(second.subscribe).to.equal(first.subscribe);
+    expect(second).to.equal(first);
   });
 
-  it('re-registration with a different module replaces stored references', () => {
-    const dc1 = fakeDc();
-    const dc2 = fakeDc();
-
-    enableDiagnosticsChannel(dc1);
-    const first = getChannels();
-    invariant(first !== undefined);
-
-    enableDiagnosticsChannel(dc2);
-    const second = getChannels();
-    invariant(second !== undefined);
+  it('re-registration with a different module throws', () => {
+    enableDiagnosticsChannel(sharedFakeDc);
 
-    expect(second.execute).to.not.equal(first.execute);
+    expect(() =>
+      enableDiagnosticsChannel({
+        tracingChannel: () => {
+          throw new Error('should not be called');
+        },
+      }),
+    ).to.throw(/different `diagnostics_channel` module/);
   });
 });

src/diagnostics.ts

@@ -74,6 +74,7 @@ export interface GraphQLChannels {
 }
 
 let channels: GraphQLChannels | undefined;
+let registeredDc: MinimalDiagnosticsChannel | undefined;
 
 /**
  * Internal accessor used at emission sites. Returns `undefined` when no
@@ -98,20 +99,31 @@ export function getChannels(): GraphQLChannels | undefined {
  *   - `graphql:subscribe`
  *   - `graphql:resolve`
  *
- * Calling this repeatedly is safe: subsequent calls replace the stored
- * channel references, but since `tracingChannel(name)` is cached by name,
- * the channel identities remain stable across registrations from the same
- * underlying module.
+ * @throws {Error} If a different `diagnostics_channel` module is registered.
  *
  * @example
  * ```ts
  * import dc from 'node:diagnostics_channel';
  * import { enableDiagnosticsChannel } from 'graphql';
  *
- * enableDiagnosticsChannel(dc);
+ * try {
+ *   enableDiagnosticsChannel(dc);
+ * } catch {
+ *   // A diagnostic_channel module was already registered, safe to subscribe.
+ * }
  * ```
  */
 export function enableDiagnosticsChannel(dc: MinimalDiagnosticsChannel): void {
+  if (registeredDc !== undefined) {
+    if (registeredDc !== dc) {
+      throw new Error(
+        'enableDiagnosticsChannel was called with a different `diagnostics_channel` module than the one previously registered. graphql-js can only publish to one module at a time; ensure all APMs share the same `node:diagnostics_channel` import.',
+      );
+    }
+    return;
+  }
+
+  registeredDc = dc;
   channels = {
     execute: dc.tracingChannel('graphql:execute'),
     parse: dc.tracingChannel('graphql:parse'),

src/execution/__tests__/execute-diagnostics-test.ts

@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, it } from 'mocha';
 
 import {
   collectEvents,
-  FakeDc,
+  sharedFakeDc,
 } from '../../__testUtils__/fakeDiagnosticsChannel.js';
 
 import { parse } from '../../language/parser.js';
@@ -32,14 +32,13 @@ const rootValue = {
   async: () => Promise.resolve('hello-async'),
 };
 
-const fakeDc = new FakeDc();
-const executeChannel = fakeDc.tracingChannel('graphql:execute');
+const executeChannel = sharedFakeDc.tracingChannel('graphql:execute');
 
 describe('execute diagnostics channel', () => {
   let active: ReturnType<typeof collectEvents> | undefined;
 
   beforeEach(() => {
-    enableDiagnosticsChannel(fakeDc);
+    enableDiagnosticsChannel(sharedFakeDc);
   });
 
   afterEach(() => {

src/execution/__tests__/resolve-diagnostics-test.ts

@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, it } from 'mocha';
 
 import {
   collectEvents,
-  FakeDc,
+  sharedFakeDc,
 } from '../../__testUtils__/fakeDiagnosticsChannel.js';
 
 import { isPromise } from '../../jsutils/isPromise.js';
@@ -46,14 +46,13 @@ const rootValue = {
   nested: { leaf: 'leaf-value' },
 };
 
-const fakeDc = new FakeDc();
-const resolveChannel = fakeDc.tracingChannel('graphql:resolve');
+const resolveChannel = sharedFakeDc.tracingChannel('graphql:resolve');
 
 describe('resolve diagnostics channel', () => {
   let active: ReturnType<typeof collectEvents> | undefined;
 
   beforeEach(() => {
-    enableDiagnosticsChannel(fakeDc);
+    enableDiagnosticsChannel(sharedFakeDc);
   });
 
   afterEach(() => {

src/execution/__tests__/subscribe-diagnostics-test.ts

@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, it } from 'mocha';
 
 import {
   collectEvents,
-  FakeDc,
+  sharedFakeDc,
 } from '../../__testUtils__/fakeDiagnosticsChannel.js';
 
 import { isPromise } from '../../jsutils/isPromise.js';
@@ -44,14 +44,13 @@ async function* twoTicks(): AsyncIterable<{ tick: string }> {
   yield { tick: 'two' };
 }
 
-const fakeDc = new FakeDc();
-const subscribeChannel = fakeDc.tracingChannel('graphql:subscribe');
+const subscribeChannel = sharedFakeDc.tracingChannel('graphql:subscribe');
 
 describe('subscribe diagnostics channel', () => {
   let active: ReturnType<typeof collectEvents> | undefined;
 
   beforeEach(() => {
-    enableDiagnosticsChannel(fakeDc);
+    enableDiagnosticsChannel(sharedFakeDc);
   });
 
   afterEach(() => {

src/language/__tests__/parser-diagnostics-test.ts

@@ -3,21 +3,20 @@ import { afterEach, beforeEach, describe, it } from 'mocha';
 
 import {
   collectEvents,
-  FakeDc,
+  sharedFakeDc,
 } from '../../__testUtils__/fakeDiagnosticsChannel.js';
 
 import { enableDiagnosticsChannel } from '../../diagnostics.js';
 
 import { parse } from '../parser.js';
 
-const fakeDc = new FakeDc();
-const parseChannel = fakeDc.tracingChannel('graphql:parse');
+const parseChannel = sharedFakeDc.tracingChannel('graphql:parse');
 
 describe('parse diagnostics channel', () => {
   let active: ReturnType<typeof collectEvents> | undefined;
 
   beforeEach(() => {
-    enableDiagnosticsChannel(fakeDc);
+    enableDiagnosticsChannel(sharedFakeDc);
   });
 
   afterEach(() => {

src/validation/__tests__/validate-diagnostics-test.ts

@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, it } from 'mocha';
 
 import {
   collectEvents,
-  FakeDc,
+  sharedFakeDc,
 } from '../../__testUtils__/fakeDiagnosticsChannel.js';
 
 import { parse } from '../../language/parser.js';
@@ -20,14 +20,13 @@ const schema = buildSchema(`
   }
 `);
 
-const fakeDc = new FakeDc();
-const validateChannel = fakeDc.tracingChannel('graphql:validate');
+const validateChannel = sharedFakeDc.tracingChannel('graphql:validate');
 
 describe('validate diagnostics channel', () => {
   let active: ReturnType<typeof collectEvents> | undefined;
 
   beforeEach(() => {
-    enableDiagnosticsChannel(fakeDc);
+    enableDiagnosticsChannel(sharedFakeDc);
   });
 
   afterEach(() => {