@bhooai/nexus-graphql 0.1.0

package/src/subscriptions/SubscriptionServer.ts

@@ -0,0 +1,203 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import type { IncomingMessage, Server as HttpServer } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { parse, validate } from 'graphql';
+import type { AuthService } from '@bhooai/nexus-auth';
+import type { Gateway, GraphQLContext } from '../types.js';
+
+export interface SubscriptionServerOptions {
+  httpServer: HttpServer;
+  gateway: Gateway;
+  /** WS path (default '/graphql/ws'). */
+  path?: string;
+  /** Optional auth: verifies access token from connection_init payload.token or ?token=. */
+  authService?: AuthService;
+  /** Build per-connection resolver context. Default: `{ user }` from auth. */
+  context?: (init: Record<string, unknown> | undefined, user: GraphQLContext['user']) => GraphQLContext | Promise<GraphQLContext>;
+  /** Reject unauthenticated connections (default true when authService provided). */
+  requireAuth?: boolean;
+}
+
+type ClientMsg =
+  | { type: 'connection_init'; payload?: Record<string, unknown> }
+  | { type: 'subscribe'; id: string; payload: { query: string; variables?: Record<string, any>; operationName?: string } }
+  | { type: 'complete'; id: string }
+  | { type: 'ping' }
+  | { type: 'pong' };
+
+interface ActiveSub {
+  iterator: AsyncIterator<unknown>;
+  done: boolean;
+}
+
+const PROTOCOL = 'graphql-transport-ws';
+
+/**
+ * GraphQL subscriptions over WebSocket (the `graphql-transport-ws` protocol).
+ * Attaches to an HTTP server's 'upgrade' event. On `connection_init` we
+ * (optionally) authenticate; on `subscribe` we run the gateway's `subscribe()`
+ * and stream each `next` result back until the client sends `complete` or the
+ * socket closes.
+ */
+export class SubscriptionServer {
+  private wss: WebSocketServer;
+  private opts: SubscriptionServerOptions;
+
+  constructor(opts: SubscriptionServerOptions) {
+    this.opts = opts;
+    this.wss = new WebSocketServer({ noServer: true });
+    this.opts.httpServer.on('upgrade', (req, socket, head) => this.handleUpgrade(req, socket, head));
+  }
+
+  private async handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): Promise<void> {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname !== (this.opts.path ?? '/graphql/ws')) return;
+
+    const protocols = (req.headers['sec-websocket-protocol'] ?? '').toString().split(',').map((s) => s.trim());
+    if (!protocols.includes(PROTOCOL)) {
+      socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+
+    this.wss.handleUpgrade(req, socket, head, (ws) => {
+      this.handleConnection(ws, url);
+    });
+  }
+
+  private async handleConnection(ws: WebSocket, url: URL): Promise<void> {
+    let user: GraphQLContext['user'];
+    let acknowledged = false;
+    const active = new Map<string, ActiveSub>();
+
+    const send = (msg: unknown) => { if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg)); };
+
+    const cleanup = async () => {
+      for (const [, sub] of active) {
+        if (!sub.done) { sub.done = true; try { await sub.iterator.return?.(); } catch { /* ignore */ } }
+      }
+      active.clear();
+    };
+
+    // If auth is required and no token is supplied via ?token=, we can reject
+    // early; but the protocol sends the token in connection_init, so we wait.
+    ws.on('message', async (data) => {
+      let msg: ClientMsg;
+      try { msg = JSON.parse(data.toString('utf8')) as ClientMsg; } catch { return; }
+
+      switch (msg.type) {
+        case 'connection_init': {
+          try {
+            user = await this.authenticate(msg.payload, url);
+          } catch (err) {
+            send({ type: 'error', id: '', payload: [{ message: (err as Error).message }] });
+            ws.close(4401, 'Unauthorized');
+            return;
+          }
+          acknowledged = true;
+          send({ type: 'connection_ack' });
+          return;
+        }
+        case 'ping':
+          send({ type: 'pong' });
+          return;
+        case 'pong':
+          return;
+        case 'subscribe': {
+          if (!acknowledged) { send({ type: 'error', id: msg.id, payload: [{ message: 'connection not acknowledged' }] }); return; }
+          await this.runSubscription(msg, ws, active, user);
+          return;
+        }
+        case 'complete': {
+          const sub = active.get(msg.id);
+          if (sub && !sub.done) { sub.done = true; try { await sub.iterator.return?.(); } catch { /* ignore */ } }
+          active.delete(msg.id);
+          return;
+        }
+      }
+    });
+
+    ws.on('close', () => void cleanup());
+    ws.on('error', () => void cleanup());
+  }
+
+  private async authenticate(payload: Record<string, unknown> | undefined, url: URL): Promise<GraphQLContext['user']> {
+    const requireAuth = this.opts.requireAuth ?? !!this.opts.authService;
+    if (!this.opts.authService) {
+      if (requireAuth) throw new Error('Authentication required but no authService configured');
+      return undefined;
+    }
+    const token = (payload?.token as string | undefined) ?? url.searchParams.get('token');
+    if (!token) {
+      if (requireAuth) throw new Error('Missing access token');
+      return undefined;
+    }
+    const claims = await this.opts.authService.verifyAccessToken(token);
+    return { sub: claims.sub, roles: claims.roles ?? [], sid: claims.sid };
+  }
+
+  private async runSubscription(
+    msg: { type: 'subscribe'; id: string; payload: { query: string; variables?: Record<string, any>; operationName?: string } },
+    ws: WebSocket,
+    active: Map<string, ActiveSub>,
+    user: GraphQLContext['user'],
+  ): Promise<void> {
+    const send = (m: unknown) => { if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(m)); };
+
+    let document;
+    try {
+      document = parse(msg.payload.query);
+    } catch (err) {
+      send({ type: 'error', id: msg.id, payload: [{ message: (err as Error).message }] });
+      return;
+    }
+
+    const errors = validate(this.opts.gateway.schema, document);
+    if (errors.length) {
+      send({ type: 'error', id: msg.id, payload: errors.map((e) => ({ message: e.message })) });
+      return;
+    }
+
+    const contextValue = this.opts.context
+      ? await this.opts.context(undefined, user)
+      : { user };
+
+    let stream;
+    try {
+      stream = await this.opts.gateway.subscribe({
+        document,
+        variableValues: msg.payload.variables,
+        operationName: msg.payload.operationName,
+        contextValue,
+      });
+    } catch (err) {
+      send({ type: 'error', id: msg.id, payload: [{ message: (err as Error).message }] });
+      return;
+    }
+
+    const sub: ActiveSub = { iterator: stream[Symbol.asyncIterator](), done: false };
+    active.set(msg.id, sub);
+
+    // Pump results asynchronously; stop when the client completes or the stream ends.
+    void (async () => {
+      try {
+        while (!sub.done) {
+          const { value, done } = await sub.iterator.next();
+          if (done) break;
+          if (ws.readyState !== ws.OPEN) break;
+          send({ type: 'next', id: msg.id, payload: value });
+        }
+        if (!sub.done && ws.readyState === ws.OPEN) send({ type: 'complete', id: msg.id });
+      } catch (err) {
+        send({ type: 'error', id: msg.id, payload: [{ message: (err as Error).message }] });
+      } finally {
+        active.delete(msg.id);
+      }
+    })();
+  }
+
+  close(): Promise<void> {
+    this.wss.close();
+    return Promise.resolve();
+  }
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+import type { GraphQLSchema, ExecutionResult, DocumentNode } from 'graphql';
+
+/** A field resolver: (parent, args, context, info) => value | Promise<value>. */
+export type Resolver = (parent: any, args: Record<string, any>, context: GraphQLContext, info: any) => any | Promise<any>;
+
+/** A subscribe resolver returning an AsyncIterable of event payloads. */
+export type SubscribeResolver = (parent: any, args: Record<string, any>, context: GraphQLContext, info: any) => AsyncIterable<any> | Promise<AsyncIterable<any>>;
+
+/** Resolvers for a type. Fields may have a plain resolver or `{ resolve, subscribe }` (subscriptions). */
+export type TypeResolvers = Record<string, Resolver | { resolve?: Resolver; subscribe?: SubscribeResolver }>;
+
+export interface Resolvers {
+  [typeName: string]: TypeResolvers;
+}
+
+/** Per-request context passed to every resolver. */
+export interface GraphQLContext {
+  /** The raw HTTP/WS request (for auth headers, ip, etc.). */
+  request?: unknown;
+  /** Authenticated user payload (sub, roles, sid) when auth is applied. */
+  user?: { sub: string; roles: string[]; sid?: string };
+  /** Anything the host wants to inject (DB connections, services, dataloaders). */
+  [key: string]: unknown;
+}
+
+/** Entity representation: `__typename` + the key fields of an entity. */
+export interface EntityRepresentation {
+  __typename: string;
+  [key: string]: unknown;
+}
+
+/** Resolves an entity by its representation. Returns the object (with fields) or null. */
+export type EntityResolver = (representation: EntityRepresentation, context: GraphQLContext) => Promise<any | null> | any | null;
+
+export interface DefineSubgraphOptions {
+  /** Subgraph name (used as the `__typename` source id and in composition). */
+  name: string;
+  /** The subgraph SDL (user types + federation directives like `@key`). */
+  typeDefs: string;
+  /** Field resolvers. */
+  resolvers?: Resolvers;
+  /** Entity resolver for `_entities`. Defaults to returning the representation as-is. */
+  entityResolver?: EntityResolver;
+}
+
+/** A built subgraph, ready to be composed or executed in-process. */
+export interface Subgraph {
+  name: string;
+  /** Executable schema including federation boilerplate (_service, _entities). */
+  schema: GraphQLSchema;
+  /** The subgraph SDL (with federation directives) — what `_service.sdl` returns. */
+  sdl: string;
+  /** Map of entity typeName -> key field paths (e.g. `["id"]` or `["id email"]`). */
+  entityKeys: Map<string, string[]>;
+  resolvers: Resolvers;
+  entityResolver: EntityResolver;
+}
+
+export interface ExecuteParams {
+  schema: GraphQLSchema;
+  document: DocumentNode;
+  resolvers: Resolvers;
+  variableValues?: Record<string, any>;
+  operationName?: string;
+  contextValue?: GraphQLContext;
+  rootValue?: any;
+}
+
+export type ExecutionResultLike = ExecutionResult;
+
+export interface Gateway {
+  /** Public (client-facing) schema — federation internals stripped. */
+  schema: GraphQLSchema;
+  subgraphs: Subgraph[];
+  execute(params: Omit<ExecuteParams, 'schema' | 'resolvers'>): Promise<ExecutionResult>;
+  subscribe(params: Omit<ExecuteParams, 'schema' | 'resolvers'>): Promise<AsyncIterable<ExecutionResult>>;
+}

