@ignex/nova 0.1.3 → 0.1.5

package/src/transport/transport.ts

@@ -14,18 +14,48 @@
  *     encoder (`bindings.encodeFrame`) — correct everywhere, slower, and the
  *     default when `ffiMode: "optional"` and no addon is available.
  *
- * `createTransport(bindings)` is a per-schema factory: it owns its own scratch +
- * stats + FFI binding, so several servers with different schemas can coexist.
- * The module-level `defaultTransport` (built-in registry, Rust required) keeps
- * the historical singleton behavior — `encodeToScratch` / `encodeEvent` /
- * `getEncodeStats` remain re-exported for backwards compatibility.
+ * ALL per-event dispatch state is resolved EAGERLY at `createTransport()`
+ * (instantiation time), not lazily on first encode: every known event name —
+ * app AND control — gets an {@link EncodeRecord} up front, holding its event
+ * id, generated encoder, NUL pre-scan and (once the addon binds) its direct
+ * FFI symbol + encode-path counters. The hot path is then one Map hit plus a
+ * couple of monomorphic field reads/increments — no lazy-init branches, no
+ * second stats Map, no per-encode counter allocation.
+ *
+ * `createTransport(bindings)` is a per-schema factory: it owns its own scratch
+ * + records + FFI binding, so several servers with different schemas can
+ * coexist. The module-level `defaultTransport` (built-in registry, Rust
+ * required) keeps the historical singleton behavior — `encodeToScratch` /
+ * `encodeEvent` / `getEncodeStats` remain re-exported for backwards compat.
  */
 
 import { defaultBindings } from "../bindings/default";
 import type { Bindings, DirectEncoder } from "../bindings/types";
 import { createFfi, type FfiDl } from "../native/ffi";
 import { createScratch, MIN_CAP } from "./scratch";
