@zerotal/broadcasting 1.0.0

package/src/ChannelRegistry.ts

@@ -0,0 +1,112 @@
+// ── Channel authorization registry ────────────────────────────────────────────
+//
+// Holds the per-pattern channel-authorization callbacks registered in `routes/channels.ts`
+// via `Broadcast.channel(...)`. The `/broadcasting/auth` route consults it to decide whether a
+// connection may subscribe to a private/presence channel.
+//
+// Patterns use the framework's file-routing `[param]` placeholder syntax, e.g.
+//   Broadcast.channel("orders.[orderId]", (user, orderId) => ...)
+// Each `[param]` matches one channel segment (no dots) and is passed to the callback positionally
+// after the authenticated user.
+
+/** Member data returned by a presence-channel authorizer. `id` identifies the member. */
+export interface PresenceMemberData {
+  id: string | number;
+  [key: string]: unknown;
+}
+
+/**
+ * A channel authorization callback.
+ * - Private channel: return a boolean (`true` = authorized).
+ * - Presence channel: return a member-data object to authorize + publish presence, or
+ *   `false`/`null`/`undefined` to deny.
+ */
+export type ChannelCallback = (
+  user: unknown,
+  ...params: string[]
+) =>
+  | boolean
+  | PresenceMemberData
+  | null
+  | undefined
+  | Promise<boolean | PresenceMemberData | null | undefined>;
+
+interface CompiledChannel {
+  pattern: string;
+  regex: RegExp;
+  paramNames: string[];
+  callback: ChannelCallback;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Compile a `[param]` pattern into a regex + ordered param names. */
+export function compileChannelPattern(pattern: string): { regex: RegExp; paramNames: string[] } {
+  const paramNames: string[] = [];
+  let regexStr = "^";
+  let lastIndex = 0;
+  const re = /\[(\w+)\]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(pattern)) !== null) {
+    regexStr += escapeRegex(pattern.slice(lastIndex, m.index));
+    regexStr += "([^.]+)";
+    paramNames.push(m[1]!);
+    lastIndex = m.index + m[0].length;
+  }
+  regexStr += escapeRegex(pattern.slice(lastIndex)) + "$";
+  return { regex: new RegExp(regexStr), paramNames };
+}
+
+/** Result of authorizing a channel subscription. */
+export type AuthorizeResult =
+  | { matched: false } // no registered pattern claims this channel
+  | { matched: true; result: boolean | PresenceMemberData | null | undefined };
+
+export class ChannelRegistry {
+  private _channels: CompiledChannel[] = [];
+
+  /**
+   * Register an authorization callback for a channel pattern.
+   *
+   * @example
+   * registry.register("orders.[orderId]", (user, orderId) => user.id === ownerOf(orderId));
+   */
+  register(pattern: string, callback: ChannelCallback): void {
+    const { regex, paramNames } = compileChannelPattern(pattern);
+    this._channels.push({ pattern, regex, paramNames, callback });
+  }
+
+  /** Registered channel patterns (for `channel:list` / introspection). */
+  all(): { pattern: string; paramNames: string[] }[] {
+    return this._channels.map((c) => ({ pattern: c.pattern, paramNames: c.paramNames }));
+  }
+
+  /** Remove all registrations (test isolation). */
+  clear(): void {
+    this._channels = [];
+  }
+
+  /**
+   * Authorize a subscription. The channel name may carry a `private-`/`presence-` prefix; it is
+   * stripped before matching (patterns are registered without the prefix).
+   *
+   * Returns `{ matched: false }` when no pattern claims the channel (caller should deny), or
+   * `{ matched: true, result }` where `result` is the callback's return value.
+   */
+  async authorize(channelName: string, user: unknown): Promise<AuthorizeResult> {
+    const bare = channelName.replace(/^private-/, "").replace(/^presence-/, "");
+    for (const ch of this._channels) {
+      const match = ch.regex.exec(bare);
+      if (!match) continue;
+      const params = match.slice(1);
+      const result = await ch.callback(user, ...params);
+      return { matched: true, result };
+    }
+    return { matched: false };
+  }
+}
+
+/** Process-wide registry shared by the `Broadcast` facade and `BroadcastProvider`. */
+export const channelRegistry = new ChannelRegistry();

package/src/PendingBroadcast.ts

