@ignex/nova 0.1.1 → 0.1.5

package/docs/wire-format.md

@@ -8,18 +8,25 @@ client from the generated FlatBuffers schema — no Bun, no Rust, no FFI needed.
 Every WebSocket **binary** frame is:
 
 ```
-┌──────────┬───────────────────┬──────────────────────────────────┐
-│ version  │ event_id          │ size-prefixed FlatBuffer         │
-│ 1 byte   │ u32 (LE)          │ (flatc: 4-byte size prefix + buf)│
-└──────────┴───────────────────┴──────────────────────────────────┘
-    offset 0      1..5                 5..
+┌──────────┬───────────────────┬─────────┬────────────┬──────────────────────────────────┐
+│ version  │ event_id          │ flags   │ seq        │ size-prefixed FlatBuffer         │
+│ 1 byte   │ u32 (LE)          │ 1 byte  │ u64 (LE)   │ (flatc: 4-byte size prefix + buf)│
+└──────────┴───────────────────┴─────────┴────────────┴──────────────────────────────────┘
+    offset 0      1..5               5           6..14       14..
 ```
 
-- `version` = `WIRE_VERSION` (currently `1`). A peer MUST drop frames whose
-  version it doesn't recognize (the decoders return `null`).
+- `version` = `WIRE_VERSION` (currently `2` — v2 added the delivery header).
+  A peer MUST drop frames whose version it doesn't recognize (the decoders
+  return `null`).
 - `event_id` = **FNV-1a 32-bit hash of the event name** (e.g.
   `fnv1a32("quote")`). Stable across schema reordering; collisions are rejected
   at generate time. The id→name table is emitted in `src/generated/registry.ts`.
+- `flags` — bit0 = "seq-valid" (see below); all other bits reserved, send 0.
+- `seq` — per-CONNECTION delivery sequence, stamped by the SERVER on every
+  **app** frame just before `ws.send` (Bun copies synchronously). Clients use
+  it for gap detection + resume. Control frames are never stamped; frames that
+  were not per-destination stamped carry `flags=0, seq=0`. Offsets are derived
+  from `WIRE_HEADER_LEN`: flags at `len-9`, seq at `len-8..len`.
 - The payload is a **size-prefixed FlatBuffer** (built by flatc, both Rust
   builders and the TS object API) with the root table for that event id.
 