package/tests/federation.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from 'vitest';
+import { parse } from 'graphql';
+import { defineSubgraph, createFederatedGateway, parseFederationMetadata } from '../src/index.js';
+
+/**
+ * Two-subgraph federation e2e (Component A, Phase 6):
+ *   - users subgraph owns User.id/name/email + Query.user
+ *   - orders subgraph extends User with `orders` (needs User.id) and owns
+ *     Order.id/total + Query.orders. Order.customer is a User resolved via @key.
+ *
+ * The naive sequential executor must stitch cross-subgraph fields: a query for
+ * `{ user(id) { id name orders { id total } } }` fetches the user from `users`
+ * then joins `orders` via `_entities` on the User key.
+ */
+
+const ORDERS = new Map<string, { id: string; total: number; customerId: string }>([
+  ['o1', { id: 'o1', total: 100, customerId: 'u1' }],
+  ['o2', { id: 'o2', total: 250, customerId: 'u1' }],
+  ['o3', { id: 'o3', total: 50, customerId: 'u2' }],
+]);
+const USERS = new Map<string, { id: string; name: string; email: string }>([
+  ['u1', { id: 'u1', name: 'Alice', email: 'alice@x.com' }],
+  ['u2', { id: 'u2', name: 'Bob', email: 'bob@x.com' }],
+]);
+
+const usersSubgraph = defineSubgraph({
+  name: 'users',
+  typeDefs: /* graphql */ `
+    type User @key(fields: "id") {
+      id: ID!
+      name: String!
+      email: String!
+    }
+    type Query {
+      user(id: ID!): User
+      users: [User!]!
+    }
+  `,
+  resolvers: {
+    Query: {
+      user: (_p: any, a: { id: string }) => USERS.get(a.id) ?? null,
+      users: () => [...USERS.values()],
+    },
+  },
+  entityResolver: (rep) => USERS.get(String(rep.id)) ?? null,
+});
+
+const ordersSubgraph = defineSubgraph({
+  name: 'orders',
+  typeDefs: /* graphql */ `
+    type Order @key(fields: "id") {
+      id: ID!
+      total: Int!
+      customerId: ID!
+    }
+    type User @key(fields: "id") @extends {
+      id: ID! @external
+      orders: [Order!]!
+    }
+    type Query {
+      orders: [Order!]!
+    }
+  `,
+  resolvers: {
+    Query: {
+      orders: () => [...ORDERS.values()],
+    },
+    User: {
+      // `orders` is owned by the orders subgraph; resolve using the parent's id
+      // (the key field carried over from the users subgraph).
+      orders: (parent: { id: string }) => [...ORDERS.values()].filter((o) => o.customerId === parent.id),
+    },
+  },
+  // The orders subgraph resolves a User entity to just its key (the id), which
+  // the User.orders resolver then uses.
+  entityResolver: (rep) => ({ __typename: 'User', id: rep.id }),
+});
+
+describe('federation: metadata parsing', () => {
+  it('detects @external, @extends, and @key on the extended User', () => {
+    const meta = parseFederationMetadata(ordersSubgraph.sdl);
+    const user = meta.get('User')!;
+    expect(user.keys).toContainEqual(['id']);
+    expect(user.fields.get('id')?.external).toBe(true);
+    expect(user.fields.get('orders')?.external).toBe(false);
+  });
+});
+
+describe('federation: two-subgraph composition + execution', () => {
+  const gateway = createFederatedGateway([usersSubgraph, ordersSubgraph]);
+
+  it('composes a merged public schema with fields from both subgraphs', () => {
+    const queryFields = Object.keys(gateway.schema.getQueryType()?.getFields() ?? {});
+    expect(queryFields).toContain('user');
+    expect(queryFields).toContain('users');
+    expect(queryFields).toContain('orders');
+    const userFields = Object.keys(gateway.schema.getType('User')?.getFields?.() ?? {});
+    expect([...userFields].sort()).toEqual(['email', 'id', 'name', 'orders'].sort());
+  });
+
+  it('plans a root fetch per owning subgraph', () => {
+    const plan = gateway.plan(parse(`{ user(id: "u1") { id name } orders { id total } }`));
+    const owners = plan.nodes.map((n) => n.subgraph).sort();
+    expect(owners).toEqual(['orders', 'users']);
+  });
+
+  it('stitches a cross-subgraph query: user from users, orders joined from orders', async () => {
+    const res = await gateway.execute({
+      document: parse(`{ user(id: "u1") { id name orders { id total } } }`),
+      contextValue: {},
+    });
+    expect(res.errors).toBeUndefined();
+    const user = (res.data as any).user;
+    expect(user.id).toBe('u1');
+    expect(user.name).toBe('Alice');
+    expect(user.orders.map((o: any) => o.id).sort()).toEqual(['o1', 'o2']);
+    expect(user.orders[0].total).toBeGreaterThan(0);
+  });
+
+  it('stitches the reverse direction: orders from orders, then customer name from users', async () => {
+    // Extend the scenario: orders owns Query.orders; Order.customerId is local.
+    // The query asks only for order fields owned by orders → single fetch, no join.
+    const res = await gateway.execute({
+      document: parse(`{ orders { id total customerId } }`),
+      contextValue: {},
+    });
+    expect(res.errors).toBeUndefined();
+    expect((res.data as any).orders.length).toBe(3);
+  });
+
+  it('stitches a list query with per-entity joins: users { id name orders }', async () => {
+    const res = await gateway.execute({
+      document: parse(`{ users { id name orders { id total } } }`),
+      contextValue: {},
+    });
+    expect(res.errors).toBeUndefined();
+    const users = (res.data as any).users as any[];
+    const alice = users.find((u) => u.id === 'u1');
+    expect(alice.name).toBe('Alice');
+    expect(alice.orders.map((o: any) => o.id).sort()).toEqual(['o1', 'o2']);
+    const bob = users.find((u) => u.id === 'u2');
+    expect(bob.orders.map((o: any) => o.id)).toEqual(['o3']);
+  });
+
+  it('returns null gracefully for an unknown user', async () => {
+    const res = await gateway.execute({
+      document: parse(`{ user(id: "zzz") { id name orders { id } } }`),
+      contextValue: {},
+    });
+    expect(res.errors).toBeUndefined();
+    expect((res.data as any).user).toBeNull();
+  });
+});

