@ignex/nova 0.1.1 → 0.1.3

package/src/bindings/assemble.ts

@@ -0,0 +1,73 @@
+/**
+ * `assembleBindings` — build a runtime `Bindings` from generated parts.
+ *
+ * The generated artifacts (`registry.ts`, `ts-ser.ts`, `direct-ser.ts`) are
+ * schema-specific SOURCE produced by `generateBindings` (public/generate.ts).
+ * This function wires them into the single `Bindings` object the server /
+ * client / NATS bridge accept. It is also what the built-in registry uses
+ * (`src/bindings/default.ts`).
+ */
+import type { TSchema } from "@sinclair/typebox";
+import type { Bindings, DirectTables } from "./types";
+
+/** Everything `assembleBindings` needs from the generated artifacts. */
+export interface BindingsParts {
+  readonly wireVersion: number;
+  readonly wireHeaderLen: number;
+  readonly schemaFingerprint: number;
+  readonly eventNameToId: Readonly<Record<string, number>>;
+  readonly idToEventName: Readonly<Record<number, string>>;
+  readonly anyEventNameToId: Readonly<Record<string, number>>;
+  readonly idToAnyEventName: Readonly<Record<number, string>>;
+  readonly controlEventNameToId: Readonly<Record<string, number>>;
+  readFrameHeader(bytes: Uint8Array): { name: string; id: number } | null;
+  isControlId(id: number): boolean;
+  decodePayload(id: number, bytes: Uint8Array): unknown;
+  decodeFrame(bytes: Uint8Array): { name: string; id: number; payload: unknown } | null;
+  encodeFrame(name: string, payload: unknown): Uint8Array;
+  readonly direct?: DirectTables;
+}
+
+export interface AssembleOptions {
+  /** "required" | "optional" — see `Bindings.ffiMode`. */
+  ffiMode?: "required" | "optional";
+  /** NATS subject prefix for bridges built from these bindings. */
+  subjectPrefix?: string;
+}
+
+/**
+ * Wire generated parts + the schema registry into a `Bindings` object.
+ * `schema.events` / `schema.controlEvents` are the user's TypeBox schemas —
+ * they power the `EventsOf<B>` type derivation on the public API.
+ */
+export function assembleBindings<
+  E extends Record<string, TSchema>,
+  C extends Record<string, TSchema>,
+>(
+  parts: BindingsParts,
+  schema: { events: E; controlEvents?: C },
+  opts: AssembleOptions = {},
+): Omit<Bindings, "events" | "controlEvents"> & { events: E; controlEvents: C } {
+  const controlEvents = (schema.controlEvents ?? {}) as C;
+  const controlIds = new Set<number>(Object.values(parts.controlEventNameToId));
+  return {
+    wireVersion: parts.wireVersion,
+    wireHeaderLen: parts.wireHeaderLen,
+    schemaFingerprint: parts.schemaFingerprint,
+    ...(opts.subjectPrefix !== undefined ? { subjectPrefix: opts.subjectPrefix } : {}),
+    ffiMode: opts.ffiMode ?? "optional",
+    events: schema.events,
+    controlEvents,
+    eventNameToId: parts.eventNameToId,
+    idToEventName: parts.idToEventName,
+    anyEventNameToId: parts.anyEventNameToId,
+    idToAnyEventName: parts.idToAnyEventName,
+    controlIds,
+    readFrameHeader: parts.readFrameHeader,
+    isControlId: parts.isControlId,
+    decodePayload: parts.decodePayload,
+    decodeFrame: parts.decodeFrame,
+    encodeFrame: parts.encodeFrame,
+    ...(parts.direct ? { direct: parts.direct } : {}),
+  };
+}

package/src/bindings/default.ts

