@ignex/nova 0.1.1

package/rust/src/transcode/mod.rs

@@ -0,0 +1,2 @@
+// @generated by scripts/generate.ts — DO NOT EDIT
+pub mod generated;

package/src/bridge/nats.ts

@@ -0,0 +1,269 @@
+/**
+ * NATS bridge — bidirectional FlatBuffer transport over NATS.
+ *
+ * OUTBOUND: the server encodes each event ONCE (Rust FFI → scratch), fans the
+ * same frame out to WS clients, then hands a COPY to `bridge.publish(subject,
+ * frame)` so other applications consume the identical wire bytes. Best-effort:
+ * if NATS is down the frame is dropped and counted in `bridgeErrors` — it
+ * never blocks or throws on the WS hot path.
+ *
+ * INBOUND: when `inbound` is enabled the bridge subscribes to `{prefix}.
+ * inbound.>` and forwards decodable app events to `onInbound` (wired by the
+ * server to fan out to clients). Control frames and unknown ids are dropped.
+ *
+ * The connection is created eagerly but non-blocking: `connect()` runs in the
+ * background with a retry loop, so a server can start while NATS is down.
+ * `createNatsBridge(opts, transport?)` accepts an injectable `NatsTransport`
+ * so tests can fake NATS entirely (no server needed in CI).
+ */
+import { connect, type NatsConnection } from "nats";
+import { decodePayload, isControlId, readFrameHeader } from "../generated/registry";
+import type { EventName } from "../schema";
+import { createSubjectBuilder, type SubjectBuilder } from "./subjects";
+
+export type NatsBridgeStatus = "connected" | "connecting" | "closed";
+
+export interface NatsBridgeOptions {
+  /** NATS servers, default ["nats://localhost:4222"] */
+  servers?: string[];
+  /** subject prefix, default "ignex" */
+  subjectPrefix?: string;
+  /** connect timeout (ms), default 5000 */
+  connectTimeout?: number;
+  /** how long to wait before retrying a failed initial connect (ms), default 2000 */
+  connectRetryMs?: number;
+  /** reconnect handled by nats.js (core NATS, no durable queues), default true */
+  reconnect?: boolean;
+  /** optional NATS token (auth) */
+  token?: string;
+  /** subscribe to inbound subjects and forward events to clients, default false */
+  inbound?: boolean;
+  /** inbound subjects (default `{prefix}.inbound.>`), requires `inbound` */
+  inboundSubjects?: string[];
+  /** only forward these inbound events (default: every app event) */
+  inboundEvents?: EventName[];
+}
+
+/** Counters folded into `server.getMetrics()`. */
+export interface NatsBridgeStats {
+  bridged: number;
+  bridgedBytes: number;
+  bridgeErrors: number;
+  bridgeInbound: number;
+  bridgeInboundErrors: number;
+}
+
+/** Minimal transport — a real NATS connection or a test fake. */
+export interface NatsTransport {
+  readonly connected: boolean;
+  /** synchronously send bytes; throws when not connected (bridge catches + counts) */
+  publish(subject: string, data: Uint8Array): void;
+  /** subscribe; `cb` receives message bytes; returns an unsubscribe function */
+  subscribe(subject: string, cb: (data: Uint8Array) => void): () => void;
+  close(): Promise<void>;
+}
+
+export interface NatsBridge {
+  readonly status: NatsBridgeStatus;
+  readonly subjects: SubjectBuilder;
+  readonly stats: NatsBridgeStats;
+  /** publish a frame to `subject` (copies the bytes — safe after scratch reuse) */
+  publish(subject: string, frame: Uint8Array): void;
+  /** wire the inbound → clients forward (set once by the server) */
+  setOnInbound(cb: (name: EventName, payload: unknown) => void): void;
+  close(): Promise<void>;
+}
+
+/** Eager, non-blocking real transport with an initial-connect retry loop. */
+function createRealTransport(opts: NatsBridgeOptions): NatsTransport {
+  let nc: NatsConnection | null = null;
+  let connected = false;
+  let closed = false;
+  const subs: Array<{ subject: string; cb: (data: Uint8Array) => void }> = [];
+  let unsubs: Array<() => void> = [];
+
+  const sync = (): void => {
+    for (const u of unsubs) u();
+    unsubs = [];
+    if (!nc) return;
+    for (const s of subs) {
+      const sub = nc.subscribe(s.subject);
+      unsubs.push(() => sub.unsubscribe());
+      void (async () => {
+        try {
+          for await (const m of sub) s.cb(new Uint8Array(m.data));
+        } catch {
+          // subscription ended / connection closed
+        }
+      })();
+    }
+  };
+
+  const attachStatus = (conn: NatsConnection): void => {
+    void conn
+      .closed()
+      .then(() => {
+        connected = false;
+        if (nc === conn) nc = null;
+      })
+      .catch(() => {
+        connected = false;
+      });
+    void (async () => {
+      try {
+        for await (const st of conn.status()) {
+          if (st.type === "disconnect") connected = false;
+          else if (st.type === "reconnect") {
+            connected = true;
+            sync(); // nats.js re-subscribes automatically; resync to be safe
+          }
+        }
+      } catch {
+        connected = false;
+      }
+    })();
+  };
+
+  const tryConnect = async (): Promise<void> => {
+    if (closed) return;
+    try {
+      const conn = await connect({
+        servers: opts.servers ?? ["nats://localhost:4222"],
+        token: opts.token,
+        timeout: opts.connectTimeout ?? 5000,
+        reconnect: opts.reconnect ?? true,
+        maxReconnectAttempts: -1,
+      });
+      nc = conn;
+      connected = true;
+      attachStatus(conn);
+      sync();
+    } catch {
+      connected = false;
+    }
+  };
+
+  void (async () => {
+    while (!closed) {
+      if (!nc || !connected) await tryConnect();
+      await Bun.sleep(opts.connectRetryMs ?? 2000);
+    }
+  })();
+
+  return {
+    get connected() {
+      return connected;
+    },
+    publish(subject, data) {
+      if (!nc) throw new Error("nats: not connected");
+      nc.publish(subject, data);
+    },
+    subscribe(subject, cb) {
+      subs.push({ subject, cb });
+      sync();
+      return () => {
+        const i = subs.findIndex((s) => s.subject === subject && s.cb === cb);
+        if (i >= 0) subs.splice(i, 1);
+        sync();
+      };
+    },
+    async close() {
+      closed = true;
+      if (nc) {
+        try {
+          await nc.close();
+        } catch {
+          // already closed
+        }
+      }
+      nc = null;
+      connected = false;
+    },
+  };
+}
+
+export function createNatsBridge(
+  opts: NatsBridgeOptions = {},
+  transport?: NatsTransport,
+): NatsBridge {
+  const t = transport ?? createRealTransport(opts);
+  const subjects = createSubjectBuilder(opts.subjectPrefix);
+  const stats: NatsBridgeStats = {
+    bridged: 0,
+    bridgedBytes: 0,
+    bridgeErrors: 0,
+    bridgeInbound: 0,
+    bridgeInboundErrors: 0,
+  };
+  let closed = false;
+  let onInbound: ((name: EventName, payload: unknown) => void) | null = null;
+  const allowlist = opts.inboundEvents ? new Set(opts.inboundEvents) : null;
+
+  // inbound subscriptions (lazy — the transport queues them until connected)
+  const subscribeInbound = (subject: string): (() => void) => {
+    return t.subscribe(subject, (data) => {
+      const header = readFrameHeader(data);
+      if (!header) {
+        stats.bridgeInboundErrors++;
+        return;
+      }
+      if (isControlId(header.id)) {
+        stats.bridgeInboundErrors++; // never forward transport-internal frames
+        return;
+      }
+      const name = header.name as EventName;
+      if (allowlist && !allowlist.has(name)) return;
+      let payload: unknown;
+      try {
+        payload = decodePayload(header.id, data);
+      } catch {
+        stats.bridgeInboundErrors++;
+        return;
+      }
+      stats.bridgeInbound++;
+      onInbound?.(name, payload);
+    });
+  };
+
+  const unsubs: Array<() => void> = [];
+  if (opts.inbound) {
+    const subjectsList = opts.inboundSubjects?.length ? opts.inboundSubjects : [subjects.inboundPrefix()];
+    for (const subject of subjectsList) unsubs.push(subscribeInbound(subject));
+  }
+
+  return {
+    get status(): NatsBridgeStatus {
+      if (closed) return "closed";
+      return t.connected ? "connected" : "connecting";
+    },
+    get subjects() {
+      return subjects;
+    },
+    get stats() {
+      return stats;
+    },
+    publish(subject, frame) {
+      if (!t.connected) {
+        stats.bridgeErrors++;
+        return;
+      }
+      // the frame view is a reused scratch — copy before handing to NATS
+      const copy = frame.slice();
+      try {
+        t.publish(subject, copy);
+        stats.bridged++;
+        stats.bridgedBytes += copy.byteLength;
+      } catch {
+        stats.bridgeErrors++;
+      }
+    },
+    setOnInbound(cb) {
+      onInbound = cb;
+    },
+    async close() {
+      closed = true;
+      for (const u of unsubs) u();
+      await t.close();
+    },
+  };
+}