package/tests/graphql.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect } from 'vitest';
+import { parse } from 'graphql';
+import {
+  defineSubgraph,
+  createGateway,
+  parseEntityKeys,
+  buildPublicSchema,
+} from '../src/index.js';
+
+const USER_TYPEDEFS = /* graphql */ `
+  type User @key(fields: "id") {
+    id: ID!
+    name: String!
+    email: String
+  }
+  type Query {
+    me: User
+    user(id: ID!): User
+  }
+  type Mutation {
+    setName(name: String!): User
+  }
+`;
+
+const USERS: Record<string, any> = {
+  u1: { id: 'u1', name: 'Alice', email: 'alice@x.com' },
+};
+
+const resolvers = {
+  Query: {
+    me: () => USERS.u1,
+    user: (_p: any, args: { id: string }) => USERS[args.id] ?? null,
+  },
+  Mutation: {
+    setName: (_p: any, args: { name: string }) => {
+      USERS.u1.name = args.name;
+      return USERS.u1;
+    },
+  },
+};
+
+describe('subgraph: defineSubgraph', () => {
+  it('parses @key directives into entityKeys', () => {
+    const keys = parseEntityKeys(USER_TYPEDEFS);
+    expect(keys.get('User')).toEqual(['id']);
+  });
+
+  it('parses composite keys', () => {
+    const keys = parseEntityKeys(`
+      type Order @key(fields: "id tenant") { id: ID! tenant: String! total: Int! }
+    `);
+    expect(keys.get('Order')).toEqual(['id', 'tenant']);
+  });
+
+  it('builds a federation-compliant schema exposing _service and _entities', () => {
+    const sub = defineSubgraph({ name: 'users', typeDefs: USER_TYPEDEFS, resolvers });
+    expect(sub.entityKeys.get('User')).toEqual(['id']);
+    // _service.sdl returns the subgraph SDL containing the @link + user types.
+    expect(sub.sdl).toContain('@link');
+    expect(sub.sdl).toContain('type User @key');
+  });
+
+  it('executes _service { sdl } and returns the subgraph SDL', async () => {
+    const sub = defineSubgraph({ name: 'users', typeDefs: USER_TYPEDEFS, resolvers });
+    const gw = createGateway({ subgraph: sub });
+    // Use the subgraph schema (which has _service), not the public gateway schema.
+    const { execute } = await import('graphql');
+    const result = await execute({
+      schema: sub.schema,
+      document: parse(`{ _service { sdl } }`),
+      fieldResolver: (await import('../src/gateway/fieldResolver.js')).createFieldResolver(sub.resolvers),
+    });
+    expect(result.errors).toBeUndefined();
+    const sdl = (result.data as any)._service.sdl as string;
+    expect(sdl).toContain('type User @key');
+  });
+
+  it('resolves _entities via the provided entityResolver', async () => {
+    const sub = defineSubgraph({
+      name: 'users',
+      typeDefs: USER_TYPEDEFS,
+      resolvers,
+      entityResolver: (rep) => ({ id: rep.id, name: `resolved-${rep.id}`, email: null }),
+    });
+    const { execute } = await import('graphql');
+    const { createFieldResolver } = await import('../src/gateway/fieldResolver.js');
+    const result = await execute({
+      schema: sub.schema,
+      document: parse(`query($reps: [_Any!]!){ _entities(representations: $reps){ ... on User { id name } } }`),
+      variableValues: { reps: [{ __typename: 'User', id: 'u1' }] },
+      fieldResolver: createFieldResolver(sub.resolvers),
+    });
+    expect(result.errors).toBeUndefined();
+    expect((result.data as any)._entities[0]).toEqual({ id: 'u1', name: 'resolved-u1' });
+  });
+
+  it('rejects an unknown directive in the user SDL', () => {
+    expect(() =>
+      defineSubgraph({ name: 'bad', typeDefs: `type X @notARealDirective { id: ID! }` }),
+    ).toThrow();
+  });
+});
+
+describe('gateway: in-process single-subgraph execution', () => {
+  it('runs a query end-to-end through resolvers', async () => {
+    const sub = defineSubgraph({ name: 'users', typeDefs: USER_TYPEDEFS, resolvers });
+    const gw = createGateway({ subgraph: sub });
+    const result = await gw.execute({
+      document: parse(`{ me { id name email } }`),
+      contextValue: {},
+    });
+    expect(result.errors).toBeUndefined();
+    expect((result.data as any).me).toEqual({ id: 'u1', name: 'Alice', email: 'alice@x.com' });
+  });
+
+  it('runs a mutation', async () => {
+    const sub = defineSubgraph({ name: 'users', typeDefs: USER_TYPEDEFS, resolvers });
+    const gw = createGateway({ subgraph: sub });
+    const result = await gw.execute({
+      document: parse(`mutation { setName(name: "Bob"){ id name } }`),
+      contextValue: {},
+    });
+    expect(result.errors).toBeUndefined();
+    expect((result.data as any).setName.name).toBe('Bob');
+  });
+
+  it('supports variables', async () => {
+    const sub = defineSubgraph({ name: 'users', typeDefs: USER_TYPEDEFS, resolvers });
+    const gw = createGateway({ subgraph: sub });
+    const result = await gw.execute({
+      document: parse(`query($id: ID!){ user(id: $id){ id name } }`),
+      variableValues: { id: 'u1' },
+      contextValue: {},
+    });
+    expect((result.data as any).user.id).toBe('u1');
+  });
+
+  it('reports validation errors for bad queries', async () => {
+    const sub = defineSubgraph({ name: 'users', typeDefs: USER_TYPEDEFS, resolvers });
+    const gw = createGateway({ subgraph: sub });
+    const result = await gw.execute({
+      document: parse(`{ me { id doesNotExist } }`),
+      contextValue: {},
+    });
+    expect(result.errors?.length).toBeGreaterThan(0);
+  });
+
+  it('exposes a public schema without federation internals', () => {
+    const sub = defineSubgraph({ name: 'users', typeDefs: USER_TYPEDEFS, resolvers });
+    const gw = createGateway({ subgraph: sub });
+    const introspect = parse(`{ __schema { queryType { name } mutationType { name } } }`);
+    // The public schema still has Query+Mutation; _service/_entities are NOT queryable.
+    // (We verify by checking the schema's query type doesn't define _entities by name.)
+    const queryFields = Object.keys((gw.schema.getQueryType()?.getFields() ?? {}) as Record<string, unknown>);
+    expect(queryFields).toContain('me');
+    expect(queryFields).not.toContain('_service');
+    expect(queryFields).not.toContain('_entities');
+  });
+
+  it('throws a clear error for multi-subgraph (Phase 6 territory)', () => {
+    const a = defineSubgraph({ name: 'a', typeDefs: `type A @key(fields:"id"){ id: ID! } type Query { a: A }` });
+    const b = defineSubgraph({ name: 'b', typeDefs: `type B @key(fields:"id"){ id: ID! } type Query { b: B }` });
+    expect(() => createGateway({ subgraphs: [a, b] })).toThrow(/Phase 6/);
+  });
+
+  it('buildPublicSchema strips federation directives', () => {
+    const sub = defineSubgraph({ name: 'users', typeDefs: USER_TYPEDEFS, resolvers });
+    // Public schema builds cleanly from the stripped SDL (no @key in the printed type).
+    const schema = buildPublicSchema(sub.sdl);
+    expect(() => schema.getQueryType()).not.toThrow();
+  });
+});