@@ -0,0 +1,65 @@
+/**
+ * The built-in `Bindings` — assembled from the repo's generated artifacts
+ * (`src/generated/*` + `src/schema`). This is the default for every entrypoint
+ * (`createServer` / `createClient` / `createNatsBridge`), so all existing code
+ * keeps working without passing `bindings`.
+ *
+ * For your own schema, see `generateBindings` (public/generate.ts) —
+ * `defaultBindings` is just the first, built-in instance of the same contract.
+ */
+
+import {
+  directEncoders,
+  directSelfTest,
+  directSymbolNames,
+  directSymbols,
+  hasNulEncoders,
+} from "../generated/direct-ser";
+import {
+  anyEventNameToId,
+  controlEventNameToId,
+  decodeFrame,
+  decodePayload,
+  eventNameToId,
+  idToAnyEventName,
+  idToEventName,
+  isControlId,
+  readFrameHeader,
+  SCHEMA_FINGERPRINT,
+  WIRE_HEADER_LEN,
+  WIRE_VERSION,
+} from "../generated/registry";
+import { encodeEventFrame } from "../generated/ts-ser";
+import { controlEvents, events } from "../schema";
+import { assembleBindings } from "./assemble";
+
+// NOTE: no explicit `: Bindings` annotation on purpose — the concrete
+// `events` / `controlEvents` schema types must survive inference so
+// `DefaultBindings` (and therefore `EventNameOf` / `EventsOf` on the default
+// API) resolves to the built-in `Events` map.
+export const defaultBindings = assembleBindings(
+  {
+    wireVersion: WIRE_VERSION,
+    wireHeaderLen: WIRE_HEADER_LEN,
+    schemaFingerprint: SCHEMA_FINGERPRINT,
+    eventNameToId,
+    idToEventName,
+    anyEventNameToId,
+    idToAnyEventName,
+    controlEventNameToId,
+    readFrameHeader,
+    isControlId,
+    decodePayload,
+    decodeFrame,
+    encodeFrame: encodeEventFrame as (name: string, payload: unknown) => Uint8Array,
+    direct: {
+      symbols: directSymbols,
+      symbolNames: directSymbolNames,
+      encoders: directEncoders,
+      hasNul: hasNulEncoders,
+      selfTest: directSelfTest,
+    },
+  },
+  { events, controlEvents },
+  { ffiMode: "required", subjectPrefix: "ignex" },
+);

