@ignex/nova 0.1.1 → 0.1.5

package/src/events/cluster/envelope.ts

@@ -0,0 +1,149 @@
+/**
+ * Cluster envelope codec — the self-describing binary frame published to the
+ * broker. Routing never depends on broker channel syntax; everything a peer
+ * needs (origin, kind, key, event name, dedupe id, trace id) rides in the
+ * header so any transport works identically.
+ *
+ * Wire layout (v2):
+ *   [envVer:1]
+ *   [originLen:u8][origin:utf8][kind:u8][keyLen:u8][key:utf8][nameLen:u8][name:utf8]
+ *   [msgIdLen:u8][msgId:utf8][traceLen:u8][trace:utf8]
+ *   [frame:bytes]
+ *
+ * v2 adds the envelope VERSION byte, a message id (broker-level redelivery
+ * dedupe) and an optional trace id (cross-instance trace correlation). A v1
+ * peer's frames fail the version check and are counted as errors.
+ *
+ * Pure functions — no I/O, no shared state.
+ */
+import {
+  CLUSTER_ENV_VERSION,
+  CLUSTER_KINDS,
+  CLUSTER_KIND_ID,
+  type ClusterKind,
+  clusterKindFromId,
+} from "./kinds";
+
+// module-global codecs: allocation happens once per process, not per message
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/** One decoded cluster message (`frame` is a view into the input buffer). */
+export interface ClusterEnvelope {
+  origin: string;
+  kind: ClusterKind;
+  key: string;
+  name: string;
+  frame: Uint8Array;
+  /** producer-assigned unique message id (dedupe across broker redeliveries) */
+  msgId: string;
+  /** optional cross-instance trace id */
+  traceId: string;
+}
+
+/** Write `[len:u8][bytes]` at `p`; returns the offset after the payload. */
+function putLenPrefixed(out: Uint8Array, p: number, bytes: Uint8Array): number {
+  out[p] = bytes.byteLength;
+  out.set(bytes, p + 1);
+  return p + 1 + bytes.byteLength;
+}
+
+/** Encode all length-prefixed header strings up-front (also validates sizes). */
+function encodeHeaderStrings(
+  origin: string,
+  key: string,
+  name: string,
+  msgId: string,
+  traceId: string,
+): [Uint8Array, Uint8Array, Uint8Array, Uint8Array, Uint8Array] {
+  const o = enc.encode(origin);
+  const k = enc.encode(key);
+  const n = enc.encode(name);
+  const m = enc.encode(msgId);
+  const t = enc.encode(traceId);
+  // length fields are single bytes — anything longer would silently wrap
+  // mod 256 and CORRUPT the frame for every peer; fail loudly instead
+  if (
+    o.byteLength > 255 ||
+    k.byteLength > 255 ||
+    n.byteLength > 255 ||
+    m.byteLength > 255 ||
+    t.byteLength > 255
+  ) {
+    throw new RangeError(
+      "ignex cluster: origin/key/name/msgId/trace exceed the 255-byte envelope limit " +
+        `(got ${o.byteLength}/${k.byteLength}/${n.byteLength}/${m.byteLength}/${t.byteLength})`,
+    );
+  }
+  return [o, k, n, m, t];
+}
+
+export function encodeClusterMessage(
+  origin: string,
+  kind: ClusterKind,
+  key: string,
+  name: string,
+  frame: Uint8Array,
+  msgId = "",
+  traceId = "",
+): Uint8Array {
+  const [o, k, n, m, t] = encodeHeaderStrings(origin, key, name, msgId, traceId);
+  // fixed bytes: envVer(1) originLen(1) kind(1) keyLen(1) nameLen(1) msgIdLen(1) traceLen(1)
+  const headerLen = 7 + o.byteLength + k.byteLength + n.byteLength + m.byteLength + t.byteLength;
+  const out = new Uint8Array(headerLen + frame.byteLength);
+  let p = 0;
+  out[p] = CLUSTER_ENV_VERSION;
+  p++;
+  p = putLenPrefixed(out, p, o);
+  out[p] = CLUSTER_KIND_ID[kind];
+  p++;
+  p = putLenPrefixed(out, p, k);
+  p = putLenPrefixed(out, p, n);
+  p = putLenPrefixed(out, p, m);
+  p = putLenPrefixed(out, p, t);
+  out.set(frame, p);
+  return out;
+}
+
+/** Read one length-prefixed string at `at`; `null` when truncated/malformed. */
+function readLenPrefixed(
+  bytes: Uint8Array,
+  at: number,
+): { str: string; next: number } | null {
+  if (at >= bytes.byteLength) return null;
+  const len = bytes[at]!;
+  if (at + 1 + len > bytes.byteLength) return null;
+  return { str: dec.decode(bytes.subarray(at + 1, at + 1 + len)), next: at + 1 + len };
+}
+
+/**
+ * Decode a cluster envelope. Returns `null` for undecodable input or a
+ * foreign/legacy envelope version (callers count those as errors).
+ */
+export function decodeClusterMessage(bytes: Uint8Array): ClusterEnvelope | null {
+  if (bytes.byteLength < 4) return null;
+  if (bytes[0] !== CLUSTER_ENV_VERSION) return null; // foreign / legacy envelope
+  const o = readLenPrefixed(bytes, 1);
+  if (!o) return null;
+  const kindId = bytes[o.next];
+  if (kindId === undefined || kindId >= CLUSTER_KINDS.length) return null;
+  const k = readLenPrefixed(bytes, o.next + 1);
+  if (!k) return null;
+  const n = readLenPrefixed(bytes, k.next);
+  if (!n) return null;
+  const m = readLenPrefixed(bytes, n.next);
+  if (!m) return null;
+  const t = readLenPrefixed(bytes, m.next);
+  if (!t) return null;
+  const kind = clusterKindFromId(kindId);
+  if (kind === undefined) return null;
+  return {
+    origin: o.str,
+    kind,
+    key: k.str,
+    name: n.str,
+    msgId: m.str,
+    traceId: t.str,
+    frame: bytes.subarray(t.next),
+  };
+}

