@ignex/nova 0.1.3 → 0.1.6

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/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

@@ -19,6 +19,7 @@ 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 {
@@ -26,18 +27,32 @@ export interface EmitCounters {
   emittedByTarget: Record<EmitTargetKind, number>;
   deliveredLocal: number;
   clusterPublished: number;
+  clusterRouted: number;
 }
 
 export interface EmitEngine {
-  emit(name: string, payload: unknown, target: EmitTarget): void;
+  emit(name: string, payload: unknown, target: EmitTarget, parentTraceId?: string): void;
 }
 
 export interface EmitterOptions {
   state: ServerState;
   bridge?: NatsBridge;
   cluster?: ClusterSync;
-  /** local sockets acting on behalf of a userId (user-target delivery) */
-  userSockets: (userId: string) => ServerWebSocket<WsData>[];
+  /**
+   * 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;
 }
 
@@ -46,7 +61,7 @@ export function deliverLocal(
   state: ServerState,
   target: EmitTarget,
   frame: Uint8Array,
-  userSockets: (userId: string) => ServerWebSocket<WsData>[],
+  eachUserSocket: EmitterOptions["eachUserSocket"],
 ): number {
   switch (target.type) {
     case "broadcast": {
@@ -64,9 +79,7 @@ export function deliverLocal(
       return n;
     }
     case "user": {
-      const list = userSockets(target.userId);
-      for (const ws of list) sendFrame(state, ws, frame);
-      return list.length;
+      return eachUserSocket(target.userId, (ws) => sendFrame(state, ws, frame));
     }
     case "client": {
       const ws = state.clients.get(target.clientId);
@@ -109,19 +122,52 @@ export function createEmitter(opts: EmitterOptions): EmitEngine {
   };
 
   return {
-    emit(name, payload, target) {
+    emit(name, payload, target, parentTraceId) {
       const frame = state.transport.encodeToScratch(name, payload);
       opts.counters.emitted++;
       opts.counters.emittedByTarget[target.type]++;
-      opts.counters.deliveredLocal += deliverLocal(state, target, frame, opts.userSockets);
+      // 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) {
-        opts.counters.clusterPublished++;
-        cluster.publish(target.type, targetKey(target), name, frame);
+        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/hub/context-factory.ts

@@ -0,0 +1,79 @@
+/**
+ * Context factory — builds and CACHES the {@link EventContext} handed to
+ * handlers.
+ *
+ * Contexts are CACHED (instantiation-time work, not per-event work): every
+ * EventContext is immutable and its closures are bound to the stable hub API,
+ * so one context per client record + one shared context per client-less
+ * source is built once and reused — dispatching an event allocates nothing.
+ *
+ * The hub reference is injected lazily (`getHub`) because the factory is
+ * constructed before the hub API object exists.
+ */
+import type { ServerWebSocket } from "bun";
+import type { Bindings } from "../../bindings/types";
+import type { WsData } from "../../core/state";
+import type { EventClient, EventContext, EventSource } from "../types";
+
+export interface ContextFactory<B extends Bindings> {
+  /** context for a client-sent event (cached per client record) */
+  forClient(client: EventClient): EventContext<B>;
+  /** full form: explicit client + source (client-less sources share one ctx) */
+  make(client: EventClient | undefined, source: EventSource): EventContext<B>;
+}
+
+export function createContextFactory<B extends Bindings>(deps: {
+  server: IgnServerOf<B>;
+  getHub: () => EventsHubOf<B>;
+}): ContextFactory<B> {
+  const { server, getHub } = deps;
+
+  /** Assemble a fresh context bound to the stable hub API. */
+  const buildCtx = (client: EventClient | undefined, source: EventSource): EventContext<B> => {
+    const hub = getHub();
+    const ctx: EventContext<B> = {
+      source,
+      hub,
+      server,
+      emit: (name, payload, target) => hub.emit(name as never, payload as never, target),
+      emitToGroup: (group, name, payload) => hub.emitToGroup(group, name as never, payload as never),
+      emitToUser: (userId, name, payload) => hub.emitToUser(userId, name as never, payload as never),
+      emitToClient: (clientId, name, payload) =>
+        hub.emitToClient(clientId, name as never, payload as never),
+      emitToTopic: (topic, name, payload) => hub.emitToTopic(topic, name as never, payload as never),
+      ...(client ? { client } : {}),
+    };
+    return ctx;
+  };
+
+  // caches: per-client contexts + one shared context per client-less source
+  const ctxByClient = new WeakMap<object, EventContext<B>>();
+  const sharedCtxs = new Map<EventSource, EventContext<B>>();
+
+  return {
+    forClient(client) {
+      let ctx = ctxByClient.get(client);
+      if (ctx === undefined) {
+        ctx = buildCtx(client, "client");
+        ctxByClient.set(client, ctx);
+      }
+      return ctx;
+    },
+    make(client, source) {
+      if (client === undefined) {
+        let shared = sharedCtxs.get(source);
+        if (shared === undefined) {
+          shared = buildCtx(undefined, source);
+          sharedCtxs.set(source, shared);
+        }
+        return shared;
+      }
+      return this.forClient(client);
+    },
+  };
+}
+
+/** Structural stand-ins to keep this module free of circular type imports. */
+type IgnServerOf<B extends Bindings> = import("../../core/server").IgnServer<B>;
+type EventsHubOf<B extends Bindings> = import("../types").EventsHub<B>;
+export type HubSocket = ServerWebSocket<WsData>;

package/src/events/hub/dispatch.ts

@@ -0,0 +1,86 @@
+/**
+ * Handler dispatch — routes an inbound event to the registry, optionally with
+ * the reliability layer (retry + DLQ). When no policy is configured this is a
+ * plain fire-and-forget dispatch: zero overhead on the hot path.
+ */
+import type { EventContext } from "../types";
+import type { HandlerRegistry } from "../registry";
+import {
+  deliverWithRetry,
+  resolveDeliveryPolicy,
+  type DeliveryPolicy,
+  type ResolvedDeliveryPolicy,
+} from "../delivery";
+
+/** How the hub counts reliability activity (folded into metrics). */
+export interface DispatchCounters {
+  /** retry schedules by the delivery layer */
+  handlerRetries: number;
+  /** events dead-lettered after exhausting retries */
+  dlqCount: number;
+}
+
+/**
+ * Build the resolved policy + registry pair used by {@link createDispatcher}.
+ * Returns `policy: null` when handlers are unconfigured (plain dispatch).
+ */
+export function resolveDispatchPolicy(
+  opts: DeliveryPolicy | undefined,
+  counters: DispatchCounters,
+): ResolvedDeliveryPolicy | null {
+  if (!opts) return null;
+  return resolveDeliveryPolicy({
+    ...opts,
+    dlq: (info) => {
+      counters.dlqCount++;
+      opts.dlq?.(info);
+    },
+  });
+}
+
+export interface Dispatcher<B extends import("../../bindings/types").Bindings> {
+  /** dispatch a client-sent event */
+  client(name: string, payload: unknown, ctx: EventContext<B>): void;
+  /** dispatch a server-side event (remote instance / bridge origin) */
+  server(name: string, payload: unknown, ctx: EventContext<B>): void;
+}
+
+/**
+ * Reliability-aware dispatcher. `mode` selects the handler surface
+ * (client-sent vs server-side); retries are counted into `counters`.
+ */
+export function createDispatcher<B extends import("../../bindings/types").Bindings>(deps: {
+  registry: HandlerRegistry & { settleDispatch: HandlerRegistry["settleDispatch"] };
+  policy: ResolvedDeliveryPolicy | null;
+  counters: DispatchCounters;
+}): Dispatcher<B> {
+  const { registry, policy, counters } = deps;
+  const dispatch = (
+    name: string,
+    payload: unknown,
+    ctx: EventContext<B>,
+    mode: "client" | "server",
+  ): void => {
+    if (policy === null) {
+      // default: plain dispatch, zero overhead
+      if (mode === "server") registry.dispatchServerEvent(name, payload, ctx);
+      else registry.dispatch(name, payload, ctx);
+      return;
+    }
+    void deliverWithRetry(
+      registry,
+      policy,
+      name,
+      payload,
+      ctx,
+      () => {
+        counters.handlerRetries++;
+      },
+      mode,
+    );
+  };
+  return {
+    client: (name, payload, ctx) => dispatch(name, payload, ctx, "client"),
+    server: (name, payload, ctx) => dispatch(name, payload, ctx, "server"),
+  };
+}