Public API

useDeduplicateRequest

import { useDeduplicateRequest } from './gateway-plugins/deduplicate-request/src/index';

function useDeduplicateRequest(): GatewayPlugin

Intercepts outgoing GET fetch calls and returns a shared in-flight promise for identical URLs and headers within the same gateway request context. Prevents redundant upstream calls when multiple subgraph resolvers hit the same endpoint simultaneously. Safe to add unconditionally; only activates for GET requests with a non-null context.

useJWT

import { useJWT, useForwardedJWT, type JWTAuthPluginOptions } from './gateway-plugins/jwt-auth/src/index';

function useJWT(options: JWTAuthPluginOptions): GatewayPlugin

interface JWTAuthPluginOptions extends JwtPluginOptions {
  forward?: {
    payload?: boolean | string;
    token?: boolean | string;
    extensionsFieldName?: string;
  };
}

Extracts and verifies JWT tokens from incoming requests at the gateway level. The forward option controls whether the raw token or decoded payload is forwarded to subgraphs via GraphQL extensions. Use useForwardedJWT in subgraph Yoga servers to consume what the gateway forwards.

useHMACUpstreamSignature (via HMACUpstreamSignatureOptions)

import type { HMACUpstreamSignatureOptions } from './gateway-plugins/hmac-upstream-signature/src/index';
// plugin is the default export pattern; see working example below

interface HMACUpstreamSignatureOptions {
  secret: string;
  shouldSign?: (input: Pick<OnSubgraphExecutePayload<{}>, 'subgraph' | 'subgraphName' | 'executionRequest'>) => boolean;
  extensionName?: string;
  serializeExecutionRequest?: (executionRequest: ExecutionRequest) => string;
}

Signs subgraph execution requests with an HMAC-SHA256 digest placed in the request extension field (default: "hmac-signature"). Use shouldSign to restrict signing to specific subgraphs. Subgraphs can verify the signature using the same shared secret.

useMCP

import { useMCP, type MCPConfig } from './gateway-plugins/mcp/src/index';

function useMCP(config?: MCPConfig): GatewayPlugin

Exposes GraphQL operations as MCP tools over the Model Context Protocol. Configure via MCPConfig to control tool sources, overrides, annotations, and description providers (e.g. Langfuse). Intended for AI agent integrations that consume the gateway as an MCP server.

useForwardedJWT

import { useForwardedJWT, type JWTAuthContextExtension } from './gateway-plugins/jwt-auth/src/index';

function useForwardedJWT(config?: {
  extensionsFieldName?: string;
  extendContextFieldName?: string;
}): YogaPlugin<JWTAuthContextExtension>

Yoga subgraph plugin that reads JWT data forwarded by the gateway from context.params.extensions and injects it into the Yoga context. Use this in downstream Yoga servers, not in the gateway itself.

Working examples

Scenario - JWT authentication with payload forwarding

The gateway verifies JWTs and forwards the decoded payload to subgraphs.

import { createGatewayRuntime } from '@graphql-hive/gateway-runtime';
import { useJWT, createInlineSigningKeyProvider } from './gateway-plugins/jwt-auth/src/index';

const gateway = createGatewayRuntime({
  plugins: () => [
    useJWT({
      singingKeyProviders: [
        createInlineSigningKeyProvider({ signingKey: process.env.JWT_SECRET! }),
      ],
      tokenLookupLocations: [
        { type: 'header', name: 'Authorization', prefix: 'Bearer' },
      ],
      reject: { missingToken: false, invalidToken: true },
      forward: {
        payload: true,
        token: 'x-forwarded-token',
        extensionsFieldName: 'jwt',
      },
    }),
  ],
});

Scenario - HMAC-signed subgraph requests

The gateway signs every outgoing subgraph execution request with a shared secret.

import { createGatewayRuntime } from '@graphql-hive/gateway-runtime';
import {
  defaultExecutionRequestSerializer,
  type HMACUpstreamSignatureOptions,
} from './gateway-plugins/hmac-upstream-signature/src/index';

// Dynamically import the plugin (it exports a named function internally)
async function buildGateway() {
  const { useHMACUpstreamSignature } = await import('./gateway-plugins/hmac-upstream-signature/src/index');

  const gateway = createGatewayRuntime({
    plugins: () => [
      useHMACUpstreamSignature({
        secret: process.env.HMAC_SECRET!,
        extensionName: 'hmac-signature',
        shouldSign: ({ subgraphName }) => subgraphName !== 'public-subgraph',
        serializeExecutionRequest: defaultExecutionRequestSerializer,
      } satisfies HMACUpstreamSignatureOptions),
    ],
  });

  return gateway;
}

Scenario - Request deduplication and MCP tools

Combine deduplication with MCP protocol exposure for AI agent access.

import { createGatewayRuntime } from '@graphql-hive/gateway-runtime';
import { useDeduplicateRequest } from './gateway-plugins/deduplicate-request/src/index';
import { useMCP } from './gateway-plugins/mcp/src/index';
import { createLangfuseProvider } from './gateway-plugins/mcp/src/index';

