@stravigor/core 0.1.0

package/src/broadcast/broadcast_manager.ts

@@ -0,0 +1,411 @@
+import type { ServerWebSocket } from 'bun'
+import Context from '../http/context.ts'
+import { compose } from '../http/middleware.ts'
+import type { Middleware } from '../http/middleware.ts'
+import type Router from '../http/router.ts'
+import type { WebSocketData } from '../http/router.ts'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Authorization callback — return true to allow subscription. */
+export type AuthorizeCallback = (
+  ctx: Context,
+  params: Record<string, string>
+) => boolean | Promise<boolean>
+
+/** Handler for client messages on a channel. */
+export type MessageHandler = (
+  ctx: Context,
+  params: Record<string, string>,
+  data: unknown
+) => void | Promise<void>
+
+/** Full channel configuration with authorization and message handlers. */
+export interface ChannelConfig {
+  authorize?: AuthorizeCallback
+  messages?: Record<string, MessageHandler>
+}
+
+export interface BootOptions {
+  /** WebSocket endpoint path. Default: `/_broadcast` */
+  path?: string
+  /** Middleware to run on each WebSocket connection (e.g. session). */
+  middleware?: Middleware[]
+  /** Keepalive ping interval in ms. 0 to disable. Default: 30000 */
+  pingInterval?: number
+}
+
+interface ChannelDefinition {
+  pattern: string
+  regex: RegExp
+  paramNames: string[]
+  authorize?: AuthorizeCallback
+  messages?: Record<string, MessageHandler>
+}
+
+interface ClientConnection {
+  ws: ServerWebSocket<WebSocketData>
+  clientId: string
+  channels: Set<string>
+  ctxReady: Promise<Context>
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parsePattern(pattern: string): { regex: RegExp; paramNames: string[] } {
+  const paramNames: string[] = []
+  const regexStr = pattern
+    .replace(/\/\*(\w+)/, (_, name) => { paramNames.push(name); return '/(.+)' })
+    .replace(/:(\w+)/g, (_, name) => { paramNames.push(name); return '([^/]+)' })
+  return { regex: new RegExp(`^${regexStr}$`), paramNames }
+}
+
+function extractParams(names: string[], match: RegExpExecArray): Record<string, string> {
+  const params: Record<string, string> = {}
+  for (let i = 0; i < names.length; i++) {
+    params[names[i]!] = match[i + 1]!
+  }
+  return params
+}
+
+// ---------------------------------------------------------------------------
+// PendingBroadcast — fluent builder for .to().except().send()
+// ---------------------------------------------------------------------------
+
+export interface PendingBroadcast {
+  /** Exclude a specific client from receiving the broadcast. */
+  except(clientId: string): PendingBroadcast
+  /** Send an event with optional data to the channel. */
+  send(event: string, data?: unknown): void
+}
+
+// ---------------------------------------------------------------------------
+// BroadcastManager
+// ---------------------------------------------------------------------------
+
+/**
+ * Channel-based WebSocket broadcasting.
+ *
+ * Manages channel definitions, client connections, subscriptions,
+ * and message routing over a single multiplexed WebSocket endpoint.
+ *
+ * @example
+ * // Bootstrap
+ * BroadcastManager.boot(router, { middleware: [session()] })
+ *
+ * // Define channels
+ * BroadcastManager.channel('notifications')
+ * BroadcastManager.channel('chats/:id', async (ctx, { id }) => !!ctx.get('user'))
+ *
+ * // Broadcast
+ * BroadcastManager.to('notifications').send('alert', { text: 'Hello' })
+ */
+export default class BroadcastManager {
+  private static _channels: ChannelDefinition[] = []
+  private static _clients = new Map<string, ClientConnection>()
+  private static _subscribers = new Map<string, Set<string>>()
+  private static _wsToClient = new WeakMap<object, string>()
+  private static _middleware: Middleware[] = []
+  private static _pingTimer: ReturnType<typeof setInterval> | null = null
+
+  /**
+   * Register the broadcast WebSocket endpoint on the router.
+   *
+   * @example
+   * BroadcastManager.boot(router, {
+   *   middleware: [session()],
+   *   pingInterval: 30_000,
+   * })
+   */
+  static boot(router: Router, options?: BootOptions): void {
+    const path = options?.path ?? '/_broadcast'
+    const pingInterval = options?.pingInterval ?? 30_000
+
+    if (options?.middleware) {
+      BroadcastManager._middleware = options.middleware
+    }
+
+    router.ws(path, {
+      open(ws) {
+        const clientId = crypto.randomUUID()
+        BroadcastManager._wsToClient.set(ws, clientId)
+
+        const ctxReady = BroadcastManager.buildContext(ws)
+        BroadcastManager._clients.set(clientId, {
+          ws,
+          clientId,
+          channels: new Set(),
+          ctxReady,
+        })
+
+        ws.send(JSON.stringify({ t: 'welcome', id: clientId }))
+      },
+
+      async message(ws, raw) {
+        try {
+          const msg = JSON.parse(raw as string)
+          const clientId = BroadcastManager._wsToClient.get(ws)
+          if (!clientId) return
+
+          const client = BroadcastManager._clients.get(clientId)
+          if (!client) return
+
+          switch (msg.t) {
+            case 'sub':
+              await BroadcastManager.handleSubscribe(client, msg.c)
+              break
+            case 'unsub':
+              BroadcastManager.handleUnsubscribe(client, msg.c)
+              break
+            case 'msg':
+              await BroadcastManager.handleMessage(client, msg.c, msg.e, msg.d)
+              break
+            case 'pong':
+              break
+          }
+        } catch {
+          // Malformed message — silently ignore
+        }
+      },
+
+      close(ws) {
+        const clientId = BroadcastManager._wsToClient.get(ws)
+        if (clientId) BroadcastManager.removeClient(clientId)
+      },
+    })
+
+    // Keepalive pings
+    if (pingInterval > 0) {
+      BroadcastManager._pingTimer = setInterval(() => {
+        const ping = JSON.stringify({ t: 'ping' })
+        for (const client of BroadcastManager._clients.values()) {
+          try { client.ws.send(ping) } catch {}
+        }
+      }, pingInterval)
+    }
+  }
+
+  /**
+   * Register a channel.
+   *
+   * Accepts either an authorization callback or a full config with
+   * message handlers for bidirectional communication.
+   *
+   * @example
+   * // Public channel
+   * BroadcastManager.channel('announcements')
+   *
+   * // Authorized channel
+   * BroadcastManager.channel('chats/:id', async (ctx, { id }) => {
+   *   return !!ctx.get('user')
+   * })
+   *
+   * // Channel with message handlers
+   * BroadcastManager.channel('chat/:id', {
+   *   authorize: async (ctx, { id }) => !!ctx.get('user'),
+   *   messages: {
+   *     async send(ctx, { id }, data) {
+   *       BroadcastManager.to(`chat/${id}`).send('new_message', data)
+   *     }
+   *   }
+   * })
+   */
+  static channel(pattern: string, config?: AuthorizeCallback | ChannelConfig): void {
+    const { regex, paramNames } = parsePattern(pattern)
+
+    let authorize: AuthorizeCallback | undefined
+    let messages: Record<string, MessageHandler> | undefined
+
+    if (typeof config === 'function') {
+      authorize = config
+    } else if (config) {
+      authorize = config.authorize
+      messages = config.messages
+    }
+
+    BroadcastManager._channels.push({ pattern, regex, paramNames, authorize, messages })
+  }
+
+  /**
+   * Begin a broadcast to a channel.
+   *
+   * @example
+   * BroadcastManager.to('chat/1').send('message', { text: 'Hello' })
+   * BroadcastManager.to('chat/1').except(senderId).send('message', data)
+   */
+  static to(channel: string): PendingBroadcast & { except(clientId: string): PendingBroadcast } {
+    let excluded: string | null = null
+
+    const pending: PendingBroadcast & { except(clientId: string): PendingBroadcast } = {
+      except(clientId: string) {
+        excluded = clientId
+        return pending
+      },
+      send(event: string, data?: unknown) {
+        BroadcastManager.broadcastToChannel(channel, event, data, excluded)
+      },
+    }
+
+    return pending
+  }
+
+  /** Number of active WebSocket connections. */
+  static get clientCount(): number {
+    return BroadcastManager._clients.size
+  }
+
+  /** Number of subscribers on a specific channel. */
+  static subscriberCount(channel: string): number {
+    return BroadcastManager._subscribers.get(channel)?.size ?? 0
+  }
+
+  /** Clear all state. Intended for test teardown. */
+  static reset(): void {
+    if (BroadcastManager._pingTimer) {
+      clearInterval(BroadcastManager._pingTimer)
+      BroadcastManager._pingTimer = null
+    }
+    BroadcastManager._channels = []
+    BroadcastManager._clients.clear()
+    BroadcastManager._subscribers.clear()
+    BroadcastManager._middleware = []
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static async buildContext(ws: ServerWebSocket<WebSocketData>): Promise<Context> {
+    const request = ws.data?.request
+    if (!request) return new Context(new Request('http://localhost'), {})
+
+    const ctx = new Context(request, {})
+
+    if (BroadcastManager._middleware.length > 0) {
+      const noop = () => new Response(null)
+      await compose(BroadcastManager._middleware, noop)(ctx)
+    }
+
+    return ctx
+  }
+
+  private static async handleSubscribe(client: ClientConnection, channelName: string): Promise<void> {
+    if (!channelName) return
+
+    // Already subscribed
+    if (client.channels.has(channelName)) {
+      client.ws.send(JSON.stringify({ t: 'ok', c: channelName }))
+      return
+    }
+
+    const match = BroadcastManager.matchChannel(channelName)
+    if (!match) {
+      client.ws.send(JSON.stringify({ t: 'err', c: channelName, r: 'unknown channel' }))
+      return
+    }
+
+    const { definition, params } = match
+
+    if (definition.authorize) {
+      try {
+        const ctx = await client.ctxReady
+        const allowed = await definition.authorize(ctx, params)
+        if (!allowed) {
+          client.ws.send(JSON.stringify({ t: 'err', c: channelName, r: 'unauthorized' }))
+          return
+        }
+      } catch {
+        client.ws.send(JSON.stringify({ t: 'err', c: channelName, r: 'authorization failed' }))
+        return
+      }
+    }
+
+    // Add to subscribers
+    client.channels.add(channelName)
+    let subs = BroadcastManager._subscribers.get(channelName)
+    if (!subs) {
+      subs = new Set()
+      BroadcastManager._subscribers.set(channelName, subs)
+    }
+    subs.add(client.clientId)
+
+    client.ws.send(JSON.stringify({ t: 'ok', c: channelName }))
+  }
+
+  private static handleUnsubscribe(client: ClientConnection, channelName: string): void {
+    if (!channelName) return
+    client.channels.delete(channelName)
+    const subs = BroadcastManager._subscribers.get(channelName)
+    if (subs) {
+      subs.delete(client.clientId)
+      if (subs.size === 0) BroadcastManager._subscribers.delete(channelName)
+    }
+  }
+
+  private static async handleMessage(
+    client: ClientConnection,
+    channelName: string,
+    event: string,
+    data: unknown
+  ): Promise<void> {
+    if (!channelName || !event) return
+    if (!client.channels.has(channelName)) return
+
+    const match = BroadcastManager.matchChannel(channelName)
+    if (!match?.definition.messages?.[event]) return
+
+    const ctx = await client.ctxReady
+    ;(ctx as any).clientId = client.clientId
+
+    await match.definition.messages[event]!(ctx, match.params, data)
+  }
+
+  private static matchChannel(
+    channelName: string
+  ): { definition: ChannelDefinition; params: Record<string, string> } | null {
+    for (const def of BroadcastManager._channels) {
+      const m = def.regex.exec(channelName)
+      if (m) return { definition: def, params: extractParams(def.paramNames, m) }
+    }
+    return null
+  }
+
+  private static broadcastToChannel(
+    channel: string,
+    event: string,
+    data: unknown,
+    excludeClientId: string | null
+  ): void {
+    const subs = BroadcastManager._subscribers.get(channel)
+    if (!subs || subs.size === 0) return
+
+    const msg = JSON.stringify({ t: 'msg', c: channel, e: event, d: data })
+
+    for (const clientId of subs) {
+      if (clientId === excludeClientId) continue
+      const client = BroadcastManager._clients.get(clientId)
+      if (client) {
+        try { client.ws.send(msg) } catch {}
+      }
+    }
+  }
+
+  private static removeClient(clientId: string): void {
+    const client = BroadcastManager._clients.get(clientId)
+    if (!client) return
+
+    for (const channel of client.channels) {
+      const subs = BroadcastManager._subscribers.get(channel)
+      if (subs) {
+        subs.delete(clientId)
+        if (subs.size === 0) BroadcastManager._subscribers.delete(channel)
+      }
+    }
+
+    BroadcastManager._clients.delete(clientId)
+  }
+}

package/src/broadcast/client.ts

@@ -0,0 +1,302 @@
+/**
+ * Browser-side Broadcast client.
+ *
+ * Connects to the server's broadcast WebSocket endpoint,
+ * manages channel subscriptions, auto-reconnects, and routes
+ * events to subscription listeners.
+ *
+ * Zero dependencies — works in any browser.
+ *
+ * @example
+ * import { Broadcast } from '@stravigor/core/broadcast/client'
+ *
+ * const bc = new Broadcast()
+ *
+ * const chat = bc.subscribe('chat/1')
+ * chat.on('new_message', (data) => console.log(data))
+ * chat.send('send', { text: 'Hello!' })
+ *
+ * bc.on('connected', () => console.log('Online'))
+ * bc.on('disconnected', () => console.log('Offline'))
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BroadcastOptions {
+  /** WebSocket URL. Default: auto-detected from current host + `/_broadcast`. */
+  url?: string
+  /** Maximum reconnection attempts. Default: Infinity */
+  maxReconnectAttempts?: number
+}
+
+type Callback = (...args: any[]) => void
+
+// ---------------------------------------------------------------------------
+// Subscription
+// ---------------------------------------------------------------------------
+
+/**
+ * A subscription to a single broadcast channel.
+ *
+ * Listen for server events, send messages to the channel,
+ * or leave the channel entirely.
+ *
+ * @example
+ * const sub = bc.subscribe('chat/1')
+ * sub.on('message', (data) => { ... })
+ * sub.send('typing', { active: true })
+ * sub.leave()
+ */
+export class Subscription {
+  private listeners = new Map<string, Set<Callback>>()
+
+  constructor(
+    /** The channel name this subscription is bound to. */
+    readonly channel: string,
+    private sendFn: (msg: object) => void,
+    private leaveFn: () => void
+  ) {}
+
+  /**
+   * Listen for a specific event on this channel.
+   * Returns a function that removes the listener when called.
+   *
+   * @example
+   * const stop = sub.on('message', (data) => console.log(data))
+   * stop() // remove listener
+   */
+  on(event: string, callback: Callback): () => void {
+    let set = this.listeners.get(event)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(event, set)
+    }
+    set.add(callback)
+    return () => { set!.delete(callback) }
+  }
+
+  /**
+   * Send a message to the server on this channel.
+   *
+   * @example
+   * sub.send('typing', { active: true })
+   */
+  send(event: string, data?: unknown): void {
+    this.sendFn({ t: 'msg', c: this.channel, e: event, d: data })
+  }
+
+  /** Unsubscribe from this channel. */
+  leave(): void {
+    this.sendFn({ t: 'unsub', c: this.channel })
+    this.listeners.clear()
+    this.leaveFn()
+  }
+
+  /** @internal Dispatch an incoming event to registered listeners. */
+  _dispatch(event: string, data: unknown): void {
+    const set = this.listeners.get(event)
+    if (set) for (const cb of set) cb(data)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Broadcast
+// ---------------------------------------------------------------------------
+
+/**
+ * Broadcast client — manages a single WebSocket connection
+ * with multiplexed channel subscriptions.
+ *
+ * @example
+ * const bc = new Broadcast()
+ * const chat = bc.subscribe('chat/1')
+ * chat.on('message', (data) => console.log(data))
+ */
+export class Broadcast {
+  private ws: WebSocket | null = null
+  private url: string
+  private maxReconnectAttempts: number
+  private reconnectAttempt = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private subscriptions = new Map<string, Subscription>()
+  private listeners = new Map<string, Set<Callback>>()
+  private queue: string[] = []
+  private _connected = false
+  private _clientId: string | null = null
+
+  constructor(options?: BroadcastOptions) {
+    this.url = options?.url ?? this.autoUrl()
+    this.maxReconnectAttempts = options?.maxReconnectAttempts ?? Infinity
+    this.connect()
+  }
+
+  /** Whether the WebSocket connection is currently open. */
+  get connected(): boolean {
+    return this._connected
+  }
+
+  /** The unique client ID assigned by the server, or null if not yet connected. */
+  get clientId(): string | null {
+    return this._clientId
+  }
+
+  /**
+   * Subscribe to a broadcast channel.
+   *
+   * Returns an existing subscription if already subscribed.
+   * On reconnect, all active subscriptions are automatically re-established.
+   *
+   * @example
+   * const notifications = bc.subscribe('notifications')
+   * notifications.on('alert', (data) => showToast(data.text))
+   */
+  subscribe(channel: string): Subscription {
+    const existing = this.subscriptions.get(channel)
+    if (existing) return existing
+
+    const sub = new Subscription(
+      channel,
+      (msg) => this.send(msg),
+      () => this.subscriptions.delete(channel)
+    )
+
+    this.subscriptions.set(channel, sub)
+
+    if (this._connected) {
+      this.rawSend({ t: 'sub', c: channel })
+    }
+
+    return sub
+  }
+
+  /**
+   * Listen for connection lifecycle events.
+   *
+   * Events:
+   * - `connected` — WebSocket connection established
+   * - `disconnected` — WebSocket connection lost
+   * - `reconnecting` — reconnection attempt (callback receives attempt number)
+   * - `subscribed` — channel subscription confirmed (callback receives channel name)
+   * - `error` — subscription error (callback receives `{ channel, reason }`)
+   *
+   * Returns a function that removes the listener.
+   */
+  on(event: string, callback: Callback): () => void {
+    let set = this.listeners.get(event)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(event, set)
+    }
+    set.add(callback)
+    return () => { set!.delete(callback) }
+  }
+
+  /** Close the connection permanently (no reconnection). */
+  close(): void {
+    this.reconnectAttempt = Infinity
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.ws?.close()
+    this.ws = null
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private autoUrl(): string {
+    const proto = location.protocol === 'https:' ? 'wss:' : 'ws:'
+    return `${proto}//${location.host}/_broadcast`
+  }
+
+  private connect(): void {
+    this.ws = new WebSocket(this.url)
+
+    this.ws.onopen = () => {
+      this._connected = true
+      this.reconnectAttempt = 0
+      this.emit('connected')
+    }
+
+    this.ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(event.data)
+        this.handleMessage(msg)
+      } catch {}
+    }
+
+    this.ws.onclose = () => {
+      const wasConnected = this._connected
+      this._connected = false
+      if (wasConnected) this.emit('disconnected')
+      this.scheduleReconnect()
+    }
+
+    this.ws.onerror = () => {
+      this.ws?.close()
+    }
+  }
+
+  private handleMessage(msg: any): void {
+    switch (msg.t) {
+      case 'welcome':
+        this._clientId = msg.id
+        // Re-subscribe to all active channels
+        for (const channel of this.subscriptions.keys()) {
+          this.rawSend({ t: 'sub', c: channel })
+        }
+        // Flush queued messages
+        for (const raw of this.queue) {
+          this.ws!.send(raw)
+        }
+        this.queue = []
+        break
+
+      case 'ok':
+        this.emit('subscribed', msg.c)
+        break
+
+      case 'err':
+        this.emit('error', { channel: msg.c, reason: msg.r })
+        break
+
+      case 'msg':
+        this.subscriptions.get(msg.c)?._dispatch(msg.e, msg.d)
+        break
+
+      case 'ping':
+        this.rawSend({ t: 'pong' })
+        break
+    }
+  }
+
+  private send(msg: object): void {
+    const raw = JSON.stringify(msg)
+    if (this._connected && this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(raw)
+    } else {
+      this.queue.push(raw)
+    }
+  }
+
+  private rawSend(msg: object): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg))
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectAttempt >= this.maxReconnectAttempts) return
+
+    this.reconnectAttempt++
+    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempt - 1), 30_000)
+    this.emit('reconnecting', this.reconnectAttempt)
+    this.reconnectTimer = setTimeout(() => this.connect(), delay)
+  }
+
+  private emit(event: string, data?: unknown): void {
+    const set = this.listeners.get(event)
+    if (set) for (const cb of set) cb(data)
+  }
+}