package/src/bridge/subjects.ts

@@ -0,0 +1,30 @@
+/**
+ * NATS subject naming for the ignex bridge.
+ *
+ * Every publish the server fans out to WS clients can ALSO be bridged to NATS
+ * so other applications consume the exact same FlatBuffer wire frame. Subjects
+ * are derived from the routing context:
+ *
+ *   - global publish            → `{prefix}.broadcast.{event}`
+ *   - publishToTopic(topic,..)  → `{prefix}.topic.{topic}.{event}`
+ *   - publishToGroup(group,..)  → `{prefix}.group.{group}.{event}`
+ *
+ * External apps push events INTO the hub by publishing on `{prefix}.inbound.>`
+ * (the default inbound subscription; the server forwards them to all clients).
+ */
+export interface SubjectBuilder {
+  broadcast(name: string): string;
+  topic(topic: string, name: string): string;
+  group(group: string, name: string): string;
+  /** wildcard subject the server subscribes to for inbound events */
+  inboundPrefix(): string;
+}
+
+export function createSubjectBuilder(prefix = "ignex"): SubjectBuilder {
+  return {
+    broadcast: (name) => `${prefix}.broadcast.${name}`,
+    topic: (topic, name) => `${prefix}.topic.${topic}.${name}`,
+    group: (group, name) => `${prefix}.group.${group}.${name}`,
+    inboundPrefix: () => `${prefix}.inbound.>`,
+  };
+}

