@ignex/nova 0.1.1

package/src/core/client.ts

@@ -0,0 +1,176 @@
+/**
+ * Client composition root — wires client-state + wire / reconnect / heartbeat
+ * into the public `IgnClient` API object (no class, no `this`). This is the
+ * ONLY place that knows how the pieces fit together; `connect` lives here
+ * because it owns the socket lifecycle.
+ *
+ * Public entry: `public/client.ts` re-exports `createClient` + the types.
+ */
+import { WIRE_VERSION } from "../generated/registry";
+import { encodeEventFrame } from "../generated/ts-ser";
+import type { Events, EventName } from "../schema";
+import { createClientState, setStatus, type ClientState, type ClientStatus, type IgnClientOptions } from "./client-state";
+import { handleMessage, sendControl, sendFrame } from "./client-wire";
+import { startHeartbeat, stopHeartbeat } from "./client-heartbeat";
+import { scheduleReconnect } from "./client-reconnect";
+
+/** The public client API (returned by `createClient`). */
+export interface IgnClient {
+  on<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
+  off<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
+  /** Register a handler that fires once for the event, then removes itself. */
+  once<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
+  /** Register a handler for EVERY incoming app event (name + payload). */
+  onAny(cb: (name: EventName, payload: unknown) => void): IgnClient;
+  offAny(cb: (name: EventName, payload: unknown) => void): IgnClient;
+  /** Names that currently have at least one handler. */
+  events(): EventName[];
+  /** Remove all handlers (optionally just for one event). */
+  removeAllListeners(name?: EventName): IgnClient;
+  /** Register an error callback (decode failures, wire-version mismatch). */
+  onError(cb: (err: Error) => void): IgnClient;
+  offError(cb: (err: Error) => void): IgnClient;
+  /** Watch connection lifecycle: "connecting" | "connected" | "disconnected" | "reconnecting" | "closed". */
+  onStatus(cb: (status: ClientStatus) => void): IgnClient;
+  offStatus(cb: (status: ClientStatus) => void): IgnClient;
+  readonly currentStatus: ClientStatus;
+  connect(): IgnClient;
+  close(): void;
+  /** Send a typed app event to the server (server must allow it via `inbound`). */
+  send<K extends EventName>(name: K, payload: Events[K]): void;
+  /** Ask the server to subscribe this socket to a topic (room membership + replay). */
+  subscribe(topic: string): void;
+  unsubscribe(topic: string): void;
+  /** Ask the server to add this socket to a server-side group. */
+  joinGroup(group: string): void;
+  leaveGroup(group: string): void;
+  /** The id the server assigned this connection ("" until `welcome` arrives). */
+  readonly clientId: string;
+  /** Server-side groups this client belongs to ([] until `welcome` arrives). */
+  readonly groups: string[];
+}
+
+export function createClient(url: string, opts: IgnClientOptions = {}): IgnClient {
+  const state: ClientState = createClientState(url, opts);
+
+  function connect(): IgnClient {
+    state.closed = false;
+    setStatus(state, state.attempts === 0 ? "connecting" : "reconnecting");
+    const ws = new WebSocket(url);
+    ws.binaryType = "arraybuffer";
+    ws.onopen = () => {
+      state.attempts = 0;
+      setStatus(state, "connected");
+      sendControl(state, "hello", { version: WIRE_VERSION, caps: [], lastSeq: 0 });
+      // re-subscribe topics from before the disconnect (server cleared them)
+      for (const t of state.subscribedTopics) sendControl(state, "subscribe", { topic: t });
+      startHeartbeat(state);
+    };
+    ws.onmessage = (ev) => handleMessage(state, ev.data as ArrayBuffer | string);
+    ws.onclose = () => {
+      stopHeartbeat(state);
+      state.ws = null;
+      if (state.closed) {
+        setStatus(state, "closed");
+        return;
+      }
+      scheduleReconnect(state, connect);
+    };
+    state.ws = ws;
+    return api;
+  }
+
+  const api: IgnClient = {
+    on(name, handler) {
+      let set = state.handlers.get(name);
+      if (!set) {
+        set = new Set();
+        state.handlers.set(name, set);
+      }
+      set.add(handler as never);
+      return api;
+    },
+    off(name, handler) {
+      state.handlers.get(name)?.delete(handler as never);
+      return api;
+    },
+    once(name, handler) {
+      const wrap = (payload: never): void => {
+        api.off(name, wrap as never);
+        handler(payload);
+      };
+      api.on(name, wrap as never);
+      return api;
+    },
+    onAny(cb) {
+      state.anyHandlers.add(cb);
+      return api;
+    },
+    offAny(cb) {
+      state.anyHandlers.delete(cb);
+      return api;
+    },
+    events() {
+      return [...state.handlers.keys()];
+    },
+    removeAllListeners(name) {
+      if (name) state.handlers.delete(name);
+      else state.handlers.clear();
+      return api;
+    },
+    onError(cb) {
+      state.errorCbs.add(cb);
+      return api;
+    },
+    offError(cb) {
+      state.errorCbs.delete(cb);
+      return api;
+    },
+    onStatus(cb) {
+      state.statusCbs.add(cb);
+      return api;
+    },
+    offStatus(cb) {
+      state.statusCbs.delete(cb);
+      return api;
+    },
+    get currentStatus(): ClientStatus {
+      return state.status;
+    },
+    connect,
+    close() {
+      state.closed = true;
+      stopHeartbeat(state);
+      if (state.reconnectTimer) clearTimeout(state.reconnectTimer);
+      state.reconnectTimer = null;
+      state.ws?.close();
+      state.ws = null;
+      setStatus(state, "closed");
+    },
+    send(name, payload) {
+      sendFrame(state, encodeEventFrame(name, payload));
+    },
+    subscribe(topic) {
+      state.subscribedTopics.add(topic);
+      sendControl(state, "subscribe", { topic });
+    },
+    unsubscribe(topic) {
+      state.subscribedTopics.delete(topic);
+      sendControl(state, "unsubscribe", { topic });
+    },
+    joinGroup(group) {
+      sendControl(state, "joinGroup", { group });
+    },
+    leaveGroup(group) {
+      sendControl(state, "leaveGroup", { group });
+    },
+    get clientId(): string {
+      return state.clientId;
+    },
+    get groups(): string[] {
+      return state.groups;
+    },
+  };
+
+  return api;
+}

