bhooai-nexus 0.1.2

package/packages/nexus-graphql/src/federation/executor.ts

@@ -0,0 +1,305 @@
+import { execute, parse, isObjectType, isInterfaceType, type DocumentNode, type SelectionSetNode, type FieldNode, type InlineFragmentNode, type FragmentSpreadNode, type ExecutionResult } from 'graphql';
+import type { Supergraph } from './composeSupergraph.js';
+import type { Subgraph, GraphQLContext } from '../types.js';
+import { createFieldResolver } from '../gateway/fieldResolver.js';
+
+/**
+ * Naive sequential federated executor (Phase 6, v1).
+ *
+ * Algorithm:
+ *   1. Root pass — group the operation's top-level fields by their owning
+ *      subgraph; for each group, execute a trimmed subquery against that
+ *      subgraph in-process. Trim keeps only fields owned by that subgraph,
+ *      plus `__typename` and entity key fields (so later passes can join).
+ *   2. Entity-join passes — scan the stitched result for entity-typed objects
+ *      whose requested fields are owned by *other* subgraphs; for each such
+ *      (subgraph, type) pair, call that subgraph's `_entities` with
+ *      representations built from the parents' keys and a trimmed subquery,
+ *      then merge the returned fields back by key. Repeat until no missing
+ *      fields remain (handles nested joins, one level per pass).
+ *
+ * Limitations (documented): sequential (no parallel fetch fan-out), `@requires`
+ * supported as "fetch the required external fields first, then resolve", no
+ * `@shareable` arbitration, no `@override`. Composition is ours; execution is
+ * in-process (shared nothing is Phase 6-distributed, designed not built).
+ */
+
+export interface FetchNode {
+  kind: 'root' | 'entities';
+  subgraph: string;
+  /** SDL selection set this fetch executes. */
+  selection: string;
+  /** For entity fetches: the entity type name being resolved. */
+  typeName?: string;
+  /** For entity fetches: key fields used to build representations. */
+  keyFields?: string[];
+}
+export interface FetchPlan {
+  nodes: FetchNode[];
+}
+
+/** Build a FetchPlan description for inspection/golden tests. */
+export function planQuery(supergraph: Supergraph, document: DocumentNode): FetchPlan {
+  const nodes: FetchNode[] = [];
+  const op = document.definitions.find((d) => d.kind === 'OperationDefinition') as
+    | { selectionSet: SelectionSetNode }
+    | undefined;
+  if (!op) return { nodes };
+  const rootType = 'Query';
+  const bySub = new Map<string, string[]>();
+  for (const sel of op.selectionSet.selections) {
+    if (sel.kind === 'Field') {
+      const owner = supergraph.ownership.get(rootType)?.get((sel as FieldNode).name.value);
+      if (owner) bySub.set(owner, [...(bySub.get(owner) ?? []), (sel as FieldNode).name.value]);
+    }
+  }
+  for (const [sub, fields] of bySub) {
+    nodes.push({ kind: 'root', subgraph: sub, selection: `{ ${fields.join(' ') } }` });
+  }
+  return { nodes };
+}
+
+/** Execute a federated query in-process against the composed subgraphs. */
+export async function executeFederated(
+  supergraph: Supergraph,
+  document: DocumentNode,
+  variableValues: Record<string, any> | undefined,
+  contextValue: GraphQLContext,
+): Promise<ExecutionResult> {
+  const op = document.definitions.find((d) => d.kind === 'OperationDefinition') as
+    | { selectionSet: SelectionSetNode; operation: string }
+    | undefined;
+  if (!op) return { errors: [{ message: 'No operation in document' }] as unknown as NonNullable<ExecutionResult['errors']> };
+  const rootType = op.operation === 'mutation' ? 'Mutation' : op.operation === 'subscription' ? 'Subscription' : 'Query';
+
+  const subgraphByName = new Map<string, Subgraph>(supergraph.subgraphs.map((s) => [s.name, s]));
+
+  // 1. Root pass: group top-level fields by owner and execute trimmed subqueries.
+  const rootGroups = new Map<string, FieldNode[]>();
+  for (const sel of op.selectionSet.selections) {
+    if (sel.kind !== 'Field') continue; // v1: no fragment spreads at root
+    const owner = supergraph.ownership.get(rootType)?.get(sel.name.value);
+    if (!owner) return { errors: [{ message: `No subgraph owns ${rootType}.${sel.name.value}` }] as unknown as NonNullable<ExecutionResult['errors']> };
+    const arr = rootGroups.get(owner) ?? [];
+    arr.push(sel);
+    rootGroups.set(owner, arr);
+  }
+
+  const data: Record<string, unknown> = {};
+  for (const [subName, fields] of rootGroups) {
+    const sub = subgraphByName.get(subName)!;
+    const sel = trimSelection(fields, rootType, subName, supergraph, true);
+    const sdl = `${op.operation} { ${sel} }`;
+    const res = await execSubgraph(sub, parse(sdl), variableValues, contextValue);
+    if (res.errors) return { errors: res.errors };
+    Object.assign(data, res.data as Record<string, unknown>);
+  }
+
+  // 2. Iterative entity-join passes.
+  for (let pass = 0; pass < 8; pass++) {
+    const pending = collectMissing(supergraph, op.selectionSet, rootType, data);
+    if (pending.length === 0) break;
+    for (const job of pending) {
+      const sub = subgraphByName.get(job.subgraph)!;
+      const reps = job.parents.map((p) => pickKeys(p, job.keyFields));
+      const sel = trimSelection(job.fieldNodes, job.typeName, job.subgraph, supergraph, true);
+      const sdl = `query($reps: [_Any!]!){ _entities(representations: $reps){ ... on ${job.typeName} { ${sel} } } }`;
+      const res = await execSubgraph(sub, parse(sdl), { ...variableValues, reps }, contextValue);
+      if (res.errors) return { errors: res.errors };
+      const entities = (res.data as Record<string, unknown> | undefined)?._entities as any[] | undefined;
+      if (!entities) continue;
+      mergeEntities(job.parents, entities, job.keyFields, job.typeName, job.missingFields);
+    }
+  }
+
+  return { data };
+}
+
+/** Run a document against a subgraph's federation schema + resolvers in-process. */
+async function execSubgraph(sub: Subgraph, document: DocumentNode, variableValues: Record<string, any> | undefined, contextValue: GraphQLContext): Promise<ExecutionResult> {
+  return execute({
+    schema: sub.schema,
+    document,
+    rootValue: undefined,
+    contextValue,
+    variableValues,
+    fieldResolver: createFieldResolver(sub.resolvers),
+  });
+}
+
+/** Unwrap a GraphQL type name to its base named type. */
+function baseType(type: string): string {
+  return type.replace(/[\[\]!]/g, '');
+}
+
+/** Output SDL type of a field on a type, from the supergraph (merged) schema. */
+function fieldType(supergraph: Supergraph, parentType: string, fieldName: string): string | undefined {
+  const t = supergraph.schema.getType(parentType);
+  if (isObjectType(t)) return t.getFields()[fieldName]?.type.toString();
+  if (isInterfaceType(t)) return t.getFields()[fieldName]?.type.toString();
+  return undefined;
+}
+
+/**
+ * Trim a list of selections (for one parent type) to fields owned by `subgraphName`,
+ * preserving field arguments, plus `__typename`. For entity-typed parents, the
+ * entity's @key fields owned by `subgraphName` are force-included so downstream
+ * join passes can build representations. Fields owned by other subgraphs are
+ * omitted here (a later entity-join pass fills them). Returns an SDL selection-set.
+ */
+function trimSelection(selections: readonly (FieldNode | InlineFragmentNode | FragmentSpreadNode)[], parentType: string, subgraphName: string, supergraph: Supergraph, _includeKeys: boolean): string {
+  const parts: string[] = [];
+  const included = new Set<string>();
+  for (const sel of selections) {
+    if (sel.kind === 'Field') {
+      const name = sel.name.value;
+      if (name === '__typename') { parts.push('__typename'); included.add(name); continue; }
+      const owner = supergraph.ownership.get(parentType)?.get(name);
+      const ft = fieldType(supergraph, parentType, name);
+      const childType = ft ? baseType(ft) : undefined;
+      if (owner === subgraphName) {
+        const sub = sel.selectionSet ? trimSelection(sel.selectionSet.selections, childType!, subgraphName, supergraph, true) : '';
+        const args = argsToSdl(sel.arguments);
+        parts.push(sub ? `${name}${args} { ${sub} }` : `${name}${args}`);
+        included.add(name);
+      }
+      // Fields owned by other subgraphs are omitted here; an entity-join pass fills them.
+    } else if (sel.kind === 'InlineFragment') {
+      const fragType = sel.typeCondition?.name.value ?? parentType;
+      const sub = trimSelection(sel.selectionSet.selections, fragType, subgraphName, supergraph, _includeKeys);
+      parts.push(`... on ${fragType} { ${sub} }`);
+    }
+    // FragmentSpread: v1 ignores (rare in generated clients)
+  }
+  // Force-include this entity's key fields (owned by this subgraph) so join passes
+  // can build representations even when the client didn't request them.
+  if (supergraph.entities.has(parentType)) {
+    const src = (supergraph.entities.get(parentType) ?? []).find((s) => s.subgraph === subgraphName);
+    if (src) {
+      for (const kf of src.keyFields) {
+        if (supergraph.ownership.get(parentType)?.get(kf) === subgraphName && !included.has(kf)) {
+          parts.push(kf);
+          included.add(kf);
+        }
+      }
+    }
+  }
+  return parts.join(' ');
+}
+
+/** Serialize a field's arguments to SDL, e.g. `(id: "u1", limit: $limit)`. */
+function argsToSdl(args: readonly import('graphql').ArgumentNode[] | undefined): string {
+  if (!args || args.length === 0) return '';
+  return '(' + args.map((a) => `${a.name.value}: ${valueToSdl(a.value)}`).join(', ') + ')';
+}
+function valueToSdl(v: import('graphql').ValueNode): string {
+  switch (v.kind) {
+    case 'IntValue': case 'FloatValue': return v.value;
+    case 'StringValue': return JSON.stringify(v.value);
+    case 'BooleanValue': return String(v.value);
+    case 'EnumValue': return v.value;
+    case 'NullValue': return 'null';
+    case 'Variable': return '$' + v.name.value;
+    case 'ListValue': return '[' + v.values.map(valueToSdl).join(', ') + ']';
+    case 'ObjectValue': return '{' + v.fields.map((f) => `${f.name.value}: ${valueToSdl(f.value)}`).join(', ') + '}';
+    default: return '';
+  }
+}
+
+function pickKeys(obj: Record<string, unknown>, keys: string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = { __typename: obj.__typename };
+  for (const k of keys) if (k in obj) out[k] = obj[k];
+  return out;
+}
+
+interface JoinJob {
+  subgraph: string;
+  typeName: string;
+  keyFields: string[];
+  parents: Record<string, unknown>[];
+  missingFields: string[];
+  fieldNodes: (FieldNode | InlineFragmentNode | FragmentSpreadNode)[];
+}
+
+/**
+ * Walk the stitched `data` against the query selection set; for each entity-typed
+ * object, find fields the query wants that are owned by a *different* subgraph
+ * than the one that produced the object, and emit a JoinJob to fetch them.
+ */
+function collectMissing(supergraph: Supergraph, selectionSet: SelectionSetNode, parentType: string, data: Record<string, unknown> | unknown[]): JoinJob[] {
+  const jobs: JoinJob[] = [];
+  walk(supergraph, selectionSet, parentType, data, jobs, new Set());
+  return jobs;
+}
+
+function walk(supergraph: Supergraph, selectionSet: SelectionSetNode, parentType: string, data: unknown, jobs: JoinJob[], seen: Set<Record<string, unknown>>): void {
+  if (data == null) return;
+  if (Array.isArray(data)) { for (const item of data) walk(supergraph, selectionSet, parentType, item, jobs, seen); return; }
+  if (typeof data !== 'object') return;
+  const obj = data as Record<string, unknown>;
+
+  // Group requested fields by their owning subgraph; identify fields owned by a
+  // subgraph other than the one that produced this object (inferred from the
+  // fields already present). For each foreign owner, build a job.
+  const requestedByOwner = new Map<string, FieldNode[]>();
+  for (const sel of selectionSet.selections) {
+    if (sel.kind !== 'Field') continue;
+    const name = sel.name.value;
+    if (name === '__typename') continue;
+    const owner = supergraph.ownership.get(parentType)?.get(name);
+    if (!owner) continue;
+    if (!(name in obj)) { // missing → needs fetching from `owner`
+      const arr = requestedByOwner.get(owner) ?? [];
+      arr.push(sel);
+      requestedByOwner.set(owner, arr);
+    } else if (sel.selectionSet) {
+      // present → recurse into children for nested joins
+      const ft = fieldType(supergraph, parentType, name);
+      const childType = ft ? baseType(ft) : undefined;
+      if (childType) walk(supergraph, sel.selectionSet, childType, obj[name], jobs, seen);
+    }
+  }
+
+  if (requestedByOwner.size === 0) return;
+  if (seen.has(obj)) return;
+  seen.add(obj);
+
+  const entitySources = supergraph.entities.get(parentType) ?? [];
+  if (entitySources.length === 0) return; // can't join a non-entity
+
+  for (const [owner, fieldNodes] of requestedByOwner) {
+    // Pick a key for this owner: an entity source whose subgraph == owner, else first.
+    const source = entitySources.find((s) => s.subgraph === owner) ?? entitySources[0]!;
+    const keyFields = source.keyFields;
+    // Only emit if we actually have the key fields present on the object.
+    if (!keyFields.every((k) => k in obj)) continue;
+    jobs.push({
+      subgraph: owner,
+      typeName: parentType,
+      keyFields,
+      parents: [obj],
+      missingFields: fieldNodes.map((f) => f.name.value),
+      fieldNodes,
+    });
+  }
+}
+
+/**
+ * Merge fetched entity fields back into the parent objects. `_entities` returns
+ * one resolved entity per representation, in order; `reps` were built from
+ * `parents` in order, so `entities[i]` corresponds to `parents[i]`. We merge by
+ * index (not by key tuple) because the fetched entity may not carry its `@key`
+ * fields — they may be `@external` on the resolving subgraph and absent from the
+ * trimmed selection. Null entries (entity resolver returned null) are skipped.
+ */
+function mergeEntities(parents: Record<string, unknown>[], entities: any[], _keyFields: string[], typeName: string, missingFields: string[]): void {
+  for (let i = 0; i < parents.length; i++) {
+    const e = entities[i];
+    const p = parents[i]!;
+    if (!e || typeof e !== 'object') continue;
+    for (const f of missingFields) {
+      if (f in e) p[f] = e[f];
+    }
+    if (!p.__typename) p.__typename = typeName;
+  }
+}