package/src/core/auth.ts

@@ -0,0 +1,56 @@
+/**
+ * Upgrade gate — pure-ish decision logic for who may open a WebSocket:
+ * connection limit → origin allowlist → bearer token → custom `authenticate`.
+ * Returns a `Response` to reject the upgrade, or `undefined` to allow it
+ * (after calling `srv.upgrade`). Mirrors the former `IgnServer.tryUpgrade`.
+ *
+ * `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).
+ */
+import type { ClientMeta, ServerState, WsData } from "./state";
+
+export async function checkUpgrade(
+  state: ServerState,
+  req: Request,
+  srv: ReturnType<typeof Bun.serve<WsData>>,
+): Promise<Response | undefined> {
+  if (state.maxConnections !== undefined && state.sockets.size >= state.maxConnections) {
+    return new Response("too many connections", { status: 503 });
+  }
+  if (state.allowedOrigins) {
+    const origin = req.headers.get("origin") ?? "";
+    if (!state.allowedOrigins.includes(origin)) {
+      return new Response("origin not allowed", { status: 403 });
+    }
+  }
+  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;
+    if (!ok) return new Response("unauthorized", { status: 401 });
+  }
+  let authMeta: ClientMeta | undefined;
+  if (state.authenticate) {
+    const res = await state.authenticate(req);
+    if (!res) return new Response("unauthorized", { status: 401 });
+    if (typeof res === "object") authMeta = res;
+  }
+  // identity: explicit id from auth, else a fresh UUID. Duplicate ids are
+  // rejected up-front (an admin can `disconnectClient` the stale session).
+  const id = authMeta?.id ?? crypto.randomUUID();
+  if (state.clients.has(id)) {
+    return new Response("client id already in use", { status: 409 });
+  }
+  const data: WsData = {
+    lastSeq: 0,
+    topics: new Set(),
+    groups: new Set(authMeta?.groups ?? []),
+    id,
+    meta: authMeta?.meta,
+    connectedAt: Date.now(),
+  };
+  // bun-types requires the WebSocketData options arg when Data != undefined
+  if (srv.upgrade(req, { data })) return undefined;
+  return new Response("upgrade failed", { status: 400 });
+}