package/src/core/groups.ts

@@ -0,0 +1,52 @@
+/**
+ * Group membership + fan-out — a server-side targeting dimension (complements
+ * rooms: rooms are client-joinable with optional replay; groups are for
+ * server-side targeting, NO replay). Pure set operations over `state.groups`.
+ *
+ * A socket's groups live in `ws.data.groups`; `state.groups` is the reverse
+ * group → member-sockets index. Groups can be seeded from `authenticate`
+ * metadata, joined programmatically via `joinGroup`, or joined by the client
+ * via the `joinGroup` / `leaveGroup` control frames (routed in `routing.ts`).
+ */
+import type { ServerWebSocket } from "bun";
+import { sendFrame } from "./outbound";
+import type { ServerState, WsData } from "./state";
+
+/** Add `ws` to `group` (idempotent) and index it in `state.groups`. */
+export function joinGroup(state: ServerState, ws: ServerWebSocket<WsData>, group: string): void {
+  ws.data.groups.add(group);
+  let set = state.groups.get(group);
+  if (!set) {
+    set = new Set();
+    state.groups.set(group, set);
+  }
+  set.add(ws);
+}
+
+/** Remove `ws` from `group`; prune the group when it becomes empty. */
+export function leaveGroup(state: ServerState, ws: ServerWebSocket<WsData>, group: string): void {
+  ws.data.groups.delete(group);
+  const set = state.groups.get(group);
+  if (!set) return;
+  set.delete(ws);
+  if (set.size === 0) state.groups.delete(group);
+}
+
+/** Fan `frame` out to every member of `group` (no replay). */
+export function publishToGroup(state: ServerState, group: string, frame: Uint8Array): void {
+  const set = state.groups.get(group);
+  if (!set) return;
+  for (const ws of set) sendFrame(state, ws, frame);
+}
+
+/** Live group names (with at least one member). */
+export function activeGroups(state: ServerState): string[] {
+  return [...state.groups.keys()];
+}
+
+/** Client ids that are currently members of `group`. */
+export function groupMembers(state: ServerState, group: string): string[] {
+  const set = state.groups.get(group);
+  if (!set) return [];
+  return [...set].map((ws) => ws.data.id);
+}

