@ignex/nova 0.1.3 → 0.1.6

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,
+  };
+}

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;
+}