@strav/broadcast 1.0.0-alpha.36 → 1.0.0-alpha.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/broadcast",
-  "version": "1.0.0-alpha.36",
+  "version": "1.0.0-alpha.38",
   "description": "Strav broadcast / pub-sub primitive — Broadcaster interface + MemoryBroadcaster (in-process) + PostgresBroadcaster (polling-ledger backplane) + per-channel authorization. Pairs with @strav/http's router.sse and @strav/notification/broadcast.",
   "type": "module",
   "main": "./src/index.ts",
@@ -9,7 +9,9 @@
     ".": "./src/index.ts",
     "./memory": "./src/drivers/memory/index.ts",
     "./postgres": "./src/drivers/postgres/index.ts",
-    "./redis": "./src/drivers/redis/index.ts"
+    "./redis": "./src/drivers/redis/index.ts",
+    "./websocket": "./src/drivers/websocket/index.ts",
+    "./client": "./src/client/index.ts"
   },
   "files": [
     "src",
@@ -22,15 +24,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.36"
+    "@strav/kernel": "1.0.0-alpha.38"
   },
   "peerDependencies": {
-    "@strav/database": "1.0.0-alpha.36",
+    "@strav/database": "1.0.0-alpha.38",
+    "@strav/http": "1.0.0-alpha.38",
     "@types/bun": ">=1.3.14"
   },
   "peerDependenciesMeta": {
     "@strav/database": {
       "optional": true
+    },
+    "@strav/http": {
+      "optional": true
     }
   },
   "devDependencies": null

package/src/client/broadcast_client.ts

