@ignex/nova 0.1.3 → 0.1.6

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