@ignex/nova 0.1.1 → 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,10 +104,12 @@ export async function checkUpgrade(
   }
   const data: WsData = {
     lastSeq: 0,
+    sendSeq: 1,
     topics: new Set(),
     groups: new Set(authMeta?.groups ?? []),
     id,
-    meta: authMeta?.meta,
+    ...(authMeta?.userId !== undefined ? { userId: authMeta.userId } : {}),
+    ...(authMeta?.meta !== undefined ? { meta: authMeta.meta } : {}),
     connectedAt: Date.now(),
   };
   // bun-types requires the WebSocketData options arg when Data != undefined

package/src/core/client-heartbeat.ts

@@ -2,8 +2,9 @@
  * Client app-level Ping/Pong heartbeat — detects half-open connections and
  * forces a close so the reconnect path re-establishes the socket.
  */
-import { sendControl } from "./client-wire";
+
 import type { ClientState } from "./client-state";
+import { sendControl } from "./client-wire";
 
 export function startHeartbeat(state: ClientState): void {
   const ms = state.opts.heartbeatMs ?? 15000;

package/src/core/client-reconnect.ts

@@ -3,10 +3,17 @@
  * drives the state machine. `connect` is passed in by the composition root so
  * the timer can re-establish the socket.
  */
-import { setStatus, type ClientState, type IgnClientOptions, type IgnReconnectOptions } from "./client-state";
+
+import type { Bindings } from "../bindings/types";
+import {
+  type ClientState,
+  type IgnClientOptions,
+  type IgnReconnectOptions,
+  setStatus,
+} from "./client-state";
 
 /** Resolve the effective reconnect options (defaults applied). */
-export function reconnectOpts(opts: IgnClientOptions): IgnReconnectOptions | null {
+export function reconnectOpts(opts: IgnClientOptions<Bindings>): IgnReconnectOptions | null {
   const rc = opts.reconnect;
   if (rc === undefined || rc === false) return null;
   if (rc === true) return { initialDelay: 250, maxDelay: 30000, jitter: true };

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

@@ -3,7 +3,9 @@
  * explicit state object the client action functions read/mutate. The option /
  * status types are the PUBLIC surface and are re-exported by `public/client.ts`.
  */
-import type { EventName, Events } from "../schema";
+
+import { defaultBindings } from "../bindings/default";
+import type { Bindings, DefaultBindings } from "../bindings/types";
 
 export type ClientStatus = "connecting" | "connected" | "disconnected" | "reconnecting" | "closed";
 
@@ -16,23 +18,40 @@ export interface IgnReconnectOptions {
   jitter?: boolean;
 }
 
-export interface IgnClientOptions {
+export interface IgnClientOptions<B extends Bindings = DefaultBindings> {
+  /**
+   * The wire stack (event ids, decoders, encoders). Defaults to the built-in
+   * registry; pass your own (from `generateBindings` + `assembleBindings`) to
+   * speak YOUR schema. When provided, the client API (`on` / `send` / ...) is
+   * typed against your `Events`.
+   */
+  bindings?: B;
   /** auto-reconnect on unexpected close, default false (boolean or options) */
   reconnect?: boolean | IgnReconnectOptions;
   /** app-level ping interval in ms (0 disables), default 15000 */
   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;
 }
 
-type Handler<K extends EventName> = (payload: Events[K]) => void;
-
 export interface ClientState {
   url: string;
-  opts: IgnClientOptions;
+  opts: IgnClientOptions<Bindings>;
+  /** the wire stack this client speaks (ids / decoders / encoders). */
+  bindings: Bindings;
   ws: WebSocket | null;
-  handlers: Map<EventName, Set<Handler<never>>>;
-  anyHandlers: Set<(name: EventName, payload: unknown) => void>;
+  handlers: Map<string, Set<(payload: unknown) => void>>;
+  anyHandlers: Set<(name: string, payload: unknown) => void>;
   errorCbs: Set<(err: Error) => void>;
   statusCbs: Set<(status: ClientStatus) => void>;
   closed: boolean;
@@ -46,12 +65,34 @@ 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(url: string, opts: IgnClientOptions = {}): ClientState {
+export function createClientState<B extends Bindings = DefaultBindings>(
+  url: string,
+  opts: IgnClientOptions<B> = {},
+): ClientState {
   return {
     url,
     opts,
+    bindings: opts.bindings ?? defaultBindings,
     ws: null,
     handlers: new Map(),
     anyHandlers: new Set(),
@@ -66,6 +107,20 @@ export function createClientState(url: string, opts: IgnClientOptions = {}): Cli
     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

@@ -1,11 +1,16 @@
 /**
  * Client wire handling — outbound frame sends + inbound decode/dispatch.
  * `handleMessage` decodes the envelope, filters control frames, and fans app
- * events out to the registered handlers.
+ * 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 { decodeFrame, isControlId, WIRE_VERSION } from "../generated/registry";
-import { encodeEventFrame } from "../generated/ts-ser";
-import type { ControlEventName, ControlEvents, EventName } from "../schema";
+import type { ControlEventName, ControlEvents } from "../schema";
 import type { ClientState } from "./client-state";
 
 /** Send an encoded frame, if the socket is open. */
@@ -21,21 +26,118 @@ export function sendControl<K extends ControlEventName>(
   name: K,
   payload: ControlEvents[K],
 ): void {
-  sendFrame(state, encodeEventFrame(name, payload));
+  sendFrame(state, state.bindings.encodeFrame(name, payload));
 }
 
 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": {
       const p = payload as ControlEvents["hello"];
-      if (p.version !== WIRE_VERSION) {
+      if (p.version !== state.bindings.wireVersion) {
         // server speaks a different wire version — refuse + surface
         state.ws?.close(1002, "wire version mismatch");
-        emitError(state, new Error(`ignex: server wire version ${p.version} does not match ${WIRE_VERSION}`));
+        emitError(state, new Error(`ignex: server wire version ${p.version} does not match ${state.bindings.wireVersion}`));
       }
       break;
     }
@@ -45,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;
@@ -56,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 = 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 (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 as EventName;
-  const set = state.handlers.get(name);
-  if (set) for (const cb of set) cb(frame.payload as never);
-  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);
 }