package/src/core/backpressure.ts

@@ -0,0 +1,39 @@
+/**
+ * Backpressure decision — a PURE function: given the policy + the socket's
+ * current state, return what `outbound.sendFrame` should do. No side effects
+ * here (no queue mutation, no counters) — that makes each policy testable in
+ * isolation and keeps the actual effects in exactly one place (`outbound.ts`).
+ */
+import type { ServerWebSocket } from "bun";
+import type { IgnBackpressureOptions, WsData } from "./state";
+
+export type SendDecision =
+  | { kind: "send" }
+  | { kind: "close" }
+  | { kind: "drop-newest" }
+  /** push the frame to the socket's drop-oldest queue, then trim `dropHead` oldest */
+  | { kind: "enqueue"; dropHead: number };
+
+export function decide(
+  bp: Required<IgnBackpressureOptions>,
+  ws: ServerWebSocket<WsData>,
+): SendDecision {
+  const hwm = bp.highWaterMark;
+  switch (bp.policy) {
+    case "disconnect":
+      return ws.getBufferedAmount() > hwm ? { kind: "close" } : { kind: "send" };
+    case "drop-newest":
+      return ws.getBufferedAmount() > hwm ? { kind: "drop-newest" } : { kind: "send" };
+    case "drop-oldest":
+    default: {
+      const q = ws.data.queue;
+      if (q && q.length > 0) {
+        // already backed up — enqueue an owned copy; while over maxQueue, drop from the head
+        const dropHead = Math.max(0, q.length + 1 - bp.maxQueue);
+        return { kind: "enqueue", dropHead };
+      }
+      if (ws.getBufferedAmount() > hwm) return { kind: "enqueue", dropHead: 0 };
+      return { kind: "send" };
+    }
+  }
+}

package/src/core/client-heartbeat.ts

@@ -0,0 +1,27 @@
+/**
+ * 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";
+
+export function startHeartbeat(state: ClientState): void {
+  const ms = state.opts.heartbeatMs ?? 15000;
+  if (ms <= 0) return;
+  state.lastPong = Date.now();
+  sendControl(state, "ping", { ts: Date.now() });
+  const misses = Math.max(1, state.opts.heartbeatMisses ?? 2);
+  state.heartbeatTimer = setInterval(() => {
+    if (Date.now() - state.lastPong > ms * misses) {
+      // connection is dead — force close so onclose triggers reconnect
+      state.ws?.close();
+      return;
+    }
+    sendControl(state, "ping", { ts: Date.now() });
+  }, ms);
+}
+
+export function stopHeartbeat(state: ClientState): void {
+  if (state.heartbeatTimer) clearInterval(state.heartbeatTimer);
+  state.heartbeatTimer = null;
+}

package/src/core/client-reconnect.ts

@@ -0,0 +1,35 @@
+/**
+ * Client auto-reconnect — pure backoff math (`nextDelay`) + a scheduler that
+ * 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";
+
+/** Resolve the effective reconnect options (defaults applied). */
+export function reconnectOpts(opts: IgnClientOptions): IgnReconnectOptions | null {
+  const rc = opts.reconnect;
+  if (rc === undefined || rc === false) return null;
+  if (rc === true) return { initialDelay: 250, maxDelay: 30000, jitter: true };
+  return { initialDelay: 250, maxDelay: 30000, jitter: true, ...rc };
+}
+
+/** Pure exponential-backoff delay (ms) for a given attempt count. */
+export function nextDelay(attempts: number, opts: IgnReconnectOptions): number {
+  const initial = opts.initialDelay ?? 250;
+  const max = opts.maxDelay ?? 30000;
+  const base = Math.min(initial * 2 ** attempts, max);
+  return opts.jitter === false ? base : base * (0.5 + Math.random());
+}
+
+export function scheduleReconnect(state: ClientState, connect: () => void): void {
+  const rc = reconnectOpts(state.opts);
+  if (!rc) {
+    setStatus(state, "closed");
+    return;
+  }
+  setStatus(state, "disconnected");
+  const delay = nextDelay(state.attempts, rc);
+  state.attempts++;
+  setStatus(state, "reconnecting");
+  state.reconnectTimer = setTimeout(() => connect(), delay);
+}

