@ignex/nova 0.1.3 → 0.1.5

package/src/core/server/http-routes.ts

@@ -0,0 +1,59 @@
+/**
+ * HTTP routes — the non-WebSocket side of `Bun.serve`'s fetch: the upgrade
+ * path, a JSON `/health` probe, an auth-gated `/clients` introspection
+ * endpoint, and the user-supplied fallback.
+ *
+ * Each route is a small pure-ish function `(state, req) => Response | null`
+ * (`null` = "not my route"); `handleHttpRequest` composes them in order.
+ */
+import type { ServerState, WsData } from "../state";
+import { authorizeHttp, checkUpgrade } from "../auth";
+import { toClientInfo } from "./client-info";
+
+/** The Bun server handle (needed by `checkUpgrade` for `srv.upgrade`). */
+type BunServer = ReturnType<typeof Bun.serve<WsData>>;
+
+/** JSON response helper (the only shape these routes return). */
+const json = (body: unknown, status = 200): Response =>
+  new Response(JSON.stringify(body), {
+    ...(status === 200 ? {} : { status }),
+    headers: { "content-type": "application/json" },
+  });
+
+/** GET /health — liveness + basic counters (never gated; safe for probes). */
+function healthRoute(state: ServerState): Response {
+  const h = state.metrics.snapshot(state.sockets.size);
+  return json({ status: "ok", clients: h.connectedClients, uptimeMs: h.uptimeMs });
+}
+
+/** GET /clients — active-client introspection. */
+async function clientsRoute(state: ServerState, req: Request): Promise<Response> {
+  // gated whenever the server has an auth surface (token or authenticate);
+  // public only for unsecured servers
+  const denied = await authorizeHttp(state, req);
+  if (denied) return denied;
+  return json([...state.clients.values()].map(toClientInfo));
+}
+
+/**
+ * Route an HTTP request. Order matters:
+ *   1. the WS upgrade path (`state.path`),
+ *   2. built-in introspection endpoints,
+ *   3. the user's custom `fetch` (when provided),
+ *   4. 404.
+ */
+export async function handleHttpRequest(
+  state: ServerState,
+  req: Request,
+  srv: BunServer,
+  customFetch?: (req: Request) => Response | Promise<Response>,
+): Promise<Response> {
+  const url = new URL(req.url);
+  if (url.pathname === state.path) {
+    return (await checkUpgrade(state, req, srv)) ?? new Response("upgrade failed", { status: 400 });
+  }
+  if (url.pathname === "/health") return healthRoute(state);
+  if (url.pathname === "/clients") return clientsRoute(state, req);
+  if (customFetch) return customFetch(req);
+  return new Response("not found", { status: 404 });
+}

package/src/core/{server.ts → server/index.ts}

@@ -2,7 +2,12 @@
  * 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.
+ * knows how the pieces fit together; each concern lives in its own module:
+ *
+ *   client-info.ts       — ClientInfo snapshot type + pure mapper
+ *   http-routes.ts       — fetch handler (health / clients / fallback)
+ *   socket-lifecycle.ts  — open/close handlers as `(state, ws)` actions
+ *   metrics-view.ts      — pure MetricsSnapshot assembly
  *
  * Generic over the wire stack: `createServer({ bindings })` with your own
  * generated bindings types `publish` / `on` / ... against YOUR events. The
@@ -11,53 +16,33 @@
  * Public entry: `public/server.ts` re-exports `createServer` + the types.
  */
 import type { ServerWebSocket } from "bun";