package/src/events/cluster/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Cluster sync — barrel. Horizontal scaling for the events layer, decomposed
+ * by concern:
+ *
+ *   kinds           — routing-kind constants + wire ids
+ *   envelope        — the self-describing binary frame codec (pure)
+ *   subjects        — broker channel names derived from the prefix
+ *   presence        — presence message codec (join/leave/sync)
+ *   presence-table  — in-memory remote-presence index with TTL pruning
+ *   dedupe          — bounded broker-redelivery dedupe window
+ *   keys            — shared-state key builders
+ *   sync            — createClusterSync composition root
+ *   transport-nats / transport-redis — ClusterTransport adapters
+ *   store-memory / store-redis       — ClusterStateStore adapters
+ *
+ * All cross-instance work is deferred to the offload queue — the emit call
+ * never blocks on a broker.
+ */
+
+export { CLUSTER_ENV_VERSION, CLUSTER_KINDS, CLUSTER_KIND_ID, clusterKindFromId, type ClusterKind } from "./kinds";
+export { decodeClusterMessage, encodeClusterMessage, type ClusterEnvelope } from "./envelope";
+export { createClusterSubjects, type ClusterSubjects } from "./subjects";
+export {
+  decodePresence,
+  encodePresence,
+  type PresenceJoin,
+  type PresenceLeave,
+  type PresenceMessage,
+  type PresenceSync,
+} from "./presence";
+export { createPresenceTable, type PresenceTable } from "./presence-table";
+export { createDedupeWindow, type DedupeWindow } from "./dedupe";
+export {
+  clientDataKey,
+  clientGroupStateKey,
+  parsePresenceMember,
+  presenceInstanceKey,
+  presenceUserKey,
+  userGroupStateKey,
+} from "./keys";
+export {
+  createClusterSync,
+  type ClusterMsgMeta,
+  type ClusterSync,
+  type ClusterSyncOptions,
+} from "./sync";
+export { createNatsClusterTransport } from "./transport-nats";
+export { createRedisClusterTransport } from "./transport-redis";
+export { createMemoryStateStore } from "./store-memory";
+export { createRedisStateStore } from "./store-redis";