package/src/bindings/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Runtime `Bindings` — the per-schema bundle that decouples the transport from
+ * ANY particular event registry.
+ *
+ * Today the transport modules import the repo's generated artifacts directly
+ * (`src/generated/registry`, `src/generated/ts-ser`, `src/generated/direct-ser`
+ * and `src/schema`). `Bindings` is the generic contract: every schema-specific
+ * piece of the wire stack (event ids, decoders, encoders, direct fast-path
+ * tables, schema metadata) is grouped into one object, and the server / client /
+ * NATS bridge accept it via `options.bindings` (defaulting to the built-in
+ * registry, so existing code keeps working unchanged).
+ *
+ * Two ways to obtain a `Bindings`:
+ *   - the built-in one: `defaultBindings` (see `src/bindings/default.ts`)
+ *   - your own schema: run `generateBindings(schema)` (public/generate.ts),
+ *     then assemble the emitted parts with `assembleBindings`
+ *     (src/bindings/assemble.ts). Everything else — encode, decode, NATS
+ *     subject naming, server/client APIs — is then typed against YOUR events.
+ */
+import type { Static, TSchema } from "@sinclair/typebox";
+
+/** Direct fast-path call signature (generated `direct-ser.ts`). */
+export type DirectCall = (...args: unknown[]) => number;
+
+/** Generated zero-alloc encoder: fields → FFI args → out buffer. */
+export type DirectEncoder = (call: DirectCall, o: unknown, out: Uint8Array) => number;
+
+/**
+ * The generated direct fast-path tables (Bun server only). Absent when the
+ * schema has no directable events or the codegen was run with `rust: false`.
+ */
+export interface DirectTables {
+  /** dlopen specs in canonical form (see `src/native/ffi.ts` `abi()`). */
+  readonly symbols: Readonly<Record<string, { args: readonly string[]; returns: string }>>;
+  /** event → FFI symbol name. */
+  readonly symbolNames: Readonly<Record<string, string>>;
+  /** event → zero-alloc encoder. */
+  readonly encoders: Readonly<Record<string, DirectEncoder>>;
+  /** event → NUL pre-scan (true routes the payload to the JSON path). */
+  readonly hasNul: Readonly<Record<string, (o: unknown) => boolean>>;
+  /** bind-time per-symbol self-test; returns the symbol names to DISABLE. */
+  readonly selfTest: (
+    raw: Record<string, (...args: unknown[]) => number>,
+    scratch: Uint8Array,
+  ) => string[];
+}
+
+/**
+ * The complete per-schema wire stack. `events` / `controlEvents` are the
+ * TypeBox schemas — from them consumers derive `EventNameOf` / `EventsOf`.
+ */
+export interface Bindings {
+  /** wire envelope version (see `scripts/constants.ts`). */
+  readonly wireVersion: number;
+  /** envelope header bytes: `[version:1][event_id:u32 LE]`. */
+  readonly wireHeaderLen: number;
+  /**
+   * Stable schema fingerprint (FNV-1a 32 over the canonical model). The Rust
+   * cdylib exports the same value (`fb_schema_fingerprint`), so a schema-
+   * mismatched addon fails the bind-time self-test instead of producing
+   * undecodable frames.
+   */
+  readonly schemaFingerprint: number;
+  /** NATS subject prefix used by bridges built from these bindings. */
+  readonly subjectPrefix?: string;
+  /**
+   * "required" — the Rust addon must exist and pass self-tests (the built-in
+   * registry: a missing addon throws). "optional" — generated for user
+   * schemas: the addon is used when `IGNEX_FFI_PATH` is set and passes
+   * self-tests; otherwise the pure-JS encoder is used (works without Rust).
+   */
+  readonly ffiMode: "required" | "optional";
+  /** app event schemas (name → TypeBox). */
+  readonly events: Readonly<Record<string, TSchema>>;
+  /** control event schemas (name → TypeBox). */
+  readonly controlEvents: Readonly<Record<string, TSchema>>;
+
+  // ── event id maps (stable FNV-1a 32 over the name) ────────────────────
+  readonly eventNameToId: Readonly<Record<string, number>>;
+  readonly idToEventName: Readonly<Record<number, string>>;
+  /** merged app + control maps (encode dispatch). */
+  readonly anyEventNameToId: Readonly<Record<string, number>>;
+  readonly idToAnyEventName: Readonly<Record<number, string>>;
+  readonly controlIds: ReadonlySet<number>;
+
+  // ── wire helpers (pure — run in browser + Bun) ────────────────────────
+  readFrameHeader(bytes: Uint8Array): { name: string; id: number } | null;
+  isControlId(id: number): boolean;
+  decodePayload(id: number, bytes: Uint8Array): unknown;
+  decodeFrame(bytes: Uint8Array): { name: string; id: number; payload: unknown } | null;
+
+  /** Pure-JS encoder: plain object → full wire frame. Works everywhere. */
+  encodeFrame(name: string, payload: unknown): Uint8Array;
+
+  /** Generated direct fast-path tables (optional — server only). */
+  readonly direct?: DirectTables;
+}
+
+// ── type-level derivation from a concrete Bindings ────────────────────────
+
+export type EventNameOf<B extends Bindings> = Extract<keyof B["events"], string>;
+export type ControlEventNameOf<B extends Bindings> = Extract<keyof B["controlEvents"], string>;
+
+/** Plain-object payload map derived from a bindings' TypeBox schemas. */
+export type EventsOf<B extends Bindings> = {
+  [K in EventNameOf<B>]: Static<B["events"][K]>;
+};
+export type ControlEventsOf<B extends Bindings> = {
+  [K in ControlEventNameOf<B>]: Static<B["controlEvents"][K]>;
+};
+
+/** The built-in registry's bindings type (see `src/bindings/default.ts`). */
+export type DefaultBindings = typeof import("./default").defaultBindings;

package/src/bridge/nats.ts

@@ -11,14 +11,25 @@
  * 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 { decodePayload, isControlId, readFrameHeader } from "../generated/registry";
-import type { EventName } from "../schema";
+import { defaultBindings } from "../bindings/default";
+import type { Bindings } from "../bindings/types";
 import { createSubjectBuilder, type SubjectBuilder } from "./subjects";
 
 export type NatsBridgeStatus = "connected" | "connecting" | "closed";