package/packages/nexus-graphql/src/federation/parseMetadata.ts

@@ -0,0 +1,87 @@
+/**
+ * Parse federation metadata from subgraph SDL: per type, its `@key` sets,
+ * whether it is an `@extends` extension, and per field whether it is
+ * `@external`, `@provides(fields)`, or `@requires(fields)`. Uses brace matching
+ * (not a full AST) — sufficient for the v1 federation subset and the kind of
+ * type blocks we generate/accept.
+ */
+export interface FieldMeta {
+  /** Field is declared `@external` (resolved by another subgraph). */
+  external: boolean;
+  /** `@provides(fields: "...")` — this subgraph provides this field on an entity. */
+  provides?: string[];
+  /** `@requires(fields: "...")` — this field is computed from external fields. */
+  requires?: string[];
+}
+export interface TypeMeta {
+  isExtend: boolean;
+  keys: string[][];
+  fields: Map<string, FieldMeta>;
+}
+
+export function parseFederationMetadata(sdl: string): Map<string, TypeMeta> {
+  const types = new Map<string, TypeMeta>();
+  // Find `type|interface Name <header> {` and capture the balanced body.
+  const headerRe = /(?:extend\s+)?(?:type|interface)\s+(\w+)([^{]*)\{/g;
+  let m: RegExpExecArray | null;
+  while ((m = headerRe.exec(sdl)) !== null) {
+    const name = m[1]!;
+    const header = m[2]!;
+    const bodyStart = m.index + m[0].length;
+    const body = balancedBody(sdl, bodyStart);
+    headerRe.lastIndex = bodyStart + body.length + 1; // skip past closing brace
+
+    const isExtend = /\bextends\b/.test(header) || /@extends\b/.test(header);
+    const keys: string[][] = [];
+    const keyRe = /@key\s*\(\s*fields:\s*"([^"]+)"\s*\)/g;
+    let k: RegExpExecArray | null;
+    while ((k = keyRe.exec(header)) !== null) keys.push(k[1]!.split(/\s+/).filter(Boolean));
+
+    const fields = parseFields(body);
+    const existing = types.get(name);
+    if (existing) {
+      existing.keys.push(...keys);
+      for (const [fn, fm] of fields) existing.fields.set(fn, fm);
+    } else {
+      types.set(name, { isExtend, keys, fields });
+    }
+  }
+  return types;
+}
+
+/** Extract the balanced `{ ... }` body starting just after an opening brace at `start-1`. */
+function balancedBody(s: string, start: number): string {
+  let depth = 1;
+  let i = start;
+  for (; i < s.length; i++) {
+    const c = s[i];
+    if (c === '{') depth++;
+    else if (c === '}') { depth--; if (depth === 0) break; }
+  }
+  return s.slice(start, i);
+}
+
+/** Parse field definitions in a type body into name → FieldMeta. */
+function parseFields(body: string): Map<string, FieldMeta> {
+  const out = new Map<string, FieldMeta>();
+  // Each field line roughly: `name(args): Type <directives>` separated by newlines.
+  // We scan line-ish fragments split on top-level commas/newlines.
+  const lines = body.split('\n').map((l) => l.trim()).filter(Boolean);
+  for (const line of lines) {
+    // Strip leading modifiers; capture field name as the first identifier.
+    const nameMatch = /^(\w+)/.exec(line);
+    if (!nameMatch) continue;
+    const name = nameMatch[1]!;
+    const external = /@external\b/.test(line);
+    const provides = matchFields(line, '@provides');
+    const requires = matchFields(line, '@requires');
+    out.set(name, { external, provides, requires });
+  }
+  return out;
+}
+
+function matchFields(line: string, directive: string): string[] | undefined {
+  const re = new RegExp(`${directive}\\s*\\(\\s*fields:\\s*"([^"]+)"\\s*\\)`);
+  const m = re.exec(line);
+  return m ? m[1]!.split(/\s+/).filter(Boolean) : undefined;
+}

package/packages/nexus-graphql/src/gateway/createGateway.ts

@@ -0,0 +1,77 @@
+import { execute, subscribe, validate, type GraphQLSchema, type ExecutionResult, type DocumentNode } from 'graphql';
+import type { Gateway, Subgraph, Resolvers, GraphQLContext, ExecuteParams } from '../types.js';
+import { createFieldResolver, createSubscribeFieldResolver } from './fieldResolver.js';
+import { buildPublicSchema } from './publicSchema.js';
+
+/**
+ * Create an in-process gateway over one or more subgraphs.
+ *
+ * Single-subgraph mode (Phase 5): the gateway exposes the subgraph's public
+ * schema and executes operations directly against the subgraph's resolvers —
+ * no network hop, shared in-process context (DB pool, services). This is the
+ * default app shape; federation overhead only kicks in when there are multiple
+ * subgraphs.
+ *
+ * Multi-subgraph composition + query planning is Phase 6; calling with >1
+ * subgraph here throws a clear "not yet" error so the API is forward-compatible.
+ */
+export function createGateway(input: { subgraph: Subgraph } | { subgraphs: Subgraph[] }): Gateway {
+  const subgraphs: Subgraph[] = 'subgraph' in input ? [input.subgraph] : input.subgraphs;
+  if (subgraphs.length === 0) throw new Error('[nexus-graphql] createGateway requires at least one subgraph');
+  if (subgraphs.length > 1) {
+    throw new Error(
+      '[nexus-graphql] Multi-subgraph federation (composition + query planning) is implemented in Phase 6. ' +
+        'Pass a single subgraph here, or use the Phase 6 composeSupergraph/createFederatedGateway.',
+    );
+  }
+
+  const only = subgraphs[0]!;
+  const resolvers: Resolvers = only.resolvers;
+  const schema: GraphQLSchema = buildPublicSchema(only.sdl);
+  const fieldResolver = createFieldResolver(resolvers);
+  const subscribeFieldResolver = createSubscribeFieldResolver(resolvers);
+
+  async function run(document: DocumentNode, params: Omit<ExecuteParams, 'schema' | 'resolvers' | 'document'>) {
+    const errors = validate(schema, document);
+    if (errors.length) return ({ errors: errors.map((e) => ({ message: e.message })) } as unknown) as ExecutionResult;
+    return execute({
+      schema,
+      document,
+      rootValue: params.rootValue,
+      contextValue: params.contextValue as GraphQLContext,
+      variableValues: params.variableValues,
+      operationName: params.operationName,
+      fieldResolver,
+    });
+  }
+
+  return {
+    schema,
+    subgraphs,
+    async execute(params) {
+      return run(params.document, params);
+    },
+    async subscribe(params) {
+      const document = params.document;
+      const errors = validate(schema, document);
+      if (errors.length) {
+        return (async function* () { yield { errors: errors.map((e) => ({ message: e.message })) }; })() as AsyncIterable<ExecutionResult>;
+      }
+      const result = await subscribe({
+        schema,
+        document,
+        rootValue: params.rootValue,
+        contextValue: params.contextValue as GraphQLContext,
+        variableValues: params.variableValues,
+        operationName: params.operationName,
+        subscribeFieldResolver,
+        fieldResolver,
+      });
+      // graphql-js returns an AsyncIterable on success or an ExecutionResult (with errors) otherwise.
+      if (Symbol.asyncIterator in (result as any)) {
+        return result as AsyncIterable<ExecutionResult>;
+      }
+      return (async function* () { yield result as ExecutionResult; })() as AsyncIterable<ExecutionResult>;
+    },
+  };
+}

package/packages/nexus-graphql/src/gateway/fieldResolver.ts

@@ -0,0 +1,45 @@
+import type { GraphQLFieldResolver, GraphQLResolveInfo } from 'graphql';
+import type { Resolvers, GraphQLContext, SubscribeResolver } from '../types.js';
+
+/**
+ * Build a graphql-js `fieldResolver` that dispatches to the user's resolvers
+ * map. Resolution order:
+ *   1. `__typename` → the parent's `__typename` (or the field's parent type name).
+ *   2. `resolvers[typeName][fieldName]` — if it's a `{ resolve, subscribe }`
+ *      shape (subscription field), use `.resolve`; otherwise call it directly.
+ *   3. Default property access: `parent[fieldName]`.
+ */
+export function createFieldResolver(resolvers: Resolvers): GraphQLFieldResolver<any, GraphQLContext> {
+  return (parent, args, context, info: GraphQLResolveInfo) => {
+    const fieldName = info.fieldName;
+    if (fieldName === '__typename') {
+      return parent?.__typename ?? info.parentType.name;
+    }
+    const typeResolvers = resolvers[info.parentType.name];
+    if (typeResolvers) {
+      const field = typeResolvers[fieldName];
+      if (field) {
+        if (typeof field === 'function') return field(parent, args, context, info);
+        if (typeof field === 'object' && field && typeof field.resolve === 'function') {
+          return field.resolve(parent, args, context, info);
+        }
+      }
+    }
+    // Default: read the property off the parent (works for DB docs/objects).
+    return parent != null ? parent[fieldName] : undefined;
+  };
+}
+
+/** Build a `subscribeFieldResolver` for subscription root fields. */
+export function createSubscribeFieldResolver(resolvers: Resolvers): GraphQLFieldResolver<any, GraphQLContext> {
+  return (parent, args, context, info: GraphQLResolveInfo): AsyncIterable<any> | Promise<AsyncIterable<any>> => {
+    const typeResolvers = resolvers[info.parentType.name];
+    const field = typeResolvers?.[info.fieldName];
+    const subscribe: SubscribeResolver | undefined =
+      field && typeof field === 'object' && field ? field.subscribe : undefined;
+    if (typeof subscribe !== 'function') {
+      throw new Error(`No 'subscribe' resolver for ${info.parentType.name}.${info.fieldName}`);
+    }
+    return subscribe(parent, args, context, info);
+  };
+}

package/packages/nexus-graphql/src/gateway/graphqlHttpHandler.ts

@@ -0,0 +1,90 @@
+import { parse, type DocumentNode } from 'graphql';
+import type { RequestContext, Handler } from '@bhooai/nexus-core';
+import type { Gateway, GraphQLContext } from '../types.js';
+
+export interface GraphqlHandlerOptions {
+  /** The gateway to execute against. */
+  gateway: Gateway;
+  /** Build the per-request resolver context. Defaults to `{ request: ctx, user: ctx.state.user }`. */
+  context?: (ctx: RequestContext) => GraphQLContext | Promise<GraphQLContext>;
+  /** Allow introspection queries (default follows config.graphql.introspection = true). */
+  introspection?: boolean;
+}
+
+interface GraphQLRequestBody {
+  query?: string;
+  variables?: Record<string, any>;
+  operationName?: string;
+}
+
+/** True when a parsed operation set contains an introspection field (`__schema`/`__type`). */
+function isIntrospectionDocument(doc: DocumentNode): boolean {
+  for (const def of doc.definitions) {
+    if (def.kind === 'OperationDefinition') {
+      const sels = def.selectionSet.selections;
+      for (const s of sels) {
+        if (s.kind === 'Field' && (s.name.value === '__schema' || s.name.value === '__type')) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * HTTP handler for `/graphql`. Accepts POST with `{ query, variables, operationName }`
+ * (or GET with `?query=`). Applies the gateway in-process. Introspection is
+ * rejected when disabled.
+ */
+export function graphqlHttpHandler(options: GraphqlHandlerOptions): Handler {
+  const { gateway, introspection = true } = options;
+  return async (ctx: RequestContext) => {
+    let body: GraphQLRequestBody;
+    if (ctx.method === 'GET') {
+      const q = ctx.query.query;
+      body = { query: Array.isArray(q) ? q[0] : q, variables: parseJsonQuery(ctx.query.variables), operationName: single(ctx.query.operationName) };
+    } else {
+      body = (ctx.body as GraphQLRequestBody) ?? {};
+    }
+
+    if (!body.query) {
+      ctx.json({ errors: [{ message: 'Must provide a query string.' }] }, 400);
+      return;
+    }
+
+    let document: DocumentNode;
+    try {
+      document = parse(body.query);
+    } catch (err) {
+      ctx.json({ errors: [{ message: (err as Error).message }] }, 400);
+      return;
+    }
+
+    if (!introspection && isIntrospectionDocument(document)) {
+      ctx.json({ errors: [{ message: 'Introspection is disabled.' }] }, 403);
+      return;
+    }
+
+    const contextValue = options.context
+      ? await options.context(ctx)
+      : { request: ctx, user: (ctx.state.user as GraphQLContext['user']) };
+
+    const result = await gateway.execute({
+      document,
+      variableValues: body.variables,
+      operationName: body.operationName,
+      contextValue,
+    });
+    ctx.json(result);
+  };
+}
+
+function parseJsonQuery(v: string | string[] | undefined): Record<string, any> | undefined {
+  if (v === undefined) return undefined;
+  const s = Array.isArray(v) ? v[0] : v;
+  if (!s) return undefined;
+  try { return JSON.parse(s as string); } catch { return undefined; }
+}
+function single(v: string | string[] | undefined): string | undefined {
+  if (v === undefined) return undefined;
+  return Array.isArray(v) ? v[0] : v;
+}

package/packages/nexus-graphql/src/gateway/publicSchema.ts

@@ -0,0 +1,26 @@
+import { buildSchema, GraphQLSchema } from 'graphql';
+
+/**
+ * Strip federation directives from subgraph SDL to produce the *public*
+ * (client-facing) schema. The gateway exposes this clean schema; the federation
+ * internals (`_service`, `_entities`, `@key`, `@external`, ...) are not part of
+ * the public API. For the single-subgraph case the public schema is simply the
+ * user's types without the federation markers.
+ */
+export function buildPublicSchema(subgraphSdl: string): GraphQLSchema {
+  const cleaned = subgraphSdl
+    // Drop the `extend schema @link(...)` clause and any standalone @link.
+    .replace(/extend\s+schema\s*@\s*link\s*\([^)]*\)/g, '')
+    .replace(/@\s*link\s*\([^)]*\)/g, '')
+    // Drop federation field/type directives.
+    .replace(/@\s*key\s*\([^)]*\)/g, '')
+    .replace(/@\s*requires\s*\([^)]*\)/g, '')
+    .replace(/@\s*provides\s*\([^)]*\)/g, '')
+    .replace(/@\s*external\b/g, '')
+    .replace(/@\s*extends\b/g, '')
+    // Collapse multiple blank lines left behind.
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+
+  return buildSchema(cleaned);
+}

package/packages/nexus-graphql/src/index.ts

@@ -0,0 +1,14 @@
+export * from './types.js';
+export * from './subgraph/federationDirectives.js';
+export * from './subgraph/parseKeys.js';
+export * from './subgraph/defineSubgraph.js';
+export * from './gateway/fieldResolver.js';
+export * from './gateway/publicSchema.js';
+export * from './gateway/createGateway.js';
+export * from './gateway/graphqlHttpHandler.js';
+export * from './subscriptions/PubSub.js';
+export * from './subscriptions/SubscriptionServer.js';
+export * from './federation/parseMetadata.js';
+export * from './federation/composeSupergraph.js';
+export * from './federation/executor.js';
+export * from './federation/createFederatedGateway.js';