@ignex/nova 0.1.3 → 0.1.6

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

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. */