package/src/core/client-state.ts

@@ -0,0 +1,76 @@
+/**
+ * Client state + option types. `createClientState(url, opts)` builds the single
+ * 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";
+
+export type ClientStatus = "connecting" | "connected" | "disconnected" | "reconnecting" | "closed";
+
+export interface IgnReconnectOptions {
+  /** initial reconnect delay (ms), default 250 */
+  initialDelay?: number;
+  /** maximum reconnect delay (ms), default 30000 */
+  maxDelay?: number;
+  /** randomize each delay (×0.5–1.5), default true */
+  jitter?: boolean;
+}
+
+export interface IgnClientOptions {
+  /** 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;
+}
+
+type Handler<K extends EventName> = (payload: Events[K]) => void;
+
+export interface ClientState {
+  url: string;
+  opts: IgnClientOptions;
+  ws: WebSocket | null;
+  handlers: Map<EventName, Set<Handler<never>>>;
+  anyHandlers: Set<(name: EventName, payload: unknown) => void>;
+  errorCbs: Set<(err: Error) => void>;
+  statusCbs: Set<(status: ClientStatus) => void>;
+  closed: boolean;
+  reconnectTimer: ReturnType<typeof setTimeout> | null;
+  heartbeatTimer: ReturnType<typeof setInterval> | null;
+  attempts: number;
+  status: ClientStatus;
+  subscribedTopics: Set<string>;
+  lastPong: number;
+  /** id the server assigned to this connection (from `welcome`; "" until known) */
+  clientId: string;
+  /** server-side groups this client belongs to (from `welcome`; [] until known) */
+  groups: string[];
+}
+
+export function createClientState(url: string, opts: IgnClientOptions = {}): ClientState {
+  return {
+    url,
+    opts,
+    ws: null,
+    handlers: new Map(),
+    anyHandlers: new Set(),
+    errorCbs: new Set(),
+    statusCbs: new Set(),
+    closed: false,
+    reconnectTimer: null,
+    heartbeatTimer: null,
+    attempts: 0,
+    status: "closed",
+    subscribedTopics: new Set(),
+    lastPong: 0,
+    clientId: "",
+    groups: [],
+  };
+}
+
+export function setStatus(state: ClientState, s: ClientStatus): void {
+  if (state.status === s) return;
+  state.status = s;
+  for (const cb of state.statusCbs) cb(s);
+}

package/src/core/client-wire.ts

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+import { decodeFrame, isControlId, WIRE_VERSION } from "../generated/registry";
+import { encodeEventFrame } from "../generated/ts-ser";
+import type { ControlEventName, ControlEvents, EventName } from "../schema";
+import type { ClientState } from "./client-state";
+
+/** Send an encoded frame, if the socket is open. */
+export function sendFrame(state: ClientState, frame: Uint8Array): void {
+  const ws = state.ws;
+  if (!ws || ws.readyState !== WebSocket.OPEN) throw new Error("ignex: client is not connected");
+  // Bun's send() wants an ArrayBuffer-backed view; cast the (owned) frame.
+  ws.send(frame as Uint8Array<ArrayBuffer>);
+}
+
+export function sendControl<K extends ControlEventName>(
+  state: ClientState,
+  name: K,
+  payload: ControlEvents[K],
+): void {
+  sendFrame(state, encodeEventFrame(name, payload));
+}
+
+export function emitError(state: ClientState, err: Error): void {
+  for (const cb of state.errorCbs) cb(err);
+}
+
+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) {
+        // 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}`));
+      }
+      break;
+    }
+    case "welcome": {
+      const p = payload as ControlEvents["welcome"];
+      state.clientId = p.clientId;
+      state.groups = [...p.groups];
+      break;
+    }
+    case "pong":
+      state.lastPong = Date.now();
+      break;
+    default:
+      break;
+  }
+}
+
+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) {
+    emitError(state, new Error("ignex: undecodable / version-mismatched frame dropped"));
+    return;
+  }
+  if (isControlId(frame.id)) {
+    handleControl(state, frame.name as ControlEventName, frame.payload);
+    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);
+}