@ignex/nova 0.1.3 → 0.1.5

package/src/core/auth.ts

@@ -7,9 +7,64 @@
  * `authenticate` may return a `ClientMeta` (`{id, groups, meta}`) to pin the
  * client's identity for targeted sends / grouping; otherwise a UUID is
  * auto-assigned. A duplicate explicit id rejects the new connection (409).
+ *
+ * Literal bearer tokens are compared in CONSTANT TIME (no length or prefix
+ * oracle for a brute-forcing caller). The same gate protects the HTTP admin
+ * surface (`GET /clients`) via `authorizeHttp` — introspection endpoints must
+ * never be wider than the WebSocket they introspect.
  */
+import { timingSafeEqual } from "node:crypto";
 import type { ClientMeta, ServerState, WsData } from "./state";
 
+/** Constant-time string equality (UTF-8 compared; length-safe). */
+export function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  if (ab.byteLength !== bb.byteLength) {
+    // burn comparable time so mismatched-length guesses aren't cheaper
+    timingSafeEqual(ab, ab);
+    return false;
+  }
+  return timingSafeEqual(ab, bb);
+}
+
+/** Evaluate the server's token gate against a raw Bearer value. */
+export function tokenOk(state: ServerState, bearer: string): boolean {
+  if (state.token === undefined) return true;
+  return typeof state.token === "function" ? state.token(bearer) : safeEqual(bearer, state.token);
+}
+
+function bearerOf(req: Request): string {
+  const auth = req.headers.get("authorization") ?? "";
+  return auth.startsWith("Bearer ") ? auth.slice("Bearer ".length) : "";
+}
+
+/**
+ * HTTP admin gate (defense-in-depth for non-WebSocket routes): when a `token`
+ * is configured the request MUST carry a valid Bearer; otherwise, when an
+ * `authenticate` hook exists it must accept the request. Unauthenticated
+ * servers stay unauthenticated (documented dev behavior).
+ */
+export async function authorizeHttp(
+  state: ServerState,
+  req: Request,
+): Promise<Response | undefined> {
+  if (state.token !== undefined || state.authenticate !== undefined) {
+    if (!tokenOk(state, bearerOf(req))) return new Response("unauthorized", { status: 401 });
+    if (state.token === undefined && state.authenticate !== undefined) {
+      // a failing auth backend must deny, not blow up the serve loop
+      let allowed: unknown;
+      try {
+        allowed = await state.authenticate(req);
+      } catch {
+        return new Response("unauthorized", { status: 401 });
+      }
+      if (!allowed) return new Response("unauthorized", { status: 401 });
+    }
+  }
+  return undefined;
+}
+
 export async function checkUpgrade(
   state: ServerState,
   req: Request,
@@ -25,14 +80,19 @@ export async function checkUpgrade(
     }
   }
   if (state.token) {
-    const auth = req.headers.get("authorization") ?? "";
-    const bearer = auth.startsWith("Bearer ") ? auth.slice("Bearer ".length) : "";
-    const ok = typeof state.token === "function" ? state.token(bearer) : bearer === state.token;
+    const ok = tokenOk(state, bearerOf(req));
     if (!ok) return new Response("unauthorized", { status: 401 });
   }
   let authMeta: ClientMeta | undefined;
   if (state.authenticate) {
-    const res = await state.authenticate(req);
+    // a throwing / rejecting hook denies the upgrade cleanly (401) instead of
+    // surfacing an unhandled error through Bun.serve's fetch loop
+    let res: Awaited<ReturnType<typeof state.authenticate>>;
+    try {
+      res = await state.authenticate(req);
+    } catch {
+      return new Response("unauthorized", { status: 401 });
+    }
     if (!res) return new Response("unauthorized", { status: 401 });
     if (typeof res === "object") authMeta = res;
   }