@@ -26,8 +37,13 @@ export type NatsBridgeStatus = "connected" | "connecting" | "closed";
 export interface NatsBridgeOptions {
   /** NATS servers, default ["nats://localhost:4222"] */
   servers?: string[];
-  /** subject prefix, default "ignex" */
+  /** 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 */
@@ -41,7 +57,13 @@ export interface NatsBridgeOptions {
   /** inbound subjects (default `{prefix}.inbound.>`), requires `inbound` */
   inboundSubjects?: string[];
   /** only forward these inbound events (default: every app event) */
-  inboundEvents?: EventName[];
+  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()`. */
@@ -67,10 +89,18 @@ 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: EventName, payload: unknown) => void): void;
+  setOnInbound(cb: (name: string, payload: unknown) => void): void;
   close(): Promise<void>;
 }
 
@@ -129,7 +159,7 @@ function createRealTransport(opts: NatsBridgeOptions): NatsTransport {
     try {
       const conn = await connect({
         servers: opts.servers ?? ["nats://localhost:4222"],
-        token: opts.token,
+        ...(opts.token !== undefined ? { token: opts.token } : {}),
         timeout: opts.connectTimeout ?? 5000,
         reconnect: opts.reconnect ?? true,
         maxReconnectAttempts: -1,
@@ -185,9 +215,11 @@ function createRealTransport(opts: NatsBridgeOptions): NatsTransport {
 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);
+  const subjects = createSubjectBuilder(opts.subjectPrefix ?? b.subjectPrefix ?? "ignex");
   const stats: NatsBridgeStats = {
     bridged: 0,
     bridgedBytes: 0,
@@ -196,26 +228,26 @@ export function createNatsBridge(
     bridgeInboundErrors: 0,
   };
   let closed = false;
-  let onInbound: ((name: EventName, payload: unknown) => void) | null = null;
+  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 = readFrameHeader(data);
+      const header = b.readFrameHeader(data);
       if (!header) {
         stats.bridgeInboundErrors++;
         return;
       }
-      if (isControlId(header.id)) {
+      if (b.isControlId(header.id)) {
         stats.bridgeInboundErrors++; // never forward transport-internal frames
         return;
       }
-      const name = header.name as EventName;
+      const name = header.name;
       if (allowlist && !allowlist.has(name)) return;
       let payload: unknown;
       try {
-        payload = decodePayload(header.id, data);
+        payload = b.decodePayload(header.id, data);
       } catch {
         stats.bridgeInboundErrors++;
         return;
@@ -227,7 +259,9 @@ export function createNatsBridge(
 
   const unsubs: Array<() => void> = [];
   if (opts.inbound) {
-    const subjectsList = opts.inboundSubjects?.length ? opts.inboundSubjects : [subjects.inboundPrefix()];
+    const subjectsList = opts.inboundSubjects?.length
+      ? opts.inboundSubjects
+      : [subjects.inboundPrefix()];
     for (const subject of subjectsList) unsubs.push(subscribeInbound(subject));
   }
 
@@ -242,6 +276,9 @@ export function createNatsBridge(
     get stats() {
       return stats;
     },
+    get clientEvents(): boolean {
+      return opts.bridgeClientEvents ?? false;
+    },
     publish(subject, frame) {
       if (!t.connected) {
         stats.bridgeErrors++;
@@ -260,6 +297,9 @@ export function createNatsBridge(
     setOnInbound(cb) {
       onInbound = cb;
     },
+    subscribeRaw(subject, cb) {
+      return t.subscribe(subject, (data) => cb(data));
+    },
     async close() {
       closed = true;
       for (const u of unsubs) u();

package/src/bridge/subjects.ts

@@ -18,6 +18,8 @@ export interface SubjectBuilder {
   group(group: string, name: string): string;
   /** wildcard subject the server subscribes to for inbound events */
   inboundPrefix(): string;
+  /** concrete inbound subject for one event — used to re-publish client events into the cluster */
+  inboundEvent(name: string): string;
 }
 
 export function createSubjectBuilder(prefix = "ignex"): SubjectBuilder {
@@ -26,5 +28,6 @@ export function createSubjectBuilder(prefix = "ignex"): SubjectBuilder {
     topic: (topic, name) => `${prefix}.topic.${topic}.${name}`,
     group: (group, name) => `${prefix}.group.${group}.${name}`,
     inboundPrefix: () => `${prefix}.inbound.>`,
+    inboundEvent: (name) => `${prefix}.inbound.${name}`,
   };
 }

package/src/codegen/constants.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared wire-format constants. These are the SINGLE source of truth for the
+ * transport envelope — every emitter (TS registry, Rust glue, direct serde)
+ * imports them so the TS and Rust sides stay in sync by construction.
+ *
+ * The Rust `fb_wire_version()` export is checked against `WIRE_VERSION` at
+ * bind time (`src/native/ffi.ts`) to catch any drift between a stale cdylib
+ * and the generated artifacts.
+ */
+
+/** Wire format version. Bump on any BREAKING envelope change. */
+export const WIRE_VERSION = 1;
+
+/**
+ * Envelope header length in bytes: `[version:1][event_id:u32 LE]`. The
+ * size-prefixed FlatBuffer payload follows immediately after.
+ */
+export const WIRE_HEADER_LEN = 5;