@ignex/nova 0.1.3 → 0.1.5

package/src/core/topic-log.ts

@@ -0,0 +1,86 @@
+/**
+ * Durable topic-log seam — the pluggable backend behind the bounded replay
+ * ring. The ring keeps the LAST N frames per topic in memory; a {@link TopicLog}
+ * receives the same frames so subscribers can resume from points the ring has
+ * already forgotten.
+ *
+ * Contract (deliberately narrow):
+ *   - `append` is SYNCHRONOUS and must never throw onto the publish hot path —
+ *     implementations buffer internally and flush on their own schedule (the
+ *     memory impl appends to an array; a file impl would hand off to a writer;
+ *     a NATS JetStream / Redis Streams impl would enqueue a publish).
+ *   - `range(topic, afterSeq, limit?)` returns frames strictly AFTER `afterSeq`
+ *     oldest → newest, synchronously. Adapters over remote stores should
+ *     maintain a local read-through cache so this stays sync-friendly.
+ *   - `latestSeq(topic)` mirrors the server's replay-seq counter for the topic
+ *     (0 = unknown/empty).
+ *
+ * Ship-with implementation: {@link createMemoryTopicLog} — per-topic bounded
+ * array (drop-oldest), process-local durability (survives ring overflow, not a
+ * restart). Production adapters (JetStream / Redis Streams / filesystem)
+ * implement the same three methods — see docs/architecture.md ("Durability").
+ */
+import { RingBuffer } from "./ring";
+
+/** One durably-retained topic frame. */
+export interface LoggedFrame {
+  /** global replay seq (the same counter stamped into the topic history) */
+  seq: number;
+  frame: Uint8Array;
+}
+
+export interface TopicLog {
+  /** Record a frame for `topic` (fire-and-forget; never throws). */
+  append(topic: string, frame: Uint8Array, seq: number): void;
+  /** Frames strictly after `afterSeq`, oldest → newest (at most `limit`). */
+  range(topic: string, afterSeq: number, limit?: number): LoggedFrame[];
+  /** Highest seq retained for `topic` (0 = none). */
+  latestSeq(topic: string): number;
+  /** Release resources (flush buffers, close files/connections). */
+  close(): void;
+}
+
+export interface MemoryTopicLogOptions {
+  /** max frames retained PER TOPIC (drop-oldest beyond), default 10_000 */
+  maxPerTopic?: number;
+}
+
+/** Process-local durable log: survives ring overflow, not a restart. */
+export function createMemoryTopicLog(
+  opts: MemoryTopicLogOptions = {},
+): TopicLog {
+  const max = Math.max(1, opts.maxPerTopic ?? 10_000);
+  const topics = new Map<string, { frames: RingBuffer<LoggedFrame>; latest: number }>();
+  const ensure = (topic: string) => {
+    let t = topics.get(topic);
+    if (!t) {
+      t = { frames: new RingBuffer<LoggedFrame>(max, true), latest: 0 };
+      topics.set(topic, t);
+    }
+    return t;
+  };
+  return {
+    append(topic, frame, seq) {
+      const t = ensure(topic);
+      t.frames.push({ seq, frame: frame.slice() });
+      if (seq > t.latest) t.latest = seq;
+    },
+    range(topic, afterSeq, limit) {
+      const t = topics.get(topic);
+      if (!t) return [];
+      const out: LoggedFrame[] = [];
+      for (const e of t.frames) {
+        if (e.seq <= afterSeq) continue;
+        out.push(e);
+        if (limit !== undefined && out.length >= limit) break;
+      }
+      return out;
+    },
+    latestSeq(topic) {
+      return topics.get(topic)?.latest ?? 0;
+    },
+    close() {
+      topics.clear();
+    },
+  };
+}

package/src/events/clients.ts

@@ -67,6 +67,11 @@ export interface ClientStore {
   get(id: string): EventClient | undefined;
   all(): EventClient[];
   byUser(userId: string): EventClient[];
+  /**
+   * Invoke `each` for every live socket of `userId`; returns the count.
+   * Allocation-free variant of {@link byUser} for emit hot paths.
+   */
+  forEachByUser(userId: string, each: (client: EventClient) => void): number;
   setUserId(clientId: string, userId: string): boolean;
   onAttach(cb: (client: EventClient) => void): void;
   onDetach(cb: (client: EventClient) => void): void;
@@ -136,6 +141,19 @@ export function createClientStore(): ClientStore {
       }
       return out;
     },
+    forEachByUser(userId, each) {
+      const ids = byUser.get(userId);
+      if (ids === undefined || ids.size === 0) return 0;
+      let n = 0;
+      for (const id of ids) {
+        const c = byId.get(id);
+        if (c !== undefined) {
+          each(c);
+          n++;
+        }
+      }
+      return n;
+    },
     setUserId(clientId, userId) {
       const client = byId.get(clientId);
       if (!client) return false;

package/src/events/cluster/dedupe.ts

@@ -0,0 +1,43 @@
+/**
+ * Broker-redelivery dedupe window — bounded recent-message-id tracking.
+ *
+ * Durable brokers may redeliver; every processed message id is recorded in a
+ * ring + set pair and duplicates are dropped. Encapsulated factory (like
+ * `createMetrics`) — the state is private, the surface is one pure predicate.
+ */
+import { RingBuffer } from "../../core/ring";
+
+export interface DedupeWindow {
+  /**
+   * Record `id` and report whether it was ALREADY seen (true → drop the
+   * message). Empty ids and a zero-size window disable tracking entirely.
+   */
+  markSeen(id: string): boolean;
+}
+
+/**
+ * @param size how many message ids to remember (0 disables; values < 16 are
+ *   clamped up so the ring has usable capacity).
+ */
+export function createDedupeWindow(size: number): DedupeWindow {
+  const window = Math.max(0, size);
+  if (window === 0) return { markSeen: () => false };
+
+  const ring = new RingBuffer<string>(Math.max(16, window), true);
+  const seen = new Set<string>();
+
+  return {
+    markSeen(id: string): boolean {
+      if (id === "") return false;
+      if (seen.has(id)) return true;
+      // evict the oldest id when the window is full (FIFO — matches redelivery)
+      if (ring.length >= window) {
+        const evict = ring.shift();
+        if (evict !== undefined) seen.delete(evict);
+      }
+      ring.push(id);
+      seen.add(id);
+      return false;
+    },
+  };
+}

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 };
+}