package/src/events/cluster/keys.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared-state key builders — the canonical key names used in the
+ * `ClusterStateStore` (Redis in production). Centralized so every instance
+ * agrees on the layout; pure string functions.
+ */
+
+/** User-group membership set (`member` = userId). */
+export const userGroupStateKey = (name: string): string => `ignex:group-users:${name}`;
+
+/** Client-group membership set (`member` = clientId). */
+export const clientGroupStateKey = (name: string): string => `ignex:group:${name}`;
+
+/** Per-user presence index (`member` = `{instanceId}:{clientId}`). */
+export const presenceUserKey = (userId: string): string => `ignex:presence:user:${userId}`;
+
+/** Per-instance presence index (`member` = clientId). */
+export const presenceInstanceKey = (instanceId: string): string =>
+  `ignex:presence:instance:${instanceId}`;
+
+/** Client data blob (JSON string). */
+export const clientDataKey = (clientId: string): string => `ignex:client-data:${clientId}`;
+
+/**
+ * Split a `{instanceId}:{clientId}` presence member back into its parts.
+ * Returns `null` for malformed members (never crashes on foreign data).
+ */
+export function parsePresenceMember(
+  member: string,
+): { instanceId: string; clientId: string } | null {
+  const idx = member.indexOf(":");
+  if (idx <= 0) return null;
+  return { instanceId: member.slice(0, idx), clientId: member.slice(idx + 1) };
+}

package/src/events/cluster/kinds.ts

@@ -0,0 +1,32 @@
+/**
+ * Cluster routing kinds — the semantic addressing modes carried in the
+ * cluster envelope. Numeric ids ride the wire; the strings are internal.
+ *
+ * Pure constants module (part of the `src/events/cluster` composition).
+ */
+
+/** Every envelope kind, in wire order (index = kind id). */
+export const CLUSTER_KINDS = ["broadcast", "topic", "group", "user", "client", "presence"] as const;
+export type ClusterKind = (typeof CLUSTER_KINDS)[number];
+
+/** Wire encoding of a {@link ClusterKind} (single byte). */
+export const CLUSTER_KIND_ID: Record<ClusterKind, number> = {
+  broadcast: 0,
+  topic: 1,
+  group: 2,
+  user: 3,
+  client: 4,
+  presence: 5,
+};
+
+/**
+ * Envelope format version. A peer on a different version fails the version
+ * check and its frames are counted as errors — mixed-version clusters during
+ * a rolling upgrade degrade visibly instead of delivering corrupt frames.
+ */
+export const CLUSTER_ENV_VERSION = 2;
+
+/** Map a numeric wire kind back to its name (`undefined` when out of range). */
+export function clusterKindFromId(id: number): ClusterKind | undefined {
+  return CLUSTER_KINDS[id];
+}

package/src/events/cluster/presence-table.ts

