Hive Console plugin for Gateway and introduce new target option

.changeset/@graphql-hive_gateway-runtime-809-dependencies.md

@@ -0,0 +1,8 @@
+---
+'@graphql-hive/gateway-runtime': patch
+---
+
+dependencies updates: 
+
+- Added dependency [`@graphql-hive/yoga@^0.41.0` ↗︎](https://www.npmjs.com/package/@graphql-hive/yoga/v/0.41.0) (to `dependencies`)
+- Removed dependency [`@graphql-mesh/plugin-hive@^0.104.0` ↗︎](https://www.npmjs.com/package/@graphql-mesh/plugin-hive/v/0.104.0) (from `dependencies`)

.changeset/plenty-llamas-push.md

@@ -0,0 +1,7 @@
+---
+'@graphql-hive/gateway': minor
+---
+
+Introduce `target` as a new Hive reporting option
+
+Deprecate the `--hive-registry-token` CLI option in favour of `--hive-usage-target` and `--hive-usage-access-token` options. [Read more on Hive's product update page.](https://the-guild.dev/graphql/hive/product-updates/2025-03-10-new-access-tokens)

.changeset/wet-kiwis-peel.md

@@ -0,0 +1,7 @@
+---
+'@graphql-hive/gateway-runtime': minor
+---
+
+Introduce `target` as a new Hive reporting option
+
+[Read more on Hive's product update page.](https://the-guild.dev/graphql/hive/product-updates/2025-03-10-new-access-tokens)

packages/gateway/src/cli.ts

@@ -72,9 +72,17 @@ export interface GatewayCLISupergraphConfig
 }
 
 export interface GatewayCLIHiveReportingOptions
-  extends Omit<GatewayHiveReportingOptions, 'token'> {
+  extends Omit<GatewayHiveReportingOptions, 'target' | 'token'> {
   /**
-   * Hive registry token for usage metrics reporting.
+   * The target to which the usage data should be reported to.
+   *
+   * @default process.env.HIVE_USAGE_TARGET
+   */
+  target?: GatewayHiveReportingOptions['target'];
+  /**
+   * Hive registry access token for usage metrics reporting.
+   *
+   * @default process.env.HIVE_USAGE_ACCESS_TOKEN || process.env.HIVE_REGISTRY_TOKEN
    */
   token?: GatewayHiveReportingOptions['token'];
 }
@@ -307,9 +315,21 @@ let cli = new Command()
   .addOption(
     new Option(
       '--hive-registry-token <token>',
-      'Hive registry token for usage metrics reporting',
+      '[DEPRECATED: please use "--hive-usage-target" and "--hive-usage-access-token"] Hive registry token for usage metrics reporting',
     ).env('HIVE_REGISTRY_TOKEN'),
   )
+  .addOption(
+    new Option(
+      '--hive-usage-target <target>',
+      'Hive registry target to which the usage data should be reported to. requires the "--hive-usage-access-token <token>" option',
+    ).env('HIVE_USAGE_TARGET'),
+  )
+  .addOption(
+    new Option(
+      '--hive-usage-access-token <token>',
+      'Hive registry access token for usage metrics reporting. requires the "--hive-usage-target <target>" option',
+    ).env('HIVE_USAGE_ACCESS_TOKEN'),
+  )
   .option(
     '--hive-persisted-documents-endpoint <endpoint>',
     '[EXPERIMENTAL] Hive CDN endpoint for fetching the persisted documents. requires the "--hive-persisted-documents-token <token>" option',

packages/gateway/src/commands/handleReportingConfig.ts

@@ -0,0 +1,100 @@
+import {
+  CLIContext,
+  GatewayConfig,
+  GatewayGraphOSReportingOptions,
+  GatewayHiveReportingOptions,
+} from '..';
+
+export interface ReportingCLIOptions {
+  hiveRegistryToken: string | undefined;
+  hiveUsageTarget: string | undefined;
+  hiveUsageAccessToken: string | undefined;
+  apolloGraphRef: string | undefined;
+  apolloKey: string | undefined;
+}
+
+export function handleReportingConfig(
+  ctx: CLIContext,
+  loadedConfig: Partial<GatewayConfig<Record<string, any>>>,
+  cliOpts: ReportingCLIOptions,
+): GatewayHiveReportingOptions | GatewayGraphOSReportingOptions | null {
+  const confOpts: Partial<ReportingCLIOptions> = {
+    ...(loadedConfig.reporting?.type === 'hive'
+      ? {
+          hiveRegistryToken: loadedConfig.reporting.token,
+          hiveUsageTarget: loadedConfig.reporting.target,
+          hiveUsageAccessToken: loadedConfig.reporting.token,
+        }
+      : {}),
+    ...(loadedConfig.reporting?.type === 'graphos'
+      ? {
+          apolloGraphRef: loadedConfig.reporting.graphRef,
+          apolloKey: loadedConfig.reporting.apiKey,
+        }
+      : {}),
+  };
+  const opts = { ...confOpts, ...cliOpts };
+
+  if (cliOpts.hiveRegistryToken && cliOpts.hiveUsageAccessToken) {
+    ctx.log.error(
+      `Cannot use "--hive-registry-token" with "--hive-usage-access-token". Please use "--hive-usage-target" and "--hive-usage-access-token" or the config instead.`,
+    );
+    process.exit(1);
+  }
+
+  if (cliOpts.hiveRegistryToken && opts.hiveUsageTarget) {
+    ctx.log.error(
+      `Cannot use "--hive-registry-token" with a target. Please use "--hive-usage-target" and "--hive-usage-access-token" or the config instead.`,
+    );
+    process.exit(1);
+  }
+
+  if (opts.hiveUsageTarget && !opts.hiveUsageAccessToken) {
+    ctx.log.error(
+      `Hive usage target needs an access token. Please provide it through the "--hive-usage-access-token <token>" option or the config.`,
+    );
+    process.exit(1);
+  }
+
+  if (opts.hiveUsageAccessToken && !opts.hiveUsageTarget) {
+    ctx.log.error(
+      `Hive usage access token needs a target. Please provide it through the "--hive-usage-target <target>" option or the config.`,
+    );
+    process.exit(1);
+  }
+
+  const hiveUsageAccessToken =
+    opts.hiveUsageAccessToken || opts.hiveRegistryToken;
+  if (hiveUsageAccessToken) {
+    // different logs w and w/o the target to disambiguate
+    if (opts.hiveUsageTarget) {
+      ctx.log.info(`Configuring Hive usage reporting`);
+    } else {
+      ctx.log.info(`Configuring Hive registry reporting`);
+    }
+    return {
+      ...loadedConfig.reporting,
+      type: 'hive',
+      token: hiveUsageAccessToken,
+      target: opts.hiveUsageTarget,
+    };
+  }
+
+  if (opts.apolloKey) {
+    ctx.log.info(`Configuring Apollo GraphOS registry reporting`);
+    if (!opts.apolloGraphRef) {
+      ctx.log.error(
+        `Apollo GraphOS requires a graph ref in the format <graph-id>@<graph-variant>. Please provide a valid graph ref.`,
+      );
+      process.exit(1);
+    }
+    return {
+      ...loadedConfig.reporting,
+      type: 'graphos',
+      apiKey: opts.apolloKey,
+      graphRef: opts.apolloGraphRef,
+    };
+  }
+
+  return null;
+}

packages/gateway/src/commands/proxy.ts

@@ -18,6 +18,7 @@ import {
 import { startServerForRuntime } from '../servers/startServerForRuntime';
 import { handleFork } from './handleFork';
 import { handleLoggingConfig } from './handleLoggingOption';
+import { handleReportingConfig } from './handleReportingConfig';
 
 export const addCommand: AddCommand = (ctx, cli) =>
   cli
@@ -35,6 +36,8 @@ export const addCommand: AddCommand = (ctx, cli) =>
         hiveCdnEndpoint,
         hiveCdnKey,
         hiveRegistryToken,
+        hiveUsageTarget,
+        hiveUsageAccessToken,
         maskedErrors,
         hivePersistedDocumentsEndpoint,
         hivePersistedDocumentsToken,
@@ -95,6 +98,19 @@ export const addCommand: AddCommand = (ctx, cli) =>
         process.exit(1);
       }
 
+      const registryConfig: Pick<ProxyConfig, 'reporting'> = {};
+      const reporting = handleReportingConfig(ctx, loadedConfig, {
+        hiveRegistryToken,
+        hiveUsageTarget,
+        hiveUsageAccessToken,
+        // proxy can only do reporting to hive registry
+        apolloGraphRef: undefined,
+        apolloKey: undefined,
+      });
+      if (reporting) {
+        registryConfig.reporting = reporting;
+      }
+
       const pubsub = loadedConfig.pubsub || new PubSub();
       const cwd = loadedConfig.cwd || process.cwd();
       if (loadedConfig.logging != null) {
@@ -128,15 +144,7 @@ export const addCommand: AddCommand = (ctx, cli) =>
             ? loadedConfig.pollingInterval
             : undefined) ||
           defaultOptions.pollingInterval,
-        ...(hiveRegistryToken
-          ? {
-              reporting: {
-                ...loadedConfig.reporting,
-                type: 'hive',
-                token: hiveRegistryToken,
-              },
-            }
-          : {}),
+        ...registryConfig,
         proxy,
         schema,
         logging: ctx.log,

packages/gateway/src/commands/subgraph.ts

@@ -22,6 +22,7 @@ import {
 import { startServerForRuntime } from '../servers/startServerForRuntime';
 import { handleFork } from './handleFork';
 import { handleLoggingConfig } from './handleLoggingOption';
+import { handleReportingConfig } from './handleReportingConfig';
 
 export const addCommand: AddCommand = (ctx, cli) =>
   cli
@@ -37,6 +38,8 @@ export const addCommand: AddCommand = (ctx, cli) =>
       const {
         maskedErrors,
         hiveRegistryToken,
+        hiveUsageTarget,
+        hiveUsageAccessToken,
         hivePersistedDocumentsEndpoint,
         hivePersistedDocumentsToken,
         ...opts
@@ -55,6 +58,19 @@ export const addCommand: AddCommand = (ctx, cli) =>
         subgraph = loadedConfig.subgraph!; // TODO: assertion wont be necessary when exactOptionalPropertyTypes
       }
 
+      const registryConfig: Pick<SubgraphConfig, 'reporting'> = {};
+      const reporting = handleReportingConfig(ctx, loadedConfig, {
+        hiveRegistryToken,
+        hiveUsageTarget,
+        hiveUsageAccessToken,
+        // subgraph can only do reporting to hive registry
+        apolloGraphRef: undefined,
+        apolloKey: undefined,
+      });
+      if (reporting) {
+        registryConfig.reporting = reporting;
+      }
+
       const pubsub = loadedConfig.pubsub || new PubSub();
       const cwd = loadedConfig.cwd || process.cwd();
       if (loadedConfig.logging != null) {
@@ -88,15 +104,7 @@ export const addCommand: AddCommand = (ctx, cli) =>
             ? loadedConfig.pollingInterval
             : undefined) ||
           defaultOptions.pollingInterval,
-        ...(hiveRegistryToken
-          ? {
-              reporting: {
-                ...loadedConfig.reporting,
-                type: 'hive',
-                token: hiveRegistryToken,
-              },
-            }
-          : {}),
+        ...registryConfig,
         subgraph,
         logging: loadedConfig.logging ?? ctx.log,
         productName: ctx.productName,

packages/gateway/src/commands/supergraph.ts

@@ -28,6 +28,7 @@ import {
 import { startServerForRuntime } from '../servers/startServerForRuntime';
 import { handleFork } from './handleFork';
 import { handleLoggingConfig } from './handleLoggingOption';
+import { handleReportingConfig } from './handleReportingConfig';
 
 export const addCommand: AddCommand = (ctx, cli) =>
   cli
@@ -50,6 +51,8 @@ export const addCommand: AddCommand = (ctx, cli) =>
         hiveCdnEndpoint,
         hiveCdnKey,
         hiveRegistryToken,
+        hiveUsageTarget,
+        hiveUsageAccessToken,
         maskedErrors,
         apolloGraphRef,
         apolloKey,
@@ -151,32 +154,16 @@ export const addCommand: AddCommand = (ctx, cli) =>
         ctx.log.info(`Using default supergraph location: ${supergraph}`);
       }
 
-      let registryConfig: Pick<SupergraphConfig, 'reporting'> = {};
-
-      if (hiveRegistryToken) {
-        ctx.log.info(`Configuring Hive registry reporting`);
-        registryConfig = {
-          reporting: {
-            ...loadedConfig.reporting,
-            type: 'hive',
-            token: hiveRegistryToken,
-          },
-        };
-      } else if (apolloKey) {
-        ctx.log.info(`Configuring Apollo GraphOS registry reporting`);
-        if (!apolloGraphRef) {
-          ctx.log.error(
-            `Apollo GraphOS requires a graph ref in the format <graph-id>@<graph-variant>. Please provide a valid graph ref.`,
-          );
-          process.exit(1);
-        }
-        registryConfig = {
-          reporting: {
-            type: 'graphos',
-            apiKey: apolloKey,
-            graphRef: apolloGraphRef,
-          },
-        };
+      const registryConfig: Pick<SupergraphConfig, 'reporting'> = {};
+      const reporting = handleReportingConfig(ctx, loadedConfig, {
+        hiveRegistryToken,
+        hiveUsageTarget,
+        hiveUsageAccessToken,
+        apolloGraphRef,
+        apolloKey,
+      });
+      if (reporting) {
+        registryConfig.reporting = reporting;
       }
 
       const pubsub = loadedConfig.pubsub || new PubSub();

packages/runtime/package.json

@@ -49,10 +49,10 @@
     "@envelop/generic-auth": "^9.0.0",
     "@graphql-hive/core": "^0.10.0",
     "@graphql-hive/logger-json": "workspace:^",
+    "@graphql-hive/yoga": "^0.41.0",
     "@graphql-mesh/cross-helpers": "^0.4.10",
     "@graphql-mesh/fusion-runtime": "workspace:^",
     "@graphql-mesh/hmac-upstream-signature": "workspace:^",
-    "@graphql-mesh/plugin-hive": "^0.104.0",
     "@graphql-mesh/plugin-response-cache": "^0.104.0",
     "@graphql-mesh/transport-common": "workspace:^",
     "@graphql-mesh/types": "^0.104.0",

packages/runtime/src/createGatewayRuntime.ts

@@ -21,7 +21,6 @@ import {
   UnifiedGraphManager,
 } from '@graphql-mesh/fusion-runtime';
 import { useHmacUpstreamSignature } from '@graphql-mesh/hmac-upstream-signature';
-import useMeshHive from '@graphql-mesh/plugin-hive';
 import useMeshResponseCache from '@graphql-mesh/plugin-response-cache';
 import { TransportContext } from '@graphql-mesh/transport-common';
 import type {
@@ -96,6 +95,7 @@ import { useCustomAgent } from './plugins/useCustomAgent';
 import { useDelegationPlanDebug } from './plugins/useDelegationPlanDebug';
 import { useDemandControl } from './plugins/useDemandControl';
 import { useFetchDebug } from './plugins/useFetchDebug';
+import useHiveConsole from './plugins/useHiveConsole';
 import { usePropagateHeaders } from './plugins/usePropagateHeaders';
 import { useRequestId } from './plugins/useRequestId';
 import { useSubgraphExecuteDebug } from './plugins/useSubgraphExecuteDebug';
@@ -202,8 +202,9 @@ export function createGatewayRuntime<
     'type' in config.persistedDocuments &&
     config.persistedDocuments?.type === 'hive'
   ) {
-    persistedDocumentsPlugin = useMeshHive({
+    persistedDocumentsPlugin = useHiveConsole({
       ...configContext,
+      enabled: false, // disables only usage reporting
       logger: configContext.logger.child({
         plugin: 'Hive Persisted Documents',
       }),