@ignex/nova 0.1.1 → 0.1.5

package/src/core/state.ts

@@ -7,11 +7,15 @@
  * PUBLIC surface and are re-exported by `public/server.ts`.
  */
 import type { ServerWebSocket } from "bun";
-import type { EventName } from "../schema";
+import { defaultBindings } from "../bindings/default";
+import type { Bindings, DefaultBindings, EventNameOf } from "../bindings/types";
+import type { NatsBridge, NatsBridgeOptions } from "../bridge/nats";
+import { createEventTrace, type EventTrace, type EventTraceOptions } from "../events/trace";
+import { createTransport, defaultTransport, type Transport } from "../transport/transport";
 import type { Int64GuardMode } from "./int64-guard";
 import { createMetrics, type Metrics } from "./metrics";
-import { RingBuffer } from "./ring";
-import type { NatsBridge, NatsBridgeOptions } from "../bridge/nats";
+import { resolveRateLimit, type RateLimitOptions, type ResolvedRateLimit } from "./rate-limit";
+import type { RingBuffer } from "./ring";
 
 /**
  * Optional identity metadata a client may carry for targeting / grouping.
@@ -20,6 +24,12 @@ import type { NatsBridge, NatsBridgeOptions } from "../bridge/nats";
 export interface ClientMeta {
   /** explicit client id; omitted → auto-assigned `crypto.randomUUID()` */
   id?: string;
+  /**
+   * The identity this connection acts ON BEHALF OF (e.g. the logged-in user).
+   * Several connections may share a `userId` (multi-tab / multi-device) — the
+   * events layer groups them for user-targeted emits (`hub.emitToUser`).
+   */
+  userId?: string;
   /** server-side groups this client belongs to on connect */
   groups?: string[];
   /** arbitrary app metadata (exposed via `getClient` / `getClients`) */
@@ -41,12 +51,23 @@ export interface WsData {
   groups: Set<string>;
   /** stable client id (auth metadata or auto-generated UUID) */
   id: string;
+  /** identity this connection acts on behalf of (undefined = anonymous) */
+  userId?: 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>;
+  /** per-connection inbound rate limiter (lazily created on first frame) */
+  rate?: import("./rate-limit").RateLimiter;
+  /**
+   * Next per-connection delivery seq to stamp (envelope v2). Starts at 1;
+   * continues a previous session's stream when a grave is adopted.
+   */
+  sendSeq: number;
+  /** bounded sent-frame history for gap recovery (lazily created, resume only) */
+  history?: import("./ring").RingBuffer<import("./resume").SentFrame>;
 }
 
 /** Slow-consumer policy (see `IgnBackpressureOptions`). */
@@ -61,15 +82,22 @@ export interface IgnBackpressureOptions {
   maxQueue?: number;
 }
 