const gateway = createGatewayRuntime({
  plugins: () => [
    useDeduplicateRequest(),
    useMCP({
      descriptionProvider: createLangfuseProvider({
        publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
        secretKey: process.env.LANGFUSE_SECRET_KEY!,
        baseUrl: process.env.LANGFUSE_BASE_URL,
      }),
    }),
  ],
});

export default gateway;

Scenario - Consuming forwarded JWT in a Yoga subgraph

import { createYoga } from 'graphql-yoga';
import { useForwardedJWT, type JWTAuthContextExtension } from './gateway-plugins/jwt-auth/src/index';
import { schema } from './schema';

const yoga = createYoga<JWTAuthContextExtension>({
  schema,
  plugins: [
    useForwardedJWT({
      extensionsFieldName: 'jwt',
      extendContextFieldName: 'jwt',
    }),
  ],
});

File walkthrough

• aws-sigv4/src/index.ts - Re-exports plugin.ts (the useAWSSigV4 plugin) and types.ts (config type definitions).
• aws-sigv4/src/plugin.ts - Implements the fetch interceptor that signs requests using AWS SigV4.
• aws-sigv4/src/types.ts - TypeScript types for AWS SigV4 plugin configuration.
• deduplicate-request/src/index.ts - Self-contained useDeduplicateRequest plugin; no sub-files.
• hmac-upstream-signature/src/index.ts - HMAC plugin, option types, and serializer utilities in a single file.
• jwt-auth/src/index.ts - JWT gateway plugin, forwarded JWT subgraph plugin, re-exports from @graphql-yoga/plugin-jwt.
• mcp/src/index.ts - Barrel export for MCP plugin, all config types, and Langfuse provider.
• mcp/src/plugin.ts - Core MCP plugin implementation and type definitions.
• mcp/src/schema-converter.ts - Converts GraphQL schema/operations to MCP tool descriptors.
• mcp/src/operation-loader.ts - Loads GraphQL operations from files or config for MCP tool registration.
• mcp/src/providers/langfuse.ts - Langfuse-backed description provider for MCP tools.
• mcp/src/registry.ts - Internal MCP tool registry management.
• mcp/src/protocol.ts - MCP protocol message handling and transport.
• mcp/examples/ - Runnable example configurations and GraphQL operations for MCP.
• opentelemetry/src/plugin.ts - Gateway plugin wiring OpenTelemetry spans to gateway lifecycle hooks.
• opentelemetry/src/setup.ts - SDK initialization and exporter configuration helpers.
• opentelemetry/src/spans.ts - Span attribute definitions and span creation utilities.
• opentelemetry/src/circuit-breaker-exporter.ts - Exporter wrapper with circuit-breaker fault tolerance.
• prometheus/src/index.ts - Prometheus metrics plugin using prom-client.
• prometheus/grafana.json - Prebuilt Grafana dashboard importing gateway Prometheus metrics.

Common pitfalls and fixes

• .js extension resolution in MCP imports: The MCP plugin uses import ... from './plugin.js' internally; ensure "moduleResolution": "node16" or "bundler" in tsconfig.json, or use a bundler like esbuild.
• crypto.subtle unavailable in Node < 19: hmac-upstream-signature requires Web Crypto API; run Node 19+ or polyfill with --experimental-global-webcrypto on Node 18.
• @graphql-yoga/plugin-jwt version mismatch: jwt-auth re-exports types from this package directly; pin it to the same version used by @graphql-hive/gateway-runtime to avoid duplicate type instances.
• WeakMap context key for deduplication: useDeduplicateRequest keys its cache on the gateway context object; if context is re-created per sub-request rather than per top-level request, deduplication will not work—ensure context is shared across subgraph calls.
• Environment variables not set for OpenTelemetry: The OTLP exporter silently no-ops if OTEL_EXPORTER_OTLP_ENDPOINT is missing; add a startup check and log a warning explicitly.
• MCP plugin requires GraphQL schema at init time: useMCP reads the gateway schema to build tool descriptors; initialize the gateway fully before exposing the MCP endpoint, or the tool list will be empty.

Vibe-coding prompt template

I have a Hive Gateway project using `@graphql-hive/gateway-runtime`. I purchased the
"Hive Gateway Plugins Collection" source block. The source files are in `./source/` and
the integration guide is in `./USAGE.md`.

Please do the following step by step:

1. Read `USAGE.md` to understand all available plugins and their exports.
2. Read the source files in `./source/` to understand the real exported functions and types.
3. Add the following plugins to my existing gateway in `src/gateway.ts`:
   - JWT authentication with inline signing key from `JWT_SECRET` env var
   - HMAC upstream signature with secret from `HMAC_SECRET` env var
   - Request deduplication
4. Update `tsconfig.json` if needed for module resolution.
5. Show me how to verify JWT forwarding works in my downstream Yoga subgraph using `useForwardedJWT`.
6. Do not invent any imports or types; only use what is exported from the source files.
7. Provide the complete updated `src/gateway.ts` file and any other changed files.

License and credit

The upstream project (graphql_hive_gateway, package collection packages/plugins) is released under the MIT license. See source/LICENSE if present, or refer to the upstream repository at https://github.com/graphql-hive/gateway. Individual plugin packages publish their changelogs in their respective CHANGELOG.md files within each subdirectory.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

GraphQL Mesh Federation Gateway for Any API

Automation, Utilities & Developer Tools

무료