@@ -0,0 +1,470 @@
+/**
+ * `BroadcastClient` — browser-side WebSocket client for
+ * `@strav/broadcast/websocket`.
+ *
+ * Zero runtime dependencies — uses only the platform `WebSocket`. Safe to
+ * bundle for any browser. The protocol module re-exports its types so
+ * callers can refer to wire shapes without re-declaring them.
+ *
+ * Highlights:
+ *
+ *   - **Multiplexed**: one socket per `BroadcastClient`, N channel
+ *     subscriptions on top.
+ *   - **Auto-reconnect** with exponential backoff (250 ms → cap), jittered.
+ *     Re-subscribes to active channels after `welcome`.
+ *   - **Outbox**: frames sent while disconnected queue up to a cap and
+ *     flush once the next `welcome` arrives.
+ *   - **Event API**: lifecycle events on the client (`open`, `close`,
+ *     `reconnecting`, `subscribed`, `error`) plus channel-level
+ *     `on(eventName, handler)` / `on('*', handler)`.
+ *   - **No throwing**: surface failures via the `error` event and `err`
+ *     channel frames; the API resolves rather than rejects when possible
+ *     so UI code stays simple.
+ *
+ * The file deliberately imports nothing from `@strav/kernel`, `@strav/http`,
+ * or any server module — bundlers tracing this entry will not pull server
+ * code into the browser bundle.
+ */
+
+import type {
+  AnyFrame,
+  ClientFrame,
+  ErrorFrame,
+  MessageFrame,
+  ServerFrame,
+  WelcomeFrame,
+} from '../drivers/websocket/protocol.ts'
+
+export type Listener<T = unknown> = (payload: T) => void
+
+export interface BroadcastClientOptions {
+  /**
+   * Full WebSocket URL — `wss://host/_broadcast`. When omitted, the client
+   * auto-derives `${ws|wss}://${location.host}/_broadcast` using the page
+   * protocol. Throws on construction in non-browser environments unless
+   * `url` is explicitly passed.
+   */
+  url?: string
+  /**
+   * Open the socket immediately on construction. Default `true`. Set
+   * `false` if you want to call `connect()` later (e.g. after login).
+   */
+  autoConnect?: boolean
+  /** Max reconnect attempts; `Infinity` to retry forever. Default `Infinity`. */
+  maxReconnectAttempts?: number
+  /** First reconnect delay in ms. Default `250`. */
+  reconnectInitialDelayMs?: number
+  /** Reconnect delay cap in ms. Default `10000`. */
+  reconnectMaxDelayMs?: number
+  /**
+   * Cap on queued outbound frames while disconnected. Older frames are
+   * dropped when the cap is hit. Default `200`.
+   */
+  outboxLimit?: number
+  /**
+   * WebSocket factory — overridable so tests can inject a mock. Defaults
+   * to `new WebSocket(url)`. The returned object must expose the standard
+   * `addEventListener` / `send` / `close` / `readyState` surface.
+   */
+  webSocketFactory?: (url: string) => WebSocketLike
+}
+
+/** The minimal WebSocket surface the client relies on. */
+export interface WebSocketLike {
+  readonly readyState: number
+  send(data: string): void
+  close(code?: number, reason?: string): void
+  addEventListener(type: 'open', listener: () => void): void
+  addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void
+  addEventListener(type: 'close', listener: () => void): void
+  addEventListener(type: 'error', listener: () => void): void
+}
+
+/** Connection lifecycle event payloads. */
+export interface BroadcastClientEvents {
+  open: void
+  close: void
+  reconnecting: { attempt: number; delayMs: number }
+  subscribed: { channel: string }
+  error: { channel?: string; reason: string }
+}
+
+const WS_OPEN = 1
+
+/**
+ * Per-channel handle. Cheap value type — call `on()` to register listeners,
+ * `publish()` to send (if the server allows it), `leave()` to detach.
+ */
+export class BroadcastChannel {
+  private listeners: Map<string, Set<Listener<unknown>>> = new Map()
+  /** @internal called by `BroadcastClient`. */
+  _onError: ((reason: string) => void) | undefined
+
+  constructor(
+    public readonly name: string,
+    private readonly sendFrame: (frame: ClientFrame) => void,
+    private readonly detach: () => void,
+  ) {}
+
+  /**
+   * Listen for a named event. Use `'*'` to receive every frame on this
+   * channel — handlers receive `(eventName, data)` for wildcards and
+   * `(data)` for named events. Returns an unsubscribe function.
+   */
+  on(event: '*', handler: (eventName: string, data: unknown) => void): () => void
+  on<T = unknown>(event: string, handler: Listener<T>): () => void
+  on(
+    event: string,
+    handler: Listener<unknown> | ((eventName: string, data: unknown) => void),
+  ): () => void {
+    let set = this.listeners.get(event)
+    if (set === undefined) {
+      set = new Set()
+      this.listeners.set(event, set)
+    }
+    set.add(handler as Listener<unknown>)
+    return () => {
+      set?.delete(handler as Listener<unknown>)
+    }
+  }
+
+  /**
+   * Publish on this channel. Server-side `allowClientPublish` decides if
+   * the publish goes through; otherwise an `error` event lands on the
+   * channel with `reason = 'publish denied'` (or 'unauthorized').
+   */
+  publish(event: string, data?: unknown): void {
+    this.sendFrame({ t: 'pub', c: this.name, e: event, d: data })
+  }
+
+  /** Unsubscribe from the channel + drop every listener. */
+  leave(): void {
+    this.sendFrame({ t: 'unsub', c: this.name })
+    this.listeners.clear()
+    this.detach()
+  }
+
+  /** @internal dispatch a `msg` frame to listeners. */
+  _dispatch(eventName: string, data: unknown): void {
+    const named = this.listeners.get(eventName)
+    if (named !== undefined) {
+      for (const listener of named) {
+        try {
+          listener(data)
+        } catch (err) {
+          reportListenerError(err)
+        }
+      }
+    }
+    const wild = this.listeners.get('*')
+    if (wild !== undefined) {
+      for (const listener of wild) {
+        try {
+          ;(listener as (eventName: string, data: unknown) => void)(eventName, data)
+        } catch (err) {
+          reportListenerError(err)
+        }
+      }
+    }
+  }
+
+  /** @internal route an `err` frame to a per-channel handler. */
+  _emitError(reason: string): void {
+    this._onError?.(reason)
+  }
+}
+
+export class BroadcastClient {
+  private readonly url: string
+  private readonly maxReconnectAttempts: number
+  private readonly reconnectInitialDelayMs: number
+  private readonly reconnectMaxDelayMs: number
+  private readonly outboxLimit: number
+  private readonly factory: (url: string) => WebSocketLike
+
+  private ws: WebSocketLike | undefined
+  private state: 'idle' | 'connecting' | 'open' | 'closed' = 'idle'
+  private explicitClose = false
+  private reconnectAttempt = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined
+  private outbox: string[] = []
+  private clientId: string | undefined
+
+  private channels = new Map<string, BroadcastChannel>()
+  private listeners = new Map<string, Set<Listener<unknown>>>()
+
+  constructor(options: BroadcastClientOptions = {}) {
+    this.url = options.url ?? autoUrl()
+    this.maxReconnectAttempts = options.maxReconnectAttempts ?? Infinity
+    this.reconnectInitialDelayMs = options.reconnectInitialDelayMs ?? 250
+    this.reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? 10_000
+    this.outboxLimit = options.outboxLimit ?? 200
+    this.factory =
+      options.webSocketFactory ??
+      ((url) => new WebSocket(url) as unknown as WebSocketLike)
+
+    if (options.autoConnect !== false) this.connect()
+  }
+
+  /** Server-minted ID for this connection — populated after `welcome`. */
+  get id(): string | undefined {
+    return this.clientId
+  }
+
+  /** Whether the socket is currently open. */
+  get connected(): boolean {
+    return this.state === 'open'
+  }
+
+  /** Open the socket (no-op if already opening/open). */
+  connect(): void {
+    if (this.state === 'connecting' || this.state === 'open') return
+    this.explicitClose = false
+    this.openSocket()
+  }
+
+  /**
+   * Subscribe to a channel. Returns the same handle on repeated calls so
+   * apps can wire multiple parts of the UI to the same channel without
+   * extra bookkeeping.
+   */
+  channel(name: string): BroadcastChannel {
+    const existing = this.channels.get(name)
+    if (existing !== undefined) return existing
+    const handle = new BroadcastChannel(
+      name,
+      (frame) => this.sendFrame(frame),
+      () => {
+        this.channels.delete(name)
+      },
+    )
+    this.channels.set(name, handle)
+    this.sendFrame({ t: 'sub', c: name })
+    return handle
+  }
+
+  /** Listen for client-level lifecycle events. Returns an unsubscribe fn. */
+  on<K extends keyof BroadcastClientEvents>(
+    event: K,
+    listener: Listener<BroadcastClientEvents[K]>,
+  ): () => void {
+    let set = this.listeners.get(event)
+    if (set === undefined) {
+      set = new Set()
+      this.listeners.set(event, set)
+    }
+    set.add(listener as Listener<unknown>)
+    return () => {
+      set?.delete(listener as Listener<unknown>)
+    }
+  }
+
+  /**
+   * Close the socket permanently — disables reconnect. Active channels
+   * are emptied; calling `channel(name)` after disconnect will reopen the
+   * socket only if you call `connect()` first.
+   */
+  disconnect(): void {
+    this.explicitClose = true
+    this.state = 'closed'
+    if (this.reconnectTimer !== undefined) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = undefined
+    }
+    if (this.ws !== undefined) {
+      try {
+        this.ws.close()
+      } catch {
+        // Already closed.
+      }
+      this.ws = undefined
+    }
+    this.channels.clear()
+    this.outbox = []
+  }
+
+  // ─── Internals ─────────────────────────────────────────────────────────────
+
+  private openSocket(): void {
+    this.state = 'connecting'
+    let ws: WebSocketLike
+    try {
+      ws = this.factory(this.url)
+    } catch (err) {
+      this.emit('error', { reason: (err as Error).message })
+      this.scheduleReconnect()
+      return
+    }
+    this.ws = ws
+    ws.addEventListener('open', () => {
+      this.state = 'open'
+      this.reconnectAttempt = 0
+      this.emit('open', undefined)
+    })
+    ws.addEventListener('message', (event) => {
+      const data = event.data
+      if (typeof data !== 'string') return
+      let frame: ServerFrame
+      try {
+        frame = JSON.parse(data) as ServerFrame
+      } catch {
+        return
+      }
+      this.handleFrame(frame)
+    })
+    ws.addEventListener('close', () => {
+      const wasOpen = this.state === 'open'
+      this.ws = undefined
+      if (this.explicitClose) {
+        this.state = 'closed'
+        if (wasOpen) this.emit('close', undefined)
+        return
+      }
+      this.state = 'idle'
+      if (wasOpen) this.emit('close', undefined)
+      this.scheduleReconnect()
+    })
+    ws.addEventListener('error', () => {
+      // The close event will fire too — handle teardown there.
+      try {
+        ws.close()
+      } catch {
+        // Already closing.
+      }
+    })
+  }
+
+  private handleFrame(frame: AnyFrame): void {
+    switch (frame.t) {
+      case 'welcome':
+        this.onWelcome(frame)
+        return
+      case 'ok':
+        this.emit('subscribed', { channel: frame.c })
+        return
+      case 'err':
+        this.onErrorFrame(frame)
+        return
+      case 'msg':
+        this.onMessage(frame)
+        return
+      case 'ping':
+        this.sendFrame({ t: 'pong' })
+        return
+      default:
+        return
+    }
+  }
+
+  private onWelcome(frame: WelcomeFrame): void {
+    this.clientId = frame.id
+    for (const name of this.channels.keys()) {
+      this.rawSend({ t: 'sub', c: name })
+    }
+    if (this.outbox.length > 0 && this.ws !== undefined) {
+      for (const raw of this.outbox) {
+        try {
+          this.ws.send(raw)
+        } catch {
+          // If sending blows up we'll catch it on the next reconnect.
+          break
+        }
+      }
+      this.outbox = []
+    }
+  }
+
+  private onErrorFrame(frame: ErrorFrame): void {
+    const channel = this.channels.get(frame.c)
+    if (channel !== undefined) channel._emitError(frame.r)
+    this.emit('error', { channel: frame.c, reason: frame.r })
+  }
+
+  private onMessage(frame: MessageFrame): void {
+    const channel = this.channels.get(frame.c)
+    if (channel === undefined) return
+    channel._dispatch(frame.e, frame.d)
+  }
+
+  private sendFrame(frame: ClientFrame): void {
+    const raw = JSON.stringify(frame)
+    if (this.state === 'open' && this.ws !== undefined && this.ws.readyState === WS_OPEN) {
+      try {
+        this.ws.send(raw)
+        return
+      } catch {
+        // Fallthrough to outbox.
+      }
+    }
+    this.enqueue(raw)
+  }
+
+  private rawSend(frame: ClientFrame): void {
+    if (this.ws !== undefined && this.ws.readyState === WS_OPEN) {
+      try {
+        this.ws.send(JSON.stringify(frame))
+      } catch {
+        // Swallow — re-subscribe will fire again on next welcome.
+      }
+    }
+  }
+
+  private enqueue(raw: string): void {
+    if (this.outbox.length >= this.outboxLimit) this.outbox.shift()
+    this.outbox.push(raw)
+  }
+
+  private scheduleReconnect(): void {
+    if (this.explicitClose) return
+    if (this.reconnectAttempt >= this.maxReconnectAttempts) return
+    this.reconnectAttempt += 1
+    const base = Math.min(
+      this.reconnectInitialDelayMs * 2 ** (this.reconnectAttempt - 1),
+      this.reconnectMaxDelayMs,
+    )
+    // Full jitter — randomise the whole interval to avoid thundering herd.
+    const delayMs = Math.floor(Math.random() * base)
+    this.emit('reconnecting', { attempt: this.reconnectAttempt, delayMs })
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined
+      this.openSocket()
+    }, delayMs)
+  }
+
+  private emit<K extends keyof BroadcastClientEvents>(
+    event: K,
+    payload: BroadcastClientEvents[K],
+  ): void {
+    const set = this.listeners.get(event)
+    if (set === undefined) return
+    for (const listener of set) {
+      try {
+        ;(listener as Listener<BroadcastClientEvents[K]>)(payload)
+      } catch (err) {
+        reportListenerError(err)
+      }
+    }
+  }
+}
+
+function autoUrl(): string {
+  // biome-ignore lint/suspicious/noExplicitAny: browser-only globals
+  const loc = (globalThis as any).location as
+    | { protocol: string; host: string }
+    | undefined
+  if (loc === undefined) {
+    throw new Error(
+      'BroadcastClient: no `url` provided and `location` is not available. Pass `url` explicitly outside a browser.',
+    )
+  }
+  const proto = loc.protocol === 'https:' ? 'wss:' : 'ws:'
+  return `${proto}//${loc.host}/_broadcast`
+}
+
+function reportListenerError(err: unknown): void {
+  // Use `console.error` if present so userland sees its own throws without
+  // taking down the socket. The check keeps the bundle SSR-safe.
+  // biome-ignore lint/suspicious/noExplicitAny: optional global
+  const c = (globalThis as any).console as { error?: (...args: unknown[]) => void } | undefined
+  c?.error?.('BroadcastClient listener threw:', err)
+}