package/src/core/int64-guard.ts

@@ -0,0 +1,44 @@
+/**
+ * Lossless-int64 guard. Plain `number` int64 fields silently lose precision
+ * above ±2^53-1 (the value is coerced through a double). The real fix is
+ * `Type.Integer({ bigint: true })` (exact `bigint` fields); this module is the
+ * safety net that catches out-of-range NUMBERS at encode time.
+ *
+ * The generated direct encoders call `checkInt64` for every non-bigint int64
+ * field. Mode is configurable (server option `int64Guard`); when `"off"` (the
+ * default) the check is a cheap no-op so the zero-alloc hot path is untouched.
+ */
+export type Int64GuardMode = "off" | "throw" | "warn";
+
+let mode: Int64GuardMode = "off";
+const warned = new Set<string>();
+
+export function setInt64GuardMode(m: Int64GuardMode): void {
+  mode = m;
+}
+
+export function getInt64GuardMode(): Int64GuardMode {
+  return mode;
+}
+
+/**
+ * Assert `v` (a plain-number int64 field) is a safe integer. No-op in "off"
+ * mode. `label` is `"<event>.<field>"` for diagnostics.
+ */
+export function checkInt64(label: string, v: unknown): void {
+  if (mode === "off") return;
+  if (typeof v === "bigint") return; // already exact
+  const n = v as number;
+  if (Number.isSafeInteger(n)) return;
+  if (mode === "throw") {
+    throw new RangeError(
+      `ignex: int64 field "${label}" value ${n} is outside the safe-integer range (±2^53-1) and would lose precision — annotate it with Type.Integer({ bigint: true })`,
+    );
+  }
+  if (!warned.has(label)) {
+    warned.add(label);
+    console.warn(
+      `ignex: int64 field "${label}" value ${n} is outside the safe-integer range (±2^53-1) and will lose precision — annotate it with Type.Integer({ bigint: true })`,
+    );
+  }
+}

package/src/core/metrics.ts

