@ignex/nova 0.1.3 → 0.1.5

package/src/core/outbound.ts

@@ -7,6 +7,7 @@ import type { ServerWebSocket } from "bun";
 import type { ControlEventName, ControlEvents } from "../schema";
 import { decide } from "./backpressure";
 import { RingBuffer } from "./ring";
+import { ensureHistory, recordSent, stampSeq } from "./resume";
 import type { ServerState, WsData } from "./state";
 
 /** Actual socket write + counters (single accounting point). */
@@ -17,17 +18,52 @@ export function doSend(state: ServerState, ws: ServerWebSocket<WsData>, frame: U
 }
 
 /**
- * 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).
+ * Send one frame to a socket, honoring the configured backpressure policy AND
+ * (when resume is enabled) stamping a per-connection delivery seq into the
+ * envelope v2 header first. Only APP frames are stamped: the delivery seq is
+ * an app-delivery guarantee, and control frames (ping/pong/welcome/resume
+ * acks) must never create ordering obligations for the client's gap gate.
+ *
+ * The stamp mutates the shared scratch view IN PLACE — safe because every
+ * external copy (bridge / cluster / replay history) is taken before this
+ * point, and `ws.send` copies synchronously.
+ *
+ * Pass `seq` to send a pre-stamped frame verbatim (resume replays keep their
+ * original delivery seqs and are not re-recorded).
  */
 export function sendFrame(
   state: ServerState,
   ws: ServerWebSocket<WsData>,
   frame: Uint8Array,
+  opts?: { readonly seq?: number },
 ): void {
+  if (opts?.seq !== undefined) {
+    // pre-stamped replay frame — write it as-is
+    const bp0 = state.bp;
+    if (!bp0) {
+      doSend(state, ws, frame);
+      return;
+    }
+    const d0 = decide(bp0, ws);
+    if (d0.kind === "send") doSend(state, ws, frame);
+    else if (d0.kind === "close") {
+      state.metrics.disconnectedSlow++;
+      ws.close(1013, "slow consumer");
+    }
+    return;
+  }
+  if (
+    state.resume !== null &&
+    state.resume !== undefined &&
+    !isControlFrame(state.bindings, frame) &&
+    ensureHistory(state, ws) !== undefined
+  ) {
+    const seq = ws.data.sendSeq++;
+    if (stampSeq(state.bindings, frame, seq)) {
+      recordSent(state, ws, frame, seq);
+      state.metrics.stampedSeq++;
+    }
+  }
   const bp = state.bp;
   if (!bp) {
     doSend(state, ws, frame);
@@ -52,7 +88,7 @@ export function sendFrame(
         q = new RingBuffer<Uint8Array>();
         ws.data.queue = q;
       }
-      q.push(frame.slice()); // owned copy for the queue
+      q.push(frame.slice()); // owned copy for the queue (already seq-stamped)
       for (let i = 0; i < d.dropHead; i++) {
         q.shift();
         state.metrics.droppedOldest++;
@@ -62,6 +98,14 @@ export function sendFrame(
   }
 }
 
+/** Cheap envelope-id probe: true when `frame` is a transport-internal event. */
+function isControlFrame(bindings: ServerState["bindings"], frame: Uint8Array): boolean {
+  if (frame.byteLength < 5) return false;
+  const id =
+    (frame[1]! | (frame[2]! << 8) | (frame[3]! << 16) | (frame[4]! << 24)) >>> 0;
+  return bindings.isControlId(id);
+}
+
 /** 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;

package/src/core/rate-limit.ts

@@ -0,0 +1,69 @@
+/**
+ * Per-connection inbound rate limiting — a token bucket evaluated on EVERY
+ * inbound frame (app AND control) before any decode work, so a flooding
+ * client pays ~nothing and can't starve the loop.
+ *
+ * Default OFF (`options.rateLimit` unset → `null`, zero hot-path overhead).
+ * When enabled, each connection lazily gets its own limiter on its first
+ * inbound frame (no per-connect allocation for idle listeners):
+ *
+ *   - tokens refill continuously at `messagesPerSecond`;
+ *   - bucket capacity is `burst` (default = messagesPerSecond), so short
+ *     spikes ride through while sustained floods are shed;
+ *   - `policy: "drop"` silently sheds over-limit frames (counted in
+ *     `metrics.rateLimited`); `policy: "close"` closes the socket 1008.
+ */
+export interface RateLimitOptions {
+  /** sustained inbound frames per second per connection, default 100 */
+  messagesPerSecond?: number;
+  /** burst capacity above the sustained rate, default = messagesPerSecond */
+  burst?: number;
+  /** what happens to over-limit frames, default "drop" */
+  policy?: "drop" | "close";
+}
+
+/** Fully-resolved options (defaults applied once at server creation). */
+export type ResolvedRateLimit = Required<RateLimitOptions>;
+
+export interface RateLimiter {
+  readonly policy: "drop" | "close";
+  /** Consume one inbound frame; false = over limit. Monotonic `now` (epoch ms). */
+  allow(now: number): boolean;
+}
+
+const MIN_RATE = 0.001; // guard against a zero refill (permanent lock-up)
+
+/** Apply option defaults once at instantiation time (not per message). */
+export function resolveRateLimit(opts?: RateLimitOptions): ResolvedRateLimit | null {
+  if (!opts) return null;
+  const messagesPerSecond = Math.max(MIN_RATE, opts.messagesPerSecond ?? 100);
+  const burst = Math.max(1, opts.burst ?? Math.ceil(messagesPerSecond));
+  return { messagesPerSecond, burst, policy: opts.policy ?? "drop" };
+}
+
+/**
+ * Create one connection's limiter from resolved options. The bucket starts
+ * FULL (`burst` tokens) so a well-behaved client is never punished for
+ * connecting right after a burst of legitimate traffic.
+ */
+export function createRateLimiter(r: ResolvedRateLimit): RateLimiter {
+  let tokens = r.burst;
+  let last = -1; // anchored on the FIRST frame (no pre-first-frame credit)
+  return {
+    policy: r.policy,
+    allow(now: number): boolean {
+      if (last < 0) {
+        last = now;
+      } else if (now > last) {
+        // continuous refill since the last consume (clamped to capacity)
+        tokens = Math.min(r.burst, tokens + ((now - last) / 1000) * r.messagesPerSecond);
+        last = now;
+      }
+      if (tokens >= 1) {
+        tokens -= 1;
+        return true;
+      }
+      return false;
+    },
+  };
+}

package/src/core/replay.ts

@@ -6,6 +6,11 @@
  * 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.
+ *
+ * DURABILITY SEAM: an optional {@link TopicLog} (see `topic-log.ts`) receives
+ * every recorded frame so history can outlive the ring window. When a client
+ * asks for a seq the ring no longer holds, `topicHistoryFrom` hydrates the
+ * missing prefix from the log.
  */
 import { RingBuffer } from "./ring";
 import type { ServerState } from "./state";
@@ -18,7 +23,9 @@ export function recordReplay(state: ServerState, topic: string, frame: Uint8Arra
     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
+  const seq = ++state.replaySeq;
+  hist.push({ seq, frame: frame.slice() }); // owned copy for replay
+  state.topicLog?.append(topic, frame, seq);
 }
 
 /** The recorded frames for `topic`, oldest → newest (already owned copies). */
@@ -29,3 +36,36 @@ export function replayFrames(state: ServerState, topic: string): Uint8Array[] {
   for (const e of hist) out.push(e.frame);
   return out;
 }
+
+/**
+ * Recorded frames for `topic` strictly after `fromSeq` (0 = everything
+ * retained), oldest → newest. Synchronous: serves from the in-memory ring;
+ * when the ring's oldest entry leaves a hole above `fromSeq` and a durable
+ * {@link TopicLog} is configured, the missing prefix is hydrated from the log
+ * (blocking briefly is acceptable on this control path).
+ */
+export function topicHistoryFrom(
+  state: ServerState,
+  topic: string,
+  fromSeq: number,
+): Uint8Array[] {
+  const hist = state.topicHistory.get(topic);
+  const ring: Array<{ seq: number; frame: Uint8Array }> = [];
+  if (hist) for (const e of hist) if (e.seq > fromSeq) ring.push(e);
+  if (ring.length === 0) {
+    // nothing in the ring at/after the resume point — try the durable log
+    const log = state.topicLog;
+    if (log && fromSeq > 0) return log.range(topic, fromSeq).map((e) => e.frame);
+    return [];
+  }
+  const oldest = ring[0]!.seq;
+  if (oldest > fromSeq + 1 && oldest > 1) {
+    // hole between fromSeq and the ring window — hydrate the prefix
+    const log = state.topicLog;
+    if (log) {
+      const prefix = log.range(topic, fromSeq, oldest - fromSeq - 1);
+      return [...prefix.map((e) => e.frame), ...ring.map((e) => e.frame)];
+    }
+  }
+  return ring.map((e) => e.frame);
+}

package/src/core/resume.ts

@@ -0,0 +1,181 @@
+/**
+ * Delivery-sequence + resume — gap-free delivery over the WS transport.
+ *
+ * Every frame the SERVER writes to a socket carries a per-connection,
+ * monotonically increasing delivery seq (envelope v2 `[flags:1][seq:u64 LE]`,
+ * stamped in place just before `ws.send` — Bun copies synchronously). Clients
+ * track the seq stream and detect loss (backpressure drops, reconnect
+ * boundaries) as gaps.
+ *
+ * Recovery has two halves:
+ *   - SAME-connection gaps → client sends the `resume` control frame with its
+ *     last contiguous seq; the server replays from the connection's bounded
+ *     sent-history ring (`ws.data.history`), frames keeping their ORIGINAL
+ *     seqs so the client's stream stays gap-free and duplicate-free.
+ *   - RECONNECT → on close the ring + counter move to a per-client-id
+ *     "graveyard" (bounded, TTL'd). A reconnecting socket whose auth-pinned id
+ *     has a grave adopts it, so `hello { lastSeq }` resumes across sessions.
+ *
+ * The stamping helpers derive offsets from `bindings.wireHeaderLen`, so v1
+ * bindings (header 5, no seq field) simply never stamp and never resume.
+ */
+import type { ServerWebSocket } from "bun";
+import type { Bindings } from "../bindings/types";
+import { RingBuffer } from "./ring";
+import type { ServerState, WsData } from "./state";
+
+/** One entry of a connection's sent-frame history (frame is an owned copy). */
+export interface SentFrame {
+  seq: number;
+  frame: Uint8Array;
+}
+
+const FLAGS_OFFSET_BACK = 9; // [..][flags:1][seq:u64 LE] tail of the header
+const SEQ_OFFSET_BACK = 8;
+
+/**
+ * Stamp `seq` into `frame`'s delivery header IN PLACE (flags bit0 = 1).
+ * Callers must own or exclusively borrow the buffer at this instant:
+ * `ws.send` copies synchronously, and queued/replayed frames are stamped
+ * before their owned copy is taken. Returns false when the bindings have no
+ * delivery header (v1) — callers then skip resume bookkeeping.
+ */
+export function stampSeq(bindings: Bindings, frame: Uint8Array, seq: number): boolean {
+  const len = bindings.wireHeaderLen;
+  if (len < FLAGS_OFFSET_BACK + 1 || frame.byteLength < len) return false;
+  frame[len - FLAGS_OFFSET_BACK] = (frame[len - FLAGS_OFFSET_BACK] ?? 0) | 1;
+  // u64 LE via two u32 halves — no BigInt/DataView allocation per frame
+  // (this runs once per app frame PER SOCKET on the fan-out loop)
+  const off = len - SEQ_OFFSET_BACK;
+  const lo = seq % 0x100000000;
+  const hi = Math.floor(seq / 0x100000000);
+  frame[off] = lo & 0xff;
+  frame[off + 1] = (lo >>> 8) & 0xff;
+  frame[off + 2] = (lo >>> 16) & 0xff;
+  frame[off + 3] = (lo >>> 24) & 0xff;
+  frame[off + 4] = hi & 0xff;
+  frame[off + 5] = (hi >>> 8) & 0xff;
+  frame[off + 6] = (hi >>> 16) & 0xff;
+  frame[off + 7] = (hi >>> 24) & 0xff;
+  return true;
+}
+
+/** Read a frame's delivery seq; null when unstamped / not present. */
+export function readSeq(bindings: Bindings, frame: Uint8Array): number | null {
+  const len = bindings.wireHeaderLen;
+  if (len < FLAGS_OFFSET_BACK + 1 || frame.byteLength < len) return null;
+  if ((frame[len - FLAGS_OFFSET_BACK]! & 1) === 0) return null;
+  const off = len - SEQ_OFFSET_BACK;
+  const lo =
+    frame[off]! | (frame[off + 1]! << 8) | (frame[off + 2]! << 16) | (frame[off + 3]! << 24);
+  const hi =
+    frame[off + 4]! | (frame[off + 5]! << 8) | (frame[off + 6]! << 16) | (frame[off + 7]! << 24);
+  return (lo >>> 0) + hi * 0x100000000;
+}
+
+/** Lazily create the per-connection sent-history ring (resume enabled only). */
+export function ensureHistory(state: ServerState, ws: ServerWebSocket<WsData>): RingBuffer<SentFrame> | undefined {
+  if (!state.resume) return undefined;
+  let h = ws.data.history;
+  if (h === undefined) {
+    h = new RingBuffer<SentFrame>(state.resume.historySize, true);
+    ws.data.history = h;
+  }
+  return h;
+}
+
+/**
+ * Record a stamped frame in the connection's history (owned copy — the caller
+ * may be handing a reused scratch view to `ws.send`). No-op when resume is off
+ * or the frame could not be stamped.
+ */
+export function recordSent(
+  _state: ServerState,
+  ws: ServerWebSocket<WsData>,
+  frame: Uint8Array,
+  seq: number,
+): void {
+  const h = ws.data.history;
+  if (!h) return;
+  h.push({ seq, frame: frame.slice() });
+}
+
+// ── graveyard (cross-connection resume) ─────────────────────────────────────
+
+const GRAVE_MAX = 1000;
+
+function pruneGraves(state: ServerState): void {
+  const now = Date.now();
+  for (const [id, g] of state.graves) {
+    if (g.expiresAt <= now) state.graves.delete(id);
+  }
+}
+
+/**
+ * On disconnect (resume enabled): park the connection's history under its
+ * client id so a future session can adopt it. Bounded: beyond `GRAVE_MAX`
+ * entries (or past TTL) the OLDEST grave is dropped first.
+ */
+export function burySession(state: ServerState, ws: ServerWebSocket<WsData>): void {
+  const ttlMs = state.resume?.ttlMs ?? 0;
+  const history = ws.data.history;
+  if (!state.resume || !history || history.length === 0) return;
+  pruneGraves(state);
+  if (state.graves.size >= GRAVE_MAX) {
+    // drop the soonest-expiring grave (Map preserves insertion order)
+    const oldest = state.graves.keys().next();
+    if (!oldest.done) state.graves.delete(oldest.value);
+  }
+  state.graves.set(ws.data.id, {
+    history,
+    nextSeq: ws.data.sendSeq,
+    expiresAt: Date.now() + ttlMs,
+  });
+}
+
+/**
+ * On open (resume enabled): adopt a parked history for this client id, if any.
+ * Returns true when the connection now continues a previous seq stream.
+ */
+export function adoptGrave(state: ServerState, ws: ServerWebSocket<WsData>): boolean {
+  if (!state.resume) return false;
+  const g = state.graves.get(ws.data.id);
+  if (!g) return false;
+  if (g.expiresAt <= Date.now()) {
+    state.graves.delete(ws.data.id);
+    return false;
+  }
+  state.graves.delete(ws.data.id);
+  ws.data.history = g.history;
+  ws.data.sendSeq = g.nextSeq;
+  return true;
+}
+
+/**
+ * Replay every retained frame strictly after `lastSeq` to `ws` (original seqs
+ * preserved). Returns `{ ok, replayed, from }`; `ok=false` means the requested
+ * hole is older than the ring (partial recovery — the client should
+ * resubscribe topics for a fresh snapshot).
+ */
+export function replayAfter(
+  _state: ServerState,
+  ws: ServerWebSocket<WsData>,
+  lastSeq: number,
+): { ok: boolean; replayed: number; from: number } {
+  const h = ws.data.history;
+  if (!h || h.length === 0) return { ok: false, replayed: 0, from: 0 };
+  let ok = true;
+  let replayed = 0;
+  let from = 0;
+  for (const e of h) {
+    if (e.seq <= lastSeq) continue;
+    if (from === 0) from = e.seq;
+    // a hole before/at the oldest retained frame cannot be filled
+    if (e.seq !== lastSeq + replayed + 1) ok = false;
+    // direct write — bypasses stamping (frames keep their original seq) and
+    // backpressure (dropping a resume into a saturated queue defeats it)
+    ws.send(e.frame);
+    replayed++;
+  }
+  return { ok, replayed, from };
+}

package/src/core/rooms.ts

@@ -4,12 +4,17 @@
  * (`publishToRoom` fans a frame out to every member).
  */
 import type { ServerWebSocket } from "bun";
-import { doSend, sendFrame } from "./outbound";
+import { 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 {
+  // every join path (control frames, programmatic, auth-seeded) is gated
+  if (state.authorizeTopic !== undefined && !state.authorizeTopic(topic, ws)) {
+    state.metrics.rejectedJoins++;
+    return;
+  }
   ws.data.topics.add(topic);
   let set = state.rooms.get(topic);
   if (!set) {
@@ -17,8 +22,10 @@ export function joinRoom(state: ServerState, ws: ServerWebSocket<WsData>, topic:
     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);
+  // snapshot replay goes through the normal outbound path so (with resume
+  // enabled) the frames are stamped into this connection's seq stream and
+  // recorded in its history — clients can gap-recover across them too.
+  for (const frame of replayFrames(state, topic)) sendFrame(state, ws, frame);
 }
 
 /** Leave `topic`; prune the room when it becomes empty. */

package/src/core/routing.ts

@@ -11,9 +11,13 @@
  */
 import type { ServerWebSocket } from "bun";
 import type { ControlEventName, ControlEvents } from "../schema";
-import { sendControl } from "./outbound";
+import { capturePayload } from "../events/trace";
+import { sendControl, doSend } from "./outbound";
+import { replayAfter } from "./resume";
 import { joinRoom, leaveRoom } from "./rooms";
+import { topicHistoryFrom } from "./replay";
 import { joinGroup, leaveGroup } from "./groups";
+import { createRateLimiter } from "./rate-limit";
 import type { ServerState, WsData } from "./state";
 
 // allocated once per process, reused for every inbound text frame
@@ -24,12 +28,44 @@ export function handleMessage(
   ws: ServerWebSocket<WsData>,
   raw: string | Buffer,
 ): void {
-  const bytes = typeof raw === "string" ? textEncoder.encode(raw) : new Uint8Array(raw as Buffer);
+  // cheap oversize pre-check BEFORE any conversion work (string length is a
+  // lower bound of its UTF-8 size, so `>` here can never false-positive)
+  if (state.maxMessageSize !== undefined) {
+    const approx = typeof raw === "string" ? raw.length : raw.byteLength;
+    if (approx > state.maxMessageSize) {
+      state.metrics.protocolErrors++;
+      ws.close(1009, "message too big");
+      return;
+    }
+  }
+  // binary frames are viewed ZERO-COPY (decode is synchronous and every
+  // downstream holder — replay history, backpressure queue, NATS bridge —
+  // takes its own owned copy); only text frames pay one transcode.
+  const bytes =
+    typeof raw === "string"
+      ? textEncoder.encode(raw)
+      : new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
   if (state.maxMessageSize !== undefined && bytes.byteLength > state.maxMessageSize) {
+    // multi-byte text frames can exceed the lower bound checked above
     state.metrics.protocolErrors++;
     ws.close(1009, "message too big");
     return;
   }
+  // per-connection token bucket — evaluated before ANY decode work so a
+  // flooding client is shed at ~constant cost (app AND control frames).
+  const rl = state.rateLimit;
+  if (rl !== null) {
+    let limiter = ws.data.rate;
+    if (limiter === undefined) {
+      limiter = createRateLimiter(rl);
+      ws.data.rate = limiter;
+    }
+    if (!limiter.allow(Date.now())) {
+      state.metrics.rateLimited++;
+      if (limiter.policy === "close") ws.close(1008, "rate limit exceeded");
+      return;
+    }
+  }
   const header = state.bindings.readFrameHeader(bytes);
   if (!header) {
     state.metrics.protocolErrors++;
@@ -43,7 +79,23 @@ export function handleMessage(
   const name = header.name;
   if (!state.inbound.has(name)) return; // not an allowed inbound event — no payload decode
   state.metrics.inbound++;
-  state.inboundHandlers.get(name)?.(state.bindings.decodePayload(header.id, bytes), ws);
+  // trace: one row per accepted client event (the debugger's "what came in").
+  // The payload itself is materialized only when somebody consumes it (a
+  // handler exists or capture is on) — never allocated otherwise.
+  const handler = state.inboundHandlers.get(name);
+  const payload =
+    handler !== undefined || state.trace.captures
+      ? state.bindings.decodePayload(header.id, bytes)
+      : undefined;
+  state.trace.record(
+    "in.client",
+    name,
+    undefined,
+    ws.data.id,
+    bytes.byteLength,
+    state.trace.captures ? capturePayload(payload, 2000) : undefined,
+  );
+  handler?.(payload, ws);
   // Horizontal scaling: when the bridge is configured with `bridgeClientEvents`,
   // every accepted client event is re-published to `{prefix}.inbound.<event>` so
   // OTHER server instances (and BE consumers) receive it. NATS-inbound frames
@@ -70,7 +122,28 @@ export function handleControl(
       if (p.version !== state.bindings.wireVersion) {
         // protocol version mismatch — refuse this client
         ws.close(1002, "wire version mismatch");
+        break;
       }
+      // cross-session resume: the client reconnects with `lastSeq > 0` and a
+      // parked history was adopted for its id (server.open wires adoption).
+      if (p.lastSeq > 0 && ws.data.history !== undefined && ws.data.history.length > 0) {
+        const r = replayAfter(state, ws, p.lastSeq);
+        state.metrics.resumesServed++;
+        state.metrics.framesReplayed += r.replayed;
+        if (!r.ok) state.metrics.resumeMisses++;
+        sendControl(state, ws, "resumed", { ok: r.ok, from: r.from });
+      }
+      break;
+    }
+    case "resume": {
+      // same-connection gap recovery: replay everything after the client's
+      // last contiguous seq (original seqs preserved — no re-stamping)
+      const lastSeq = (payload as ControlEvents["resume"]).lastSeq;
+      const r = replayAfter(state, ws, lastSeq);
+      state.metrics.resumesServed++;
+      state.metrics.framesReplayed += r.replayed;
+      if (!r.ok) state.metrics.resumeMisses++;
+      sendControl(state, ws, "resumed", { ok: r.ok, from: r.from });
       break;
     }
     case "subscribe": {
@@ -96,8 +169,58 @@ export function handleControl(
     case "pong":
       // client keepalive reply — tracked on the client side (heartbeat)
       break;
-    case "snapshotRequest":
-      // per-topic replay from the ring buffer (see replay.ts)
+    case "snapshotRequest": {
+      // per-topic replay from the ring buffer (+ topic log when configured),
+      // strictly after `fromSeq` (0 = from the beginning of retained history)
+      const p = payload as ControlEvents["snapshotRequest"];
+      for (const frame of topicHistoryFrom(state, p.topic, p.fromSeq)) doSend(state, ws, frame);
+      break;
+    }
+    case "rpcCall": {
+      const p = payload as ControlEvents["rpcCall"];
+      const responder = state.rpcHandlers.get(p.name);
+      const reply = (ok: boolean, payloadB64: string, err = ""): void => {
+        sendControl(state, ws, "rpcResult", { id: p.id, ok, err, payloadB64 });
+      };
+      if (!responder) {
+        reply(false, "", `no handler for "${p.name}"`);
+        return;
+      }
+      const inner = decodeB64Frame(state, p.payloadB64);
+      if (!inner) {
+        reply(false, "", "undecodable request payload");
+        return;
+      }
+      void (async () => {
+        try {
+          const out = await responder(inner.payload, ws);
+          // encode with the SAME event name (request/response share a schema)
+          const frame = state.transport.encodeToScratch(p.name, out);
+          reply(true, b64(frame));
+        } catch (err) {
+          reply(false, "", err instanceof Error ? err.message : String(err));
+        }
+      })();
       break;
+    }
   }
 }
+
+/** Decode a base64 wire frame (rpcCall payload) into { name, payload }. */
+function decodeB64Frame(
+  state: ServerState,
+  b64: string,
+): { name: string; payload: unknown } | null {
+  try {
+    const bytes = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+    return state.bindings.decodeFrame(bytes) as { name: string; payload: unknown } | null;
+  } catch {
+    return null;
+  }
+}
+
+const b64 = (bytes: Uint8Array): string => {
+  let s = "";
+  for (let i = 0; i < bytes.byteLength; i++) s += String.fromCharCode(bytes[i]!);
+  return btoa(s);
+};

package/src/core/server/client-info.ts

@@ -0,0 +1,37 @@
+/**
+ * Client introspection view — the snapshot shape returned by
+ * `server.getClient` / `server.getClients` and the GET /clients endpoint.
+ *
+ * `toClientInfo` is a PURE mapper from live socket state to the plain object.
+ */
+import type { ServerWebSocket } from "bun";
+import 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;
+}
+
+export 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,
+  };
+}