-import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../bindings/types";
-import { createNatsBridge } from "../bridge/nats";
-import { createEventsHub, type EventsHubInternal } from "../events/hub";
-import type { EventsHub } from "../events/types";
-import { checkUpgrade } from "./auth";
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../../bindings/types";
+import { createNatsBridge } from "../../bridge/nats";
+import { createEventsHub, type EventsHubInternal } from "../../events/hub";
+import type {
+  EventTraceRow,
+  EventTraceStats,
+  TraceQueryOptions,
+} from "../../events/trace";
+import { joinGroup as addToGroup } from "../groups";
+import { setInt64GuardMode } from "../int64-guard";
+import type { MetricsSnapshot } from "../metrics";
+import { drainSocket, sendFrame } from "../outbound";
 import {
   activeGroups,
-  joinGroup as addToGroup,
   groupMembers as groupMemberIds,
   publishToGroup as publishToGroupState,
   leaveGroup as removeFromGroup,
-} from "./groups";
-import { setInt64GuardMode } from "./int64-guard";
-import type { MetricsSnapshot } from "./metrics";
-import { drainSocket, sendControl, sendFrame } from "./outbound";
-import { joinRoom, leaveRoom, publishToRoom, roomTopics } from "./rooms";
-import { handleMessage } from "./routing";
-import { createServerState, type IgnServerOptions, type WsData } from "./state";
-
-/** A snapshot of an active client (from `getClient` / `getClients` / GET /clients). */
-export interface ClientInfo {
-  id: string;
-  /** identity this connection acts on behalf of (undefined if none) */
-  userId?: 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;
-}
+} from "../groups";
+import { joinRoom, leaveRoom, publishToRoom, roomTopics } from "../rooms";
+import { handleMessage } from "../routing";
+import { createServerState, type IgnServerOptions, type WsData } from "../state";
+import { toClientInfo, type ClientInfo } from "./client-info";
+import { handleHttpRequest } from "./http-routes";
+import { buildServerMetrics } from "./metrics-view";
+import { onSocketClose, onSocketOpen } from "./socket-lifecycle";
 
-function toClientInfo(ws: ServerWebSocket<WsData>): ClientInfo {
-  return {
-    id: ws.data.id,
-    ...(ws.data.userId !== undefined ? { userId: ws.data.userId } : {}),
-    ...(ws.data.meta !== undefined ? { meta: ws.data.meta } : {}),
-    groups: [...ws.data.groups],
-    topics: [...ws.data.topics],
-    connectedAt: ws.data.connectedAt,
-    ip: ws.remoteAddress,
-  };
-}
+export type { ClientInfo } from "./client-info";
 
 /** The public server API (returned by `createServer`). */
 export interface IgnServer<B extends Bindings = DefaultBindings> {
@@ -111,12 +96,34 @@ export interface IgnServer<B extends Bindings = DefaultBindings> {
     handler: (payload: EventsOf<B>[K], ws: ServerWebSocket<WsData>) => void,
   ): IgnServer<B>;
   off<K extends EventNameOf<B>>(name: K): IgnServer<B>;
+  /**
+   * Register a request/response responder for `name`: clients call it via
+   * `client.request(name, payload)` and receive the returned payload (encoded
+   * with the SAME event schema). Request/response share the event's schema.
+   */
+  handle<K extends EventNameOf<B>>(
+    name: K,
+    responder: (payload: EventsOf<B>[K], ws: ServerWebSocket<WsData>) => Promise<EventsOf<B>[K]> | EventsOf<B>[K],
+  ): IgnServer<B>;
+  /**
+   * The event trace ring — what fired recently (emitted / published /
+   * received), with per-event aggregates. Debugger-facing (ignex debugbar,
+   * MCP); rows are materialized on read only.
+   */
+  getEventTrace(options?: TraceQueryOptions): {
+    enabled: boolean;
+    capacity: number;
+    stats: EventTraceStats;
+    recent: EventTraceRow[];
+  };
+  /** Drop all retained trace records (counters survive). */
+  clearEventTrace(): void;
   /**
    * The events hub — present when `createServer({ events: {...} })` is used:
    * typed handlers (`server.events.on`), client records, groups, and the
    * cluster-aware emit surface.
    */
-  readonly events: EventsHub<B> | undefined;
+  readonly events: import("../../events/types").EventsHub<B> | undefined;
   /** Graceful drain: stop accepting, wait up to `timeoutMs` for queues to flush. */
   drain(timeoutMs?: number): Promise<void>;
   stop(force?: boolean): void;
@@ -128,27 +135,42 @@ export function createServer<B extends Bindings = DefaultBindings>(
   const state = createServerState(options);
   setInt64GuardMode(options.int64Guard ?? "off");
   const bindings = state.bindings;
+  const trace = state.trace; // hot-path local (one property load, ever)
 
   // 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, undefined, bindings);
+    // discriminate on `subjects` (bridge-only surface): both bridges AND raw
+    // transports have `publish`, so a publish-based probe misclassifies
+    state.bridge = "subjects" in natsOpt ? natsOpt : createNatsBridge(natsOpt, undefined, bindings);
+
+  // Encode once. EXTERNAL copies (NATS bridge / cluster envelope) are taken
+  // BEFORE any per-socket delivery-seq stamping mutates the scratch header —
+  // external consumers must see pristine frames.
 
-  // 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.
+  /** Encode + count + trace a broadcast frame (no delivery yet). */
   function fanOutAll(name: string, payload: unknown): Uint8Array {
     const frame = state.transport.encodeToScratch(name, payload);
     state.metrics.published++;
-    for (const ws of state.sockets) sendFrame(state, ws, frame);
+    trace.record("out.publish", name, "broadcast", undefined, frame.byteLength);
     return frame;
   }
 
+  /** Deliver an already-encoded frame to every connected socket. */
+  function fanOutAllLocal(frame: Uint8Array): void {
+    for (const ws of state.sockets) sendFrame(state, ws, frame);
+  }
+
   let eventsHub: EventsHubInternal<B> | undefined;
 
   if (state.bridge) {
     state.bridge.setOnInbound((name, payload) => {
-      fanOutAll(name, payload);
+      // trace: the event ARRIVED from the bridge, then is fanned out locally
+      // by fanOutAll below (which records its own out.publish row).
+      const id = bindings.anyEventNameToId[name];
+      if (id !== undefined) trace.record("in.bridge", name, undefined, undefined, 0);
+      const frame = fanOutAll(name, payload);
+      fanOutAllLocal(frame);
       // server-side handling of externally-published events (the events layer)
       eventsHub?.dispatchBridgeInbound(name, payload);
     });
@@ -159,55 +181,17 @@ export function createServer<B extends Bindings = DefaultBindings>(
     ...(options.hostname !== undefined ? { hostname: options.hostname } : {}),
     idleTimeout: options.idleTimeout ?? 30,
     ...(options.tls !== undefined ? { 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 });
-    },
+    fetch: (req, srv) => handleHttpRequest(state, req, srv, options.fetch),
     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);
-        // events-layer attach (client record + presence) BEFORE group seeding
-        state.onConnect?.(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: bindings.wireVersion, 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) => {
-        // events-layer detach FIRST (client record still carries groups/topics)
-        state.onDisconnect?.(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;
-      },
+      open: (ws) => onSocketOpen(state, ws),
+      close: (ws) => onSocketClose(state, ws),
       message: (ws, msg) => handleMessage(state, ws, msg),
       drain: (ws) => drainSocket(state, ws),
     },
   });
 