package/src/client/index.ts

@@ -0,0 +1,28 @@
+// `@strav/broadcast/client` — browser WebSocket client for the gateway.
+//
+// Zero server-side imports: this subpath is safe to bundle for browsers.
+// Wire-protocol types are re-exported so callers can refer to them without
+// reaching into the driver subpath.
+
+export {
+  BroadcastChannel,
+  BroadcastClient,
+  type BroadcastClientEvents,
+  type BroadcastClientOptions,
+  type Listener,
+  type WebSocketLike,
+} from './broadcast_client.ts'
+export type {
+  AnyFrame,
+  AckFrame,
+  ClientFrame,
+  ErrorFrame,
+  MessageFrame,
+  PingFrame,
+  PongFrame,
+  PublishFrame,
+  ServerFrame,
+  SubscribeFrame,
+  UnsubscribeFrame,
+  WelcomeFrame,
+} from '../drivers/websocket/protocol.ts'

package/src/drivers/websocket/index.ts

@@ -0,0 +1,22 @@
+// `@strav/broadcast/websocket` — browser-WebSocket gateway over a Broadcaster.
+
+export {
+  type AnyFrame,
+  type AckFrame,
+  type ClientFrame,
+  DEFAULT_PATH,
+  type ErrorFrame,
+  type MessageFrame,
+  type PingFrame,
+  type PongFrame,
+  type PublishFrame,
+  type ServerFrame,
+  type SubscribeFrame,
+  type UnsubscribeFrame,
+  type WelcomeFrame,
+} from './protocol.ts'
+export {
+  BroadcastWebSocketGateway,
+  type BroadcastWebSocketGatewayOptions,
+  type ClientPublishContext,
+} from './websocket_gateway.ts'