@@ -27,6 +34,18 @@ There is **no per-frame checksum and no authentication** — the envelope id byt
 is trusted. Integrity and AuthN are the application's job (see
 [Security](#security)).
 
+## String fields carry raw UTF-8
+
+A FlatBuffer `string` field stores its content as raw UTF-8 bytes in the frame,
+so any JSON document placed in a string field appears **verbatim** inside the
+(binary) frame — expected behavior, not corruption. If a captured frame shows
+`{"items":[...]}` text in the payload, the event schema models that data as a
+`string` field (a JSON-in-a-string envelope, or a field written as
+`Type.Any()`/`Type.Unknown()`, which the codegen now rejects at generate time —
+see docs/generic-bindings.md). Prefer typed fields — `Type.Array(Table)` for
+lists, `Type.Integer()` for counts — so the frame carries structure instead of
+JSON text.
+
 ## Event ids
 
 Event ids are stable hashes, so adding events, reordering the registry, or
@@ -46,13 +65,17 @@ SAME codegen, but are routed internally (never delivered to app handlers):
 
 | name | direction | payload |
 | --- | --- | --- |
-| `hello` | both | `{ version, caps: string[], lastSeq }` — sent on connect; version mismatch → close(1002) |
+| `hello` | both | `{ version, caps: string[], lastSeq }` — sent on connect; version mismatch → close(1002). `lastSeq > 0` asks the server to resume this client id's delivery stream after that seq (cross-session resume) |
 | `welcome` | server→client | `{ clientId, groups: string[] }` — identity assigned to this connection (auth metadata or UUID) + its server-side groups |
 | `subscribe` | client→server | `{ topic }` — join a room (server replies with replay history) |
 | `unsubscribe` | client→server | `{ topic }` |
 | `joinGroup` | client→server | `{ group }` — join a server-side group |
 | `leaveGroup` | client→server | `{ group }` |
-| `snapshotRequest` | client→server | `{ topic }` — reserved for future replay control |
+| `snapshotRequest` | client→server | `{ topic, fromSeq }` — replay recorded topic history STRICTLY after `fromSeq` (0 = from the beginning of retained history); hydrates from the durable topic log when the in-memory ring has moved on |
+| `resume` | client→server | `{ lastSeq }` — same-connection gap recovery: re-send everything after the last CONTIGUOUS delivery seq (original seqs preserved) |
+| `resumed` | server→client | `{ ok: boolean, from: number }` — ack before the replayed frames; `ok:false` = the hole is older than the retained history (partial recovery — resubscribe topics for a fresh snapshot) |
+| `rpcCall` | client→server | `{ id, name, payloadB64 }` — request/response: `payloadB64` is base64 of a full wire frame encoded with event `name`'s schema; the response reuses the SAME schema |
+| `rpcResult` | server→client | `{ id, ok, err, payloadB64 }` — correlated by `id`; `ok:false` carries a plain-text `err` |
 | `ping` | client→server | `{ ts }` — heartbeat |
 | `pong` | server→client | `{ ts }` |
 
@@ -113,16 +136,23 @@ Bridge state is observable via `server.getMetrics()`
 ### Decoding bridged frames (external consumers)
 
 `bun run generate` emits `src/generated/wire-registry.json` — a machine-readable
-`{ version, events: { name: id } }` map of the FNV-1a ids. A consumer in any
-language:
+`{ version, fingerprint, events: { name: id } }` map of the FNV-1a ids. A
+consumer in any language:
 
 1. reads `version` (byte 0) and `event_id` (bytes 1..5) from the frame,
 2. maps `event_id` → name via `wire-registry.json`,
-3. decodes the size-prefixed FlatBuffer from `frame[5..]` with a flatc build of
+3. decodes the size-prefixed FlatBuffer from `frame[14..]` with a flatc build of
    `src/generated/fbs/backend.fbs`.
 
 See `examples/nats-consumer.ts` for a working reference.
 
+For YOUR OWN schema, `generateBindings` (see
+[docs/generic-bindings.md](generic-bindings.md)) emits the same
+`backend.fbs` + `wire-registry.json` into your project, plus a `fingerprint`
+field — the cdylib and the generated registry share it, so a schema-mismatched
+native addon fails the bind-time self-test instead of emitting undecodable
+frames.
+
 ## Heartbeat
 
 Clients send `ping` every `heartbeatMs` (default 15000). The server replies
@@ -130,12 +160,26 @@ Clients send `ping` every `heartbeatMs` (default 15000). The server replies
 long-idle sockets alive; a client that misses `heartbeatMisses` pongs force-
 closes and reconnects.
 
-## Sequence / replay
-
-The current model replays **recent history on subscribe** (bounded ring per
-topic, last-value snapshot). Full gap-based replay (per-frame sequence numbers
-in the envelope + `hello.lastSeq` negotiation) is a documented future extension;
-the envelope reserves no space for a per-frame seq today.
+## Sequence / resume / request-response
+
+- **Delivery seqs (v2)**: when the server starts with `resume`, every app frame
+  it writes to a socket carries an increasing per-connection `seq` (envelope
+  flags bit0). Clients track the stream; a GAP (lost frame — backpressure drop,
+  transport hiccup) is recovered by sending `resume { lastSeq }`; the server
+  replays from the connection's bounded sent-history ring with ORIGINAL seqs so
+  redelivery is in-order and duplicate-free. On disconnect the ring parks in a
+  per-client-id graveyard (bounded, TTL'd); a reconnecting session with the
+  same auth-pinned id continues the stream via `hello { lastSeq }`.
+- **Topic snapshots**: `snapshotRequest { topic, fromSeq }` replays recorded
+  topic history strictly after a topic seq; a durable `topicLog`
+  (`createServer({ topicLog })`, e.g. `createMemoryTopicLog()`) hydrates ranges
+  the replay ring has already forgotten. Topic-history seqs are a SEPARATE
+  counter (global replay order) from per-connection delivery seqs.
+- **Request/response**: `client.request(name, payload)` wraps a full wire frame
+  (base64) in an `rpcCall` control frame with a correlation id; the server's
+  registered responder (via `server.handle(name, fn)` or `hub.onRequest`)
+  returns the response payload encoded with the SAME event schema. Timeouts and
+  errors are correlated client-side.
 
 ## Security
 
@@ -144,7 +188,17 @@ the envelope reserves no space for a per-frame seq today.
   happily decode the payload as the claimed type. Add integrity at the
   application layer if the wire crosses an untrusted boundary.
 - Server-side guards (all optional): `authenticate(req)` async hook, origin
-  allowlist, bearer `token`, `maxConnections`, `maxMessageSize`.
+  allowlist, bearer `token` (literal tokens compared in constant time),
+  `maxConnections`, `maxMessageSize`, per-connection inbound rate limiting
+  (`rateLimit`: token bucket over app AND control frames — drop or close 1008,
+  counted in `metrics.rateLimited`).
+- Join authorization: `authorizeTopic(topic, ws)` / `authorizeGroup(group, ws)`
+  gate EVERY room/group join path (control frames, programmatic joins, and
+  auth-seeded membership); rejections are counted in `metrics.rejectedJoins`.
+  Leaving is always allowed.
+- Introspection: `GET /clients` is gated by the same token/`authenticate`
+  surface when one is configured (public only on servers with no auth at all);
+  `/health` stays public (counters only).
 - Slow consumers: `backpressure` policy (`drop-oldest`/`drop-newest`/
   `disconnect`) bounds per-socket buffering; without it a hot publish loop can
   balloon memory.
@@ -161,7 +215,7 @@ the envelope reserves no space for a per-frame seq today.
 3. Read `version` (byte 0) and `event_id` (bytes 1..5) from each binary frame.
    Compute ids with FNV-1a 32 over the name (see above) or read the emitted
    `src/generated/registry.ts` table.
-4. `flatbuffers.ByteBuffer(frame[5..])` + `getSizePrefixedRootAs<T>` (or the
+4. `flatbuffers.ByteBuffer(frame[14..])` + `getSizePrefixedRootAs<T>` (or the
    language equivalent) gives you the payload.
 5. Implement the control frames (at minimum `hello` + `ping`/`pong`) to be a
    good citizen; `subscribe` for rooms.

package/index.ts

@@ -2,45 +2,61 @@
  * ignex-nova — public package root.
  *
  * Re-exports the full typed pub/sub API (server + client + NATS bridge +
- * schema types) so a single `import ... from "ignex-nova"` works in Bun
- * projects.
+ * schema types + generic bindings codegen) so a single `import ... from
+ * "@ignex/nova"` works in Bun projects.
  *
  * For leaner / target-specific imports use the subpath entrypoints — each
  * resolves to its own source file and tree-shakes independently:
  *
- *   import { createServer } from "ignex-nova/server";   // Bun-only (Rust FFI)
- *   import { createClient } from "ignex-nova/client";   // browser + Bun
- *   import { createNatsBridge } from "ignex-nova/nats"; // standalone bridge
+ *   import { createServer } from "@ignex/nova/server";     // Bun-only (Rust FFI)
+ *   import { createClient } from "@ignex/nova/client";     // browser + Bun
+ *   import { createNatsBridge } from "@ignex/nova/nats";   // standalone bridge
+ *   import { on, emit } from "@ignex/nova/events";         // events layer + global emit
+ *   import { generateBindings } from "@ignex/nova/generate"; // ANY-schema codegen
+ *   import { assembleBindings, defaultBindings } from "@ignex/nova/bindings";
+ *   import { encodeUtf8Into } from "@ignex/nova/internal";   // codegen helpers
  *
  * Note: the root entry also pulls in the Bun-only server + FFI path, so
- * browser bundles should import "ignex-nova/client" instead.
+ * browser bundles should import "@ignex/nova/client" instead.
  *
  * The README (and docs/publishing.md) covers consuming this from an npm
- * package: `bun add ignex-nova`, then use the subpaths above.
+ * package: `bun add @ignex/nova`, then use the subpaths above.
  */
-export { createServer } from "./public/server";
-export type {
-  IgnServer,
-  ClientInfo,
-  IgnServerOptions,
-  IgnBackpressureOptions,
-  BackpressurePolicy,
-  WsData,
-  ClientMeta,
-  AuthResult,
-  MetricsSnapshot,
-  Int64GuardMode,
-} from "./public/server";
 
-export { createClient } from "./public/client";
 export type {
+  AssembleOptions,
+  Bindings,
+  BindingsParts,
+  ControlEventNameOf,
+  ControlEventsOf,
+  DefaultBindings,
+  DirectCall,
+  DirectEncoder,
+  DirectTables,
+  EventNameOf,
+  EventsOf,
+} from "./public/bindings";
+export { assembleBindings, defaultBindings } from "./public/bindings";
+export type {
+  ClientStatus,
   IgnClient,
   IgnClientOptions,
   IgnReconnectOptions,
-  ClientStatus,
 } from "./public/client";
 
-export { createNatsBridge, createSubjectBuilder } from "./public/nats";
+export { createClient } from "./public/client";
+export type { GeneratedBindings, GenerateOptions, SchemaRegistry } from "./public/generate";
+// ── generic bindings (ANY schema) ──────────────────────────────────────────
+export { generateBindings } from "./public/generate";
+// runtime helpers used by generated code (also exported via `@ignex/nova/internal`)
+export {
+  checkInt64,
+  encodeUtf8Into,
+  ensureCapacity,
+  pooledByteBuffer,
+  setInt64GuardMode,
+  utf8Len,
+} from "./public/internal";
 export type {
   NatsBridge,
   NatsBridgeOptions,
@@ -49,13 +65,45 @@ export type {
   NatsTransport,
   SubjectBuilder,
 } from "./public/nats";
+export { createNatsBridge, createSubjectBuilder } from "./public/nats";
+// events layer types (the runtime singleton API is `@ignex/nova/events`)
+export type {
+  AuthResult,
+  BackpressurePolicy,
+  ClientData,
+  ClientGroup,
+  ClientInfo,
+  ClientMeta,
+  ClusterStateStore,
+  ClusterTransport,
+  EmitTarget,
+  EmitTargetKind,
+  EventClient,
+  EventContext,
+  EventHandler,
+  EventsClusterOptions,
+  EventsHub,
+  EventsMetricsSnapshot,
+  EventsOptions,
+  IgnBackpressureOptions,
+  IgnServer,
+  IgnServerOptions,
+  Int64GuardMode,
+  MetricsSnapshot,
+  RedisConnectionOptions,
+  RemoteClient,
+  ServerEventHandler,
+  UserGroup,
+  WsData,
+} from "./public/server";
+export { createServer } from "./public/server";
 
 // Plain-object payload types consumers type against (e.g. `Events["quote"]`).
 // Import as types only — the runtime `events` registry is transport-internal.
 export type {
-  Events,
-  EventName,
   AnyEventName,
-  ControlEvents,
   ControlEventName,
-} from "./src/schema";
+  ControlEvents,
+  EventName,
+  Events,
+} from "./src/schema";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ignex/nova",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "type": "module",
   "description": "TypeBox-driven FlatBuffer transport: Rust FFI serializer + Bun WebSocket + typed pub/sub API for server and FE.",
   "license": "MIT",
@@ -48,6 +48,10 @@
     "./server": "./public/server.ts",
     "./client": "./public/client.ts",
     "./nats": "./public/nats.ts",
+    "./events": "./public/events.ts",
+    "./bindings": "./public/bindings.ts",
+    "./generate": "./public/generate.ts",
+    "./internal": "./public/internal.ts",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -57,7 +61,7 @@
     "generate": "bun scripts/generate.ts",
     "build:rust": "cargo build --release --manifest-path rust/Cargo.toml",
     "build:client": "bun build ./client/main.ts --outdir ./client-dist --target=browser --splitting",
-    "build:dist": "bun build ./index.ts ./public/server.ts ./public/client.ts ./public/nats.ts --outdir ./dist --target=bun --splitting && bunx tsc --emitDeclarationOnly -p tsconfig.dist.json",
+    "build:dist": "bun build ./index.ts ./public/server.ts ./public/client.ts ./public/nats.ts ./public/events.ts ./public/bindings.ts ./public/generate.ts ./public/internal.ts --outdir ./dist --target=bun --splitting && bunx tsc --emitDeclarationOnly -p tsconfig.dist.json",
     "build": "bun run generate && bun run build:rust && bun run build:client",
     "prebuild": "bun scripts/build-prebuild.ts",
     "test": "bun test",
@@ -65,8 +69,10 @@
     "typecheck": "bunx tsc --noEmit -p tsconfig.json",
     "verify": "bun run typecheck && bun run lint && bun test",
     "pack:check": "bun scripts/check-pack.ts",
+    "gen:ai-map": "bun scripts/gen-ai-map.ts",
     "serve": "bun run src/server.ts",
     "bench:serialize": "bun run bench/serialize.ts",
+    "bench:dispatch": "bun run bench/dispatch.ts",
     "bench:throughput": "bun run bench/throughput.ts",
     "release": "bun scripts/release.ts",
     "release:dry": "bun scripts/release.ts --dry-run",
@@ -85,5 +91,10 @@
   },
   "peerDependencies": {
     "typescript": "^7"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
   }
 }