-import { createStats } from "./stats";
+
+/** Everything the hot path needs for one event — built once at instantiation. */
+interface EncodeRecord {
+  /** stable wire id (anyEventNameToId) — used by the JSON fallback */
+  readonly id: number;
+  /** generated zero-alloc encoder (absent for JSON-only events) */
+  readonly encoder: DirectEncoder | undefined;
+  /** FFI symbol name in the addon (absent when there is no direct table) */
+  readonly symName: string | undefined;
+  /** per-event NUL pre-scan (absent when the event has no string fields) */
+  readonly hasNul: ((o: unknown) => boolean) | undefined;
+  /**
+   * Resolved FFI symbol: undefined = not yet bound OR disabled/JSON-only.
+   * Flipped to a function once the addon binds; set back to undefined when a
+   * runtime failure (`ffiMode: "optional"`) permanently demotes this event to
+   * the JSON path.
+   */
+  call: ((...args: unknown[]) => number) | undefined;
+  /** encode-path counters — incremented IN PLACE on the record (no Maps) */
+  directCount: number;
+  jsonCount: number;
+  jsCount: number;
+}
 
 export interface Transport {
   /**
@@ -44,24 +74,26 @@ export interface Transport {
   };
 }
 
-/**
- * Resolved direct-path record for one event — populated lazily on first encode
- * and immutable afterwards (a direct symbol that was disabled by the bind-time
- * self-test never re-enables, so caching the resolved call is safe).
- */
-interface ResolvedDirect {
-  /** generated zero-alloc encoder (absent for JSON-only events) */
-  encoder?: DirectEncoder;
-  /** resolved FFI symbol (undefined = symbol disabled → JSON fallback) */
-  call: ((...args: unknown[]) => number) | undefined;
-  /** per-event NUL pre-scan (absent when the event has no string fields) */
-  hasNul?: (o: unknown) => boolean;
-}
-
 export function createTransport(bindings: Bindings): Transport {
   const scratch = createScratch();
-  const stats = createStats();
-  const resolvedDirect = new Map<string, ResolvedDirect>();
+
+  // ── instantiation-time resolution: one record per known event ────────────
+  const records = new Map<string, EncodeRecord>();
+  for (const name of Object.keys(bindings.anyEventNameToId)) {
+    const direct = bindings.direct;
+    const encoder = direct?.encoders[name];
+    const hasNul = direct?.hasNul[name];
+    records.set(name, {
+      id: bindings.anyEventNameToId[name] as number,
+      encoder,
+      ...(encoder !== undefined ? { symName: direct?.symbolNames[name] } : { symName: undefined }),
+      hasNul,
+      call: undefined,
+      directCount: 0,
+      jsonCount: 0,
+      jsCount: 0,
+    });
+  }
 
   // Lazily bound once: undefined = not yet resolved, null = JS-only mode,
   // FfiDl = bound addon. For ffiMode "required" the bind throws (missing /
@@ -73,77 +105,75 @@ export function createTransport(bindings: Bindings): Transport {
     return ffi;
   };
 
-  const guard = bindings.ffiMode === "optional";
-
-  function resolveDirect(name: string): ResolvedDirect {
-    let r = resolvedDirect.get(name);
-    if (r === undefined) {
-      r = { call: undefined };
-      const encoder = bindings.direct?.encoders[name];
-      if (encoder) {
-        r.encoder = encoder;
-        const dl = getFfiDl();
-        const symName = bindings.direct?.symbolNames[name];
-        r.call = dl ? dl.raw[symName ?? ""] : undefined;
-        const hasNul = bindings.direct?.hasNul[name];
-        if (hasNul !== undefined) r.hasNul = hasNul;
-      }
-      resolvedDirect.set(name, r);
+  /**
+   * Bind the addon once and fan the resolved symbols out across ALL records
+   * in a single pass — the first encode pays the dlopen + self-test, every
+   * later encode sees a plain populated field. Self-test-disabled symbols are
+   * left undefined (their events take the JSON path).
+   */
+  const bindSymbols = (): void => {
+    const dl = getFfiDl();
+    if (dl === null) return;
+    const disabled = dl.disabledDirect;
+    for (const r of records.values()) {
+      if (r.encoder === undefined || r.symName === undefined) continue;
+      if (disabled.has(r.symName)) continue;
+      const sym = dl.raw[r.symName];
+      if (sym !== undefined) r.call = sym;
     }
-    return r;
-  }
+  };
 
   function encodeToScratch(name: string, payload: unknown): Uint8Array {
-    const r = resolveDirect(name);
+    const r = records.get(name);
+    if (r === undefined) throw new Error(`ignex: unknown event "${name}"`);
     const encoder = r.encoder;
-    if (encoder && r.call) {
-      // `call` is undefined when the bind-time self-test disabled the symbol —
-      // fall through to the JSON path (graceful degradation). Embedded NULs route
-      // to JSON too: the `cstring` direct path truncates them (silent data loss),
-      // the JSON path preserves them exactly.
-      if (!(r.hasNul?.(payload) ?? false)) {
-        if (!guard) {
-          // required mode — zero-alloc hot path, no try/catch
-          scratch.grow(MIN_CAP);
-          const w = scratch.neededSize(name, encoder(r.call, payload, scratch.view), () =>
-            encoder(r.call!, payload, scratch.view),
-          );
-          stats.bump(name, "direct");
-          return scratch.view.subarray(0, w);
-        }
-        try {
-          scratch.grow(MIN_CAP);
-          const w = scratch.neededSize(name, encoder(r.call, payload, scratch.view), () =>
-            encoder(r.call!, payload, scratch.view),
-          );
-          stats.bump(name, "direct");
-          return scratch.view.subarray(0, w);
-        } catch {
-          // optional mode: a direct-call failure (e.g. ABI drift at runtime)
-          // permanently demotes this event to the JSON path.
-          r.call = undefined;
+    if (encoder !== undefined) {
+      if (r.call === undefined && ffi === undefined) bindSymbols();
+      const call = r.call;
+      if (call !== undefined) {
+        // Embedded NULs route to JSON: the `cstring` direct path truncates
+        // them (silent data loss); the JSON path preserves them exactly.
+        if (!(r.hasNul?.(payload) ?? false)) {
+          if (bindings.ffiMode !== "optional") {
+            // required mode — zero-alloc hot path, no try/catch
+            scratch.grow(MIN_CAP);
+            const w = scratch.neededSize(name, encoder(call, payload, scratch.view), () =>
+              encoder(r.call as (...args: unknown[]) => number, payload, scratch.view),
+            );
+            r.directCount++;
+            return scratch.view.subarray(0, w);
+          }
+          try {
+            scratch.grow(MIN_CAP);
+            const w = scratch.neededSize(name, encoder(call, payload, scratch.view), () =>
+              encoder(r.call as (...args: unknown[]) => number, payload, scratch.view),
+            );
+            r.directCount++;
+            return scratch.view.subarray(0, w);
+          } catch {
+            // optional mode: a direct-call failure (e.g. ABI drift at runtime)
+            // permanently demotes this event to the JSON path.
+            r.call = undefined;
+          }
         }
       }
     }
 
-    const dl = getFfiDl();
-    if (dl) {
+    const dl = ffi === undefined ? getFfiDl() : ffi;
+    if (dl !== null) {
       // JSON fallback (vector/nested events, or a disabled direct symbol).
-      const id = bindings.anyEventNameToId[name];
-      if (id === undefined) throw new Error(`ignex: unknown event "${name}"`);
       const json = JSON.stringify(payload);
-      const ffi2 = dl.bindings;
       scratch.grow(Math.max(MIN_CAP, json.length * 2 + 128));
-      const w = scratch.neededSize(name, ffi2.fb_serialize(id, json, scratch.view), () =>
-        ffi2.fb_serialize(id, json, scratch.view),
+      const w = scratch.neededSize(name, dl.bindings.fb_serialize(r.id, json, scratch.view), () =>
+        dl.bindings.fb_serialize(r.id, json, scratch.view),
       );
-      stats.bump(name, "json");
+      r.jsonCount++;
       return scratch.view.subarray(0, w);
     }
 
     // JS-only mode (user schema, no native addon) — the pure-JS encoder.
     const frame = bindings.encodeFrame(name, payload);
-    stats.bump(name, "js");
+    r.jsCount++;
     return frame;
   }
 
@@ -157,7 +187,17 @@ export function createTransport(bindings: Bindings): Transport {
   return {
     encodeToScratch,
     encodeEvent,
-    getEncodeStats: () => stats.get(),
+    getEncodeStats() {
+      const direct: Record<string, number> = {};
+      const json: Record<string, number> = {};
+      const js: Record<string, number> = {};
+      for (const [name, r] of records) {
+        if (r.directCount > 0) direct[name] = r.directCount;
+        if (r.jsonCount > 0) json[name] = r.jsonCount;
+        if (r.jsCount > 0) js[name] = r.jsCount;
+      }
+      return { direct, json, js };
+    },
   };
 }
 

package/src/bridge/nats.ts

@@ -1,309 +0,0 @@
-/**
- * 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.
- *
- * HORIZONTAL SCALING: when `bridgeClientEvents` is set, the server re-publishes
- * every accepted client-sent event to `{prefix}.inbound.<event>` so OTHER
- * server instances (and BE consumers) receive it — a cluster of servers sharing
- * a prefix behaves as one hub (see docs/generic-bindings.md). Loop prevention:
- * frames that arrive via NATS are forwarded to clients through `onInbound` and
- * never re-bridged.
- *
- * GENERIC: `createNatsBridge(opts, transport?, bindings?)` decodes inbound
- * frames with the given `Bindings` (default: the built-in registry), so the
- * bridge works for ANY schema — the same wire bytes the server speaks.
- *
- * 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 { defaultBindings } from "../bindings/default";
-import type { Bindings } from "../bindings/types";
-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" (or the bindings' subjectPrefix) */
-  subjectPrefix?: string;
-  /**
-   * The wire stack used to decode inbound frames (default: built-in registry).
-   * Pass your own generated bindings so the bridge decodes YOUR events.
-   */
-  bindings?: Bindings;
-  /** 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?: string[];
-  /**
-   * Re-publish every accepted client-sent event to `{prefix}.inbound.<event>`
-   * so other servers in the cluster (and BE consumers) receive it, default
-   * false. See the horizontal-scaling docs.
-   */
-  bridgeClientEvents?: boolean;
-}
-
-/** 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;
-  /** whether client-sent events are re-published to `{prefix}.inbound.<event>` */
-  readonly clientEvents: boolean;
-  /** publish a frame to `subject` (copies the bytes — safe after scratch reuse) */
-  publish(subject: string, frame: Uint8Array): void;
-  /**
-   * Raw byte subscription (used by the events cluster layer). Unlike the
-   * inbound path this does NOT decode or forward — bytes are handed to `cb`
-   * verbatim, re-subscribed automatically after a NATS reconnect.
-   */
-  subscribeRaw(subject: string, cb: (data: Uint8Array) => void): () => void;
-  /** wire the inbound → clients forward (set once by the server) */
-  setOnInbound(cb: (name: string, 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"],
-        ...(opts.token !== undefined ? { 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,
-  bindings?: Bindings,
-): NatsBridge {
-  const b = bindings ?? opts.bindings ?? defaultBindings;
-  const t = transport ?? createRealTransport(opts);
-  const subjects = createSubjectBuilder(opts.subjectPrefix ?? b.subjectPrefix ?? "ignex");
-  const stats: NatsBridgeStats = {
-    bridged: 0,
-    bridgedBytes: 0,
-    bridgeErrors: 0,
-    bridgeInbound: 0,
-    bridgeInboundErrors: 0,
-  };
-  let closed = false;
-  let onInbound: ((name: string, 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 = b.readFrameHeader(data);
-      if (!header) {
-        stats.bridgeInboundErrors++;
-        return;
-      }
-      if (b.isControlId(header.id)) {
-        stats.bridgeInboundErrors++; // never forward transport-internal frames
-        return;
-      }
-      const name = header.name;
-      if (allowlist && !allowlist.has(name)) return;
-      let payload: unknown;
-      try {
-        payload = b.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;
-    },
-    get clientEvents(): boolean {
-      return opts.bridgeClientEvents ?? false;
-    },
-    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;
-    },
-    subscribeRaw(subject, cb) {
-      return t.subscribe(subject, (data) => cb(data));
-    },
-    async close() {
-      closed = true;
-      for (const u of unsubs) u();
-      await t.close();
-    },
-  };
-}