+  // ── publish actions (encode once → bridge copy → local fan-out) ──────
+
   const api: IgnServer<B> = {
     get port(): number {
       return bun.port ?? 0;
@@ -216,48 +200,45 @@ export function createServer<B extends Bindings = DefaultBindings>(
       return state.sockets.size;
     },
     getMetrics(): MetricsSnapshot {
-      const stats = state.transport.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");
-      }
-      for (const [name, n] of Object.entries(stats.js)) {
-        if (n > 0) state.metrics.countPath(name, "js");
-      }
-      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;
-      }
-      if (eventsHub) snapshot.events = eventsHub.metrics();
-      return snapshot;
+      return buildServerMetrics(state, eventsHub?.metrics());
+    },
+    getEventTrace(options?: TraceQueryOptions) {
+      return {
+        enabled: state.trace.enabled,
+        capacity: state.trace.capacity,
+        stats: state.trace.stats(),
+        recent: state.trace.recent(options),
+      };
+    },
+    clearEventTrace() {
+      state.trace.clear();
     },
     publish(name, payload) {
       const frame = fanOutAll(name, payload);
+      // pristine frame out FIRST (bridge copies), then seq-stamped local sends
       state.bridge?.publish(state.bridge.subjects.broadcast(name), frame);
+      fanOutAllLocal(frame);
     },
     publishTo(ws, name, payload) {
       state.metrics.published++;
-      sendFrame(state, ws, state.transport.encodeToScratch(name, payload));
+      const frame = state.transport.encodeToScratch(name, payload);
+      trace.record("out.publish", name, "client", ws.data.id, frame.byteLength);
+      sendFrame(state, ws, frame);
     },
     publishToTopic(topic, name, payload) {
       const frame = state.transport.encodeToScratch(name, payload);
       state.metrics.published++;
-      publishToRoom(state, topic, frame);
+      trace.record("out.publish", name, "topic", topic, frame.byteLength);
       state.bridge?.publish(state.bridge.subjects.topic(topic, name), frame);
+      publishToRoom(state, topic, frame);
     },
     publishToClient(id, name, payload) {
       const ws = state.clients.get(id);
       if (!ws) return false;
       state.metrics.published++;
-      sendFrame(state, ws, state.transport.encodeToScratch(name, payload));
+      const frame = state.transport.encodeToScratch(name, payload);
+      trace.record("out.publish", name, "client", id, frame.byteLength);
+      sendFrame(state, ws, frame);
       return true;
     },
     allowInbound(name) {
@@ -284,8 +265,9 @@ export function createServer<B extends Bindings = DefaultBindings>(
     publishToGroup(group, name, payload) {
       const frame = state.transport.encodeToScratch(name, payload);
       state.metrics.published++;
-      publishToGroupState(state, group, frame);
+      trace.record("out.publish", name, "group", group, frame.byteLength);
       state.bridge?.publish(state.bridge.subjects.group(group, name), frame);
+      publishToGroupState(state, group, frame);
     },
     groups() {
       return activeGroups(state);
@@ -324,7 +306,17 @@ export function createServer<B extends Bindings = DefaultBindings>(
       state.inboundHandlers.delete(name);
       return api;
     },
-    get events(): EventsHub<B> | undefined {
+    handle(name, responder) {
+      state.rpcHandlers.set(
+        name,
+        responder as (
+          payload: unknown,
+          ws: ServerWebSocket<WsData>,
+        ) => Promise<unknown>,
+      );
+      return api;
+    },
+    get events() {
       return eventsHub;
     },
     async drain(timeoutMs = 2000): Promise<void> {
@@ -344,7 +336,7 @@ export function createServer<B extends Bindings = DefaultBindings>(
     },
   };
 
-  // ── events layer (opt-in) ─────────────────────────────────────────────
+  // ── events layer (opt-in) ────────────────────────────────────────────
   if (options.events) {
     eventsHub = createEventsHub({
       state,

package/src/core/server/metrics-view.ts

@@ -0,0 +1,53 @@
+/**
+ * Metrics view — assembles the server-level `MetricsSnapshot` by folding the
+ * transport's cumulative per-path encode counters and the bridge stats into
+ * the core metrics snapshot. Pure assembly: no counter is re-accumulated, so
+ * polling `getMetrics()` repeatedly never inflates what it reports.
+ */
+import type { NatsBridge } from "../../bridge/nats";
+import type { MetricsSnapshot } from "../metrics";
+import type { ServerState } from "../state";
+
+/**
+ * Derive per-event path counts from the transport's OWN cumulative counters
+ * (totals since start) — a pure projection of `{direct,json,js}` per name.
+ */
+function buildPathCounts(state: ServerState): MetricsSnapshot["pathCounts"] {
+  const encodeStats = state.transport.getEncodeStats();
+  const pathCountsObj: Record<string, { direct: number; json: number; js: number }> = {};
+  const names = new Set<string>([
+    ...Object.keys(encodeStats.direct),
+    ...Object.keys(encodeStats.json),
+    ...Object.keys(encodeStats.js),
+  ]);
+  for (const name of names) {
+    const direct = encodeStats.direct[name] ?? 0;
+    const json = encodeStats.json[name] ?? 0;
+    const js = encodeStats.js[name] ?? 0;
+    if (direct > 0 || json > 0 || js > 0) pathCountsObj[name] = { direct, json, js };
+  }
+  return pathCountsObj;
+}
+
+/** Fold bridge counters into the snapshot (only when a bridge is wired). */
+function foldBridgeStats(snapshot: MetricsSnapshot, bridge: NatsBridge | undefined): void {
+  if (!bridge) return;
+  snapshot.bridged = bridge.stats.bridged;
+  snapshot.bridgedBytes = bridge.stats.bridgedBytes;
+  snapshot.bridgeErrors = bridge.stats.bridgeErrors;
+  snapshot.bridgeInbound = bridge.stats.bridgeInbound;
+  snapshot.bridgeInboundErrors = bridge.stats.bridgeInboundErrors;
+  snapshot.natsStatus = bridge.status;
+}
+
+/** Build the complete server metrics snapshot for `getMetrics()`. */
+export function buildServerMetrics(
+  state: ServerState,
+  eventsMetrics: MetricsSnapshot["events"],
+): MetricsSnapshot {
+  const snapshot = state.metrics.snapshot(state.sockets.size);
+  snapshot.pathCounts = buildPathCounts(state);
+  foldBridgeStats(snapshot, state.bridge);
+  if (eventsMetrics !== undefined) snapshot.events = eventsMetrics;
+  return snapshot;
+}

package/src/core/server/socket-lifecycle.ts

@@ -0,0 +1,57 @@
+/**
+ * Socket lifecycle — the server-side `open` / `close` WebSocket handlers as
+ * small `(state, ws)` actions (functional-composition style, like the other
+ * core action modules). The composition root (`index.ts`) wires them into
+ * `Bun.serve`'s websocket handlers.
+ */
+import type { ServerWebSocket } from "bun";
+import type { Bindings } from "../../bindings/types";
+import { joinGroup as addToGroup, leaveGroup as removeFromGroup } from "../groups";
+import { sendControl } from "../outbound";
+import { adoptGrave, burySession } from "../resume";
+import { leaveRoom } from "../rooms";
+import type { ServerState, WsData } from "../state";
+
+/** A socket opened: register, adopt resume history, seed groups, greet. */
+export function onSocketOpen(state: ServerState, ws: ServerWebSocket<WsData>): void {
+  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);
+  // resume: adopt a parked history for this client id (continues the
+  // previous session's delivery-seq stream) BEFORE anything is sent
+  adoptGrave(state, ws);
+  // events-layer attach (client record + presence) BEFORE group seeding
+  state.onConnect?.(ws);
+  for (const g of ws.data.groups) addToGroup(state, ws, g);
+  greetClient(state, ws);
+}
+
+/** Announce wire version + capabilities, then pin this client's identity. */
+function greetClient(state: ServerState, ws: ServerWebSocket<WsData>): void {
+  // announce our wire version + capabilities so clients can negotiate
+  sendControl(state, ws, "hello", {
+    version: (state.bindings as Bindings).wireVersion,
+    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] });
+}
+
+/** A socket closed: detach everywhere and park the resume history. */
+export function onSocketClose(state: ServerState, ws: ServerWebSocket<WsData>): void {
+  // events-layer detach FIRST (client record still carries groups/topics)
+  state.onDisconnect?.(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;
+  // resume: park the sent-history so a reconnect with the same id can
+  // pick up where this session left off (no-op when resume is off)
+  burySession(state, ws);
+}

package/src/core/state.ts

@@ -10,9 +10,11 @@ import type { ServerWebSocket } from "bun";
 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 { resolveRateLimit, type RateLimitOptions, type ResolvedRateLimit } from "./rate-limit";
 import type { RingBuffer } from "./ring";
 
 /**
@@ -57,6 +59,15 @@ export interface WsData {
   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`). */
@@ -97,9 +108,23 @@ export interface IgnServerOptions<B extends Bindings = DefaultBindings> {
    * 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.
    */
@@ -115,6 +140,22 @@ export interface IgnServerOptions<B extends Bindings = DefaultBindings> {
   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" —
@@ -141,6 +182,13 @@ export interface IgnServerOptions<B extends Bindings = DefaultBindings> {
    * (`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>;
 }
@@ -163,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>>;
@@ -175,11 +227,23 @@ export interface ServerState {
   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<B extends Bindings = DefaultBindings>(
@@ -205,7 +269,12 @@ export function createServerState<B extends Bindings = DefaultBindings>(
     ...(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(),
@@ -213,5 +282,8 @@ export function createServerState<B extends Bindings = DefaultBindings>(
     inboundHandlers: new Map(),
     topicHistory: new Map(),
     replaySeq: 0,
+    rpcHandlers: new Map(),
+    graves: new Map(),
+    trace: createEventTrace(options.trace),
   };
 }