@@ -0,0 +1,105 @@
+/**
+ * Server-side metrics counters — a `createMetrics()` factory returning a plain
+ * counter object (no class, no `this`). Zero dependencies, no allocations in
+ * the steady state (counters are plain numbers; `countPath` only allocates on
+ * the first occurrence of an event name).
+ */
+export interface PathCounts {
+  /** encodes that used the zero-alloc Rust FFI direct fast path */
+  direct: number;
+  /** encodes that fell back to the JSON path (nested/unions or disabled symbol) */
+  json: number;
+}
+
+export interface MetricsSnapshot {
+  /** encode calls (publish / publishTo / publishToTopic) */
+  published: number;
+  /** frames actually handed to a socket */
+  sent: number;
+  /** frames skipped because the socket was over its high-water mark (drop-newest) */
+  droppedNewest: number;
+  /** frames dropped from a slow socket's bounded queue (drop-oldest) */
+  droppedOldest: number;
+  /** slow consumers closed by the disconnect policy */
+  disconnectedSlow: number;
+  /** inbound app messages delivered to server.on() handlers */
+  inbound: number;
+  /** inbound control frames routed internally */
+  inboundControl: number;
+  /** undecodable / version-mismatched / unknown-id frames received */
+  protocolErrors: number;
+  bytesSent: number;
+  /** per-event encode path counts (direct vs json) */
+  pathCounts: Record<string, PathCounts>;
+  connectedClients: number;
+  uptimeMs: number;
+  /** NATS bridge counters (present only when a bridge is configured) */
+  bridged?: number;
+  bridgedBytes?: number;
+  bridgeErrors?: number;
+  bridgeInbound?: number;
+  bridgeInboundErrors?: number;
+  /** "connected" | "connecting" | "closed" (undefined when no bridge) */
+  natsStatus?: string;
+}
+
+export interface Metrics {
+  published: number;
+  sent: number;
+  droppedNewest: number;
+  droppedOldest: number;
+  disconnectedSlow: number;
+  inbound: number;
+  inboundControl: number;
+  protocolErrors: number;
+  bytesSent: number;
+  readonly pathCounts: Map<string, PathCounts>;
+  /** Count an encode on a given path for an event (direct = zero-alloc FFI). */
+  countPath(name: string, path: "direct" | "json"): void;
+  snapshot(connectedClients: number): MetricsSnapshot;
+}
+
+export function createMetrics(startedAt = Date.now()): Metrics {
+  const pathCounts = new Map<string, PathCounts>();
+
+  const m: Metrics = {
+    published: 0,
+    sent: 0,
+    droppedNewest: 0,
+    droppedOldest: 0,
+    disconnectedSlow: 0,
+    inbound: 0,
+    inboundControl: 0,
+    protocolErrors: 0,
+    bytesSent: 0,
+    pathCounts,
+    countPath(name, path) {
+      let pc = pathCounts.get(name);
+      if (!pc) {
+        pc = { direct: 0, json: 0 };
+        pathCounts.set(name, pc);
+      }
+      pc[path]++;
+    },
+    snapshot(connectedClients) {
+      const pathCountsObj: Record<string, PathCounts> = {};
+      for (const [name, pc] of pathCounts) pathCountsObj[name] = { ...pc };
+      return {
+        published: m.published,
+        sent: m.sent,
+        droppedNewest: m.droppedNewest,
+        droppedOldest: m.droppedOldest,
+        disconnectedSlow: m.disconnectedSlow,
+        inbound: m.inbound,
+        inboundControl: m.inboundControl,
+        protocolErrors: m.protocolErrors,
+        bytesSent: m.bytesSent,
+        pathCounts: pathCountsObj,
+        connectedClients,
+        uptimeMs: Date.now() - startedAt,
+      };
+    },
+  };
+
+  return m;
+}

package/src/core/outbound.ts

@@ -0,0 +1,76 @@
+/**
+ * Outbound write path — the ONLY place that talks to `ws.send` and mutates the
+ * per-socket backpressure queue / send counters. `sendFrame` executes the pure
+ * `decide()` result; `doSend` is the single accounting point.
+ */
+import type { ServerWebSocket } from "bun";
+import { encodeToScratch } from "../transport/transport";
+import { decide } from "./backpressure";
+import { RingBuffer } from "./ring";
+import type { ServerState, WsData } from "./state";
+import type { ControlEventName, ControlEvents } from "../schema";
+
+/** Actual socket write + counters (single accounting point). */
+export function doSend(state: ServerState, ws: ServerWebSocket<WsData>, frame: Uint8Array): void {
+  ws.send(frame);
+  state.metrics.sent++;
+  state.metrics.bytesSent += frame.byteLength;
+}
+
+/**
+ * Send one frame to a socket, honoring the configured backpressure policy.
+ * Happy path (no backpressure configured, or socket under the high-water mark)
+ * is a direct `ws.send` — zero allocations. Under pressure, `ws.send` is
+ * replaced by a bounded queue (drop-oldest) / skip (drop-newest) / close
+ * (disconnect).
+ */
+export function sendFrame(state: ServerState, ws: ServerWebSocket<WsData>, frame: Uint8Array): void {
+  const bp = state.bp;
+  if (!bp) {
+    doSend(state, ws, frame);
+    return;
+  }
+  const d = decide(bp, ws);
+  switch (d.kind) {
+    case "send":
+      doSend(state, ws, frame);
+      return;
+    case "close":
+      state.metrics.disconnectedSlow++;
+      ws.close(1013, "slow consumer");
+      return;
+    case "drop-newest":
+      state.metrics.droppedNewest++;
+      return;
+    case "enqueue": {
+      // RingBuffer: O(1) push + drop-from-head (no array shift() memmove).
+      const q = (ws.data.queue ??= new RingBuffer<Uint8Array>());
+      q.push(frame.slice()); // owned copy for the queue
+      for (let i = 0; i < d.dropHead; i++) {
+        q.shift();
+        state.metrics.droppedOldest++;
+      }
+      return;
+    }
+  }
+}
+
+/** Flush a slow socket's drop-oldest queue as the OS buffers drain. */
+export function drainSocket(state: ServerState, ws: ServerWebSocket<WsData>): void {
+  const q = ws.data.queue;
+  if (!q || q.length === 0 || !state.bp) return;
+  while (q.length > 0) {
+    if (ws.getBufferedAmount() > state.bp.highWaterMark) break; // still backed up
+    doSend(state, ws, q.shift()!);
+  }
+}
+
+/** Send a control frame (hello / subscribe / ping / ...) through the same outbound path. */
+export function sendControl<K extends ControlEventName>(
+  state: ServerState,
+  ws: ServerWebSocket<WsData>,
+  name: K,
+  payload: ControlEvents[K],
+): void {
+  sendFrame(state, ws, encodeToScratch(name, payload));
+}

