@bhooai/nexus-realtime 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @bhooai/nexus-realtime
+
+WebSocket server with rooms, a Redis pub/sub adapter for horizontal scale, WS
+auth, WebRTC signaling over WS, and a mediasoup SFU adapter.
+
+## Exports
+
+- **RealtimeServer** — `new RealtimeServer({ httpServer, path, authService,
+  csrfOptions? })`. Auth via access token on the WS upgrade; optional CSRF
+  origin/double-submit check on the upgrade.
+- **PubSubAdapter / RedisPubSubAdapter** — fan-out across instances.
+- **MediasoupAdapter** — mediasoup SFU worker (native; RTP/SFU is **not** hand-rolled).
+
+## Wire protocol
+
+Client → server: `{type:'join'|'offer'|'answer'|'candidate'|'broadcast'|'media'|'ping'}`.
+Server → client: `{type:'joined'|'peer-joined'|'peer-left'|'offer'|'answer'|'candidate'|
+'broadcast'|'media'|'pong'|'error'}`.
+
+Mediasoup media actions: `getRouterRtpCapabilities`, `createWebRtcTransport{direction}`,
+`connectTransport{direction,dtlsParameters}`, `produce{kind,rtpParameters}→{id,kind}`,
+`consume{producerId,rtpCapabilities}→{id,producerId,kind,rtpParameters}`,
+`closeProducer`/`closeConsumer`. The frontend uses `mediasoup-client` (see
+`apps/frontend/src/lib/stream.ts`).

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@bhooai/nexus-realtime",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "@bhooai/nexus-auth": "^0.1.0",
+    "ws": "^8.18.0"
+  },
+  "optionalDependencies": {
+    "mediasoup": "^3.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/adapter/PubSubAdapter.ts

@@ -0,0 +1,42 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Pub/sub adapter for cross-instance room broadcast fanout. The default
+ * `MemoryPubSubAdapter` is a single-process EventEmitter-backed implementation
+ * (fine for tests and single-node deployments). A Redis-backed adapter is used
+ * for horizontal scaling — see `RedisPubSubAdapter`.
+ *
+ * Broadcast model: `RealtimeServer` publishes a room event; every instance's
+ * subscriber (including the originator) delivers it to its local members. This
+ * gives exactly-once delivery per instance without the originator also sending
+ * locally.
+ */
+export interface PubSubAdapter {
+  /** Publish a message to a channel (room). Returns void (fire-and-forget). */
+  publish(channel: string, message: Buffer | string): void;
+  /** Subscribe to a channel; the handler is called for each published message. */
+  subscribe(channel: string, handler: (message: Buffer | string) => void): Promise<void> | void;
+  /** Unsubscribe a handler from a channel. */
+  unsubscribe(channel: string, handler: (message: Buffer | string) => void): Promise<void> | void;
+}
+
+export class MemoryPubSubAdapter implements PubSubAdapter {
+  private bus = new EventEmitter();
+
+  constructor() {
+    // Many subscribers per channel; allow headroom for fanout.
+    this.bus.setMaxListeners(0);
+  }
+
+  publish(channel: string, message: Buffer | string): void {
+    this.bus.emit(channel, message);
+  }
+
+  subscribe(channel: string, handler: (message: Buffer | string) => void): void {
+    this.bus.on(channel, handler);
+  }
+
+  unsubscribe(channel: string, handler: (message: Buffer | string) => void): void {
+    this.bus.off(channel, handler);
+  }
+}

package/src/adapter/RedisPubSubAdapter.ts

@@ -0,0 +1,59 @@
+import type { PubSubAdapter } from './PubSubAdapter.js';
+
+/**
+ * Minimal Redis client interface this adapter depends on (compatible with
+ * `node-redis` i.e. `createClient()`). Kept structural so the realtime package
+ * does not hard-depend on a redis client at import time — `nexus-cache`
+ * (Phase 7) supplies a configured client.
+ */
+export interface RedisLike {
+  publish(channel: string, message: string): Promise<number>;
+  subscribe(...channels: string[]): Promise<number>;
+  unsubscribe(...channels: string[]): Promise<number>;
+  on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+  off(event: 'message', listener: (channel: string, message: string) => void): unknown;
+}
+
+/**
+ * Redis-backed pub/sub adapter for multi-instance room broadcast. Uses one
+ * configured Redis client in subscribe mode; messages are JSON strings.
+ */
+export class RedisPubSubAdapter implements PubSubAdapter {
+  private handlers = new Map<string, Set<(message: Buffer | string) => void>>();
+
+  constructor(private client: RedisLike) {
+    // Route incoming Redis messages to registered handlers.
+    const route = (channel: string, message: string) => {
+      const set = this.handlers.get(channel);
+      if (set) for (const h of set) h(message);
+    };
+    this.route = route;
+    client.on('message', route);
+  }
+
+  private route: (channel: string, message: string) => void;
+
+  publish(channel: string, message: Buffer | string): void {
+    void this.client.publish(channel, typeof message === 'string' ? message : message.toString('utf8'));
+  }
+
+  async subscribe(channel: string, handler: (message: Buffer | string) => void): Promise<void> {
+    let set = this.handlers.get(channel);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(channel, set);
+      await this.client.subscribe(channel);
+    }
+    set.add(handler);
+  }
+
+  async unsubscribe(channel: string, handler: (message: Buffer | string) => void): Promise<void> {
+    const set = this.handlers.get(channel);
+    if (!set) return;
+    set.delete(handler);
+    if (set.size === 0) {
+      this.handlers.delete(channel);
+      await this.client.unsubscribe(channel);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './adapter/PubSubAdapter.js';
+export * from './adapter/RedisPubSubAdapter.js';
+export * from './server/RealtimeServer.js';
+export * from './mediasoup/MediasoupAdapter.js';

package/src/mediasoup/MediasoupAdapter.ts

@@ -0,0 +1,176 @@
+import type { Connection } from '../types.js';
+import type { MediaAction } from '../types.js';
+
+/**
+ * mediasoup SFU adapter. Lazily imports `mediasoup` (an optional native
+ * dependency) so the realtime package loads even when mediasoup is not
+ * installed; media actions return a clear error in that case.
+ *
+ * One mediasoup worker is created per adapter; one router per room (with a
+ * default Opus audio + VP8 video RTP capability set). Each connection gets a
+ * send WebRtcTransport and a recv WebRtcTransport; producers/consumers are
+ * tracked per connection. This is a functional single-room SFU demo; full
+ * multi-room capacity scaling is wired but tuned in a later pass.
+ */
+export interface MediasoupAdapterOptions {
+  /** RTC listen IP announced to clients (default 127.0.0.1). */
+  announceIp?: string;
+  /** RTC port range (defaults let mediasoup choose). */
+  rtcMinPort?: number;
+  rtcMaxPort?: number;
+  /** Number of mediasoup workers (default 1). */
+  workerCount?: number;
+}
+
+// Default router media codecs: Opus audio + VP8 video. (RTX omitted for portability —
+// adding it requires a correctly-bound `apt` referencing the VP8 payload type; not needed for the demo.)
+const ROUTER_MEDIA_CODECS = [
+  { kind: 'audio', mimeType: 'audio/opus', clockRate: 48000, channels: 2 },
+  { kind: 'video', mimeType: 'video/VP8', clockRate: 90000, rtcpFeedback: [{ type: 'nack' }, { type: 'nack', parameter: 'pli' }, { type: 'ccm', parameter: 'fir' }, { type: 'goog-remb' }] },
+];
+
+interface ConnState {
+  sendTransport?: unknown;
+  recvTransport?: unknown;
+  producers: Map<string, unknown>;
+  consumers: Map<string, unknown>;
+}
+
+export class MediasoupAdapter {
+  private workerPromise?: Promise<unknown>;
+  private routers = new Map<string, Promise<unknown>>();
+  private states = new WeakMap<Connection, ConnState>();
+  private opts: MediasoupAdapterOptions;
+
+  constructor(opts: MediasoupAdapterOptions = {}) {
+    this.opts = opts;
+  }
+
+  private state(conn: Connection): ConnState {
+    let s = this.states.get(conn);
+    if (!s) { s = { producers: new Map(), consumers: new Map() }; this.states.set(conn, s); }
+    return s;
+  }
+
+  private async worker(): Promise<unknown> {
+    if (!this.workerPromise) {
+      const mod = await import('mediasoup');
+      this.workerPromise = mod.createWorker({
+        logLevel: 'warn',
+        rtcMinPort: this.opts.rtcMinPort ?? 40000,
+        rtcMaxPort: this.opts.rtcMaxPort ?? 40100,
+      }) as Promise<unknown>;
+    }
+    return this.workerPromise;
+  }
+
+  private async router(room: string): Promise<unknown> {
+    let p = this.routers.get(room);
+    if (!p) {
+      p = (async () => {
+        const w = await this.worker();
+        const r = await (w as any).createRouter({ mediaCodecs: ROUTER_MEDIA_CODECS });
+        return r;
+      })();
+      this.routers.set(room, p);
+    }
+    return p;
+  }
+
+  async handle(conn: Connection, action: MediaAction, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const room = String(payload.room ?? 'default');
+    const router = await this.router(room);
+    const s = this.state(conn);
+
+    switch (action) {
+      case 'getRouterRtpCapabilities':
+        return { rtpCapabilities: (router as any).rtpCapabilities };
+
+      case 'createWebRtcTransport': {
+        const dir = (payload.direction ?? 'send') as 'send' | 'recv';
+        const t = await (router as any).createWebRtcTransport({
+          listenIps: [{ ip: '0.0.0.0', announcedIp: this.opts.announceIp ?? '127.0.0.1' }],
+          enableUdp: true,
+          enableTcp: true,
+          preferUdp: true,
+        });
+        if (dir === 'send') s.sendTransport = t; else s.recvTransport = t;
+        return {
+          id: t.id,
+          iceParameters: t.iceParameters,
+          iceCandidates: t.iceCandidates,
+          dtlsParameters: t.dtlsParameters,
+          direction: dir,
+        };
+      }
+
+      case 'connectTransport': {
+        const dir = (payload.direction ?? 'send') as 'send' | 'recv';
+        const t = dir === 'send' ? s.sendTransport : s.recvTransport;
+        if (!t) return { error: 'transport not found' };
+        await (t as any).connect({ dtlsParameters: payload.dtlsParameters });
+        return { connected: true };
+      }
+
+      case 'produce': {
+        if (!s.sendTransport) return { error: 'send transport not found' };
+        const producer = await (s.sendTransport as any).produce({
+          kind: payload.kind,
+          rtpParameters: payload.rtpParameters,
+          paused: false,
+        });
+        s.producers.set(producer.id, producer);
+        return { id: producer.id, kind: producer.kind };
+      }
+
+      case 'consume': {
+        if (!s.recvTransport) return { error: 'recv transport not found' };
+        const canConsume = (router as any).canConsume({ producerId: payload.producerId, rtpCapabilities: payload.rtpCapabilities });
+        if (!canConsume) return { error: 'cannot consume' };
+        const consumer = await (s.recvTransport as any).consume({
+          producerId: payload.producerId,
+          rtpCapabilities: payload.rtpCapabilities,
+          paused: true,
+        });
+        s.consumers.set(consumer.id, consumer);
+        return {
+          id: consumer.id,
+          producerId: consumer.producerId,
+          kind: consumer.kind,
+          rtpParameters: consumer.rtpParameters,
+        };
+      }
+
+      case 'closeProducer': {
+        const p = s.producers.get(String(payload.producerId));
+        if (p) { (p as any).close(); s.producers.delete(String(payload.producerId)); }
+        return { closed: true };
+      }
+
+      case 'closeConsumer': {
+        const c = s.consumers.get(String(payload.consumerId));
+        if (c) { (c as any).close(); s.consumers.delete(String(payload.consumerId)); }
+        return { closed: true };
+      }
+
+      default:
+        return { error: `unknown media action` };
+    }
+  }
+
+  /** Clean up a connection's transports/producers/consumers on disconnect. */
+  cleanup(conn: Connection): void {
+    const s = this.states.get(conn);
+    if (!s) return;
+    for (const p of s.producers.values()) try { (p as any).close(); } catch { /* ignore */ }
+    for (const c of s.consumers.values()) try { (c as any).close(); } catch { /* ignore */ }
+    try { (s.sendTransport as any)?.close(); } catch { /* ignore */ }
+    try { (s.recvTransport as any)?.close(); } catch { /* ignore */ }
+    this.states.delete(conn);
+  }
+
+  /** Whether mediasoup is importable on this process (for capability checks). */
+  static async isAvailable(): Promise<boolean> {
+    try { await import('mediasoup'); return true; } catch { return false; }
+  }
+}

package/src/server/RealtimeServer.ts

@@ -0,0 +1,252 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import type { IncomingMessage, Server as HttpServer } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { randomBytes } from 'node:crypto';
+import type { AuthService, CsrfOptions } from '@bhooai/nexus-auth';
+import { checkWsUpgrade } from '@bhooai/nexus-auth';
+import { AuthenticationError } from '@bhooai/nexus-core';
+import type { ClientMessage, ServerMessage, Connection } from '../types.js';
+import type { PubSubAdapter } from '../adapter/PubSubAdapter.js';
+import { MemoryPubSubAdapter } from '../adapter/PubSubAdapter.js';
+import type { MediasoupAdapter } from '../mediasoup/MediasoupAdapter.js';
+
+export interface RealtimeServerOptions {
+  /** The HTTP server to attach the WebSocket upgrade handler to. */
+  httpServer: HttpServer;
+  /** WS path (default '/ws'). */
+  path?: string;
+  /** Auth service for access-token verification on upgrade (optional → anonymous). */
+  authService?: AuthService;
+  /** CSRF options for the WS upgrade origin + double-submit check (optional). */
+  csrfOptions?: CsrfOptions;
+  /** Pub/sub adapter for cross-instance fanout (default in-memory). */
+  adapter?: PubSubAdapter;
+  /** mediasoup SFU adapter for media routing (optional). */
+  mediasoup?: MediasoupAdapter;
+  /** Require authentication on upgrade (default true when authService provided). */
+  requireAuth?: boolean;
+}
+
+const CONN_CHANNEL = (id: string) => `conn:${id}`;
+const ROOM_CHANNEL = (room: string) => `room:${room}`;
+
+/**
+ * WebSocket realtime server. Attaches to an HTTP server's 'upgrade' event,
+ * authenticates the upgrade (access token via `?token=` query, optional CSRF
+ * origin/double-submit check), and dispatches client messages: room join/leave,
+ * WebRTC offer/answer/ICE-candidate relay, and app broadcasts.
+ *
+ * Cross-instance fanout uses the pub/sub adapter: direct peer messages are
+ * published to `conn:<id>` (delivered by whichever instance hosts the peer);
+ * room events are published to `room:<room>` (delivered to every instance with
+ * local members).
+ */
+export class RealtimeServer {
+  private wss: WebSocketServer;
+  private adapter: PubSubAdapter;
+  private connections = new Map<string, Connection>();
+  /** Local members per room (connIds on THIS instance). */
+  private roomMembers = new Map<string, Set<string>>();
+  private subscribedRooms = new Set<string>();
+  private opts: RealtimeServerOptions;
+
+  constructor(opts: RealtimeServerOptions) {
+    this.opts = opts;
+    this.adapter = opts.adapter ?? new MemoryPubSubAdapter();
+    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');
+    // Only handle our WS path; let other upgrade listeners handle the rest.
+    if (url.pathname !== (this.opts.path ?? '/ws')) return;
+
+    try {
+      // 1. CSRF + origin check (WS has no CORS preflight).
+      if (this.opts.csrfOptions) checkWsUpgrade(req.headers as Record<string, string | string[] | undefined>, this.opts.csrfOptions);
+
+      // 2. Authenticate via ?token=<accessToken> (or subprotocol).
+      const token = (url.searchParams.get('token') ?? req.headers['sec-websocket-protocol']?.split(',').map((s) => s.trim())[0]) ?? '';
+      let userId: string | undefined;
+      let roles: string[] = [];
+      if (this.opts.authService && token) {
+        const payload = await this.opts.authService.verifyAccessToken(token);
+        userId = payload.sub;
+        roles = payload.roles ?? [];
+      } else if (this.opts.requireAuth ?? !!this.opts.authService) {
+        throw new AuthenticationError('Missing access token');
+      }
+
+      this.wss.handleUpgrade(req, socket, head, (ws) => {
+        const id = userId ?? randomBytes(9).toString('base64url');
+        this.register(ws, id, userId, roles);
+      });
+    } catch (err) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+      socket.destroy();
+    }
+  }
+
+  private register(ws: WebSocket, id: string, userId: string | undefined, roles: string[]): void {
+    const conn: Connection = {
+      id,
+      userId,
+      roles,
+      rooms: new Set(),
+      get isOpen() { return ws.readyState === ws.OPEN; },
+      send: (message) => { if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(message)); },
+      close: (code, reason) => ws.close(code, reason),
+    };
+    this.connections.set(id, conn);
+
+    // Subscribe to this connection's direct channel (cross-instance delivery).
+    const direct = (raw: Buffer | string) => {
+      const msg = JSON.parse(raw.toString()) as ServerMessage;
+      conn.send(msg);
+    };
+    this.adapter.subscribe(CONN_CHANNEL(id), direct);
+    (conn as Connection & { _direct?: unknown })._direct = direct;
+
+    ws.on('message', (data) => this.onMessage(conn, data.toString('utf8')));
+    ws.on('close', () => this.onClose(conn, direct));
+    ws.on('error', () => this.onClose(conn, direct));
+  }
+
+  private async onMessage(conn: Connection, raw: string): Promise<void> {
+    let msg: ClientMessage;
+    try {
+      msg = JSON.parse(raw) as ClientMessage;
+    } catch {
+      conn.send({ type: 'error', message: 'Invalid JSON' });
+      return;
+    }
+    switch (msg.type) {
+      case 'ping':
+        conn.send({ type: 'pong' });
+        return;
+      case 'join':
+        await this.joinRoom(conn, msg.room);
+        return;
+      case 'leave':
+        await this.leaveRoom(conn, msg.room);
+        return;
+      case 'offer':
+      case 'answer':
+      case 'candidate': {
+        const to = this.connections.get(msg.to);
+        if (to) {
+          // Same instance: send directly.
+          to.send(this.relayFrom(conn, msg));
+        } else {
+          // Cross-instance: publish to the peer's direct channel (best-effort).
+          this.adapter.publish(CONN_CHANNEL(msg.to), JSON.stringify(this.relayFrom(conn, msg)));
+        }
+        return;
+      }
+      case 'broadcast':
+        this.broadcastRoom(msg.room, { type: 'broadcast', room: msg.room, from: conn.id, event: msg.event, data: msg.data });
+        return;
+      case 'media':
+        await this.handleMedia(conn, msg);
+        return;
+      default:
+        conn.send({ type: 'error', message: `Unknown message type` });
+    }
+  }
+
+  private relayFrom(conn: Connection, msg: ClientMessage): ServerMessage {
+    if (msg.type === 'offer') return { type: 'offer', from: conn.id, sdp: msg.sdp };
+    if (msg.type === 'answer') return { type: 'answer', from: conn.id, sdp: msg.sdp };
+    if (msg.type === 'candidate') return { type: 'candidate', from: conn.id, candidate: msg.candidate };
+    throw new Error('Cannot relay a non-peer message');
+  }
+
+  private async joinRoom(conn: Connection, room: string): Promise<void> {
+    if (conn.rooms.has(room)) return;
+    let set = this.roomMembers.get(room);
+    const wasEmpty = !set || set.size === 0;
+    if (!set) { set = new Set(); this.roomMembers.set(room, set); }
+    set.add(conn.id);
+    conn.rooms.add(room);
+
+    if (wasEmpty && !this.subscribedRooms.has(room)) {
+      this.adapter.subscribe(ROOM_CHANNEL(room), this.deliverRoom);
+      this.subscribedRooms.add(room);
+    }
+    // Notify everyone (including cross-instance) that a peer joined.
+    this.adapter.publish(ROOM_CHANNEL(room), JSON.stringify({ type: 'peer-joined', room, peer: conn.id }));
+    // Tell the joiner who's already here (local members).
+    const peers = [...set].filter((id) => id !== conn.id);
+    conn.send({ type: 'joined', room, peers });
+  }
+
+  private async leaveRoom(conn: Connection, room: string): Promise<void> {
+    conn.rooms.delete(room);
+    const set = this.roomMembers.get(room);
+    if (!set) return;
+    set.delete(conn.id);
+    this.adapter.publish(ROOM_CHANNEL(room), JSON.stringify({ type: 'peer-left', room, peer: conn.id }));
+    conn.send({ type: 'left', room });
+    if (set.size === 0) {
+      this.roomMembers.delete(room);
+      this.subscribedRooms.delete(room);
+      this.adapter.unsubscribe(ROOM_CHANNEL(room), this.deliverRoom);
+    }
+  }
+
+  /** Deliver a room-channel message to all local members of that room, skipping the originator. */
+  private deliverRoom = (raw: Buffer | string): void => {
+    const msg = JSON.parse(raw.toString()) as ServerMessage & { room?: string };
+    const room = msg.room;
+    if (!room) return;
+    const set = this.roomMembers.get(room);
+    if (!set) return;
+    // The originator must not receive its own join/leave/broadcast echo.
+    const origin =
+      msg.type === 'peer-joined' || msg.type === 'peer-left' ? (msg as { peer: string }).peer
+      : msg.type === 'broadcast' ? (msg as { from: string }).from
+      : undefined;
+    for (const id of set) {
+      if (id === origin) continue;
+      this.connections.get(id)?.send(msg);
+    }
+  };
+
+  private broadcastRoom(room: string, msg: ServerMessage): void {
+    this.adapter.publish(ROOM_CHANNEL(room), JSON.stringify(msg));
+  }
+
+  /** Publish an application event to every authenticated connection in a room. */
+  broadcast(room: string, event: string, data?: unknown): void {
+    this.broadcastRoom(room, { type: 'broadcast', room, from: 'server', event, data });
+  }
+
+  private async handleMedia(conn: Connection, msg: ClientMessage & { type: 'media' }): Promise<void> {
+    if (!this.opts.mediasoup) {
+      conn.send({ type: 'error', message: 'mediasoup SFU not enabled', code: 'NO_SFU' });
+      return;
+    }
+    const reply = await this.opts.mediasoup.handle(conn, msg.action, msg.payload);
+    conn.send({ type: 'media', action: msg.action, payload: reply });
+  }
+
+  private async onClose(conn: Connection, direct: (raw: Buffer | string) => void): Promise<void> {
+    this.connections.delete(conn.id);
+    this.adapter.unsubscribe(CONN_CHANNEL(conn.id), direct);
+    for (const room of [...conn.rooms]) await this.leaveRoom(conn, room);
+    this.opts.mediasoup?.cleanup(conn);
+  }
+
+  /** Number of live connections (test/monitoring helper). */
+  get connectionCount(): number {
+    return this.connections.size;
+  }
+
+  /** Close the WS server and all connections. */
+  close(): Promise<void> {
+    for (const conn of this.connections.values()) conn.close(1001, 'server shutting down');
+    this.wss.close();
+    return Promise.resolve();
+  }
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+/** Messages a client may send over the WebSocket. */
+export type ClientMessage =
+  | { type: 'join'; room: string }
+  | { type: 'leave'; room: string }
+  | { type: 'offer'; to: string; sdp: string; room?: string }
+  | { type: 'answer'; to: string; sdp: string; room?: string }
+  | { type: 'candidate'; to: string; candidate: unknown; room?: string }
+  | { type: 'broadcast'; room: string; event: string; data?: unknown }
+  | { type: 'ping' }
+  | { type: 'media'; action: MediaAction; payload: Record<string, unknown> };
+
+/** Messages the server sends to a client. */
+export type ServerMessage =
+  | { type: 'joined'; room: string; peers: string[] }
+  | { type: 'left'; room: string }
+  | { type: 'peer-joined'; room: string; peer: string }
+  | { type: 'peer-left'; room: string; peer: string }
+  | { type: 'offer'; from: string; sdp: string }
+  | { type: 'answer'; from: string; sdp: string }
+  | { type: 'candidate'; from: string; candidate: unknown }
+  | { type: 'broadcast'; room: string; from: string; event: string; data?: unknown }
+  | { type: 'pong' }
+  | { type: 'media'; action: MediaAction; payload: Record<string, unknown> }
+  | { type: 'error'; message: string; code?: string };
+
+/** mediasoup signaling actions relayed over WS. */
+export type MediaAction =
+  | 'getRouterRtpCapabilities'
+  | 'createWebRtcTransport'
+  | 'connectTransport'
+  | 'produce'
+  | 'consume'
+  | 'closeProducer'
+  | 'closeConsumer';
+
+/** A connected client's server-side record. */
+export interface Connection {
+  /** Stable id for this connection (the user id when authenticated, else random). */
+  id: string;
+  /** Authenticated user id (undefined for anonymous connections). */
+  userId?: string;
+  /** Roles from the access token. */
+  roles: string[];
+  /** Rooms this connection has joined (on this instance). */
+  rooms: Set<string>;
+  /** Send a JSON message to the client. */
+  send(message: ServerMessage): void;
+  /** Close the connection. */
+  close(code?: number, reason?: string): void;
+  /** Whether the underlying socket is still open. */
+  readonly isOpen: boolean;
+}

package/tests/realtime.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, afterEach, beforeAll } from 'vitest';
+import { createServer, type Server as HttpServer } from 'node:http';
+import { WebSocket, type RawData } from 'ws';
+import type { AddressInfo } from 'node:net';
+import { AuthService, MemorySessionStore } from '@bhooai/nexus-auth';
+import { RealtimeServer, MemoryPubSubAdapter, MediasoupAdapter } from '../src/index.js';
+
+const JWT = { secret: 'rt-test-secret-long-enough-for-hs256-signing', issuer: 'nexus-test', accessTtl: 60, refreshTtl: 3600 };
+
+function boot(opts: { authService?: AuthService; requireAuth?: boolean } = {}): { http: HttpServer; rt: RealtimeServer; port: number; close: () => Promise<void> } {
+  const http = createServer((_req, res) => res.end());
+  const rt = new RealtimeServer({ httpServer: http, authService: opts.authService, requireAuth: opts.requireAuth, path: '/ws' });
+  return {
+    http,
+    rt,
+    port: 0,
+    async close() {
+      await rt.close();
+      await new Promise<void>((r) => http.close(() => r()));
+    },
+  };
+}
+
+function listen(s: { http: HttpServer; port: number }): Promise<number> {
+  return new Promise((resolve) => {
+    s.http.listen(0, '127.0.0.1', () => {
+      s.port = (s.http.address() as AddressInfo).port;
+      resolve(s.port);
+    });
+  });
+}
+
+interface Client {
+  ws: WebSocket;
+  messages: import('../src/types.js').ServerMessage[];
+  next(): Promise<import('../src/types.js').ServerMessage>;
+  send(msg: unknown): void;
+  close(): Promise<void>;
+}
+
+function connect(port: number, query = '', protocols?: string[]): Promise<Client> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/ws${query}`, protocols);
+    const messages: import('../src/types.js').ServerMessage[] = [];
+    ws.on('open', () => resolve(makeClient(ws, messages)));
+    ws.on('error', reject);
+    ws.on('message', (d: RawData) => messages.push(JSON.parse(d.toString())));
+  });
+}
+
+function makeClient(ws: WebSocket, messages: import('../src/types.js').ServerMessage[]): Client {
+  return {
+    ws,
+    messages,
+    next() {
+      return new Promise((resolve) => {
+        const tick = () => {
+          if (messages.length) resolve(messages.shift()!);
+          else setTimeout(tick, 10);
+        };
+        tick();
+      });
+    },
+    send(msg) { ws.send(JSON.stringify(msg)); },
+    close() { return new Promise<void>((r) => ws.on('close', () => r()).close()); },
+  };
+}
+
+describe('realtime: adapter', () => {
+  it('delivers published messages to subscribers', async () => {
+    const adapter = new MemoryPubSubAdapter();
+    const got: string[] = [];
+    adapter.subscribe('room:lobby', (m) => got.push(m.toString()));
+    adapter.publish('room:lobby', 'hello');
+    adapter.publish('room:other', 'nope');
+    expect(got).toEqual(['hello']);
+  });
+});
+
+describe('realtime: auth + connection', () => {
+  let svc: AuthService;
+  let s: ReturnType<typeof boot>;
+  beforeAll(() => { svc = new AuthService(JWT, new MemorySessionStore()); });
+  afterEach(async () => s && (await s.close()));
+
+  it('accepts a connection with a valid access token', async () => {
+    s = boot({ authService: svc });
+    const port = await listen(s);
+    const pair = await svc.login({ userId: 'u1', roles: ['user'] });
+    const c = await connect(port, `?token=${pair.accessToken}`);
+    c.send({ type: 'ping' });
+    const msg = await c.next();
+    expect(msg.type).toBe('pong');
+    expect(s.rt.connectionCount).toBe(1);
+    await c.close();
+  });
+
+  it('rejects a connection without a token when auth is required', async () => {
+    s = boot({ authService: svc, requireAuth: true });
+    const port = await listen(s);
+    await expect(connect(port)).rejects.toThrow();
+    expect(s.rt.connectionCount).toBe(0);
+  });
+
+  it('allows anonymous connections when no authService is configured', async () => {
+    s = boot({ requireAuth: false });
+    const port = await listen(s);
+    const c = await connect(port);
+    c.send({ type: 'ping' });
+    expect((await c.next()).type).toBe('pong');
+    await c.close();
+  });
+});
+
+describe('realtime: rooms + signaling + broadcast', () => {
+  let svc: AuthService;
+  let s: ReturnType<typeof boot>;
+  beforeAll(() => { svc = new AuthService(JWT, new MemorySessionStore()); });
+  afterEach(async () => s && (await s.close()));
+
+  async function twoClients() {
+    s = boot({ authService: svc });
+    const port = await listen(s);
+    const p1 = await svc.login({ userId: 'u-a', roles: ['user'] });
+    const p2 = await svc.login({ userId: 'u-b', roles: ['user'] });
+    const a = await connect(port, `?token=${p1.accessToken}`);
+    const b = await connect(port, `?token=${p2.accessToken}`);
+    return { port, a, b };
+  }
+
+  it('notifies peers when someone joins a room and reports existing peers', async () => {
+    const { a, b } = await twoClients();
+    a.send({ type: 'join', room: 'lobby' });
+    expect((await a.next()).type).toBe('joined');
+    b.send({ type: 'join', room: 'lobby' });
+    // B learns A is already here:
+    const bJoined = await b.next();
+    expect(bJoined.type).toBe('joined');
+    expect(bJoined).toMatchObject({ type: 'joined', room: 'lobby' });
+    if (bJoined.type === 'joined') expect(bJoined.peers).toContain('u-a');
+    // A is told B joined:
+    const aPeer = await a.next();
+    expect(aPeer.type).toBe('peer-joined');
+    if (aPeer.type === 'peer-joined') expect(aPeer.peer).toBe('u-b');
+    await a.close();
+    await b.close();
+  });
+
+  it('relays WebRTC offer/answer/candidate between peers', async () => {
+    const { a, b } = await twoClients();
+    a.send({ type: 'join', room: 'call' });
+    await a.next(); // joined
+    b.send({ type: 'join', room: 'call' });
+    await b.next(); // joined
+    await a.next(); // peer-joined (B)
+
+    a.send({ type: 'offer', to: 'u-b', sdp: 'OFFER-SDP', room: 'call' });
+    const bOffer = await b.next();
+    expect(bOffer.type).toBe('offer');
+    if (bOffer.type === 'offer') { expect(bOffer.from).toBe('u-a'); expect(bOffer.sdp).toBe('OFFER-SDP'); }
+
+    b.send({ type: 'answer', to: 'u-a', sdp: 'ANSWER-SDP', room: 'call' });
+    const aAnswer = await a.next();
+    expect(aAnswer.type).toBe('answer');
+    if (aAnswer.type === 'answer') expect(aAnswer.sdp).toBe('ANSWER-SDP');
+
+    a.send({ type: 'candidate', to: 'u-b', candidate: { c: 1 }, room: 'call' });
+    const bCand = await b.next();
+    expect(bCand.type).toBe('candidate');
+    await a.close();
+    await b.close();
+  });
+
+  it('broadcasts an event to all room members', async () => {
+    const { a, b } = await twoClients();
+    a.send({ type: 'join', room: 'stage' });
+    await a.next();
+    b.send({ type: 'join', room: 'stage' });
+    await b.next();
+    await a.next(); // peer-joined
+    a.send({ type: 'broadcast', room: 'stage', event: 'chat', data: { msg: 'hi' } });
+    const bEvt = await b.next();
+    expect(bEvt.type).toBe('broadcast');
+    if (bEvt.type === 'broadcast') { expect(bEvt.event).toBe('chat'); expect(bEvt.from).toBe('u-a'); }
+    await a.close();
+    await b.close();
+  });
+
+  it('notifies peers when someone leaves', async () => {
+    const { a, b } = await twoClients();
+    a.send({ type: 'join', room: 'x' });
+    await a.next();
+    b.send({ type: 'join', room: 'x' });
+    await b.next();
+    await a.next(); // peer-joined
+    await a.close();
+    const left = await b.next();
+    expect(left.type).toBe('peer-left');
+    await b.close();
+  });
+});
+
+describe('realtime: mediasoup SFU (skip if unavailable)', () => {
+  it('returns router RTP capabilities', async (ctx) => {
+    if (!(await MediasoupAdapter.isAvailable())) ctx.skip();
+    const adapter = new MediasoupAdapter({ announceIp: '127.0.0.1', rtcMinPort: 41000, rtcMaxPort: 41100 });
+    // Stand-in connection object (the adapter only uses it as a WeakMap key).
+    const conn = { id: 'm1', roles: [], rooms: new Set(), send() {}, close() {}, isOpen: true } as unknown as import('../src/types.js').Connection;
+    const reply = await adapter.handle(conn, 'getRouterRtpCapabilities', { room: 'test' });
+    expect(reply.rtpCapabilities).toBeDefined();
+    adapter.cleanup(conn);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../nexus-core" },
+    { "path": "../nexus-auth" }
+  ]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    globals: false,
+    testTimeout: 15_000,
+  },
+});