@@ -0,0 +1,99 @@
+/**
+ * Presence table — in-memory index of OTHER instances' connections, learned
+ * from presence join/leave/sync messages and pruned by TTL.
+ *
+ * Encapsulated factory (like `createMetrics`): all mutation is private; the
+ * surface is queries + pure-ish updates. No timers, no I/O — the sync layer
+ * drives it from broker messages and the heartbeat tick.
+ */
+import type { RemoteClient } from "../types";
+
+export interface PresenceTable {
+  /** record that `instance` was heard from at epoch ms `at` */
+  touch(instance: string, at: number): void;
+  /** heartbeat from `instance`: refresh the instance AND its reported clients */
+  refreshInstance(instance: string, at: number): void;
+  /** a connection joined on a remote instance */
+  join(clientId: string, instanceId: string, userId: string | undefined, at: number): void;
+  /**
+   * a connection left a remote instance — only honored when the reporting
+   * instance still owns the record (stale leaves from older epochs are ignored)
+   */
+  leave(clientId: string, instanceId: string): void;
+  /** drop clients/instances not heard from within `ttlMs` */
+  prune(ttlMs: number, now?: number): void;
+  /** instances that currently hold `clientId` ([] = unknown) */
+  instancesForClient(clientId: string): string[];
+  /** unique instances holding any connection of `userId` */
+  instancesForUser(userId: string): string[];
+  /** every other instance heard from recently */
+  knownInstances(): string[];
+  /** snapshot of remote connection records */
+  remoteClients(): RemoteClient[];
+}
+
+export function createPresenceTable(): PresenceTable {
+  // clientId → remote record
+  const remote = new Map<string, RemoteClient>();
+  // other instanceId → last-seen epoch ms
+  const instanceSeen = new Map<string, number>();
+
+  return {
+    touch(instance, at) {
+      instanceSeen.set(instance, at);
+    },
+
+    refreshInstance(instance, at) {
+      instanceSeen.set(instance, at);
+      for (const r of remote.values()) {
+        if (r.instanceId === instance) r.lastSeen = at;
+      }
+    },
+
+    join(clientId, instanceId, userId, at) {
+      instanceSeen.set(instanceId, at);
+      remote.set(clientId, {
+        clientId,
+        instanceId,
+        ...(userId !== undefined ? { userId } : {}),
+        lastSeen: at,
+      });
+    },
+
+    leave(clientId, instanceId) {
+      instanceSeen.set(instanceId, Date.now());
+      const r = remote.get(clientId);
+      if (r && r.instanceId === instanceId) remote.delete(clientId);
+    },
+
+    prune(ttlMs, now = Date.now()) {
+      for (const [clientId, r] of remote) {
+        if (now - r.lastSeen > ttlMs) remote.delete(clientId);
+      }
+      for (const [inst, at] of instanceSeen) {
+        if (now - at > ttlMs) instanceSeen.delete(inst);
+      }
+    },
+
+    instancesForClient(clientId) {
+      const r = remote.get(clientId);
+      return r ? [r.instanceId] : [];
+    },
+
+    instancesForUser(userId) {
+      const out: string[] = [];
+      for (const r of remote.values()) {
+        if (r.userId === userId && !out.includes(r.instanceId)) out.push(r.instanceId);
+      }
+      return out;
+    },
+
+    knownInstances() {
+      return [...instanceSeen.keys()];
+    },
+
+    remoteClients() {
+      return [...remote.values()];
+    },
+  };
+}

package/src/events/cluster/presence.ts

@@ -0,0 +1,53 @@
+/**
+ * Presence messages — the tiny JSON payloads exchanged on the `presence`
+ * channel (kind = "presence", frame = JSON) so instances learn about each
+ * other's connections WITHOUT any shared state.
+ *
+ * Pure codec module.
+ */
+
+/** A connection joined on instance `i`. */
+export interface PresenceJoin {
+  t: "j";
+  i: string;
+  c: string;
+  u?: string;
+  at: number;
+}
+
+/** A connection left instance `i`. */
+export interface PresenceLeave {
+  t: "l";
+  i: string;
+  c: string;
+}
+
+/** Periodic per-instance heartbeat (also refreshes liveness). */
+export interface PresenceSync {
+  t: "s";
+  i: string;
+  at: number;
+}
+
+export type PresenceMessage = PresenceJoin | PresenceLeave | PresenceSync;
+
+// module-global codecs: allocated once, reused for every message
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/** Encode a presence message into the envelope's frame bytes. */
+export function encodePresence(msg: PresenceMessage): Uint8Array {
+  return enc.encode(JSON.stringify(msg));
+}
+
+/**
+ * Decode presence bytes; `null` when malformed (callers drop silently —
+ * presence is advisory and self-healing via heartbeat/TTL).
+ */
+export function decodePresence(bytes: Uint8Array): PresenceMessage | null {
+  try {
+    return JSON.parse(dec.decode(bytes)) as PresenceMessage;
+  } catch {
+    return null;
+  }
+}