package/src/drivers/websocket/protocol.ts

@@ -0,0 +1,81 @@
+/**
+ * Wire protocol for the `@strav/broadcast/websocket` gateway.
+ *
+ * Tiny one-letter keys (`t`, `c`, `e`, `d`, `i`, `r`, `id`) — saves bytes
+ * on every frame and matches the 0.x shape. Encoding is JSON.
+ *
+ * Frame types:
+ *
+ * Server → client:
+ *   - `welcome` — first frame after upgrade, carries the server-minted client ID.
+ *   - `ok`      — ack of a sub / unsub for channel `c`.
+ *   - `err`     — failure for channel `c`, reason in `r`.
+ *   - `msg`     — broadcast event for channel `c` (`e`/`d`/`i` = event/data/id).
+ *   - `ping`    — keepalive; client replies with `pong`.
+ *
+ * Client → server:
+ *   - `sub`   — subscribe to channel `c`.
+ *   - `unsub` — unsubscribe from channel `c`.
+ *   - `pub`   — publish (`e`/`d` = event/data) on channel `c`. Gated by the
+ *               gateway's `allowClientPublish` option — denied by default.
+ *   - `pong`  — reply to a server `ping`.
+ *
+ * Unknown frame types are dropped silently on both sides. The protocol is
+ * forward-compatible: receivers only act on tags they know.
+ */
+
+export interface WelcomeFrame {
+  t: 'welcome'
+  id: string
+}
+
+export interface AckFrame {
+  t: 'ok'
+  c: string
+}
+
+export interface ErrorFrame {
+  t: 'err'
+  c: string
+  r: string
+}
+
+export interface MessageFrame {
+  t: 'msg'
+  c: string
+  e: string
+  d: unknown
+  i: string
+}
+
+export interface PingFrame {
+  t: 'ping'
+}
+
+export interface PongFrame {
+  t: 'pong'
+}
+
+export interface SubscribeFrame {
+  t: 'sub'
+  c: string
+}
+
+export interface UnsubscribeFrame {
+  t: 'unsub'
+  c: string
+}
+
+export interface PublishFrame {
+  t: 'pub'
+  c: string
+  e: string
+  d: unknown
+}
+
+export type ServerFrame = WelcomeFrame | AckFrame | ErrorFrame | MessageFrame | PingFrame
+export type ClientFrame = SubscribeFrame | UnsubscribeFrame | PublishFrame | PongFrame
+export type AnyFrame = ServerFrame | ClientFrame
+
+/** Default mount path for the gateway endpoint. */
+export const DEFAULT_PATH = '/_broadcast'

