@ignex/nova 0.1.1

package/src/core/routing.ts

@@ -0,0 +1,94 @@
+/**
+ * Inbound routing — table-driven dispatch for app + control frames received
+ * from a socket. Parses the envelope, enforces `maxMessageSize` + the inbound
+ * allowlist, and routes to handlers / room operations.
+ *
+ * Decode is HEADER-FIRST: only the cheap envelope (version + event id) is
+ * parsed before deciding what to do, so an event that isn't in the inbound
+ * allowlist (or is a control frame) never pays the cost of a full `.unpack()`
+ * payload decode — a client can't force us to fully materialize a frame we're
+ * going to discard.
+ */
+import type { ServerWebSocket } from "bun";
+import { decodePayload, isControlId, readFrameHeader, WIRE_VERSION } from "../generated/registry";
+import type { ControlEventName, ControlEvents, EventName } from "../schema";
+import { sendControl } from "./outbound";
+import { joinRoom, leaveRoom } from "./rooms";
+import { joinGroup, leaveGroup } from "./groups";
+import type { ServerState, WsData } from "./state";
+
+// allocated once per process, reused for every inbound text frame
+const textEncoder = new TextEncoder();
+
+export function handleMessage(
+  state: ServerState,
+  ws: ServerWebSocket<WsData>,
+  raw: string | Buffer,
+): void {
+  const bytes = typeof raw === "string" ? textEncoder.encode(raw) : new Uint8Array(raw as Buffer);
+  if (state.maxMessageSize !== undefined && bytes.byteLength > state.maxMessageSize) {
+    state.metrics.protocolErrors++;
+    ws.close(1009, "message too big");
+    return;
+  }
+  const header = readFrameHeader(bytes);
+  if (!header) {
+    state.metrics.protocolErrors++;
+    return; // undecodable / wrong version / unknown id — drop
+  }
+  if (isControlId(header.id)) {
+    state.metrics.inboundControl++;
+    handleControl(state, ws, header.name as ControlEventName, decodePayload(header.id, bytes) as never);
+    return;
+  }
+  const name = header.name as EventName;
+  if (!state.inbound.has(name)) return; // not an allowed inbound event — no payload decode
+  state.metrics.inbound++;
+  state.inboundHandlers.get(name)?.(decodePayload(header.id, bytes), ws);
+}
+
+export function handleControl(
+  state: ServerState,
+  ws: ServerWebSocket<WsData>,
+  name: ControlEventName,
+  payload: unknown,
+): void {
+  switch (name) {
+    case "hello": {
+      const p = payload as ControlEvents["hello"];
+      ws.data.version = p.version;
+      ws.data.lastSeq = p.lastSeq;
+      if (p.version !== WIRE_VERSION) {
+        // protocol version mismatch — refuse this client
+        ws.close(1002, "wire version mismatch");
+      }
+      break;
+    }
+    case "subscribe": {
+      joinRoom(state, ws, (payload as ControlEvents["subscribe"]).topic);
+      break;
+    }
+    case "unsubscribe": {
+      leaveRoom(state, ws, (payload as ControlEvents["unsubscribe"]).topic);
+      break;
+    }
+    case "joinGroup": {
+      joinGroup(state, ws, (payload as ControlEvents["joinGroup"]).group);
+      break;
+    }
+    case "leaveGroup": {
+      leaveGroup(state, ws, (payload as ControlEvents["leaveGroup"]).group);
+      break;
+    }
+    case "ping": {
+      sendControl(state, ws, "pong", { ts: (payload as ControlEvents["ping"]).ts });
+      break;
+    }
+    case "pong":
+      // client keepalive reply — tracked on the client side (heartbeat)
+      break;
+    case "snapshotRequest":
+      // per-topic replay from the ring buffer (see replay.ts)
+      break;
+  }
+}

package/src/core/server.ts