package/src/events/cluster/redis-client.ts

@@ -0,0 +1,50 @@
+/**
+ * Lazy `ioredis` loader — shared by the Redis cluster transport and the Redis
+ * state store. Redis is an OPTIONAL peer dependency: it is never bundled and
+ * only loaded when a Redis option is actually used.
+ *
+ * The structural types below describe the small slice of ioredis nova uses;
+ * they are intentionally loose (the library is untyped here) but ABI-exact.
+ */
+import { createRequire } from "node:module";
+import type { RedisConnectionOptions } from "../types";
+
+const nodeRequire = createRequire(import.meta.url);
+
+/** Structural type of the ioredis client surface nova relies on. */
+export interface IoredisClient {
+  publish(channel: string, data: Buffer): Promise<unknown>;
+  subscribe(...channels: string[]): Promise<unknown>;
+  psubscribe(...patterns: string[]): Promise<unknown>;
+  unsubscribe(...channels: string[]): Promise<unknown>;
+  punsubscribe(...patterns: string[]): Promise<unknown>;
+  on(event: string, cb: (...args: unknown[]) => void): unknown;
+  get(key: string): Promise<unknown>;
+  set(...args: unknown[]): Promise<unknown>;
+  del(...keys: string[]): Promise<unknown>;
+  sadd(key: string, member: string): Promise<unknown>;
+  srem(key: string, member: string): Promise<unknown>;
+  smembers(key: string): Promise<unknown>;
+  expire(key: string, seconds: number): Promise<unknown>;
+  quit(): Promise<unknown>;
+  readonly status: string;
+}
+
+/** Synchronously load the ioredis constructor (throws with install guidance). */
+export function loadRedis(): new (...args: unknown[]) => IoredisClient {
+  try {
+    return nodeRequire("ioredis") as new (...args: unknown[]) => IoredisClient;
+  } catch {
+    throw new Error(
+      "ignex events cluster: Redis configured but 'ioredis' is not installed — run `bun add ioredis` (or pass a custom cluster.transport / cluster.state)",
+    );
+  }
+}
+
+/** Split connection options into ioredis ctor args ({url} vs {options}). */
+export function redisConnArgs(opts: RedisConnectionOptions): {
+  url?: string;
+  options?: Record<string, unknown>;
+} {
+  return typeof opts === "string" ? { url: opts } : { options: opts };
+}

package/src/events/cluster/store-memory.ts

@@ -0,0 +1,67 @@
+/**
+ * In-memory state store — per-process default `ClusterStateStore`.
+ * Pass a SHARED `Map` to simulate a cross-instance store in tests /
+ * single-process multi-instance setups.
+ *
+ * TTLs are modeled with a parallel `__ttl:` key checked lazily on read.
+ */
+import type { ClusterStateStore } from "../types";
+
+export function createMemoryStateStore(
+  shared?: Map<string, unknown>,
+): ClusterStateStore & { close(): Promise<void> } {
+  const data = shared ?? new Map<string, unknown>();
+
+  const ttlKey = (key: string): string => `__ttl:${key}`;
+
+  /** Lazily expire: drop the key when its TTL has passed; report liveness. */
+  const alive = (key: string): boolean => {
+    const ttl = data.get(ttlKey(key));
+    if (ttl === undefined) return true;
+    if (Date.now() > Number(ttl)) {
+      data.delete(key);
+      data.delete(ttlKey(key));
+      return false;
+    }
+    return true;
+  };
+
+  return {
+    async get(key) {
+      if (!alive(key)) return null;
+      const v = data.get(key);
+      return typeof v === "string" ? v : null;
+    },
+    async set(key, value, ttlMs) {
+      data.set(key, value);
+      if (ttlMs !== undefined) data.set(ttlKey(key), Date.now() + ttlMs);
+    },
+    async del(key) {
+      data.delete(key);
+      data.delete(ttlKey(key));
+    },
+    async sadd(key, member) {
+      let s = data.get(key);
+      if (!(s instanceof Set)) {
+        s = new Set<string>();
+        data.set(key, s);
+      }
+      (s as Set<string>).add(member);
+    },
+    async srem(key, member) {
+      const s = data.get(key);
+      if (s instanceof Set) (s as Set<string>).delete(member);
+    },
+    async smembers(key) {
+      if (!alive(key)) return [];
+      const s = data.get(key);
+      return s instanceof Set ? [...(s as Set<string>)] : [];
+    },
+    async expire(key, ttlMs) {
+      data.set(ttlKey(key), Date.now() + ttlMs);
+    },
+    async close() {
+      data.clear();
+    },
+  };
+}