@@ -44,6 +104,7 @@ export async function checkUpgrade(
   }
   const data: WsData = {
     lastSeq: 0,
+    sendSeq: 1,
     topics: new Set(),
     groups: new Set(authMeta?.groups ?? []),
     id,

package/src/core/client-rpc.ts

@@ -0,0 +1,75 @@
+/**
+ * Client RPC — the request/response half of `client.request(name, payload)`.
+ *
+ * Extracted from the client composition root so the wire-level plumbing
+ * (base64 framing, pending-call registry, timeout bookkeeping) lives in one
+ * small module. The reply side (`rpcResult` handling) is in `client-wire.ts`.
+ */
+import type { Bindings } from "../bindings/types";
+import { sendControl } from "./client-wire";
+import type { ClientState } from "./client-state";
+
+/** Encode bytes as base64 without pulling in a Buffer dependency (browser-safe). */
+export function bytesToB64(bytes: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < bytes.byteLength; i++) s += String.fromCharCode(bytes[i]!);
+  return btoa(s);
+}
+
+/** Reject every pending rpc call (client close / socket loss). */
+export function failAllPending(
+  state: ClientState,
+  err: Error,
+): void {
+  for (const [id, call] of state.rpcPending) {
+    clearTimeout(call.timer);
+    call.reject(err);
+    state.rpcPending.delete(id);
+  }
+}
+
+/**
+ * Run a request/response round-trip: encode `payload` with the event's own
+ * schema, send it inside an `rpcCall` control frame, and settle with
+ * `{ payload }` from the responder. Rejects on timeout, transport loss, or a
+ * server-side error — never leaves a pending entry behind.
+ */
+export function createRpcRequest<B extends Bindings>(
+  state: ClientState,
+  name: string,
+  payload: unknown,
+  opts: { readonly timeoutMs?: number } | undefined,
+  bindings: B,
+): Promise<unknown> {
+  const ws = state.ws;
+  if (!ws || ws.readyState !== WebSocket.OPEN)
+    return Promise.reject(new Error("ignex: client is not connected"));
+
+  const id = crypto.randomUUID();
+  const inner = bindings.encodeFrame(name, payload);
+  const b64 = bytesToB64(inner);
+  const timeoutMs = opts?.timeoutMs ?? state.requestTimeoutMs;
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      state.rpcPending.delete(id);
+      reject(new Error(`ignex rpc "${name}" timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    // registered BEFORE the send so a fast reply can never race the insert
+    state.rpcPending.set(id, {
+      name,
+      // the wire resolves with the bare payload — wrap it into RpcResult here
+      resolve: (out) => resolve({ payload: out }),
+      reject,
+      timer,
+    });
+    try {
+      sendControl(state, "rpcCall", { id, name, payloadB64: b64 });
+    } catch (err) {
+      clearTimeout(timer);
+      state.rpcPending.delete(id);
+      reject(err instanceof Error ? err : new Error(String(err)));
+    }
+  });
+}

package/src/core/client-state.ts

@@ -32,6 +32,16 @@ export interface IgnClientOptions<B extends Bindings = DefaultBindings> {
   heartbeatMs?: number;
   /** miss this many heartbeats before assuming the connection is dead, default 2 */
   heartbeatMisses?: number;
+  /**
+   * Gap-free delivery (requires the server started with `resume`): track the
+   * server's per-connection delivery seqs, detect gaps, and automatically
+   * request re-delivery via the `resume` control frame. Buffered out-of-order
+   * frames are bounded by `maxPending`. Default: true (no-op against servers
+   * that don't stamp seqs).
+   */
+  resume?: boolean | { maxPending?: number; timeoutMs?: number };
+  /** request/response default timeout (ms), default 10_000 */
+  requestTimeoutMs?: number;
 }
 
 export interface ClientState {
@@ -55,6 +65,24 @@ export interface ClientState {
   clientId: string;
   /** server-side groups this client belongs to (from `welcome`; [] until known) */
   groups: string[];
+
+  // ── delivery-seq tracking / gap recovery (envelope v2) ──────────────────
+  /** resolved resume options (enabled: false when off) */
+  resume: { enabled: boolean; maxPending: number; timeoutMs: number };
+  /** last CONTIGUOUS delivery seq processed (0 = none yet) */
+  rxSeq: number;
+  /** frames held out-of-order while a gap is being filled (seq → frame bytes) */
+  pending: Map<number, Uint8Array[]>;
+  /** seq the pending buffer is waiting to fill from */
+  pendingFrom: number;
+  /** in-flight resume request flag (throttles re-asks) */
+  resumeInFlight: boolean;
+  /** force-flush timer for an unfillable gap */
+  gapTimer: ReturnType<typeof setTimeout> | null;
+  /** request/response: correlation id → pending call */
+  rpcPending: Map<string, { resolve: (payload: unknown) => void; reject: (err: Error) => void; timer: ReturnType<typeof setTimeout>; name: string }>;
+  /** default request timeout (ms) */
+  requestTimeoutMs: number;
 }
 
 export function createClientState<B extends Bindings = DefaultBindings>(
@@ -79,6 +107,20 @@ export function createClientState<B extends Bindings = DefaultBindings>(
     lastPong: 0,
     clientId: "",
     groups: [],
+    resume: {
+      enabled: opts.resume !== false,
+      maxPending:
+        (typeof opts.resume === "object" ? opts.resume.maxPending : undefined) ?? 1024,
+      timeoutMs:
+        (typeof opts.resume === "object" ? opts.resume.timeoutMs : undefined) ?? 5_000,
+    },
+    rxSeq: 0,
+    pending: new Map(),
+    pendingFrom: 0,
+    resumeInFlight: false,
+    gapTimer: null,
+    rpcPending: new Map(),
+    requestTimeoutMs: opts.requestTimeoutMs ?? 10_000,
   };
 }
 

package/src/core/client-wire.ts

@@ -3,6 +3,12 @@
  * `handleMessage` decodes the envelope, filters control frames, and fans app
  * events out to the registered handlers. All decode/encode goes through
  * `state.bindings`, so a client speaks whatever wire stack it was given.
+ *
+ * With envelope v2 (delivery seqs) and `resume` enabled, app frames pass
+ * through a small ordering gate: contiguous seqs deliver immediately; a GAP
+ * buffers out-of-order frames and asks the server to re-send the hole
+ * (`resume` control frame); replayed hole-fills keep their original seqs so
+ * delivery stays in-order and duplicate-free.
  */
 import type { ControlEventName, ControlEvents } from "../schema";
 import type { ClientState } from "./client-state";
@@ -27,6 +33,103 @@ export function emitError(state: ClientState, err: Error): void {
   for (const cb of state.errorCbs) cb(err);
 }
 
+/** Delivery header offsets derived from the bindings' header length. */
+const flagsAt = (state: ClientState): number => state.bindings.wireHeaderLen - 9;
+const seqAt = (state: ClientState): number => state.bindings.wireHeaderLen - 8;
+
+function readDeliverySeq(state: ClientState, bytes: Uint8Array): number | null {
+  const len = state.bindings.wireHeaderLen;
+  if (len < 14 || bytes.byteLength < len) return null;
+  if ((bytes[flagsAt(state)]! & 1) === 0) return null;
+  return Number(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getBigUint64(seqAt(state), true));
+}
+
+/** Ask the server to re-send everything after `state.rxSeq` (throttled). */
+export function requestResume(state: ClientState): void {
+  if (!state.resume.enabled || state.resumeInFlight) return;
+  try {
+    sendControl(state, "resume", { lastSeq: state.rxSeq });
+    state.resumeInFlight = true;
+  } catch {
+    // not connected — reconnect flow will carry lastSeq in `hello`
+  }
+}
+
+/** Force-drain the pending buffer after an unfillable gap (accept loss). */
+export function flushPending(state: ClientState): void {
+  if (state.pending.size === 0) return;
+  const seqs = [...state.pending.keys()].sort((a, b) => a - b);
+  for (const s of seqs) {
+    for (const f of state.pending.get(s)!) dispatchAppFrame(state, f);
+    state.pending.delete(s);
+  }
+  if (seqs.length > 0 && seqs[seqs.length - 1]! > state.rxSeq) {
+    state.rxSeq = seqs[seqs.length - 1]!;
+  }
+  state.pendingFrom = 0;
+}
+
+/** Dispatch one decoded APP frame to handlers (no ordering). */
+function dispatchAppFrame(state: ClientState, bytes: Uint8Array): void {
+  const frame = state.bindings.decodeFrame(bytes);
+  if (!frame) return;
+  const set = state.handlers.get(frame.name);
+  if (set) for (const cb of set) cb(frame.payload);
+  for (const cb of state.anyHandlers) cb(frame.name, frame.payload);
+}
+
+/**
+ * Ordered delivery of one raw app frame. Returns true when the frame was
+ * consumed here (contiguous / buffered / replayed); false = not tracking.
+ */
+function orderedDeliver(state: ClientState, bytes: Uint8Array, seq: number): boolean {
+  if (!state.resume.enabled) return false;
+  if (seq === state.rxSeq + 1) {
+    state.rxSeq = seq;
+    dispatchAppFrame(state, bytes);
+    // drain anything the gap-fill delivered contiguously behind us
+    while (state.pending.has(state.rxSeq + 1)) {
+      const next = state.rxSeq + 1;
+      for (const f of state.pending.get(next)!) dispatchAppFrame(state, f);
+      state.pending.delete(next);
+      state.rxSeq = next;
+    }
+    if (state.pending.size === 0) state.pendingFrom = 0;
+    return true;
+  }
+  if (seq <= state.rxSeq) {
+    // Duplicate of an already-dispatched frame. Every seq ≤ rxSeq has been
+    // delivered (contiguously or via the pending drain), so a late replay of
+    // it must NOT be dispatched again. This happens when a `resume`/`hello`
+    // replay range overlaps frames the client already received live — e.g.
+    // the server processed our `hello { lastSeq }` AFTER the frames were sent
+    // (reconnect race), or a gap-fill replay re-sends frames that were already
+    // drained out of `pending`. Redelivering here would break the duplicate-
+    // free contract, so we consume and drop.
+    return true;
+  }
+  // seq > rxSeq + 1 → GAP: buffer, then ask the server to fill it
+  let list = state.pending.get(seq);
+  if (!list) {
+    if (state.pending.size >= state.resume.maxPending) {
+      flushPending(state); // accept loss rather than grow unbounded
+    }
+    list = [];
+    state.pending.set(seq, list);
+  }
+  list.push(bytes);
+  if (state.pendingFrom === 0) state.pendingFrom = state.rxSeq;
+  requestResume(state);
+  if (state.gapTimer === null) {
+    state.gapTimer = setTimeout(() => {
+      state.gapTimer = null;
+      // server could not fill the hole (resume-miss / offline) — accept loss
+      flushPending(state);
+    }, state.resume.timeoutMs);
+  }
+  return true;
+}
+
 export function handleControl(state: ClientState, name: ControlEventName, payload: unknown): void {
   switch (name) {
     case "hello": {
@@ -44,6 +147,37 @@ export function handleControl(state: ClientState, name: ControlEventName, payloa
       state.groups = [...p.groups];
       break;
     }
+    case "resumed": {
+      state.resumeInFlight = false;
+      const p = payload as ControlEvents["resumed"];
+      if (!p.ok && p.from === 0) {
+        // server has nothing after our seq (fresh process / grave evicted) —
+        // accept the loss and continue from the buffered frames
+        flushPending(state);
+      }
+      // ok=true: replayed frames follow with their original seqs and slot
+      // into the ordering gate automatically.
+      break;
+    }
+    case "rpcResult": {
+      const p = payload as ControlEvents["rpcResult"];
+      const call = state.rpcPending.get(p.id);
+      if (!call) break;
+      state.rpcPending.delete(p.id);
+      clearTimeout(call.timer);
+      if (!p.ok) {
+        call.reject(new Error(`ignex rpc "${call.name}" failed: ${p.err}`));
+        break;
+      }
+      try {
+        const bytes = Uint8Array.from(atob(p.payloadB64), (c) => c.charCodeAt(0));
+        const frame = state.bindings.decodeFrame(bytes);
+        call.resolve(frame?.payload);
+      } catch (err) {
+        call.reject(err instanceof Error ? err : new Error("ignex rpc: bad result"));
+      }
+      break;
+    }
     case "pong":
       state.lastPong = Date.now();
       break;
@@ -55,17 +189,17 @@ export function handleControl(state: ClientState, name: ControlEventName, payloa
 export function handleMessage(state: ClientState, data: ArrayBuffer | string): void {
   if (typeof data === "string") return; // ignore text frames
   const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : (data as Uint8Array);
-  const frame = state.bindings.decodeFrame(bytes);
-  if (!frame) {
+  // fast envelope check before any decode
+  const header = state.bindings.readFrameHeader(bytes);
+  if (!header) {
     emitError(state, new Error("ignex: undecodable / version-mismatched frame dropped"));
     return;
   }
-  if (state.bindings.isControlId(frame.id)) {
-    handleControl(state, frame.name as ControlEventName, frame.payload);
+  if (state.bindings.isControlId(header.id)) {
+    handleControl(state, header.name as ControlEventName, state.bindings.decodePayload(header.id, bytes));
     return;
   }
-  const name = frame.name;
-  const set = state.handlers.get(name);
-  if (set) for (const cb of set) cb(frame.payload);
-  for (const cb of state.anyHandlers) cb(name, frame.payload);
+  const seq = readDeliverySeq(state, bytes);
+  if (seq !== null && orderedDeliver(state, bytes, seq)) return;
+  dispatchAppFrame(state, bytes);
 }

package/src/core/client.ts

@@ -12,9 +12,15 @@
  */
 import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../bindings/types";
 import { createClientState, setStatus, type ClientState, type ClientStatus, type IgnClientOptions } from "./client-state";
-import { handleMessage, sendControl, sendFrame } from "./client-wire";
+import { handleMessage, emitError, sendControl, sendFrame, flushPending } from "./client-wire";
 import { startHeartbeat, stopHeartbeat } from "./client-heartbeat";
 import { scheduleReconnect } from "./client-reconnect";
+import { failAllPending, createRpcRequest } from "./client-rpc";
+
+/** Result of a request/response round-trip. */
+export interface RpcResult<P> {
+  payload: P;
+}
 
 /** The public client API (returned by `createClient`). */
 export interface IgnClient<B extends Bindings = DefaultBindings> {
@@ -40,9 +46,21 @@ export interface IgnClient<B extends Bindings = DefaultBindings> {
   close(): void;
   /** Send a typed app event to the server (server must allow it via `inbound`). */
   send<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K]): void;
+  /**
+   * Request/response: send `name` and await the responder's payload (encoded
+   * with the SAME event schema). Rejects on timeout (`timeoutMs`, default
+   * `requestTimeoutMs`) or when no responder is registered server-side.
+   */
+  request<K extends EventNameOf<B>>(
+    name: K,
+    payload: EventsOf<B>[K],
+    opts?: { readonly timeoutMs?: number },
+  ): Promise<RpcResult<EventsOf<B>[K]>>;
   /** Ask the server to subscribe this socket to a topic (room membership + replay). */
   subscribe(topic: string): void;
   unsubscribe(topic: string): void;
+  /** Ask the server to re-send recorded topic history strictly after `fromSeq`. */
+  snapshotRequest(topic: string, fromSeq?: number): void;
   /** Ask the server to add this socket to a server-side group. */
   joinGroup(group: string): void;
   leaveGroup(group: string): void;
@@ -59,22 +77,54 @@ export function createClient<B extends Bindings = DefaultBindings>(
   const state: ClientState = createClientState(url, opts);
 
   function connect(): IgnClient<B> {
+    // idempotent: an already-open / opening socket is never leaked or replaced
+    if (state.ws !== null) {
+      const ready = state.ws.readyState;
+      if (ready === WebSocket.OPEN || ready === WebSocket.CONNECTING) return api;
+    }
     state.closed = false;
     setStatus(state, state.attempts === 0 ? "connecting" : "reconnecting");
     const ws = new WebSocket(url);
     ws.binaryType = "arraybuffer";
+    // ownership guard: once a NEWER socket occupies `state.ws`, callbacks from
+    // this (stale) socket must not touch shared state or reschedule reconnects
+    const ownsState = (): boolean => state.ws === null || state.ws === ws;
     ws.onopen = () => {
+      if (!ownsState()) return;
       state.attempts = 0;
       setStatus(state, "connected");
-      sendControl(state, "hello", { version: state.bindings.wireVersion, caps: [], lastSeq: 0 });
+      state.resumeInFlight = false;
+      if (state.gapTimer !== null) {
+        clearTimeout(state.gapTimer);
+        state.gapTimer = null;
+      }
+      // carry the last contiguous delivery seq so a resume-capable server can
+      // re-send what this session missed (cross-session resume)
+      sendControl(state, "hello", {
+        version: state.bindings.wireVersion,
+        caps: [],
+        lastSeq: state.resume.enabled ? state.rxSeq : 0,
+      });
       // re-subscribe topics from before the disconnect (server cleared them)
       for (const t of state.subscribedTopics) sendControl(state, "subscribe", { topic: t });
       startHeartbeat(state);
     };
-    ws.onmessage = (ev) => handleMessage(state, ev.data as ArrayBuffer | string);
+    ws.onmessage = (ev) => {
+      if (!ownsState()) return;
+      handleMessage(state, ev.data as ArrayBuffer | string);
+    };
+    ws.onerror = () => {
+      // surface refused upgrades / transport failures (onclose follows and
+      // drives the reconnect state machine — no double scheduling here)
+      if (!ownsState()) return;
+      emitError(state, new Error("ignex: connection error"));
+    };
     ws.onclose = () => {
+      if (!ownsState()) return; // replaced by a newer socket — its lifecycle wins
       stopHeartbeat(state);
       state.ws = null;
+      state.resumeInFlight = false;
+      flushPending(state); // accept in-flight gap loss; hello carries rxSeq on reconnect
       if (state.closed) {
         setStatus(state, "closed");
         return;
@@ -148,6 +198,13 @@ export function createClient<B extends Bindings = DefaultBindings>(
       stopHeartbeat(state);
       if (state.reconnectTimer) clearTimeout(state.reconnectTimer);
       state.reconnectTimer = null;
+      if (state.gapTimer !== null) {
+        clearTimeout(state.gapTimer);
+        state.gapTimer = null;
+      }
+      state.pending.clear();
+      state.pendingFrom = 0;
+      failAllPending(state, new Error("ignex: client closed"));
       state.ws?.close();
       state.ws = null;
       setStatus(state, "closed");
@@ -155,6 +212,15 @@ export function createClient<B extends Bindings = DefaultBindings>(
     send(name, payload) {
       sendFrame(state, state.bindings.encodeFrame(name, payload));
     },
+    request(name, payload, opts) {
+      return createRpcRequest(
+        state,
+        name,
+        payload,
+        opts,
+        state.bindings,
+      ) as Promise<RpcResult<EventsOf<B>[typeof name]>>;
+    },
     subscribe(topic) {
       state.subscribedTopics.add(topic);
       sendControl(state, "subscribe", { topic });
@@ -163,6 +229,9 @@ export function createClient<B extends Bindings = DefaultBindings>(
       state.subscribedTopics.delete(topic);
       sendControl(state, "unsubscribe", { topic });
     },
+    snapshotRequest(topic, fromSeq = 0) {
+      sendControl(state, "snapshotRequest", { topic, fromSeq });
+    },
     joinGroup(group) {
       sendControl(state, "joinGroup", { group });
     },

package/src/core/groups.ts

@@ -14,6 +14,11 @@ import type { ServerState, WsData } from "./state";
 
 /** Add `ws` to `group` (idempotent) and index it in `state.groups`. */
 export function joinGroup(state: ServerState, ws: ServerWebSocket<WsData>, group: string): void {
+  // every join path (control frames, programmatic, auth-seeded) is gated
+  if (state.authorizeGroup !== undefined && !state.authorizeGroup(group, ws)) {
+    state.metrics.rejectedJoins++;
+    return;
+  }
   ws.data.groups.add(group);
   let set = state.groups.get(group);
   if (!set) {

package/src/core/metrics.ts

@@ -1,8 +1,11 @@
 /**
  * Server-side metrics counters — a `createMetrics()` factory returning a plain
- * counter object (no class, no `this`). Zero dependencies, no allocations in
- * the steady state (counters are plain numbers; `countPath` only allocates on
- * the first occurrence of an event name).
+ * counter object (no class, no `this`). Zero dependencies and zero allocation
+ * in the steady state (every counter is a plain number field).
+ *
+ * Per-event encode-path counts (`pathCounts`) are NOT tracked here: they live
+ * once, cumulatively, in the transport's per-event records and are derived at
+ * read time by `server.getMetrics()` — polling can never double-count.
  */
 export interface PathCounts {
   /** encodes that used the zero-alloc Rust FFI direct fast path */
@@ -30,8 +33,20 @@ export interface MetricsSnapshot {
   inboundControl: number;
   /** undecodable / version-mismatched / unknown-id frames received */
   protocolErrors: number;
+  /** inbound frames shed by the per-connection rate limiter */
+  rateLimited: number;
+  /** topic/group joins rejected by `authorizeTopic` / `authorizeGroup` */
+  rejectedJoins: number;
   bytesSent: number;
-  /** per-event encode path counts (direct vs json vs js) */
+  /** frames stamped with a per-connection delivery seq (envelope v2, resume on) */
+  stampedSeq: number;
+  /** `resume` control frames served from a connection's history ring */
+  resumesServed: number;
+  /** frames re-delivered by resume replays */
+  framesReplayed: number;
+  /** resume requests that could not fully fill the requested hole */
+  resumeMisses: number;
+  /** per-event encode path counts (derived from the transport at read time) */
   pathCounts: Record<string, PathCounts>;
   connectedClients: number;
   uptimeMs: number;
@@ -56,16 +71,17 @@ export interface Metrics {
   inbound: number;
   inboundControl: number;
   protocolErrors: number;
+  rateLimited: number;
+  rejectedJoins: number;
   bytesSent: number;
-  readonly pathCounts: Map<string, PathCounts>;
-  /** Count an encode on a given path for an event (direct = zero-alloc FFI). */
-  countPath(name: string, path: "direct" | "json" | "js"): void;
+  stampedSeq: number;
+  resumesServed: number;
+  framesReplayed: number;
+  resumeMisses: number;
   snapshot(connectedClients: number): MetricsSnapshot;
 }
 
 export function createMetrics(startedAt = Date.now()): Metrics {
-  const pathCounts = new Map<string, PathCounts>();
-
   const m: Metrics = {
     published: 0,
     sent: 0,
@@ -75,19 +91,14 @@ export function createMetrics(startedAt = Date.now()): Metrics {
     inbound: 0,
     inboundControl: 0,
     protocolErrors: 0,
+    rateLimited: 0,
+    rejectedJoins: 0,
     bytesSent: 0,
-    pathCounts,
-    countPath(name, path) {
-      let pc = pathCounts.get(name);
-      if (!pc) {
-        pc = { direct: 0, json: 0, js: 0 };
-        pathCounts.set(name, pc);
-      }
-      pc[path]++;
-    },
+    stampedSeq: 0,
+    resumesServed: 0,
+    framesReplayed: 0,
+    resumeMisses: 0,
     snapshot(connectedClients) {
-      const pathCountsObj: Record<string, PathCounts> = {};
-      for (const [name, pc] of pathCounts) pathCountsObj[name] = { ...pc };
       return {
         published: m.published,
         sent: m.sent,
@@ -97,8 +108,14 @@ export function createMetrics(startedAt = Date.now()): Metrics {
         inbound: m.inbound,
         inboundControl: m.inboundControl,
         protocolErrors: m.protocolErrors,
+        rateLimited: m.rateLimited,
+        rejectedJoins: m.rejectedJoins,
         bytesSent: m.bytesSent,
-        pathCounts: pathCountsObj,
+        stampedSeq: m.stampedSeq,
+        resumesServed: m.resumesServed,
+        framesReplayed: m.framesReplayed,
+        resumeMisses: m.resumeMisses,
+        pathCounts: {},
         connectedClients,
         uptimeMs: Date.now() - startedAt,
       };