@plasius/graph-gateway-core

Read-path graph gateway orchestration core with stale-serving, retry, and timeout controls.

Apache-2.0. ESM + CJS builds. TypeScript types included.

Requirements

• Node.js 24+ (matches .nvmrc and CI/CD)
• @plasius/graph-contracts

Installation

npm install @plasius/graph-gateway-core

Exports

import { GraphGateway, type GraphGatewayOptions } from "@plasius/graph-gateway-core";

Quick Start

import { GraphGateway } from "@plasius/graph-gateway-core";

const gateway = new GraphGateway({
  resolver: {
    async resolve(request) {
      return {
        key: request.key,
        data: { id: request.key },
        stale: false,
        tags: request.tags ?? [],
      };
    },
  },
  maxFanout: 8,
  timeoutMs: 750,
  retryAttempts: 2,
  retryBudgetMs: 1_500,
  isRetryableError: (error) =>
    typeof error === "object" &&
    error !== null &&
    "retryable" in error &&
    error.retryable === true,
  circuitBreaker: {
    canRequest: async (resolver) => resolver !== "disabled.resolver",
  },
});

const result = await gateway.execute({
  requests: [{ resolver: "user.profile", key: "user:1" }],
});

console.log(result.partial, result.stale);

Development

npm run clean
npm install
npm run lint
npm run typecheck
npm run test:coverage
npm run build

Resilience and Observability

• Query planning/fanout control via maxFanout.
• Retry policy controls:
  • timeoutMs
  • retryAttempts
  • retryBudgetMs
  • retryBackoffMs
  • retryJitterRatio
  • isRetryableError to control retryability when callers want explicit override
• Circuit breaker hooks:
  • canRequest
  • onSuccess
  • onFailure
• Telemetry events:
  • graph.execute.latency
  • graph.cache.outcome
  • graph.resolve.latency
  • graph.resolve.backoff_ms
  • graph.upstream.error
• Runtime query payloads are validated at execution boundary (isGraphQuery).
• Default behavior is transient-only: without a custom isRetryableError, the gateway retries only errors marked as retryable via error.transient (or error.retryable) and fails fast on other failures.

Architecture

• Package ADRs: docs/adrs
• Cross-package ADRs: plasius-ltd-site/docs/adrs/adr-0020 to adr-0024

License

Licensed under the Apache-2.0 License.

Release integrity

CI keeps the administrative contributor registry outside Git and npm package artifacts using exact, case-normalised path checks. Both CI jobs use the literal Public CI - Quarantined group and [self-hosted, Linux, X64] labels for trusted repository pushes only. Fork and PR events cannot schedule self-hosted work. The group independently restricts repositories and workflow refs; a reviewed maintainer branch needs a temporary explicit workflow admission, removed after delivery. Missing capacity fails closed with no hosted fallback. Checkout does not persist credentials, package-manager cache finalization stays disabled, and ordinary npm ci retains the committed lockfile. Bounded jobs preserve lint, types, runtime audit, build, 80% line coverage and final pack checks. Publication uses the GitHub-hosted production job with Node 24 and a pinned npm 11.6.2 client. It is token-free and proceeds only while the prepared SHA is the exact main head after successful push-triggered CI. Do not dispatch CD until the npm trusted-publisher binding is verified. Use the approved two-phase cd.yml prepare/publish path on main with a fresh version; verify exact-main CI, immutable registry bytes/provenance and the GitHub release before completion.

Feature platform.public-artifact-integrity.enabled governs staged public restoration. Enabled permits verified restoration; disabled pauses restoration; rollback disables the affected workflow/channel or removes its admission. Mandatory source/package admission remains enforced in all three states. No local override or capability is introduced. Never restore the prohibited administrative path during rollback. See ADR-0005.