package/public/bindings.ts

@@ -0,0 +1,24 @@
+/**
+ * Public bindings API — `@ignex/nova/bindings`.
+ *
+ *   import { assembleBindings, defaultBindings } from "@ignex/nova/bindings";
+ *   import type { Bindings, EventsOf } from "@ignex/nova/bindings";
+ *
+ * `defaultBindings` is the built-in registry's wire stack; `assembleBindings`
+ * builds a `Bindings` from generated parts (see `@ignex/nova/generate`).
+ */
+
+export type { AssembleOptions, BindingsParts } from "../src/bindings/assemble";
+export { assembleBindings } from "../src/bindings/assemble";
+export { defaultBindings } from "../src/bindings/default";
+export type {
+  Bindings,
+  ControlEventNameOf,
+  ControlEventsOf,
+  DefaultBindings,
+  DirectCall,
+  DirectEncoder,
+  DirectTables,
+  EventNameOf,
+  EventsOf,
+} from "../src/bindings/types";

package/public/client.ts

@@ -3,7 +3,7 @@
  * build stable). The implementation lives in the functional modules under
  * `src/core/`; this file just exposes the public surface.
  *
- *   import { createClient } from "ignex-nova/client";
+ *   import { createClient } from "@ignex/nova/client";
  *
  *   const client = createClient("ws://localhost:3000/ws", { reconnect: true });
  *   client.on("quote", (q) => { /* q: Events["quote"] — a plain object *\/ });
@@ -11,6 +11,10 @@
  *   client.send("chat", {...});     // typed client→server (server must allow it)
  *   client.connect();
  *
+ *   // your own schema (see @ignex/nova/generate):
+ *   const client = createClient("ws://localhost:3000/ws", { bindings });
+ *   client.on("yourEvent", (e) => {...}); // typed against YOUR Events
+ *
  * Works in the browser (bundle with `bun build --target=browser`) AND in Bun.
  * Outgoing frames are encoded by the generated PURE-JS encoder — no Rust FFI
  * needed, so the browser can send too.

package/public/events.ts

@@ -0,0 +1,71 @@
+/**
+ * Public events API — the application-facing event-driven layer on top of the
+ * FlatBuffer transport core.
+ *
+ *   import { createServer } from "@ignex/nova/server";
+ *   import { on, emit, emitToUser, emitToGroup } from "@ignex/nova/events";
+ *
+ *   const server = createServer({ port: 3000, events: {} });
+ *
+ *   // the "events file": where events are received
+ *   on("chat.message", (ctx) => {
+ *     emitToUser(ctx.client.userId ?? "", "chat.ack", { ok: true });
+ *   });
+ *
+ *   // the global emit: send events through websockets from anywhere
+ *   emit("quote", { symbol: "AAPL", bid: 180.1, ask: 180.2, ... });   // broadcast
+ *   emitToGroup("traders", "alert", { ... });                          // to a group
+ *   emitToUser("u-42", "order.update", { ... });                       // to a user's sockets
+ *
+ * Typed against the BUILT-IN event registry; custom-schema apps use
+ * `server.events` (fully typed against YOUR events) — or pass your bindings to
+ * `createServer({ bindings, events })` and use `server.events`.
+ *
+ * The events layer is opt-in (`createServer({ events })`); without it there is
+ * zero overhead and the singleton throws a descriptive error on use.
+ */
+
+export {
+  createMemoryStateStore,
+  createNatsClusterTransport,
+  createRedisClusterTransport,
+  createRedisStateStore,
+} from "../src/events/cluster";
+export {
+  bindEvents,
+  emit,
+  emitToClient,
+  emitToGroup,
+  emitToTopic,
+  emitToUser,
+  getEventsHub,
+  isEventsBound,
+  off,
+  offAny,
+  offServerEvent,
+  on,
+  onAny,
+  once,
+  onServerEvent,
+  unbindEvents,
+} from "../src/events/global";
+export type {
+  ClientData,
+  ClientGroup,
+  ClusterStateStore,
+  ClusterTransport,
+  EmitTarget,
+  EmitTargetKind,
+  EventClient,
+  EventContext,
+  EventHandler,
+  EventSource,
+  EventsClusterOptions,
+  EventsHub,
+  EventsMetricsSnapshot,
+  EventsOptions,
+  RedisConnectionOptions,
+  RemoteClient,
+  ServerEventHandler,
+  UserGroup,
+} from "../src/events/types";