@ignex/nova 0.1.1 → 0.1.5

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

@@ -10,11 +10,14 @@
  * going to discard.
  */
 import type { ServerWebSocket } from "bun";
-import { decodePayload, isControlId, readFrameHeader, WIRE_VERSION } from "../generated/registry";
-import type { ControlEventName, ControlEvents, EventName } from "../schema";
-import { sendControl } from "./outbound";
+import type { ControlEventName, ControlEvents } from "../schema";
+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
@@ -25,26 +28,84 @@ 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;
   }
-  const header = readFrameHeader(bytes);
+  // 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++;
     return; // undecodable / wrong version / unknown id — drop
   }
-  if (isControlId(header.id)) {
+  if (state.bindings.isControlId(header.id)) {
     state.metrics.inboundControl++;
-    handleControl(state, ws, header.name as ControlEventName, decodePayload(header.id, bytes) as never);
+    handleControl(state, ws, header.name as ControlEventName, state.bindings.decodePayload(header.id, bytes) as never);
     return;
   }
-  const name = header.name as EventName;
+  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)?.(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
+  // arrive via `onInbound` → `fanOutAll` (never through this path), so there is
+  // no loop; this server's own clients are re-delivered exactly once through its
+  // own inbound subscription (the app handler should therefore not ALSO
+  // broadcast, or the event would be delivered twice locally).
+  if (state.bridge?.clientEvents) {
+    state.bridge.publish(state.bridge.subjects.inboundEvent(name), bytes);
+  }
 }
 
 export function handleControl(
@@ -58,12 +119,33 @@ export function handleControl(
       const p = payload as ControlEvents["hello"];
       ws.data.version = p.version;
       ws.data.lastSeq = p.lastSeq;
-      if (p.version !== WIRE_VERSION) {
+      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": {
       joinRoom(state, ws, (payload as ControlEvents["subscribe"]).topic);
       break;
@@ -87,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 });
+}