package/src/core/replay.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-topic replay history (last-value snapshots on subscribe / reconnect).
+ * Pure data operations on `state.topicHistory` — no socket writes here
+ * (`rooms.joinRoom` reads the recorded frames via `replayFrames`).
+ *
+ * History is a bounded `RingBuffer` (capacity = historySize): recording is O(1)
+ * and, once full, the OLDEST frame is overwritten automatically — same
+ * semantics as the old `push` + `shift`, but without the O(n) array shift.
+ */
+import { RingBuffer } from "./ring";
+import type { ServerState } from "./state";
+
+/** Record an owned copy of `frame` for `topic`, bounded to historySize. */
+export function recordReplay(state: ServerState, topic: string, frame: Uint8Array): void {
+  if (!state.replay) return;
+  let hist = state.topicHistory.get(topic);
+  if (!hist) {
+    hist = new RingBuffer<{ seq: number; frame: Uint8Array }>(state.replay.historySize, true);
+    state.topicHistory.set(topic, hist);
+  }
+  hist.push({ seq: ++state.replaySeq, frame: frame.slice() }); // owned copy for replay
+}
+
+/** The recorded frames for `topic`, oldest → newest (already owned copies). */
+export function replayFrames(state: ServerState, topic: string): Uint8Array[] {
+  const hist = state.topicHistory.get(topic);
+  if (!hist || hist.length === 0) return [];
+  const out: Uint8Array[] = [];
+  for (const e of hist) out.push(e.frame);
+  return out;
+}

package/src/core/ring.ts