@@ -0,0 +1,294 @@
+/**
+ * Server composition root — wires `createServerState` + the action modules
+ * (auth / rooms / outbound / routing) into `Bun.serve`, and returns a plain
+ * `IgnServer` API object (no class, no `this`). This is the ONLY place that
+ * knows how the pieces fit together.
+ *
+ * Public entry: `public/server.ts` re-exports `createServer` + the types.
+ */
+import type { ServerWebSocket } from "bun";
+import { WIRE_VERSION } from "../generated/registry";
+import type { Events, EventName } from "../schema";
+import { getEncodeStats, encodeToScratch } from "../transport/transport";
+import { setInt64GuardMode } from "./int64-guard";
+import type { MetricsSnapshot } from "./metrics";
+import { checkUpgrade } from "./auth";
+import { drainSocket, sendControl, sendFrame } from "./outbound";
+import { handleMessage } from "./routing";
+import { joinRoom, leaveRoom, publishToRoom, roomTopics } from "./rooms";
+import {
+  activeGroups,
+  groupMembers as groupMemberIds,
+  joinGroup as addToGroup,
+  leaveGroup as removeFromGroup,
+  publishToGroup as publishToGroupState,
+} from "./groups";
+import { createServerState, type IgnServerOptions, type WsData } from "./state";
+import { createNatsBridge } from "../bridge/nats";
+
+/** A snapshot of an active client (from `getClient` / `getClients` / GET /clients). */
+export interface ClientInfo {
+  id: string;
+  /** arbitrary app metadata from `authenticate` (undefined if none) */
+  meta?: Record<string, unknown>;
+  /** server-side groups this client belongs to */
+  groups: string[];
+  /** topics/rooms this client has joined */
+  topics: string[];
+  /** epoch ms the socket connected */
+  connectedAt: number;
+  /** remote IP (from the socket) */
+  ip: string;
+}
+
+function toClientInfo(ws: ServerWebSocket<WsData>): ClientInfo {
+  return {
+    id: ws.data.id,
+    meta: ws.data.meta,
+    groups: [...ws.data.groups],
+    topics: [...ws.data.topics],
+    connectedAt: ws.data.connectedAt,
+    ip: ws.remoteAddress,
+  };
+}
+
+/** The public server API (returned by `createServer`). */
+export interface IgnServer {
+  readonly port: number;
+  readonly clientCount: number;
+  getMetrics(): MetricsSnapshot;
+  /** Broadcast a typed event to every connected client (zero-alloc on the happy path). */
+  publish<K extends EventName>(name: K, payload: Events[K]): void;
+  /** Send a typed event to a single socket (zero-alloc on the happy path). */
+  publishTo<K extends EventName>(ws: ServerWebSocket<WsData>, name: K, payload: Events[K]): void;
+  /** Publish a typed event to every socket subscribed to `topic`. */
+  publishToTopic<K extends EventName>(topic: string, name: K, payload: Events[K]): void;
+  /** Send a typed event to a specific client by id. Returns false if that client is offline. */
+  publishToClient<K extends EventName>(id: string, name: K, payload: Events[K]): boolean;
+  /** Programmatic room membership (clients can also join via subscribe frames). */
+  join(topic: string, ws: ServerWebSocket<WsData>): void;
+  leave(topic: string, ws: ServerWebSocket<WsData>): void;
+  /** Live topic names (with at least one subscriber). */
+  topics(): string[];
+  /** Server-side group membership (targeted fan-out, no replay). */
+  joinGroup(id: string, group: string): void;
+  leaveGroup(id: string, group: string): void;
+  /** Publish a typed event to every client in a server-side group. */
+  publishToGroup<K extends EventName>(group: string, name: K, payload: Events[K]): void;
+  /** Live server-side group names (with at least one member). */
+  groups(): string[];
+  /** Client ids currently in `group`. */
+  groupMembers(group: string): string[];
+  /** Groups a client belongs to ([] if offline/unknown). */
+  clientGroups(id: string): string[];
+  /** Active-client introspection. */
+  getClient(id: string): ClientInfo | undefined;
+  getClients(): ClientInfo[];
+  /** Force-close a specific client socket (e.g. from a policy / admin action). */
+  closeClient(ws: ServerWebSocket<WsData>): void;
+  /** Disconnect a client by id. Returns false if that client is offline. */
+  disconnectClient(id: string): boolean;
+  /** Register a handler for an inbound app event (must be in `options.inbound`). */
+  on<K extends EventName>(name: K, handler: (payload: Events[K], ws: ServerWebSocket<WsData>) => void): IgnServer;
+  off<K extends EventName>(name: K): IgnServer;
+  /** Graceful drain: stop accepting, wait up to `timeoutMs` for queues to flush. */
+  drain(timeoutMs?: number): Promise<void>;
+  stop(force?: boolean): void;
+}
+
+export function createServer(options: IgnServerOptions): IgnServer {
+  const state = createServerState(options);
+  setInt64GuardMode(options.int64Guard ?? "off");
+
+  // NATS bridge (optional, best-effort — created eagerly, connects in the background)
+  const natsOpt = options.nats;
+  if (natsOpt) state.bridge = "publish" in natsOpt ? natsOpt : createNatsBridge(natsOpt);
+
+  // Encode once + broadcast to every connected client (NO bridge) — the shared
+  // hot path for `publish` and NATS-inbound forwarding. Loop prevention: inbound
+  // events reach clients but are never re-bridged to NATS.
+  function fanOutAll(name: Parameters<typeof encodeToScratch>[0], payload: unknown): Uint8Array {
+    const frame = encodeToScratch(name, payload);
+    state.metrics.published++;
+    for (const ws of state.sockets) sendFrame(state, ws, frame);
+    return frame;
+  }
+
+  if (state.bridge) {
+    state.bridge.setOnInbound((name, payload) => {
+      fanOutAll(name, payload);
+    });
+  }
+
+  const bun = Bun.serve<WsData>({
+    port: options.port,
+    hostname: options.hostname,
+    idleTimeout: options.idleTimeout ?? 30,
+    tls: options.tls,
+    fetch: (req, srv) => {
+      const url = new URL(req.url);
+      if (url.pathname === state.path) return checkUpgrade(state, req, srv);
+      if (url.pathname === "/health") {
+        const h = state.metrics.snapshot(state.sockets.size);
+        return new Response(
+          JSON.stringify({ status: "ok", clients: h.connectedClients, uptimeMs: h.uptimeMs }),
+          { headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url.pathname === "/clients") {
+        return new Response(JSON.stringify([...state.clients.values()].map(toClientInfo)), {
+          headers: { "content-type": "application/json" },
+        });
+      }
+      if (options.fetch) return options.fetch(req);
+      return new Response("not found", { status: 404 });
+    },
+    websocket: {
+      open: (ws) => {
+        state.sockets.add(ws);
+        // belt-and-suspenders: an auth race could double-register an id — kick the stale session
+        const existing = state.clients.get(ws.data.id);
+        if (existing && existing !== ws) existing.close(1000, "replaced by newer session");
+        state.clients.set(ws.data.id, ws);
+        for (const g of ws.data.groups) addToGroup(state, ws, g);
+        // announce our wire version + capabilities so clients can negotiate
+        sendControl(state, ws, "hello", { version: WIRE_VERSION, caps: [], lastSeq: 0 });
+        // then assign identity so the client knows its id + server-side groups
+        sendControl(state, ws, "welcome", { clientId: ws.data.id, groups: [...ws.data.groups] });
+      },
+      close: (ws) => {
+        state.sockets.delete(ws);
+        state.clients.delete(ws.data.id);
+        for (const g of ws.data.groups) removeFromGroup(state, ws, g);
+        ws.data.groups.clear();
+        for (const t of ws.data.topics) leaveRoom(state, ws, t);
+        ws.data.topics.clear();
+        delete ws.data.queue;
+      },
+      message: (ws, msg) => handleMessage(state, ws, msg),
+      drain: (ws) => drainSocket(state, ws),
+    },
+  });
+
+  const api: IgnServer = {
+    get port(): number {
+      return bun.port ?? 0;
+    },
+    get clientCount(): number {
+      return state.sockets.size;
+    },
+    getMetrics(): MetricsSnapshot {
+      const stats = getEncodeStats();
+      for (const [name, n] of Object.entries(stats.direct)) {
+        if (n > 0) state.metrics.countPath(name, "direct");
+      }
+      for (const [name, n] of Object.entries(stats.json)) {
+        if (n > 0) state.metrics.countPath(name, "json");
+      }
+      const snapshot = state.metrics.snapshot(state.sockets.size);
+      const b = state.bridge;
+      if (b) {
+        snapshot.bridged = b.stats.bridged;
+        snapshot.bridgedBytes = b.stats.bridgedBytes;
+        snapshot.bridgeErrors = b.stats.bridgeErrors;
+        snapshot.bridgeInbound = b.stats.bridgeInbound;
+        snapshot.bridgeInboundErrors = b.stats.bridgeInboundErrors;
+        snapshot.natsStatus = b.status;
+      }
+      return snapshot;
+    },
+    publish(name, payload) {
+      const frame = fanOutAll(name, payload);
+      state.bridge?.publish(state.bridge.subjects.broadcast(name), frame);
+    },
+    publishTo(ws, name, payload) {
+      state.metrics.published++;
+      sendFrame(state, ws, encodeToScratch(name, payload));
+    },
+    publishToTopic(topic, name, payload) {
+      const frame = encodeToScratch(name, payload);
+      state.metrics.published++;
+      publishToRoom(state, topic, frame);
+      state.bridge?.publish(state.bridge.subjects.topic(topic, name), frame);
+    },
+    publishToClient(id, name, payload) {
+      const ws = state.clients.get(id);
+      if (!ws) return false;
+      state.metrics.published++;
+      sendFrame(state, ws, encodeToScratch(name, payload));
+      return true;
+    },
+    join(topic, ws) {
+      joinRoom(state, ws, topic);
+    },
+    leave(topic, ws) {
+      leaveRoom(state, ws, topic);
+    },
+    topics() {
+      return roomTopics(state);
+    },
+    joinGroup(id, group) {
+      const ws = state.clients.get(id);
+      if (ws) addToGroup(state, ws, group);
+    },
+    leaveGroup(id, group) {
+      const ws = state.clients.get(id);
+      if (ws) removeFromGroup(state, ws, group);
+    },
+    publishToGroup(group, name, payload) {
+      const frame = encodeToScratch(name, payload);
+      state.metrics.published++;
+      publishToGroupState(state, group, frame);
+      state.bridge?.publish(state.bridge.subjects.group(group, name), frame);
+    },
+    groups() {
+      return activeGroups(state);
+    },
+    groupMembers(group) {
+      return groupMemberIds(state, group);
+    },
+    clientGroups(id) {
+      const ws = state.clients.get(id);
+      return ws ? [...ws.data.groups] : [];
+    },
+    getClient(id) {
+      const ws = state.clients.get(id);
+      return ws ? toClientInfo(ws) : undefined;
+    },
+    getClients() {
+      return [...state.clients.values()].map(toClientInfo);
+    },
+    closeClient(ws) {
+      ws.close(1000, "closed by server");
+    },
+    disconnectClient(id) {
+      const ws = state.clients.get(id);
+      if (!ws) return false;
+      ws.close(1000, "closed by server");
+      return true;
+    },
+    on(name, handler) {
+      state.inboundHandlers.set(name, handler as (payload: unknown, ws: ServerWebSocket<WsData>) => void);
+      return api;
+    },
+    off(name) {
+      state.inboundHandlers.delete(name);
+      return api;
+    },
+    async drain(timeoutMs = 2000): Promise<void> {
+      bun.stop(false); // stop listening; keep active sockets draining
+      await state.bridge?.close();
+      const deadline = Date.now() + timeoutMs;
+      while (state.sockets.size > 0 && Date.now() < deadline) {
+        await Bun.sleep(10);
+      }
+      bun.stop(true);
+    },
+    stop(force = true): void {
+      bun.stop(force);
+      void state.bridge?.close();
+    },
+  };
+
+  return api;
+}

package/src/core/state.ts

@@ -0,0 +1,179 @@
+/**
+ * Server state + public option types. `createServerState(options)` produces the
+ * single explicit state object that every server action function reads/mutates
+ * (functional composition — no class, no `this`).
+ *
+ * The option types (IgnServerOptions / IgnBackpressureOptions / WsData) are the
+ * PUBLIC surface and are re-exported by `public/server.ts`.
+ */
+import type { ServerWebSocket } from "bun";
+import type { EventName } from "../schema";
+import type { Int64GuardMode } from "./int64-guard";
+import { createMetrics, type Metrics } from "./metrics";
+import { RingBuffer } from "./ring";
+import type { NatsBridge, NatsBridgeOptions } from "../bridge/nats";
+
+/**
+ * Optional identity metadata a client may carry for targeting / grouping.
+ * Returned from the `authenticate` hook (or filled in programmatically).
+ */
+export interface ClientMeta {
+  /** explicit client id; omitted → auto-assigned `crypto.randomUUID()` */
+  id?: string;
+  /** server-side groups this client belongs to on connect */
+  groups?: string[];
+  /** arbitrary app metadata (exposed via `getClient` / `getClients`) */
+  meta?: Record<string, unknown>;
+}
+
+/** What `authenticate` may return: `true`/`false` (old behavior) or metadata. */
+export type AuthResult = boolean | ClientMeta;
+
+/** Per-socket metadata carried on the upgraded WebSocket (`ws.data`). */
+export interface WsData {
+  /** wire version the client announced in its hello (undefined until then) */
+  version?: number;
+  /** last sequence the client has seen (0 = none) — used for replay */
+  lastSeq: number;
+  /** topics this socket has joined (client-joinable rooms) */
+  topics: Set<string>;
+  /** server-side groups this socket belongs to (auth-seeded + programmatic) */
+  groups: Set<string>;
+  /** stable client id (auth metadata or auto-generated UUID) */
+  id: string;
+  /** arbitrary app metadata from `authenticate` (undefined if none) */
+  meta?: Record<string, unknown>;
+  /** epoch ms when the socket opened (for `getClients` ordering/uptime) */
+  connectedAt: number;
+  /** drop-oldest backpressure queue (only non-empty while the socket is saturated) */
+  queue?: RingBuffer<Uint8Array>;
+}
+
+/** Slow-consumer policy (see `IgnBackpressureOptions`). */
+export type BackpressurePolicy = "drop-oldest" | "drop-newest" | "disconnect";
+
+export interface IgnBackpressureOptions {
+  /** per-socket buffered bytes that trigger backpressure, default 1 MiB */
+  highWaterMark?: number;
+  /** what to do with a slow consumer, default "drop-oldest" */
+  policy?: BackpressurePolicy;
+  /** max queued frames per slow socket (drop-oldest only), default 256 */
+  maxQueue?: number;
+}
+
+export interface IgnServerOptions {
+  port: number;
+  hostname?: string;
+  /** seconds; 0 = no timeout */
+  idleTimeout?: number;
+  /** websocket path, default "/ws" */
+  path?: string;
+  /** app events clients are ALLOWED to send; control events are always allowed. default [] */
+  inbound?: EventName[];
+  /** slow-consumer protection. default: off (unbounded buffering) */
+  backpressure?: IgnBackpressureOptions;
+  /**
+   * Per-topic history for last-value snapshots on subscribe (and reconnect
+   * replay). When set, every `publishToTopic` records an owned copy of the
+   * frame (bounded to `historySize`), and a socket that joins the topic
+   * immediately receives the recorded frames (oldest → newest) before live
+   * traffic. Off by default to keep the hot path allocation-free.
+   */
+  replay?: { historySize?: number };
+  /**
+   * Async auth hook run BEFORE the WebSocket upgrade. Return `false` to reject
+   * the connection (401). Return `true` to allow it (client gets an auto-
+   * generated id), or a `ClientMeta` object to pin the client id / seed its
+   * server-side groups / attach metadata. Inspect `req` as needed.
+   */
+  authenticate?: (req: Request) => boolean | ClientMeta | Promise<boolean | ClientMeta>;
+  /** if set, only these exact `Origin` header values may connect (403 otherwise) */
+  allowedOrigins?: string[];
+  /**
+   * Optional built-in bearer-token auth: either a literal token, or a
+   * predicate `(token) => boolean` checking the `Authorization: Bearer` header.
+   */
+  token?: string | ((token: string) => boolean);
+  /** maximum concurrent WebSocket clients (reject with 503 beyond) */
+  maxConnections?: number;
+  /** maximum inbound frame size in bytes (close 1009 beyond) */
+  maxMessageSize?: number;
+  /**
+   * Lossless-int64 guard for plain `number` int64 fields: values outside the
+   * safe-integer range (±2^53-1) throw / warn at encode time (default "off" —
+   * no overhead; the exact fix is `Type.Integer({ bigint: true })` fields).
+   */
+  int64Guard?: Int64GuardMode;
+  /** Bun.serve TLS options (keyFile/certFile) — enables `wss://` */
+  tls?: Bun.ServeOptions<unknown>["tls"];
+  /**
+   * Optional NATS bridge — either `NatsBridgeOptions` (a built-in bridge is
+   * created eagerly and connects in the background) or a pre-built
+   * `NatsBridge` (e.g. `createNatsBridge(opts, transport)` with a custom /
+   * fake transport — handy for tests). Every broadcast / topic / group
+   * publish is ALSO published (as the same FlatBuffer wire frame) to a NATS
+   * subject for other applications, and (when `inbound` is set) NATS subjects
+   * are forwarded to clients. Best-effort: the WS hot path never blocks on
+   * NATS.
+   */
+  nats?: NatsBridgeOptions | NatsBridge;
+  /** additional HTTP handler for non-ws routes (e.g. serving a static demo page) */
+  fetch?: (req: Request) => Response | Promise<Response>;
+}
+
+type InboundHandler = (payload: unknown, ws: ServerWebSocket<WsData>) => void;
+
+/** The full, explicit server state — created once per server, passed to actions. */
+export interface ServerState {
+  path: string;
+  inbound: ReadonlySet<EventName>;
+  bp: Required<IgnBackpressureOptions> | null;
+  metrics: Metrics;
+  startedAt: number;
+  authenticate?: (req: Request) => boolean | ClientMeta | Promise<boolean | ClientMeta>;
+  allowedOrigins?: string[];
+  token?: string | ((token: string) => boolean);
+  maxConnections?: number;
+  maxMessageSize?: number;
+  replay: { historySize: number } | null;
+  sockets: Set<ServerWebSocket<WsData>>;
+  /** id → live socket (client registry for targeted sends / introspection) */
+  clients: Map<string, ServerWebSocket<WsData>>;
+  rooms: Map<string, Set<ServerWebSocket<WsData>>>;
+  /** group → member sockets (server-side targeting dimension, no replay) */
+  groups: Map<string, Set<ServerWebSocket<WsData>>>;
+  /** optional NATS bridge (wired in createServer when `options.nats` is set) */
+  bridge?: NatsBridge;
+  inboundHandlers: Map<EventName, InboundHandler>;
+  topicHistory: Map<string, RingBuffer<{ seq: number; frame: Uint8Array }>>;
+  replaySeq: number;
+}
+
+export function createServerState(options: IgnServerOptions): ServerState {
+  return {
+    path: options.path ?? "/ws",
+    inbound: new Set(options.inbound ?? []),
+    bp: options.backpressure
+      ? {
+          highWaterMark: options.backpressure.highWaterMark ?? 1024 * 1024,
+          policy: options.backpressure.policy ?? "drop-oldest",
+          maxQueue: options.backpressure.maxQueue ?? 256,
+        }
+      : null,
+    metrics: createMetrics(),
+    startedAt: Date.now(),
+    authenticate: options.authenticate,
+    allowedOrigins: options.allowedOrigins,
+    token: options.token,
+    maxConnections: options.maxConnections,
+    maxMessageSize: options.maxMessageSize,
+    replay: options.replay ? { historySize: options.replay.historySize ?? 64 } : null,
+    sockets: new Set(),
+    clients: new Map(),
+    rooms: new Map(),
+    groups: new Map(),
+    inboundHandlers: new Map(),
+    topicHistory: new Map(),
+    replaySeq: 0,
+  };
+}