@ignex/nova 0.1.1 → 0.1.5

package/src/events/groups.ts

@@ -0,0 +1,118 @@
+/**
+ * Groups — named fan-out dimensions with explicit differentiation:
+ *
+ *   - CLIENT groups (`hub.group(name)`): membership by connection id. These
+ *     reuse the transport's group registry (`state.groups`), so auth-seeded
+ *     groups, control frames (`client.joinGroup`), `server.joinGroup` and the
+ *     events layer all see the SAME membership.
+ *   - USER groups (`hub.userGroup(name)`): membership by `userId`. Emitting to
+ *     a user group fans out to every socket acting on behalf of each member
+ *     user — the "broadcast to a group of people" case, independent of how
+ *     many devices each person has open.
+ *
+ * Both are cluster-aware at the hub level: emit → `emitToGroup` / `emitToUser`
+ * (which publish to the cluster subjects), and membership syncs to the shared
+ * state store when one is configured.
+ */
+import type { ServerWebSocket } from "bun";
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../bindings/types";
+import { activeGroups, groupMembers as stateGroupMembers, joinGroup, leaveGroup } from "../core/groups";
+import type { ServerState, WsData } from "../core/state";
+import type { ClientGroup, UserGroup } from "./types";
+
+export interface GroupManager<B extends Bindings = DefaultBindings> {
+  clientGroup(name: string): ClientGroup<B>;
+  clientGroups(): string[];
+  userGroup(name: string): UserGroup<B>;
+  userGroups(): string[];
+}
+
+export interface GroupManagerOptions<B extends Bindings = DefaultBindings> {
+  state: ServerState;
+  emitToGroup: <K extends EventNameOf<B>>(group: string, name: K, payload: EventsOf<B>[K]) => void;
+  emitToUser: <K extends EventNameOf<B>>(userId: string, name: K, payload: EventsOf<B>[K]) => void;
+  /** fired on user-group membership change (hub wires cluster sync here) */
+  onUserGroupChange?: (name: string, members: ReadonlySet<string>) => void;
+}
+
+export function createGroupManager<B extends Bindings = DefaultBindings>(opts: GroupManagerOptions<B>): GroupManager<B> {
+  const userGroupsMap = new Map<string, Set<string>>();
+
+  const touchUserGroup = (name: string): void => {
+    opts.onUserGroupChange?.(name, userGroupsMap.get(name) ?? new Set());
+  };
+
+  const userGroupHandle = (name: string): UserGroup<B> => {
+    let set = userGroupsMap.get(name);
+    if (!set) {
+      set = new Set();
+      userGroupsMap.set(name, set);
+    }
+    return {
+      get name(): string {
+        return name;
+      },
+      add(userId) {
+        set!.add(userId);
+        touchUserGroup(name);
+      },
+      remove(userId) {
+        const existed = set!.delete(userId);
+        if (existed) {
+          if (set!.size === 0) userGroupsMap.delete(name);
+          touchUserGroup(name);
+        }
+      },
+      has(userId) {
+        return set!.has(userId);
+      },
+      members() {
+        return [...set!];
+      },
+      get size(): number {
+        return set!.size;
+      },
+      emit(event, payload) {
+        const snapshot = [...set!];
+        for (const userId of snapshot) opts.emitToUser(userId, event, payload);
+      },
+    };
+  };
+
+  const clientGroupHandle = (name: string): ClientGroup<B> => {
+    const socket = (clientId: string): ServerWebSocket<WsData> | undefined => opts.state.clients.get(clientId);
+    return {
+      get name(): string {
+        return name;
+      },
+      add(clientId) {
+        const ws = socket(clientId);
+        if (ws) joinGroup(opts.state, ws, name);
+      },
+      remove(clientId) {
+        const ws = socket(clientId);
+        if (ws) leaveGroup(opts.state, ws, name);
+      },
+      has(clientId) {
+        const ws = socket(clientId);
+        return ws !== undefined && ws.data.groups.has(name);
+      },
+      members() {
+        return stateGroupMembers(opts.state, name);
+      },
+      get size(): number {
+        return stateGroupMembers(opts.state, name).length;
+      },
+      emit(event, payload) {
+        opts.emitToGroup(name, event, payload);
+      },
+    };
+  };
+
+  return {
+    clientGroup: clientGroupHandle,
+    clientGroups: () => activeGroups(opts.state),
+    userGroup: userGroupHandle,
+    userGroups: () => [...userGroupsMap.keys()],
+  };
+}

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