@@ -0,0 +1,85 @@
+/**
+ * `RingBuffer<T>` — a fixed/auto-growing FIFO ring buffer with O(1) `push`
+ * and `shift` (no array `shift()` memmove). Used by the drop-oldest
+ * backpressure queue (`outbound.ts`) and the bounded replay history
+ * (`replay.ts`), both of which previously used `Array.prototype.push` +
+ * `shift` and were O(n) per operation while saturated.
+ *
+ * Two modes:
+ *   - `bounded: true`  — capacity is fixed at construction; once full, `push`
+ *     OVERWRITES the oldest element (drop-oldest). Ideal for "keep the last N".
+ *   - `bounded: false` (default) — capacity doubles on demand (FIFO queue).
+ *
+ * Iteration walks oldest → newest without consuming.
+ */
+export class RingBuffer<T> {
+  private buf: (T | undefined)[];
+  private head = 0; // index of the oldest element
+  private len = 0;
+  private readonly bounded: boolean;
+
+  constructor(capacity = 16, bounded = false) {
+    this.buf = Array.from({ length: Math.max(1, capacity) }, () => undefined as T | undefined);
+    this.bounded = bounded;
+  }
+
+  /** Number of elements currently held. */
+  get length(): number {
+    return this.len;
+  }
+
+  /** Current backing capacity (grows on demand when unbounded). */
+  get capacity(): number {
+    return this.buf.length;
+  }
+
+  /**
+   * Append `v`. When `bounded` and full, the OLDEST element is overwritten
+   * (drop-oldest); otherwise the backing array grows.
+   */
+  push(v: T): void {
+    if (this.len === this.buf.length) {
+      if (this.bounded) {
+        // overwrite the oldest slot, then treat it as the new tail
+        this.buf[this.head] = v;
+        this.head = (this.head + 1) % this.buf.length;
+        return;
+      }
+      this.grow();
+    }
+    this.buf[(this.head + this.len) % this.buf.length] = v;
+    this.len++;
+  }
+
+  /** Remove + return the oldest element, or `undefined` when empty. */
+  shift(): T | undefined {
+    if (this.len === 0) return undefined;
+    const v = this.buf[this.head];
+    this.buf[this.head] = undefined;
+    this.head = (this.head + 1) % this.buf.length;
+    this.len--;
+    return v;
+  }
+
+  /** Iterate oldest → newest (non-consuming). */
+  *[Symbol.iterator](): Iterator<T> {
+    for (let i = 0; i < this.len; i++) {
+      yield this.buf[(this.head + i) % this.buf.length] as T;
+    }
+  }
+
+  clear(): void {
+    this.buf.fill(undefined);
+    this.head = 0;
+    this.len = 0;
+  }
+
+  private grow(): void {
+    const next = Array.from({ length: this.buf.length * 2 }, () => undefined as T | undefined);
+    for (let i = 0; i < this.len; i++) {
+      next[i] = this.buf[(this.head + i) % this.buf.length];
+    }
+    this.buf = next;
+    this.head = 0;
+  }
+}

package/src/core/rooms.ts

@@ -0,0 +1,44 @@
+/**
+ * Room (topic) membership + fan-out. Pure set operations over `state.rooms`,
+ * wired to replay (`joinRoom` sends recorded history) and the outbound path
+ * (`publishToRoom` fans a frame out to every member).
+ */
+import type { ServerWebSocket } from "bun";
+import { doSend, sendFrame } from "./outbound";
+import { recordReplay, replayFrames } from "./replay";
+import type { ServerState, WsData } from "./state";
+
+/** Join `ws` to `topic`, replaying any recorded history (oldest → newest). */
+export function joinRoom(state: ServerState, ws: ServerWebSocket<WsData>, topic: string): void {
+  ws.data.topics.add(topic);
+  let set = state.rooms.get(topic);
+  if (!set) {
+    set = new Set();
+    state.rooms.set(topic, set);
+  }
+  set.add(ws);
+  // replay uses a direct send (not backpressure-gated) — matches the original
+  for (const frame of replayFrames(state, topic)) doSend(state, ws, frame);
+}
+
+/** Leave `topic`; prune the room when it becomes empty. */
+export function leaveRoom(state: ServerState, ws: ServerWebSocket<WsData>, topic: string): void {
+  ws.data.topics.delete(topic);
+  const set = state.rooms.get(topic);
+  if (!set) return;
+  set.delete(ws);
+  if (set.size === 0) state.rooms.delete(topic);
+}
+
+/** Live topic names (with at least one subscriber). */
+export function roomTopics(state: ServerState): string[] {
+  return [...state.rooms.keys()];
+}
+
+/** Record replay (if enabled) then deliver `frame` to every room member. */
+export function publishToRoom(state: ServerState, topic: string, frame: Uint8Array): void {
+  recordReplay(state, topic, frame);
+  const set = state.rooms.get(topic);
+  if (!set) return;
+  for (const ws of set) sendFrame(state, ws, frame);
+}