package/src/events/cluster/store-redis.ts

@@ -0,0 +1,44 @@
+/**
+ * Redis state store (lazy `ioredis`). The production `ClusterStateStore` for
+ * horizontally scaled deployments — every call is issued from the offload
+ * queue, never from the WS hot path.
+ */
+import type { ClusterStateStore, RedisConnectionOptions } from "../types";
+import { loadRedis } from "./redis-client";
+
+export function createRedisStateStore(
+  opts: RedisConnectionOptions = {},
+): ClusterStateStore & { close(): Promise<void> } {
+  const Redis = loadRedis();
+  const r = new Redis(opts);
+  return {
+    async get(key) {
+      const v = await r.get(key);
+      return v == null ? null : String(v);
+    },
+    async set(key, value, ttlMs) {
+      if (ttlMs !== undefined) await r.set(key, value, "PX", ttlMs);
+      else await r.set(key, value);
+    },
+    async del(key) {
+      await r.del(key);
+    },
+    async sadd(key, member) {
+      await r.sadd(key, member);
+    },
+    async srem(key, member) {
+      await r.srem(key, member);
+    },
+    async smembers(key) {
+      const v = await r.smembers(key);
+      return Array.isArray(v) ? v.map(String) : [];
+    },
+    // redis EXPIRE is second-granularity — round up so short TTLs still hold
+    async expire(key, ttlMs) {
+      await r.expire(key, Math.max(1, Math.ceil(ttlMs / 1000)));
+    },
+    async close() {
+      await r.quit();
+    },
+  };
+}

package/src/events/cluster/subjects.ts

@@ -0,0 +1,30 @@
+/**
+ * Cluster subject space — the broker channel names derived from the prefix.
+ *
+ * Every instance subscribes ONE wildcard channel (full-mesh kinds + presence)
+ * plus its own per-instance channel (routed targeted delivery). The envelope
+ * carries routing, so these names are pure syntax.
+ *
+ * Pure factory — no I/O.
+ */
+import type { EmitTargetKind } from "../types";
+
+/** The three subject shapes used by cluster messaging. */
+export interface ClusterSubjects {
+  /** the one channel every instance subscribes to (full-mesh kinds) */
+  all(): string;
+  /** per-instance channel — routed targeted delivery lands here only */
+  instance(id: string): string;
+  /** publish channel for a target kind (also the external visibility of the subject space) */
+  event(kind: EmitTargetKind, key: string | undefined, name: string): string;
+}
+
+export function createClusterSubjects(prefix: string): ClusterSubjects {
+  const base = `${prefix}.cluster`;
+  return {
+    all: () => `${base}.>`,
+    instance: (id) => `${base}.instance.${id}`,
+    event: (kind, key, name) =>
+      key === undefined ? `${base}.${kind}.${name}` : `${base}.${kind}.${key}.${name}`,
+  };
+}