@@ -0,0 +1,53 @@
+import { Broadcast } from "./facades/Broadcast.ts";
+import { currentSocketId } from "./currentSocketId.ts";
+import type { BroadcastEvent } from "./types.ts";
+
+/**
+ * A deferred broadcast returned by `broadcast(event)`. It is thenable and sends automatically on
+ * the next microtask (or immediately when awaited), so `.toOthers()` can configure it first.
+ */
+export class PendingBroadcast implements PromiseLike<void> {
+  private _toOthers = false;
+  private _sent = false;
+
+  constructor(private readonly event: BroadcastEvent) {}
+
+  /**
+   * Exclude the connection that originated the triggering request (its `X-Socket-ID`), so the
+   * user who just made an optimistic update doesn't receive a duplicate.
+   */
+  toOthers(): this {
+    this._toOthers = true;
+    return this;
+  }
+
+  /** Send now (idempotent). Called automatically on microtask / await. */
+  send(): void {
+    if (this._sent) return;
+    this._sent = true;
+    const exceptSocketId = this._toOthers ? currentSocketId() : undefined;
+    Broadcast.send(this.event, exceptSocketId ? { exceptSocketId } : {});
+  }
+
+  then<TResult1 = void, TResult2 = never>(
+    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    this.send();
+    return Promise.resolve().then(onfulfilled, onrejected);
+  }
+}
+
+/**
+ * Broadcast an event with fluent modifiers. Sends automatically (no `.send()` needed).
+ *
+ * @example
+ * broadcast(new OrderShipmentStatusUpdated(update)).toOthers();
+ * await broadcast(new OrderShipmentStatusUpdated(update));
+ */
+export function broadcast(event: BroadcastEvent): PendingBroadcast {
+  const pending = new PendingBroadcast(event);
+  // Auto-send after the synchronous chain (so .toOthers() runs first). Awaiting sends sooner.
+  queueMicrotask(() => pending.send());
+  return pending;
+}

package/src/PusherCompatManager.ts

