@ignex/nova 0.1.1 → 0.1.5

package/src/events/cluster-rpc.ts

@@ -0,0 +1,196 @@
+/**
+ * Cross-instance RPC — request/response between hub instances over the
+ * {@link ClusterTransport} (NATS / Redis / custom). Complements the WS-level
+ * `client.request` ⇄ `server.handle` path: THIS layer is server ⇄ server,
+ * e.g. "instance A, what is your live client count?" or "run this against the
+ * instance holding user u-42's socket".
+ *
+ * Wire format: a small JSON envelope (this is an admin/control path, never
+ * the WS hot path):
+ *   { v: 1, t: "req" | "res", id, from, method, args?, ok?, err?, result? }
+ *
+ * Subjects: `{prefix}.cluster.rpc.{instanceId}` (targeted) and
+ * `{prefix}.cluster.rpc.any` (any-instance calls — every instance receives
+ * the request; the FIRST response wins and later ones are ignored).
+ *
+ * All transport work runs through the offload queue contract: publish() is
+ * sync-but-cheap on the transport, subscriptions deliver on the broker's
+ * callbacks; pending calls carry their own timeout so a dead instance can
+ * never hang a caller beyond it.
+ */
+import type { ClusterTransport } from "./types";
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+interface RpcRequest {
+  v: 1;
+  t: "req";
+  id: string;
+  from: string;
+  method: string;
+  args: unknown;
+}
+interface RpcResponse {
+  v: 1;
+  t: "res";
+  id: string;
+  from: string;
+  ok: boolean;
+  err?: string;
+  result?: unknown;
+}
+type RpcMessage = RpcRequest | RpcResponse;
+
+export type RpcMethodHandler = (args: unknown, fromInstanceId: string) => unknown | Promise<unknown>;
+
+export interface ClusterRpc {
+  /**
+   * Call `method` on ONE instance (`instanceId`) or on any instance
+   * (omit → `{prefix}.cluster.rpc.any`; first response wins). Rejects on
+   * timeout (`timeoutMs`, default 5000) with no response.
+   */
+  call(method: string, args?: unknown, opts?: { readonly instanceId?: string; readonly timeoutMs?: number }): Promise<unknown>;
+  /** register a method handler (last registration wins) */
+  on(method: string, handler: RpcMethodHandler): void;
+  /** registered method names */
+  methods(): string[];
+  stats(): { sent: number; received: number; timeouts: number; errors: number };
+  close(): void;
+}
+
+export interface ClusterRpcOptions {
+  instanceId: string;
+  prefix: string;
+  transport: ClusterTransport;
+}
+
+export function createClusterRpc(opts: ClusterRpcOptions): ClusterRpc {
+  const base = `${opts.prefix}.cluster.rpc`;
+  const selfSubject = `${base}.${opts.instanceId}`;
+  const anySubject = `${base}.any`;
+  const handlers = new Map<string, RpcMethodHandler>();
+  const pending = new Map<
+    string,
+    { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }
+  >();
+  let sent = 0;
+  let received = 0;
+  let timeouts = 0;
+  let errors = 0;
+
+  const post = (msg: RpcMessage, subject: string): boolean => {
+    if (!opts.transport.connected) {
+      errors++;
+      return false;
+    }
+    try {
+      opts.transport.publish(subject, enc.encode(JSON.stringify(msg)));
+      return true;
+    } catch {
+      errors++;
+      return false;
+    }
+  };
+
+  const handleMessage = (data: Uint8Array): void => {
+    let msg: RpcMessage | null = null;
+    try {
+      msg = JSON.parse(dec.decode(data)) as RpcMessage;
+    } catch {
+      return;
+    }
+    if (!msg || msg.v !== 1) return;
+    if (msg.t === "req") {
+      received++;
+      const handler = handlers.get(msg.method);
+      if (!handler) return; // not ours — another instance answers (.any)
+      void (async () => {
+        try {
+          const result = await handler(msg.args, msg.from);
+          post(
+            { v: 1, t: "res", id: msg.id, from: opts.instanceId, ok: true, result },
+            `${base}.${msg.from}`,
+          );
+        } catch (err) {
+          post(
+            {
+              v: 1,
+              t: "res",
+              id: msg.id,
+              from: opts.instanceId,
+              ok: false,
+              err: err instanceof Error ? err.message : String(err),
+            },
+            `${base}.${msg.from}`,
+          );
+        }
+      })();
+      return;
+    }
+    // response — first one wins for .any fan-in
+    const p = pending.get(msg.id);
+    if (!p) return;
+    pending.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.ok) p.resolve(msg.result);
+    else p.reject(new Error(`ignex cluster rpc failed: ${msg.err ?? "unknown error"}`));
+  };
+
+  const unsubs = [opts.transport.subscribe(selfSubject, handleMessage), opts.transport.subscribe(anySubject, handleMessage)];
+
+  return {
+    call(method, args, rpcOpts) {
+      const timeoutMs = rpcOpts?.timeoutMs ?? 5_000;
+      const instanceId = rpcOpts?.instanceId;
+      return new Promise((resolve, reject) => {
+        const id = crypto.randomUUID();
+        const timer = setTimeout(() => {
+          if (!pending.has(id)) return;
+          pending.delete(id);
+          timeouts++;
+          reject(new Error(`ignex cluster rpc "${method}" timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        pending.set(id, { resolve, reject, timer });
+        const req: RpcRequest = {
+          v: 1,
+          t: "req",
+          id,
+          from: opts.instanceId,
+          method,
+          args,
+        };
+        if (!post(req, instanceId !== undefined ? `${base}.${instanceId}` : anySubject)) {
+          clearTimeout(timer);
+          pending.delete(id);
+          reject(new Error("ignex cluster rpc: transport offline"));
+          return;
+        }
+        sent++;
+      });
+    },
+    on(method, handler) {
+      handlers.set(method, handler);
+    },
+    methods() {
+      return [...handlers.keys()];
+    },
+    stats() {
+      return { sent, received, timeouts, errors };
+    },
+    close() {
+      for (const u of unsubs)
+        try {
+          u();
+        } catch {
+          // already unsubscribed
+        }
+      for (const [, p] of pending) {
+        clearTimeout(p.timer);
+        p.reject(new Error("ignex cluster rpc: closed"));
+      }
+      pending.clear();
+      handlers.clear();
+    },
+  };
+}

package/src/events/data.ts

@@ -0,0 +1,38 @@
+/**
+ * Per-connection app data store — the "what to store for each client" half of
+ * the client record. A tiny Map-backed key/value bag with JSON export, created
+ * on attach and discarded on detach (no leak across reconnects).
+ */
+import type { ClientData } from "./types";
+
+export function createClientData(): ClientData {
+  const map = new Map<string, unknown>();
+  return {
+    get(key) {
+      return map.get(key);
+    },
+    set(key, value) {
+      map.set(key, value);
+    },
+    has(key) {
+      return map.has(key);
+    },
+    delete(key) {
+      return map.delete(key);
+    },
+    clear() {
+      map.clear();
+    },
+    keys() {
+      return [...map.keys()];
+    },
+    entries() {
+      return [...map.entries()];
+    },
+    toJSON() {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of map) out[k] = v;
+      return out;
+    },
+  };
+}

package/src/events/delivery.ts

@@ -0,0 +1,83 @@
+/**
+ * Handler reliability — retry with backoff + a dead-letter sink for events
+ * whose handlers keep failing. Opt-in via
+ * `createServer({ events: { handlers: { retries, backoffMs, dlq } } })`.
+ *
+ * Without `handlers` (the default) dispatch is the plain zero-alloc registry
+ * path — this layer is never touched. With it, client / remote / bridge
+ * dispatches go through {@link deliverWithRetry}: each attempt uses the
+ * registry's settling dispatch so async handler rejections count; failures
+ * schedule the next attempt after an exponentially growing delay; exhausting
+ * the budget hands the event to `dlq` (dead-letter queue) — by default a
+ * counter-only sink.
+ */
+
+export type DeadLetterHandler = (info: {
+  readonly name: string;
+  readonly payload: unknown;
+  readonly err: Error;
+  readonly attempts: number;
+}) => void;
+
+export interface DeliveryPolicy {
+  /** retry attempts AFTER the first try (0 = fire once), default 2 */
+  retries?: number;
+  /** base backoff before the first retry (doubles each attempt), default 100 */
+  backoffMs?: number;
+  /** called once when all attempts failed */
+  dlq?: DeadLetterHandler;
+}
+
+export interface ResolvedDeliveryPolicy {
+  retries: number;
+  backoffMs: number;
+  dlq: DeadLetterHandler;
+}
+
+export function resolveDeliveryPolicy(opts: DeliveryPolicy = {}): ResolvedDeliveryPolicy {
+  return {
+    retries: opts.retries ?? 2,
+    backoffMs: opts.backoffMs ?? 100,
+    dlq:
+      opts.dlq ??
+      (() => {
+        /* counter-only default — surfaced via metrics.dlqCount */
+      }),
+  };
+}
+
+interface SettlingRegistry {
+  settleDispatch(name: string, payload: unknown, ctx: unknown, mode?: "client" | "server"): Promise<Error[]>;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Dispatch `name` to `registry`, retrying (with doubling backoff) while any
+ * handler fails, then dead-lettering. Resolves when the event reached its
+ * final state (delivered / dead-lettered). Never throws.
+ */
+export async function deliverWithRetry(
+  registry: SettlingRegistry,
+  policy: ResolvedDeliveryPolicy,
+  name: string,
+  payload: unknown,
+  ctx: unknown,
+  onRetry?: () => void,
+  mode: "client" | "server" = "client",
+): Promise<void> {
+  for (let attempt = 0; ; attempt++) {
+    const errors = await registry.settleDispatch(name, payload, ctx, mode);
+    if (errors.length === 0) return;
+    if (attempt >= policy.retries) {
+      try {
+        policy.dlq({ name, payload, err: errors[errors.length - 1]!, attempts: attempt + 1 });
+      } catch {
+        // a failing DLQ must never break the caller
+      }
+      return;
+    }
+    onRetry?.();
+    await sleep(policy.backoffMs * 2 ** attempt);
+  }
+}

package/src/events/emit.ts

@@ -0,0 +1,173 @@
+/**
+ * Emit engine — the "global emit" hot path. Encodes ONCE through the transport
+ * scratch (zero-alloc on the happy path), delivers to the target's local
+ * sockets synchronously, then hands the SAME frame to the external bridge
+ * (existing NATS broadcast/topic/group subjects) and the cluster sync
+ * (offloaded) so other instances deliver it too.
+ *
+ * Hot-path guarantees:
+ *   - encode + local delivery are synchronous and allocation-free (Bun copies
+ *     on `ws.send`);
+ *   - the bridge `publish` copies the scratch frame (never holds a stale view);
+ *   - cluster work is enqueued on the offload queue — a slow broker can never
+ *     stall the socket loop.
+ */
+import type { ServerWebSocket } from "bun";
+import type { NatsBridge } from "../bridge/nats";
+import type { ServerState, WsData } from "../core/state";
+import { sendFrame } from "../core/outbound";
+import { publishToGroup } from "../core/groups";
+import { publishToRoom } from "../core/rooms";
+import type { ClusterSync } from "./cluster";
+import { capturePayload } from "./trace";
+import type { EmitTarget, EmitTargetKind } from "./types";
+
+export interface EmitCounters {
+  emitted: number;
+  emittedByTarget: Record<EmitTargetKind, number>;
+  deliveredLocal: number;
+  clusterPublished: number;
+  clusterRouted: number;
+}
+
+export interface EmitEngine {
+  emit(name: string, payload: unknown, target: EmitTarget, parentTraceId?: string): void;
+}
+
+export interface EmitterOptions {
+  state: ServerState;
+  bridge?: NatsBridge;
+  cluster?: ClusterSync;
+  /**
+   * Invoke `each` for every LOCAL socket acting on behalf of `userId` and
+   * return how many were invoked. Callback-style (not array-returning) so a
+   * user-targeted emit allocates nothing on the hot path.
+   */
+  eachUserSocket: (
+    userId: string,
+    each: (ws: ServerWebSocket<WsData>) => void,
+  ) => number;
+  /**
+   * ROUTED targeted delivery: for client/user targets return the instance ids
+   * that own the destination connection(s) (presence), or null when unknown —
+   * null falls back to the full-mesh wildcard publish. Absent when no cluster.
+   */
+  routeInstances?: (target: EmitTarget) => readonly string[] | null;
+  counters: EmitCounters;
+}
+
+/** Deliver `frame` to the target's LOCAL sockets; returns the number written. */
+export function deliverLocal(
+  state: ServerState,
+  target: EmitTarget,
+  frame: Uint8Array,
+  eachUserSocket: EmitterOptions["eachUserSocket"],
+): number {
+  switch (target.type) {
+    case "broadcast": {
+      for (const ws of state.sockets) sendFrame(state, ws, frame);
+      return state.sockets.size;
+    }
+    case "topic": {
+      const n = state.rooms.get(target.topic)?.size ?? 0;
+      publishToRoom(state, target.topic, frame);
+      return n;
+    }
+    case "group": {
+      const n = state.groups.get(target.group)?.size ?? 0;
+      publishToGroup(state, target.group, frame);
+      return n;
+    }
+    case "user": {
+      return eachUserSocket(target.userId, (ws) => sendFrame(state, ws, frame));
+    }
+    case "client": {
+      const ws = state.clients.get(target.clientId);
+      if (!ws) return 0;
+      sendFrame(state, ws, frame);
+      return 1;
+    }
+  }
+}
+
+export function targetKey(target: EmitTarget): string | undefined {
+  switch (target.type) {
+    case "broadcast":
+      return undefined;
+    case "topic":
+      return target.topic;
+    case "group":
+      return target.group;
+    case "user":
+      return target.userId;
+    case "client":
+      return target.clientId;
+  }
+}
+
+export function createEmitter(opts: EmitterOptions): EmitEngine {
+  const { state, bridge, cluster } = opts;
+
+  const bridgeSubject = (target: EmitTarget, name: string): string | undefined => {
+    switch (target.type) {
+      case "broadcast":
+        return bridge?.subjects.broadcast(name);
+      case "topic":
+        return bridge?.subjects.topic(target.topic, name);
+      case "group":
+        return bridge?.subjects.group(target.group, name);
+      default:
+        return undefined; // user/client targets are not bridged externally
+    }
+  };
+
+  return {
+    emit(name, payload, target, parentTraceId) {
+      const frame = state.transport.encodeToScratch(name, payload);
+      opts.counters.emitted++;
+      opts.counters.emittedByTarget[target.type]++;
+      // trace first (cheap typed-array stores) so a debugger sees the event
+      // even when delivery has zero local sockets / the bridge is down.
+      state.trace.record(
+        "out.emit",
+        name,
+        target.type,
+        targetKey(target),
+        frame.byteLength,
+        state.trace.captures ? capturePayload(payload, 2000) : undefined,
+      );
+      // EXTERNAL copies (bridge / cluster envelope) come FIRST — they must see
+      // the pristine frame, before per-socket delivery-seq stamping mutates
+      // the shared scratch header below. Both copy the bytes synchronously.
+      if (bridge) {
+        const subject = bridgeSubject(target, name);
+        if (subject) bridge.publish(subject, frame); // copies the scratch view
+      }
+      if (cluster) {
+        const msgId = crypto.randomUUID();
+        const traceId = parentTraceId ?? "";
+        if (opts.routeInstances !== undefined && (target.type === "client" || target.type === "user")) {
+          // ROUTED targeted delivery: only the owning instances receive it
+          const instances = opts.routeInstances(target);
+          if (instances !== null) {
+            opts.counters.clusterPublished++;
+            opts.counters.clusterRouted++;
+            cluster.route(instances, target.type as "client" | "user", targetKey(target) ?? "", name, frame, {
+              msgId,
+              traceId,
+            });
+          } else {
+            // presence knows nothing — fall back to the full mesh
+            opts.counters.clusterPublished++;
+            cluster.publish(target.type, targetKey(target), name, frame, { msgId, traceId });
+          }
+        } else {
+          opts.counters.clusterPublished++;
+          cluster.publish(target.type, targetKey(target), name, frame, { msgId, traceId });
+        }
+      }
+      // local delivery LAST: stamps delivery seqs into the scratch header
+      opts.counters.deliveredLocal += deliverLocal(state, target, frame, opts.eachUserSocket);
+    },
+  };
+}

package/src/events/global.ts

@@ -0,0 +1,117 @@
+/**
+ * Global emit — the module-level singleton the events layer exposes so ANY
+ * module in the app can send events through websockets without holding a
+ * server reference (the "global emit" of the events file pattern):
+ *
+ *   import { on, emit } from "ignex-nova/events";
+ *   on("order.created", (ctx) => { ... });
+ *   emit("quote", { symbol: "AAPL", ... });                       // broadcast
+ *   emit("order", payload, { type: "group", group: "traders" });  // to a group
+ *   emit("alert", payload, { type: "user", userId: "u-1" });      // to a user
+ *
+ * Bound automatically when `createServer({ events: {...} })` runs (last hub
+ * wins — one active hub per process is the supported topology; use
+ * `server.events` directly for per-server control). Calls before binding
+ * throw a descriptive error; calls after `close()` are dropped silently.
+ *
+ * Typed against the BUILT-IN event registry. Custom-schema apps should use
+ * `server.events.emit` / `server.events.on` (fully typed against YOUR events).
+ */
+
+import type { DefaultBindings } from "../bindings/types";
+import type { EventName, Events } from "../schema";
+import type { EmitTarget, EventContext, EventHandler, EventsHub } from "./types";
+
+let bound: EventsHub | null = null;
+
+/** Bind the singleton to a hub (called by the hub on creation). */
+export function bindEvents(hub: EventsHub): void {
+  bound = hub;
+}
+
+/** Unbind the singleton (called by the hub on close). */
+export function unbindEvents(): void {
+  bound = null;
+}
+
+export function isEventsBound(): boolean {
+  return bound !== null;
+}
+
+/** The currently bound hub (null when none). */
+export function getEventsHub(): EventsHub | null {
+  return bound;
+}
+
+function requireHub(): EventsHub {
+  if (!bound) {
+    throw new Error(
+      "ignex events: no events hub bound — pass `events: {}` to createServer() (or call bindEvents(hub) once)",
+    );
+  }
+  return bound;
+}
+
+export function emit<K extends EventName>(name: K, payload: Events[K], target?: EmitTarget): void {
+  requireHub().emit(name as never, payload as never, target);
+}
+
+export function emitToTopic<K extends EventName>(topic: string, name: K, payload: Events[K]): void {
+  requireHub().emitToTopic(topic, name as never, payload as never);
+}
+
+export function emitToGroup<K extends EventName>(group: string, name: K, payload: Events[K]): void {
+  requireHub().emitToGroup(group, name as never, payload as never);
+}
+
+export function emitToUser<K extends EventName>(userId: string, name: K, payload: Events[K]): void {
+  requireHub().emitToUser(userId, name as never, payload as never);
+}
+
+export function emitToClient<K extends EventName>(
+  clientId: string,
+  name: K,
+  payload: Events[K],
+): void {
+  requireHub().emitToClient(clientId, name as never, payload as never);
+}
+
+export function on<K extends EventName>(name: K, handler: EventHandler<DefaultBindings, K>): void {
+  requireHub().on(name as never, handler as never);
+}
+
+export function off<K extends EventName>(
+  name: K,
+  handler?: EventHandler<DefaultBindings, K>,
+): void {
+  requireHub().off(name as never, handler as never);
+}
+
+export function once<K extends EventName>(
+  name: K,
+  handler: EventHandler<DefaultBindings, K>,
+): void {
+  requireHub().once(name as never, handler as never);
+}
+
+export function onAny(cb: (name: string, payload: unknown, ctx: EventContext) => void): void {
+  requireHub().onAny(cb as never);
+}
+
+export function offAny(cb: (name: string, payload: unknown, ctx: EventContext) => void): void {
+  requireHub().offAny(cb as never);
+}
+
+export function onServerEvent<K extends EventName>(
+  name: K,
+  handler: EventHandler<DefaultBindings, K>,
+): void {
+  requireHub().onServerEvent(name as never, handler as never);
+}
+
+export function offServerEvent<K extends EventName>(
+  name: K,
+  handler?: EventHandler<DefaultBindings, K>,
+): void {
+  requireHub().offServerEvent(name as never, handler as never);
+}