package/src/drivers/websocket/websocket_gateway.ts

@@ -0,0 +1,474 @@
+/**
+ * `BroadcastWebSocketGateway` — bridges browser WebSocket clients to a
+ * `Broadcaster` backplane (Memory / Postgres / Redis / any user driver).
+ *
+ * Architecture:
+ *
+ *   browser ──ws──> gateway ──┐
+ *                             ├──> Broadcaster (the backplane)
+ *   browser ──ws──> gateway ──┘                ▲
+ *                                              │
+ *                                  server-side broadcaster.publish(...)
+ *
+ * The gateway is **not** itself a `Broadcaster` driver. The application
+ * keeps registering its preferred backplane (`BroadcastProvider`,
+ * `PostgresBroadcastProvider`, `RedisBroadcastProvider`); the gateway sits
+ * on top, exposing a single multiplexed WebSocket endpoint per node.
+ *
+ * Why split it out:
+ *
+ *   - Multi-node fan-out is the backplane's job. Two nodes both running
+ *     a gateway naturally share traffic through the shared Postgres/Redis
+ *     they're both subscribed to — every gateway sees every publish.
+ *   - Client publishes go through the same `broadcaster.publish` path as
+ *     server publishes, so authorization, deduping, and cross-node
+ *     delivery all reuse one code path.
+ *
+ * Per-channel upstream coalescing: at most one `broadcaster.subscribe(ch)`
+ * runs per gateway per channel, regardless of how many local clients are
+ * on it. The upstream subscription is created when the first local client
+ * subscribes and torn down when the last one leaves.
+ *
+ * Authorization:
+ *
+ *   - Subscribe path: `broadcaster.authorizeFor(channel, subject)` —
+ *     same path SSE uses. The `subject` comes from a user-supplied
+ *     `resolveSubject(request)` hook (typically reads a session cookie).
+ *   - Publish path: client publishes are **denied by default**. Apps opt
+ *     in by passing `allowClientPublish` — a predicate that decides
+ *     per (channel, event, subject, clientId) whether the publish goes
+ *     through. The subscribe-side authorizer ALSO runs first, so a
+ *     client can't publish to a channel they can't subscribe to.
+ */
+
+import { Logger, ulid } from '@strav/kernel'
+import type { Router, WebSocketData, WebSocketHandlers } from '@strav/http'
+import type { ServerWebSocket } from 'bun'
+import { BroadcastUnauthorizedError } from '../../broadcast_error.ts'
+import type { Broadcaster } from '../../broadcaster.ts'
+import type { BroadcastEvent, BroadcastSubscription } from '../../types.ts'
+import {
+  type ClientFrame,
+  DEFAULT_PATH,
+  type ServerFrame,
+} from './protocol.ts'
+
+export interface ClientPublishContext {
+  channel: string
+  event: string
+  /** JSON-deserialized payload from the client. */
+  data: unknown
+  /** Whatever `resolveSubject(request)` returned for this connection. */
+  subject: unknown
+  /** Server-minted ID for this socket — unique across the gateway's lifetime. */
+  clientId: string
+}
+
+export interface BroadcastWebSocketGatewayOptions {
+  /** The backplane every connected client publishes / subscribes through. */
+  broadcaster: Broadcaster
+  /** Mount path for the WS endpoint. Default `/_broadcast`. */
+  path?: string
+  /**
+   * Server → client keepalive interval (ms). The client replies with
+   * `pong`. Set `0` to disable. Default `30000`.
+   */
+  pingIntervalMs?: number
+  /**
+   * Per-connection auth hook — resolves a subject from the original
+   * upgrade `Request`. The subject is passed to
+   * `broadcaster.authorizeFor(channel, subject)` on every sub attempt and
+   * to `allowClientPublish` on every pub attempt.
+   *
+   * Default: `undefined` (no subject). With no subject, `private-*` /
+   * `presence-*` channels are denied by the broadcaster's default policy
+   * unless a custom authorizer is registered.
+   */
+  resolveSubject?: (request: Request) => unknown | Promise<unknown>
+  /**
+   * Gate for client → server publishes. Returning falsy denies the
+   * publish (an `err` frame goes back to the client). Default: deny all
+   * client publishes.
+   *
+   * The subscribe-side `broadcaster.authorizeFor(channel, subject)`
+   * runs FIRST — clients can't publish to channels they can't subscribe
+   * to. This hook is the second gate.
+   */
+  allowClientPublish?: (ctx: ClientPublishContext) => boolean | Promise<boolean>
+  /**
+   * Optional logger. Defaults to a no-op when omitted; tests typically
+   * leave it unset and assert via the public diagnostics
+   * (`clientCount`, `channelCount`, `subscriberCount`).
+   */
+  logger?: Pick<Logger, 'error' | 'warn'>
+}
+
+interface GatewayClient {
+  ws: ServerWebSocket<WebSocketData>
+  clientId: string
+  /** Channels this client is subscribed to. */
+  channels: Set<string>
+  /** Cached subject from `resolveSubject(request)`. */
+  subjectReady: Promise<unknown>
+}
+
+interface UpstreamChannel {
+  subscription: BroadcastSubscription
+  clients: Set<string>
+  /** The forwarding loop's promise — awaited by `close()`. */
+  loop: Promise<void>
+}
+
+export class BroadcastWebSocketGateway {
+  private readonly broadcaster: Broadcaster
+  private readonly path: string
+  private readonly pingIntervalMs: number
+  private readonly resolveSubject: (
+    request: Request,
+  ) => unknown | Promise<unknown>
+  private readonly allowClientPublish: (
+    ctx: ClientPublishContext,
+  ) => boolean | Promise<boolean>
+  private readonly logger: Pick<Logger, 'error' | 'warn'> | undefined
+
+  private readonly clients = new Map<string, GatewayClient>()
+  private readonly upstream = new Map<string, UpstreamChannel>()
+  private pingTimer: ReturnType<typeof setInterval> | undefined
+  private closed = false
+
+  constructor(options: BroadcastWebSocketGatewayOptions) {
+    this.broadcaster = options.broadcaster
+    this.path = options.path ?? DEFAULT_PATH
+    this.pingIntervalMs = options.pingIntervalMs ?? 30_000
+    this.resolveSubject = options.resolveSubject ?? (() => undefined)
+    this.allowClientPublish = options.allowClientPublish ?? (() => false)
+    this.logger = options.logger
+  }
+
+  /** Register the gateway's WS endpoint on a `@strav/http` router. */
+  register(router: Router): void {
+    router.ws(this.path, this.handlers())
+    if (this.pingIntervalMs > 0) {
+      this.pingTimer = setInterval(() => this.pingAll(), this.pingIntervalMs)
+      // Don't keep the event loop alive solely for pings.
+      const t = this.pingTimer as unknown as { unref?: () => void }
+      t.unref?.()
+    }
+  }
+
+  /** Mounted path — useful for tests and diagnostics. */
+  get mountPath(): string {
+    return this.path
+  }
+
+  /** Number of connected clients. */
+  get clientCount(): number {
+    return this.clients.size
+  }
+
+  /** Number of channels currently fanned out upstream from this gateway. */
+  get channelCount(): number {
+    return this.upstream.size
+  }
+
+  /** Number of local clients subscribed to `channel`. */
+  subscriberCount(channel: string): number {
+    return this.upstream.get(channel)?.clients.size ?? 0
+  }
+
+  /**
+   * Tear down: stop the ping timer, unsubscribe upstream, close every
+   * socket. Idempotent.
+   */
+  async close(): Promise<void> {
+    if (this.closed) return
+    this.closed = true
+    if (this.pingTimer !== undefined) {
+      clearInterval(this.pingTimer)
+      this.pingTimer = undefined
+    }
+    for (const client of this.clients.values()) {
+      try {
+        client.ws.close()
+      } catch {
+        // Already closed.
+      }
+    }
+    this.clients.clear()
+    const teardowns = Array.from(this.upstream.values()).map(async (u) => {
+      try {
+        await u.subscription.unsubscribe()
+      } catch {
+        // Best-effort.
+      }
+      try {
+        await u.loop
+      } catch {
+        // Loop exit is expected on unsubscribe.
+      }
+    })
+    this.upstream.clear()
+    await Promise.all(teardowns)
+  }
+
+  // ─── Internals ─────────────────────────────────────────────────────────────
+
+  private handlers(): WebSocketHandlers {
+    return {
+      open: (ws) => this.onOpen(ws),
+      message: (ws, raw) => this.onMessage(ws, raw),
+      close: (ws) => this.onClose(ws),
+      pong: () => {
+        // Client-originated pong — keepalive accounting is implicit (the
+        // socket would have died long before we cared about a missing pong).
+      },
+    }
+  }
+
+  private onOpen(ws: ServerWebSocket<WebSocketData>): void {
+    if (this.closed) {
+      try {
+        ws.close()
+      } catch {
+        // Already gone.
+      }
+      return
+    }
+    const clientId = ulid()
+    const client: GatewayClient = {
+      ws,
+      clientId,
+      channels: new Set(),
+      subjectReady: Promise.resolve(this.resolveSubject(ws.data.request)).catch(
+        (err) => {
+          this.logger?.warn('broadcast.ws.resolve_subject_failed', { err })
+          return undefined
+        },
+      ),
+    }
+    this.clients.set(clientId, client)
+    ws.data.state.clientId = clientId
+    this.sendFrame(ws, { t: 'welcome', id: clientId })
+  }
+
+  private async onMessage(
+    ws: ServerWebSocket<WebSocketData>,
+    raw: string | Buffer,
+  ): Promise<void> {
+    const clientId = ws.data.state.clientId as string | undefined
+    if (clientId === undefined) return
+    const client = this.clients.get(clientId)
+    if (client === undefined) return
+
+    let frame: ClientFrame
+    try {
+      const text = typeof raw === 'string' ? raw : raw.toString('utf8')
+      frame = JSON.parse(text) as ClientFrame
+    } catch {
+      // Malformed JSON — silently drop. A noisy client doesn't deserve a reply.
+      return
+    }
+    if (typeof frame !== 'object' || frame === null || typeof frame.t !== 'string') {
+      return
+    }
+
+    switch (frame.t) {
+      case 'sub':
+        await this.handleSubscribe(client, frame.c)
+        return
+      case 'unsub':
+        this.handleUnsubscribe(client, frame.c)
+        return
+      case 'pub':
+        await this.handlePublish(client, frame.c, frame.e, frame.d)
+        return
+      case 'pong':
+        return
+      default:
+        // Unknown tag — drop. Forward-compatible.
+        return
+    }
+  }
+
+  private onClose(ws: ServerWebSocket<WebSocketData>): void {
+    const clientId = ws.data.state.clientId as string | undefined
+    if (clientId === undefined) return
+    const client = this.clients.get(clientId)
+    if (client === undefined) return
+    this.clients.delete(clientId)
+    for (const channel of client.channels) {
+      this.dropFromUpstream(channel, clientId)
+    }
+  }
+
+  private async handleSubscribe(client: GatewayClient, channel: string): Promise<void> {
+    if (typeof channel !== 'string' || channel.length === 0) return
+    if (client.channels.has(channel)) {
+      this.sendFrame(client.ws, { t: 'ok', c: channel })
+      return
+    }
+    const subject = await client.subjectReady
+    let allowed: boolean
+    try {
+      const result = await this.broadcaster.authorizeFor(channel, subject)
+      allowed = result.authorized
+    } catch (err) {
+      this.logger?.error('broadcast.ws.authorize_failed', { channel, err })
+      this.sendFrame(client.ws, { t: 'err', c: channel, r: 'authorization failed' })
+      return
+    }
+    if (!allowed) {
+      this.sendFrame(client.ws, { t: 'err', c: channel, r: 'unauthorized' })
+      return
+    }
+    client.channels.add(channel)
+    this.ensureUpstream(channel).clients.add(client.clientId)
+    this.sendFrame(client.ws, { t: 'ok', c: channel })
+  }
+
+  private handleUnsubscribe(client: GatewayClient, channel: string): void {
+    if (typeof channel !== 'string' || channel.length === 0) return
+    if (!client.channels.delete(channel)) return
+    this.dropFromUpstream(channel, client.clientId)
+  }
+
+  private async handlePublish(
+    client: GatewayClient,
+    channel: string,
+    event: string,
+    data: unknown,
+  ): Promise<void> {
+    if (typeof channel !== 'string' || channel.length === 0) return
+    if (typeof event !== 'string' || event.length === 0) return
+
+    const subject = await client.subjectReady
+    let authorized: boolean
+    try {
+      authorized = (await this.broadcaster.authorizeFor(channel, subject)).authorized
+    } catch (err) {
+      this.logger?.error('broadcast.ws.publish_authorize_failed', { channel, err })
+      this.sendFrame(client.ws, { t: 'err', c: channel, r: 'authorization failed' })
+      return
+    }
+    if (!authorized) {
+      this.sendFrame(client.ws, { t: 'err', c: channel, r: 'unauthorized' })
+      return
+    }
+    let permitted: boolean
+    try {
+      permitted = await this.allowClientPublish({
+        channel,
+        event,
+        data,
+        subject,
+        clientId: client.clientId,
+      })
+    } catch (err) {
+      this.logger?.error('broadcast.ws.allow_publish_failed', {
+        channel,
+        event,
+        err,
+      })
+      this.sendFrame(client.ws, { t: 'err', c: channel, r: 'publish denied' })
+      return
+    }
+    if (!permitted) {
+      this.sendFrame(client.ws, { t: 'err', c: channel, r: 'publish denied' })
+      return
+    }
+    try {
+      await this.broadcaster.publish(channel, {
+        event,
+        data,
+        id: ulid(),
+      })
+    } catch (err) {
+      if (err instanceof BroadcastUnauthorizedError) {
+        this.sendFrame(client.ws, { t: 'err', c: channel, r: 'unauthorized' })
+        return
+      }
+      this.logger?.error('broadcast.ws.publish_failed', { channel, event, err })
+      this.sendFrame(client.ws, { t: 'err', c: channel, r: 'publish failed' })
+    }
+  }
+
+  private ensureUpstream(channel: string): UpstreamChannel {
+    const existing = this.upstream.get(channel)
+    if (existing !== undefined) return existing
+    const subscription = this.broadcaster.subscribe(channel)
+    const clients = new Set<string>()
+    const upstream: UpstreamChannel = {
+      subscription,
+      clients,
+      loop: this.forwardLoop(channel, subscription, clients),
+    }
+    this.upstream.set(channel, upstream)
+    return upstream
+  }
+
+  private async forwardLoop(
+    channel: string,
+    subscription: BroadcastSubscription,
+    clients: Set<string>,
+  ): Promise<void> {
+    try {
+      for await (const event of subscription) {
+        if (this.closed) return
+        this.fanout(channel, event, clients)
+      }
+    } catch (err) {
+      this.logger?.error('broadcast.ws.forward_loop_failed', { channel, err })
+    }
+  }
+
+  private fanout(channel: string, event: BroadcastEvent, clientIds: Set<string>): void {
+    const frame: ServerFrame = {
+      t: 'msg',
+      c: channel,
+      e: event.event,
+      d: event.data,
+      i: event.id,
+    }
+    const payload = JSON.stringify(frame)
+    for (const id of clientIds) {
+      const client = this.clients.get(id)
+      if (client === undefined) continue
+      try {
+        client.ws.send(payload)
+      } catch {
+        // The socket already errored; the close handler will clean up.
+      }
+    }
+  }
+
+  private dropFromUpstream(channel: string, clientId: string): void {
+    const upstream = this.upstream.get(channel)
+    if (upstream === undefined) return
+    upstream.clients.delete(clientId)
+    if (upstream.clients.size > 0) return
+    this.upstream.delete(channel)
+    void upstream.subscription.unsubscribe().catch(() => {
+      // Best-effort — a transient driver error here shouldn't crash the gateway.
+    })
+  }
+
+  private pingAll(): void {
+    const frame: ServerFrame = { t: 'ping' }
+    const payload = JSON.stringify(frame)
+    for (const client of this.clients.values()) {
+      try {
+        client.ws.send(payload)
+      } catch {
+        // Same rationale as `fanout` — let the close handler do the cleanup.
+      }
+    }
+  }
+
+  private sendFrame(ws: ServerWebSocket<WebSocketData>, frame: ServerFrame): void {
+    try {
+      ws.send(JSON.stringify(frame))
+    } catch {
+      // Socket gone; close handler will run.
+    }
+  }
+}