@@ -0,0 +1,330 @@
+import { safeEqual, hmacHex } from "@zerotal/core";
+import { BroadcastManager, _isValidChannel } from "./BroadcastManager.ts";
+import type { PresenceMember } from "./BroadcastManager.ts";
+import type { WsConnectionData } from "./types.ts";
+
+type WS = ServerWebSocket<WsConnectionData>;
+
+interface PusherSubscribeData {
+  channel: string;
+  auth?: string;
+  channel_data?: string;
+}
+
+interface PusherClientMessage {
+  event: string;
+  data?: PusherSubscribeData | Record<string, unknown>;
+  channel?: string;
+}
+
+/**
+ * Callback for resolving a presence-channel member from an HTTP auth request.
+ * Return `false` to deny authorization.
+ */
+export type PusherPresenceResolver = (
+  req: Request,
+  channel: string,
+) =>
+  | Promise<{ id: string | number; info?: Record<string, unknown> } | false>
+  | { id: string | number; info?: Record<string, unknown> }
+  | false;
+
+/**
+ * Pusher/Reverb-compatible WebSocket broadcast manager.
+ *
+ * Implements the Pusher wire protocol on top of `BroadcastManager` so that
+ * Any Pusher-compatible client can connect to a Zerotal
+ * backend without modifications.
+ *
+ * Key protocol differences from the native Zerotal protocol:
+ *  - Connection event: `pusher:connection_established` (data is JSON string)
+ *  - Subscribe event: `pusher:subscribe` (channel inside `data` object)
+ *  - Subscription succeeded: `pusher_internal:subscription_succeeded`
+ *  - All server-sent data fields are JSON strings, not objects
+ *  - Auth for private/presence channels uses HMAC-SHA256 signatures
+ *
+ * Auth flow:
+ *  1. Echo calls POST /broadcasting/auth with socket_id + channel_name
+ *  2. Server signs with `signAuth()` and returns `{auth: "key:sig"}`
+ *  3. Echo includes `auth` in the pusher:subscribe message
+ *  4. Manager verifies HMAC before allowing subscription
+ *
+ * @example
+ * // config/broadcasting.ts
+ * BroadcastConfig({
+ *   driver: 'pusher',
+ *   pusher: {
+ *     appKey:    Bun.env.PUSHER_APP_KEY!,
+ *     appSecret: Bun.env.PUSHER_APP_SECRET!,
+ *   },
+ * });
+ */
+export class PusherCompatManager extends BroadcastManager {
+  private _presenceResolver: PusherPresenceResolver | undefined;
+
+  constructor(
+    private readonly _appKey: string,
+    private readonly _appSecret: string,
+  ) {
+    super();
+  }
+
+  // ── Auth ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Register a callback that resolves presence-channel member data for the
+   * HTTP auth endpoint. Return `false` to deny the subscription.
+   *
+   * @example
+   * pusher.resolvePresenceWith(async (req, _channel) => {
+   *   const userId = await getUserIdFromSession(req);
+   *   if (!userId) return false;
+   *   return { id: userId, info: { name: await getUserName(userId) } };
+   * });
+   */
+  resolvePresenceWith(fn: PusherPresenceResolver): void {
+    this._presenceResolver = fn;
+  }
+
+  /**
+   * Generate a Pusher auth token for a given socket/channel pair.
+   * Called by the HTTP auth endpoint before returning the token to the client.
+   *
+   * For private channels: `signAuth(socketId, channel)`
+   * For presence channels: `signAuth(socketId, channel, channelData)`
+   * where `channelData = JSON.stringify({ user_id, user_info })`
+   */
+  signAuth(socketId: string, channel: string, channelData?: string): string {
+    const str = channelData ? `${socketId}:${channel}:${channelData}` : `${socketId}:${channel}`;
+    const sig = hmacHex(str, this._appSecret);
+    return `${this._appKey}:${sig}`;
+  }
+
+  /**
+   * Resolve presence member data for the HTTP auth endpoint.
+   * Returns `false` when no resolver is registered or the resolver denies.
+   */
+  async resolvePresence(
+    req: Request,
+    channel: string,
+  ): Promise<{ id: string | number; info?: Record<string, unknown> } | false> {
+    if (!this._presenceResolver) return false;
+    return this._presenceResolver(req, channel);
+  }
+
+  // ── WS lifecycle ──────────────────────────────────────────────────────────
+
+  override handleOpen(ws: WS): void {
+    this._conns.set(ws.data.id, ws);
+    ws.send(
+      JSON.stringify({
+        event: "pusher:connection_established",
+        data: JSON.stringify({ socket_id: ws.data.id, activity_timeout: 120 }),
+      }),
+    );
+  }
+
+  override async handleMessage(ws: WS, raw: string | Uint8Array): Promise<void> {
+    let msg: PusherClientMessage;
+    try {
+      msg = JSON.parse(
+        typeof raw === "string" ? raw : new TextDecoder().decode(raw),
+      ) as PusherClientMessage;
+    } catch {
+      ws.send(
+        JSON.stringify({
+          event: "pusher:error",
+          data: JSON.stringify({ message: "Invalid JSON.", code: 4001 }),
+        }),
+      );
+      return;
+    }
+
+    switch (msg.event) {
+      case "pusher:subscribe": {
+        const data = (msg.data ?? {}) as PusherSubscribeData;
+        await this._pusherSubscribe(ws, data);
+        break;
+      }
+      case "pusher:unsubscribe": {
+        const channel = ((msg.data ?? {}) as PusherSubscribeData).channel;
+        if (channel) this._subs.get(channel)?.delete(ws.data.id);
+        break;
+      }
+      case "pusher:ping":
+        ws.send(JSON.stringify({ event: "pusher:pong", data: {} }));
+        break;
+      default:
+        // Forward client-* events to other channel subscribers
+        if (typeof msg.event === "string" && msg.event.startsWith("client-") && msg.channel) {
+          this._forwardClientEvent(ws, msg);
+        }
+    }
+  }
+
+  override handleClose(ws: WS): void {
+    this._conns.delete(ws.data.id);
+
+    for (const [ch, ids] of this._subs) {
+      ids.delete(ws.data.id);
+      if (ids.size === 0) this._subs.delete(ch);
+    }
+
+    for (const [ch, members] of this._members) {
+      if (members.has(ws.data.id)) {
+        const member = members.get(ws.data.id)!;
+        members.delete(ws.data.id);
+        if (members.size === 0) this._members.delete(ch);
+        this.to(ch, "pusher_internal:member_removed", { user_id: String(member.id) });
+      }
+    }
+  }
+
+  // ── Broadcast API ─────────────────────────────────────────────────────────
+
+  /**
+   * Broadcast an event to all subscribers.
+   * Pusher format: `data` is always a JSON string, not an object.
+   */
+  override to(
+    channel: string,
+    eventName: string,
+    data: unknown = {},
+    opts?: { exceptSocketId?: string },
+  ): void {
+    const ids = this._subs.get(channel);
+    if (!ids || ids.size === 0) return;
+    const msg = JSON.stringify({ event: eventName, channel, data: JSON.stringify(data) });
+    for (const id of ids) {
+      // `toOthers()` excludes the originating connection. Declaring three parameters and
+      // dropping the fourth made the exclusion vanish here without a type error.
+      if (opts?.exceptSocketId && id === opts.exceptSocketId) continue;
+      this._conns.get(id)?.send(msg);
+    }
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  private _verifyAuth(
+    socketId: string,
+    channel: string,
+    auth: string,
+    channelData?: string,
+  ): boolean {
+    return safeEqual(auth, this.signAuth(socketId, channel, channelData));
+  }
+
+  private async _pusherSubscribe(ws: WS, data: PusherSubscribeData): Promise<void> {
+    const { channel, auth, channel_data } = data;
+
+    // Reject structurally invalid channel names before anything is signed or verified.
+    //
+    // signAuth() keeps Pusher's `socketId:channel:channelData` wire format for protocol
+    // compatibility, so a channel name containing `:` could otherwise be crafted to shift the
+    // field boundaries — signAuth(s, 'presence-chat.5:{"user_id":1}') produces the same bytes
+    // as signAuth(s, 'presence-chat.5', '{"user_id":1}'), letting an attacker obtain a token
+    // for a channel they may join and replay it as another member's presence identity.
+    // _isValidChannel excludes `:` for exactly this reason. It also rejects non-strings and
+    // over-long names, which previously threw out of the handler.
+    if (!_isValidChannel(channel)) {
+      ws.send(
+        JSON.stringify({
+          event: "pusher:error",
+          data: JSON.stringify({ message: "Invalid channel name.", code: 4009 }),
+        }),
+      );
+      return;
+    }
+
+    const isPresence = channel.startsWith("presence-");
+    const isPrivate = channel.startsWith("private-") || isPresence;
+
+    if (isPrivate) {
+      if (!auth || !this._verifyAuth(ws.data.id, channel, auth, channel_data)) {
+        ws.send(
+          JSON.stringify({
+            event: "pusher:error",
+            data: JSON.stringify({ message: "Unauthorized.", code: 4009 }),
+          }),
+        );
+        return;
+      }
+    }
+
+    if (isPresence) {
+      let memberData: { user_id?: string | number; user_info?: Record<string, unknown> } = {};
+      try {
+        if (channel_data) {
+          memberData = JSON.parse(channel_data) as typeof memberData;
+        }
+      } catch {
+        /* use defaults */
+      }
+
+      const member: PresenceMember = {
+        id: memberData.user_id ?? ws.data.id,
+        info: memberData.user_info ?? {},
+      };
+
+      if (!this._members.has(channel)) this._members.set(channel, new Map());
+      if (!this._subs.has(channel)) this._subs.set(channel, new Set());
+
+      // Notify existing subscribers BEFORE adding the new one (no self-notify)
+      this.to(channel, "pusher_internal:member_added", {
+        user_id: String(member.id),
+        user_info: member.info,
+      });
+
+      this._members.get(channel)!.set(ws.data.id, member);
+      this._subs.get(channel)!.add(ws.data.id);
+
+      const allMembers = [...this._members.get(channel)!.values()];
+      const presenceData = {
+        presence: {
+          count: allMembers.length,
+          ids: allMembers.map((m) => String(m.id)),
+          hash: Object.fromEntries(allMembers.map((m) => [String(m.id), m.info])),
+        },
+      };
+
+      ws.send(
+        JSON.stringify({
+          event: "pusher_internal:subscription_succeeded",
+          data: JSON.stringify(presenceData),
+          channel,
+        }),
+      );
+      return;
+    }
+
+    if (!this._subs.has(channel)) this._subs.set(channel, new Set());
+    this._subs.get(channel)!.add(ws.data.id);
+    ws.send(
+      JSON.stringify({
+        event: "pusher_internal:subscription_succeeded",
+        data: "{}",
+        channel,
+      }),
+    );
+  }
+
+  private _forwardClientEvent(ws: WS, msg: PusherClientMessage): void {
+    const channel = msg.channel!;
+
+    // Pusher permits client events only on private/presence channels, and only from a
+    // connection that is actually subscribed to the channel. This checked neither: it verified
+    // the `client-` event-name prefix and nothing else, so any socket — never subscribed, never
+    // authenticated — could inject a frame into `private-admin` and every real subscriber
+    // received it as though it came from a peer.
+    if (!channel.startsWith("private-") && !channel.startsWith("presence-")) return;
+
+    const ids = this._subs.get(channel);
+    if (!ids) return;
+    if (!ids.has(ws.data.id)) return; // sender is not a member of this channel
+
+    const out = JSON.stringify({ event: msg.event, channel, data: msg.data });
+    for (const id of ids) {
+      if (id !== ws.data.id) this._conns.get(id)?.send(out);
+    }
+  }
+}

package/src/RedisBroadcastDriver.ts

@@ -0,0 +1,121 @@
+import { RedisClient } from "bun";
+import { BroadcastManager } from "./BroadcastManager.ts";
+import { frameworkLog } from "@zerotal/core/logger";
+
+const TOPIC = "__zerotal:broadcast";
+
+interface Envelope {
+  channel: string;
+  event: string;
+  data: unknown;
+  /**
+   * The originating connection, when the broadcast came from `toOthers()`.
+   *
+   * It has to cross the pub/sub hop: the socket to exclude is connected to whichever node
+   * published, and every *other* node has to know to skip it too — or rather, has to know
+   * that it does not hold it. Without this field the exclusion could not survive the hop
+   * even in principle, so `toOthers()` was a silent no-op on the driver documented for
+   * horizontal scaling, and every optimistic update double-applied in production.
+   */
+  exceptSocketId?: string;
+}
+
+/**
+ * Redis-backed broadcast driver for horizontal scaling.
+ *
+ * Extends `BroadcastManager` and overrides `to()` to publish through
+ * Redis Pub/Sub instead of writing directly to local WebSocket connections.
+ * Every server instance subscribes on `__zerotal:broadcast` and delivers
+ * incoming messages to its own local WS clients.
+ *
+ * Result: a broadcast on Server A is received by subscribers on Server B,
+ * Server C, etc. — no direct server-to-server connection needed.
+ *
+ * Architecture:
+ *
+ *   Server A                   Redis                    Server B
+ *   ─────────────────          ──────────────           ─────────────────
+ *   Broadcast.to(ch, ev)
+ *     → pub.publish(TOPIC) ──► fan-out ───────────────► sub.subscribe cb
+ *                          ◄───────────────────────────  super.to() → ws
+ *
+ * The publishing server also receives its own message via the subscriber,
+ * so all delivery — local or remote — flows through the same path.
+ *
+ * @example
+ * // config/broadcasting.ts
+ * export default BroadcastConfig({
+ *   driver: 'redis',
+ *   redis:  { url: Bun.env.REDIS_URL ?? 'redis://localhost:6379' },
+ * });
+ */
+export class RedisBroadcastDriver extends BroadcastManager {
+  private _pub!: RedisClient;
+  private _sub!: RedisClient;
+
+  constructor(private readonly _url: string) {
+    super();
+  }
+
+  /**
+   * Open the pub + sub connections and start listening for cross-server
+   * broadcasts. Call once during application boot.
+   *
+   * If `_pub`/`_sub` are already set (e.g. injected in tests), this method
+   * skips creating new clients and only registers the subscriber callback.
+   */
+  async boot(): Promise<void> {
+    if (!this._pub) {
+      this._pub = new RedisClient(this._url);
+      // Bun.Redis cannot publish and subscribe on the same connection.
+      // duplicate() creates a new independent connection with the same URL.
+      this._sub = await this._pub.duplicate();
+    }
+
+    await this._sub.subscribe(TOPIC, (msg: string) => {
+      let envelope: Envelope;
+      try {
+        envelope = JSON.parse(msg) as Envelope;
+      } catch {
+        return;
+      }
+      // Deliver to local WebSocket clients on this server instance.
+      // super.to() bypasses our Redis override so we don't re-publish. The exclusion is
+      // applied on every node: only one of them holds that connection, and the others
+      // simply have nothing matching to skip.
+      super.to(
+        envelope.channel,
+        envelope.event,
+        envelope.data,
+        envelope.exceptSocketId ? { exceptSocketId: envelope.exceptSocketId } : undefined,
+      );
+    });
+  }
+
+  /** Unsubscribe the Redis listener. Called when the application stops. */
+  async stop(): Promise<void> {
+    await this._sub.unsubscribe(TOPIC);
+  }
+
+  /**
+   * Publish the event to Redis instead of delivering locally.
+   * All server instances — including this one — receive it through
+   * the subscriber and deliver it to their own local WS clients.
+   */
+  override to(
+    channel: string,
+    event: string,
+    data: unknown = {},
+    opts?: { exceptSocketId?: string },
+  ): void {
+    const msg = JSON.stringify({
+      channel,
+      event,
+      data,
+      ...(opts?.exceptSocketId ? { exceptSocketId: opts.exceptSocketId } : {}),
+    } satisfies Envelope);
+    this._pub.publish(TOPIC, msg).catch((err: Error) => {
+      frameworkLog("broadcast").error("Redis publish failed", undefined, err);
+    });
+  }
+}