-export interface IgnServerOptions {
+export interface IgnServerOptions<B extends Bindings = DefaultBindings> {
   port: number;
   hostname?: string;
   /** seconds; 0 = no timeout */
   idleTimeout?: number;
   /** websocket path, default "/ws" */
   path?: string;
+  /**
+   * The wire stack (event ids, decoders, encoders). Defaults to the built-in
+   * registry; pass your own (from `generateBindings` + `assembleBindings`) to
+   * serve YOUR schema. When provided, the server API (`publish` / `on` / ...)
+   * is typed against your `Events`.
+   */
+  bindings?: B;
   /** app events clients are ALLOWED to send; control events are always allowed. default [] */
-  inbound?: EventName[];
+  inbound?: EventNameOf<B>[];
   /** slow-consumer protection. default: off (unbounded buffering) */
   backpressure?: IgnBackpressureOptions;
   /**
@@ -80,9 +108,23 @@ export interface IgnServerOptions {
    * traffic. Off by default to keep the hot path allocation-free.
    */
   replay?: { historySize?: number };
+  /**
+   * Gap-free delivery (envelope v2 seq + resume). When set, every frame sent
+   * to a socket carries a per-connection delivery seq, the connection keeps a
+   * bounded sent-history ring, and closed sessions park that ring in a
+   * per-client-id graveyard so reconnects can resume missed frames.
+   */
+  resume?: { historySize?: number; ttlMs?: number };
+  /**
+   * Durable topic log behind the replay ring (`src/core/topic-log.ts`). When
+   * set, every recorded topic frame is appended and `snapshotRequest`s older
+   * than the ring hydrate from the log. Default: none (ring-only).
+   */
+  topicLog?: import("./topic-log").TopicLog;
   /**
    * Async auth hook run BEFORE the WebSocket upgrade. Return `false` to reject
-   * the connection (401). Return `true` to allow it (client gets an auto-
+   * the connection (401) — a hook that throws (or rejects) denies it too.
+   * 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.
    */
@@ -98,6 +140,22 @@ export interface IgnServerOptions {
   maxConnections?: number;
   /** maximum inbound frame size in bytes (close 1009 beyond) */
   maxMessageSize?: number;
+  /**
+   * Per-connection inbound rate limiting (token bucket over ALL frames — app
+   * AND control). Default: off (zero hot-path overhead). Over-limit frames are
+   * dropped (default) or the socket is closed (`policy: "close"`, code 1008);
+   * either way the event is counted in `metrics.rateLimited`.
+   */
+  rateLimit?: RateLimitOptions;
+  /**
+   * Authorize a client's topic (room) join — enforced for EVERY join path:
+   * `subscribe` control frames, programmatic `server.join`, and auth-seeded
+   * topics. Return false to reject (the frame/ call is ignored and counted in
+   * `metrics.rejectedJoins`). Default: allow all.
+   */
+  authorizeTopic?: (topic: string, ws: ServerWebSocket<WsData>) => boolean;
+  /** Authorize a server-side group join (same contract as `authorizeTopic`). */
+  authorizeGroup?: (group: string, ws: ServerWebSocket<WsData>) => boolean;
   /**
    * Lossless-int64 guard for plain `number` int64 fields: values outside the
    * safe-integer range (±2^53-1) throw / warn at encode time (default "off" —
@@ -117,6 +175,20 @@ export interface IgnServerOptions {
    * NATS.
    */
   nats?: NatsBridgeOptions | NatsBridge;
+  /**
+   * Enable the events layer (typed event handlers + the global emit, client
+   * records with per-connection data, groups, optional cluster sync). Exposed
+   * as `server.events`; the module-global `emit`/`on` singleton
+   * (`ignex-nova/events`) is bound by default.
+   */
+  events?: import("../events/types").EventsOptions<B>;
+  /**
+   * Event trace ring — records every fired event (emitted / published /
+   * received) into a pre-allocated structure-of-arrays buffer so a debugger
+   * (ignex debugbar, MCP) can see what fired without any hot-path allocation.
+   * Default: on with capacity 1024; `IGNEX_NOVA_TRACE=0` disables globally.
+   */
+  trace?: EventTraceOptions;
   /** additional HTTP handler for non-ws routes (e.g. serving a static demo page) */
   fetch?: (req: Request) => Response | Promise<Response>;
 }
@@ -125,8 +197,12 @@ type InboundHandler = (payload: unknown, ws: ServerWebSocket<WsData>) => void;
 
 /** The full, explicit server state — created once per server, passed to actions. */
 export interface ServerState {
+  /** the wire stack this server speaks (ids / decoders / encoders). */
+  bindings: Bindings;
+  /** per-server encoder (scratch + FFI binding or pure-JS fallback). */
+  transport: Transport;
   path: string;
-  inbound: ReadonlySet<EventName>;
+  inbound: Set<string>;
   bp: Required<IgnBackpressureOptions> | null;
   metrics: Metrics;
   startedAt: number;
@@ -135,7 +211,11 @@ export interface ServerState {
   token?: string | ((token: string) => boolean);
   maxConnections?: number;
   maxMessageSize?: number;
+  rateLimit: ResolvedRateLimit | null;
+  authorizeTopic?: (topic: string, ws: ServerWebSocket<WsData>) => boolean;
+  authorizeGroup?: (group: string, ws: ServerWebSocket<WsData>) => boolean;
   replay: { historySize: number } | null;
+  resume: { historySize: number; ttlMs: number } | null;
   sockets: Set<ServerWebSocket<WsData>>;
   /** id → live socket (client registry for targeted sends / introspection) */
   clients: Map<string, ServerWebSocket<WsData>>;
@@ -144,13 +224,35 @@ export interface ServerState {
   groups: Map<string, Set<ServerWebSocket<WsData>>>;
   /** optional NATS bridge (wired in createServer when `options.nats` is set) */
   bridge?: NatsBridge;
-  inboundHandlers: Map<EventName, InboundHandler>;
+  inboundHandlers: Map<string, InboundHandler>;
   topicHistory: Map<string, RingBuffer<{ seq: number; frame: Uint8Array }>>;
   replaySeq: number;
+  /** optional durable topic log (wired in createServer when `options.topicLog` is set) */
+  topicLog?: import("./topic-log").TopicLog;
+  /**
+   * Responder registry for request/response (`rpcCall` control frames):
+   * inner event name → async responder. Registered via `server.handle` /
+   * `hub.onRequest`.
+   */
+  rpcHandlers: Map<string, (payload: unknown, ws: ServerWebSocket<WsData>) => Promise<unknown>>;
+  /** parked sent-history rings of closed sessions (cross-connection resume) */
+  graves: Map<string, { history: RingBuffer<import("./resume").SentFrame>; nextSeq: number; expiresAt: number }>;
+  /** events-layer lifecycle hooks (wired by createServer when `events` is set) */
+  onConnect?: (ws: ServerWebSocket<WsData>) => void;
+  onDisconnect?: (ws: ServerWebSocket<WsData>) => void;
+  /** fired on ANY group membership change (auth seed, control frames, programmatic) */
+  onGroupChange?: (group: string, ws: ServerWebSocket<WsData>, joined: boolean) => void;
+  /** event trace ring (debugger visibility; pre-allocated, zero-GC writes) */
+  trace: EventTrace;
 }
 
-export function createServerState(options: IgnServerOptions): ServerState {
+export function createServerState<B extends Bindings = DefaultBindings>(
+  options: IgnServerOptions<B>,
+): ServerState {
+  const bindings = options.bindings ?? defaultBindings;
   return {
+    bindings,
+    transport: bindings === defaultBindings ? defaultTransport : createTransport(bindings),
     path: options.path ?? "/ws",
     inbound: new Set(options.inbound ?? []),
     bp: options.backpressure
@@ -162,12 +264,17 @@ export function createServerState(options: IgnServerOptions): ServerState {
       : null,
     metrics: createMetrics(),
     startedAt: Date.now(),
-    authenticate: options.authenticate,
-    allowedOrigins: options.allowedOrigins,
-    token: options.token,
-    maxConnections: options.maxConnections,
-    maxMessageSize: options.maxMessageSize,
+    ...(options.authenticate !== undefined ? { authenticate: options.authenticate } : {}),
+    ...(options.allowedOrigins !== undefined ? { allowedOrigins: options.allowedOrigins } : {}),
+    ...(options.token !== undefined ? { token: options.token } : {}),
+    ...(options.maxConnections !== undefined ? { maxConnections: options.maxConnections } : {}),
+    ...(options.maxMessageSize !== undefined ? { maxMessageSize: options.maxMessageSize } : {}),
+    rateLimit: resolveRateLimit(options.rateLimit),
+    ...(options.authorizeTopic !== undefined ? { authorizeTopic: options.authorizeTopic } : {}),
+    ...(options.authorizeGroup !== undefined ? { authorizeGroup: options.authorizeGroup } : {}),
+    ...(options.topicLog !== undefined ? { topicLog: options.topicLog } : {}),
     replay: options.replay ? { historySize: options.replay.historySize ?? 64 } : null,
+    resume: options.resume ? { historySize: options.resume.historySize ?? 256, ttlMs: options.resume.ttlMs ?? 60_000 } : null,
     sockets: new Set(),
     clients: new Map(),
     rooms: new Map(),
@@ -175,5 +282,8 @@ export function createServerState(options: IgnServerOptions): ServerState {
     inboundHandlers: new Map(),
     topicHistory: new Map(),
     replaySeq: 0,
+    rpcHandlers: new Map(),
+    graves: new Map(),
+    trace: createEventTrace(options.trace),
   };
 }

package/src/core/topic-log.ts

@@ -0,0 +1,86 @@
+/**
+ * Durable topic-log seam — the pluggable backend behind the bounded replay
+ * ring. The ring keeps the LAST N frames per topic in memory; a {@link TopicLog}
+ * receives the same frames so subscribers can resume from points the ring has
+ * already forgotten.
+ *
+ * Contract (deliberately narrow):
+ *   - `append` is SYNCHRONOUS and must never throw onto the publish hot path —
+ *     implementations buffer internally and flush on their own schedule (the
+ *     memory impl appends to an array; a file impl would hand off to a writer;
+ *     a NATS JetStream / Redis Streams impl would enqueue a publish).
+ *   - `range(topic, afterSeq, limit?)` returns frames strictly AFTER `afterSeq`
+ *     oldest → newest, synchronously. Adapters over remote stores should
+ *     maintain a local read-through cache so this stays sync-friendly.
+ *   - `latestSeq(topic)` mirrors the server's replay-seq counter for the topic
+ *     (0 = unknown/empty).
+ *
+ * Ship-with implementation: {@link createMemoryTopicLog} — per-topic bounded
+ * array (drop-oldest), process-local durability (survives ring overflow, not a
+ * restart). Production adapters (JetStream / Redis Streams / filesystem)
+ * implement the same three methods — see docs/architecture.md ("Durability").
+ */
+import { RingBuffer } from "./ring";
+
+/** One durably-retained topic frame. */
+export interface LoggedFrame {
+  /** global replay seq (the same counter stamped into the topic history) */
+  seq: number;
+  frame: Uint8Array;
+}
+
+export interface TopicLog {
+  /** Record a frame for `topic` (fire-and-forget; never throws). */
+  append(topic: string, frame: Uint8Array, seq: number): void;
+  /** Frames strictly after `afterSeq`, oldest → newest (at most `limit`). */
+  range(topic: string, afterSeq: number, limit?: number): LoggedFrame[];
+  /** Highest seq retained for `topic` (0 = none). */
+  latestSeq(topic: string): number;
+  /** Release resources (flush buffers, close files/connections). */
+  close(): void;
+}
+
+export interface MemoryTopicLogOptions {
+  /** max frames retained PER TOPIC (drop-oldest beyond), default 10_000 */
+  maxPerTopic?: number;
+}
+
+/** Process-local durable log: survives ring overflow, not a restart. */
+export function createMemoryTopicLog(
+  opts: MemoryTopicLogOptions = {},
+): TopicLog {
+  const max = Math.max(1, opts.maxPerTopic ?? 10_000);
+  const topics = new Map<string, { frames: RingBuffer<LoggedFrame>; latest: number }>();
+  const ensure = (topic: string) => {
+    let t = topics.get(topic);
+    if (!t) {
+      t = { frames: new RingBuffer<LoggedFrame>(max, true), latest: 0 };
+      topics.set(topic, t);
+    }
+    return t;
+  };
+  return {
+    append(topic, frame, seq) {
+      const t = ensure(topic);
+      t.frames.push({ seq, frame: frame.slice() });
+      if (seq > t.latest) t.latest = seq;
+    },
+    range(topic, afterSeq, limit) {
+      const t = topics.get(topic);
+      if (!t) return [];
+      const out: LoggedFrame[] = [];
+      for (const e of t.frames) {
+        if (e.seq <= afterSeq) continue;
+        out.push(e);
+        if (limit !== undefined && out.length >= limit) break;
+      }
+      return out;
+    },
+    latestSeq(topic) {
+      return topics.get(topic)?.latest ?? 0;
+    },
+    close() {
+      topics.clear();
+    },
+  };
+}

package/src/events/clients.ts

@@ -0,0 +1,174 @@
+/**
+ * Client store — the live registry of active connections, "who is connected,
+ * on whose behalf, and what the app remembers about them".
+ *
+ * - `byId: Map<clientId, EventClient>` — one record per socket.
+ * - `byUser: Map<userId, Set<clientId>>` — the reverse "on what behalf" index,
+ *   so a user with several tabs/devices is one logical target.
+ * - Each record carries a per-connection `data` store (created on attach,
+ *   dropped on detach) — `hub.setClientData` / `client.data` read/write it.
+ *
+ * Pure local state: cross-instance presence / state sync lives in `cluster.ts`
+ * and is driven FROM this store via the `onAttach` / `onDetach` hooks (which
+ * the hub wires to offloaded queue work, keeping connect/disconnect O(1)).
+ */
+import type { ServerWebSocket } from "bun";
+import type { WsData } from "../core/state";
+import { createClientData } from "./data";
+import type { ClientData, EventClient } from "./types";
+
+/** Factory for a client record bound to a live socket. */
+export function createEventClient(
+  ws: ServerWebSocket<WsData>,
+): EventClient {
+  const client: MutableEventClient = {
+    get id(): string {
+      return ws.data.id;
+    },
+    // `userId` is the identity this connection acts on behalf of — read live
+    // from the socket data (single source of truth; `setUserId` writes there).
+    get userId(): string | undefined {
+      return ws.data.userId;
+    },
+    get meta(): Record<string, unknown> | undefined {
+      return ws.data.meta;
+    },
+    data: createClientData(),
+    get groups(): ReadonlySet<string> {
+      return ws.data.groups;
+    },
+    get topics(): ReadonlySet<string> {
+      return ws.data.topics;
+    },
+    get connectedAt(): number {
+      return ws.data.connectedAt;
+    },
+    get ip(): string {
+      return ws.remoteAddress;
+    },
+    // plain mutable property — the store flips it to true on detach
+    closed: false,
+    get ws(): ServerWebSocket<WsData> {
+      return ws;
+    },
+  };
+  return client;
+}
+
+/** The client record with readonly modifiers stripped (internal mutation). */
+export type MutableEventClient = {
+  -readonly [K in keyof EventClient]: EventClient[K];
+};
+
+export interface ClientStore {
+  readonly size: number;
+  attach(ws: ServerWebSocket<WsData>): EventClient;
+  detach(ws: ServerWebSocket<WsData>): EventClient | undefined;
+  get(id: string): EventClient | undefined;
+  all(): EventClient[];
+  byUser(userId: string): EventClient[];
+  /**
+   * Invoke `each` for every live socket of `userId`; returns the count.
+   * Allocation-free variant of {@link byUser} for emit hot paths.
+   */
+  forEachByUser(userId: string, each: (client: EventClient) => void): number;
+  setUserId(clientId: string, userId: string): boolean;
+  onAttach(cb: (client: EventClient) => void): void;
+  onDetach(cb: (client: EventClient) => void): void;
+}
+
+export function createClientStore(): ClientStore {
+  const byId = new Map<string, MutableEventClient>();
+  const byUser = new Map<string, Set<string>>();
+  const attachCbs: Array<(client: EventClient) => void> = [];
+  const detachCbs: Array<(client: EventClient) => void> = [];
+
+  const indexUser = (client: EventClient): void => {
+    const userId = client.userId;
+    if (!userId) return;
+    let set = byUser.get(userId);
+    if (!set) {
+      set = new Set();
+      byUser.set(userId, set);
+    }
+    set.add(client.id);
+  };
+
+  const unindexUser = (client: EventClient): void => {
+    const userId = client.userId;
+    if (!userId) return;
+    const set = byUser.get(userId);
+    if (!set) return;
+    set.delete(client.id);
+    if (set.size === 0) byUser.delete(userId);
+  };
+
+  return {
+    get size(): number {
+      return byId.size;
+    },
+    attach(ws) {
+      const existing = byId.get(ws.data.id);
+      if (existing) return existing;
+      const client = createEventClient(ws);
+      byId.set(client.id, client);
+      indexUser(client);
+      for (const cb of attachCbs) cb(client);
+      return client;
+    },
+    detach(ws) {
+      const client = byId.get(ws.data.id);
+      if (!client) return undefined;
+      byId.delete(client.id);
+      unindexUser(client);
+      client.closed = true;
+      for (const cb of detachCbs) cb(client);
+      return client;
+    },
+    get(id) {
+      return byId.get(id);
+    },
+    all() {
+      return [...byId.values()];
+    },
+    byUser(userId) {
+      const ids = byUser.get(userId);
+      if (!ids) return [];
+      const out: EventClient[] = [];
+      for (const id of ids) {
+        const c = byId.get(id);
+        if (c) out.push(c);
+      }
+      return out;
+    },
+    forEachByUser(userId, each) {
+      const ids = byUser.get(userId);
+      if (ids === undefined || ids.size === 0) return 0;
+      let n = 0;
+      for (const id of ids) {
+        const c = byId.get(id);
+        if (c !== undefined) {
+          each(c);
+          n++;
+        }
+      }
+      return n;
+    },
+    setUserId(clientId, userId) {
+      const client = byId.get(clientId);
+      if (!client) return false;
+      client.ws.data.userId = userId;
+      unindexUser(client);
+      indexUser(client);
+      return true;
+    },
+    onAttach(cb) {
+      attachCbs.push(cb as (client: EventClient) => void);
+    },
+    onDetach(cb) {
+      detachCbs.push(cb as (client: EventClient) => void);
+    },
+  };
+}
+
+export type { ClientData };

package/src/events/cluster/dedupe.ts

@@ -0,0 +1,43 @@
+/**
+ * Broker-redelivery dedupe window — bounded recent-message-id tracking.
+ *
+ * Durable brokers may redeliver; every processed message id is recorded in a
+ * ring + set pair and duplicates are dropped. Encapsulated factory (like
+ * `createMetrics`) — the state is private, the surface is one pure predicate.
+ */
+import { RingBuffer } from "../../core/ring";
+
+export interface DedupeWindow {
+  /**
+   * Record `id` and report whether it was ALREADY seen (true → drop the
+   * message). Empty ids and a zero-size window disable tracking entirely.
+   */
+  markSeen(id: string): boolean;
+}
+
+/**
+ * @param size how many message ids to remember (0 disables; values < 16 are
+ *   clamped up so the ring has usable capacity).
+ */
+export function createDedupeWindow(size: number): DedupeWindow {
+  const window = Math.max(0, size);
+  if (window === 0) return { markSeen: () => false };
+
+  const ring = new RingBuffer<string>(Math.max(16, window), true);
+  const seen = new Set<string>();
+
+  return {
+    markSeen(id: string): boolean {
+      if (id === "") return false;
+      if (seen.has(id)) return true;
+      // evict the oldest id when the window is full (FIFO — matches redelivery)
+      if (ring.length >= window) {
+        const evict = ring.shift();
+        if (evict !== undefined) seen.delete(evict);
+      }
+      ring.push(id);
+      seen.add(id);
+      return false;
+    },
+  };
+}