@stacksjs/realtime 0.70.53 → 0.70.55

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/realtime",
   "type": "module",
-  "version": "0.70.53",
+  "version": "0.70.55",
   "description": "The Stacks realtime integration. Built on top of ts-broadcasting.",
   "author": "Chris Breuer",
   "contributors": [
@@ -40,7 +40,8 @@
   "types": "dist/index.d.ts",
   "files": [
     "README.md",
-    "dist"
+    "dist",
+    "src"
   ],
   "scripts": {
     "build": "bun build.ts",

package/src/broadcast.ts

@@ -0,0 +1,303 @@
+import type { BroadcastEvent, ChannelType } from 'ts-broadcasting'
+import { log } from '@stacksjs/logging'
+import { recordBroadcast } from './replay-buffer'
+import { getServer } from './server-instance'
+
+/**
+ * Backpressure guard config (stacksjs/stacks#1877 R-2). The default
+ * threshold is 1 MiB of buffered-bytes per socket — above this, the
+ * configured `onSlow` callback fires once per offending socket per
+ * broadcast. Apps install via `setBackpressureGuard({...})`; the
+ * default is "no guard" for backwards-compat, so existing callers
+ * see no behavior change until they opt in.
+ *
+ * Why opt-in: the underlying ts-broadcasting `server.broadcast()` is
+ * synchronous and we can't inject between message-serialize and
+ * socket-write. The best we can do at the Stacks layer is detect
+ * slow consumers AROUND the broadcast call and let the app decide
+ * what to do (close socket, drop client from channel, scale up).
+ */
+export interface BackpressureGuardConfig {
+  /**
+   * Per-socket buffered-bytes threshold. Sockets with `backpressure`
+   * (Bun.ServerWebSocket property) above this value trigger `onSlow`.
+   * Default: 1 MiB (1024 * 1024).
+   */
+  maxPerSocketBytes?: number
+  /**
+   * Called once per slow socket per broadcast tick. Default action
+   * is to log a warning; install a custom handler to close the
+   * socket, drop the client from the channel, etc.
+   */
+  onSlow?: (info: { channelName: string, backpressure: number, socket: unknown }) => void
+}
+
+let backpressureConfig: Required<BackpressureGuardConfig> | null = null
+
+/**
+ * Install (or clear) the backpressure guard. Pass `null` to disable.
+ */
+export function setBackpressureGuard(cfg: BackpressureGuardConfig | null): void {
+  if (!cfg) {
+    backpressureConfig = null
+    return
+  }
+  backpressureConfig = {
+    maxPerSocketBytes: cfg.maxPerSocketBytes ?? 1024 * 1024,
+    onSlow: cfg.onSlow ?? ((info) => {
+      log.warn(`[realtime] slow consumer on '${info.channelName}': ${info.backpressure} bytes buffered`)
+    }),
+  }
+}
+
+/**
+ * Read the currently-installed guard config (useful for tests).
+ */
+export function getBackpressureGuard(): Required<BackpressureGuardConfig> | null {
+  return backpressureConfig
+}
+
+/**
+ * Walk the server's per-channel socket set and check `backpressure`
+ * against the configured threshold. Best-effort: ts-broadcasting may
+ * expose the socket set under a few different property names and
+ * sockets without a `.backpressure` field are silently skipped.
+ */
+function checkBackpressure(server: any, channelName: string): void {
+  if (!backpressureConfig) return
+  try {
+    const channels = server.channels ?? server.clients
+    const set = channels && typeof channels.get === 'function' ? channels.get(channelName) : null
+    if (!set || typeof set[Symbol.iterator] !== 'function') return
+
+    const { maxPerSocketBytes, onSlow } = backpressureConfig
+    for (const entry of set) {
+      // ts-broadcasting may store either the bare socket or a
+      // wrapper — probe both shapes.
+      const ws = (entry && typeof entry === 'object' && 'ws' in entry) ? (entry as { ws: unknown }).ws : entry
+      const bp = ws && typeof ws === 'object' && 'backpressure' in ws ? (ws as { backpressure: unknown }).backpressure : null
+      if (typeof bp === 'number' && bp > maxPerSocketBytes) {
+        onSlow({ channelName, backpressure: bp, socket: ws })
+      }
+    }
+  }
+  catch {
+    // Introspection failed — same fallthrough policy as hasSubscribers.
+  }
+}
+
+/**
+ * Best-effort check for whether anyone is subscribed to `channelName`.
+ *
+ * The `BroadcastServer` interface is stable but the subscriber-count
+ * accessor isn't — different ts-broadcasting versions expose it as
+ * `hasSubscribers`, `channelCount`, or via `clients.get(name)?.size`.
+ * We try the public surface first and fall back to a permissive
+ * `true` so we never *block* a legitimate broadcast just because we
+ * couldn't introspect the subscriber set. This stays a perf hint, not
+ * a correctness gate.
+ */
+function hasSubscribers(server: any, channelName: string): boolean {
+  try {
+    if (typeof server.hasSubscribers === 'function') {
+      return Boolean(server.hasSubscribers(channelName))
+    }
+    if (typeof server.subscriberCount === 'function') {
+      return server.subscriberCount(channelName) > 0
+    }
+    const channels = server.channels ?? server.clients
+    if (channels && typeof channels.get === 'function') {
+      const set = channels.get(channelName)
+      const size = (set && (set.size ?? set.length)) ?? null
+      if (typeof size === 'number') return size > 0
+    }
+  }
+  catch {
+    // Fall through — if introspection threw, treat as "subscribers might exist".
+  }
+  return true
+}
+
+export interface BroadcastInstance {
+  channel?: () => string | string[]
+  broadcastOn?: () => string | string[]
+  event?: () => string
+  broadcastAs?: () => string
+  data?: () => any
+  broadcastWith?: () => any
+  handle?: (payload?: any) => Promise<void> | void
+}
+
+/**
+ * Stacks Broadcast class for backward compatibility
+ * Wraps ts-broadcasting's BroadcastServer
+ */
+export class Broadcast {
+  /**
+   * Connect to the realtime service
+   */
+  async connect(): Promise<void> {
+    // No-op - connection is managed by BroadcastServer
+  }
+
+  /**
+   * Disconnect from the realtime service
+   */
+  async disconnect(): Promise<void> {
+    // No-op - disconnection is managed by BroadcastServer
+  }
+
+  /**
+   * Subscribe to a channel
+   */
+  subscribe(channel: string, callback: (data: any) => void): void {
+    // Subscription is client-side, not server-side
+    // This is handled by BroadcastClient
+    log.warn('Broadcast.subscribe() is a client-side operation. Use BroadcastClient instead.')
+  }
+
+  /**
+   * Unsubscribe from a channel
+   */
+  unsubscribe(channel: string): void {
+    // Unsubscription is client-side, not server-side
+    log.warn('Broadcast.unsubscribe() is a client-side operation. Use BroadcastClient instead.')
+  }
+
+  /**
+   * Broadcast an event to a channel
+   *
+   * Skips the wire-level broadcast when no subscribers are listening on
+   * the resolved channel. Without this, every emit walked the channel
+   * multiplexer, serialized the payload, and looped through an empty
+   * subscriber set — which is wasted work that compounds when chatty
+   * model-event broadcasts run on cold sockets.
+   */
+  broadcast(channel: string, event: string, data?: any, type: ChannelType = 'public'): void {
+    const server = getServer()
+
+    if (!server) {
+      log.warn('Broadcast server not initialized')
+      return
+    }
+
+    let channelName = channel
+    if (type === 'private' && !channel.startsWith('private-')) {
+      channelName = `private-${channel}`
+    }
+    else if (type === 'presence' && !channel.startsWith('presence-')) {
+      channelName = `presence-${channel}`
+    }
+
+    if (!hasSubscribers(server, channelName)) {
+      log.debug(`[Broadcast] Skipping '${event}' on '${channelName}' — no subscribers`)
+      return
+    }
+
+    // Backpressure guard (stacksjs/stacks#1877 R-2). Opt-in via
+    // `setBackpressureGuard({...})`. Default is no-op so existing
+    // callers see no behavior change. Runs before the broadcast so
+    // a slow consumer detected on the previous tick fires its
+    // `onSlow` handler before more bytes are queued onto its socket.
+    checkBackpressure(server, channelName)
+
+    // Record the message in the replay buffer BEFORE the wire-level
+    // broadcast (stacksjs/stacks#1877 R-3). Opt-in via
+    // `setReplayBuffer({...})`; default is no-op so non-buffered
+    // channels see zero overhead. Recording first means a transient
+    // broadcast failure (next try block) doesn't leave a buffered
+    // ghost on a channel where nobody received the event.
+    recordBroadcast(channelName, event, data)
+
+    try {
+      server.broadcast(channelName, event, data)
+    }
+    catch (err) {
+      log.error(`[Broadcast] Failed to broadcast event '${event}' to channel '${channelName}':`, err)
+    }
+  }
+
+  /**
+   * Check if connected to the realtime service
+   */
+  isConnected(): boolean {
+    return getServer() !== null
+  }
+}
+
+/**
+ * Run a broadcast from a broadcast file
+ *
+ * @example
+ * await runBroadcast('OrderCreated', { orderId: 123 })
+ */
+export async function runBroadcast(name: string, payload?: any): Promise<void> {
+  // Dynamically import path utilities to avoid build-time issues
+  const { appPath } = await import('@stacksjs/path')
+  const bun = await import('bun')
+
+  let broadcastFiles: string[]
+  try {
+    broadcastFiles = (bun as any).globSync([appPath('Broadcasts/**/*.ts')], { absolute: true })
+  }
+  catch (error) {
+    throw new Error(`Failed to scan broadcast files: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  const broadcastFile = broadcastFiles.find((file: string) => file.endsWith(`${name}.ts`))
+
+  if (!broadcastFile)
+    throw new Error(`Broadcast ${name} not found`)
+
+  let broadcastModule: any
+  try {
+    broadcastModule = await import(broadcastFile)
+  }
+  catch (error) {
+    throw new Error(`Failed to import broadcast '${name}': ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  const instance = broadcastModule.default as BroadcastInstance
+
+  // Handle using handle() method
+  if (instance.handle) {
+    await instance.handle(payload)
+    return
+  }
+
+  // Handle using BroadcastEvent-like interface
+  const server = getServer()
+  if (!server) {
+    throw new Error('Broadcast server not initialized')
+  }
+
+  const channels = instance.broadcastOn?.() || instance.channel?.() || []
+  const eventName = instance.broadcastAs?.() || instance.event?.() || name
+  const data = instance.broadcastWith?.() || instance.data?.() || payload
+
+  // Convert to BroadcastEvent and broadcast
+  const event: BroadcastEvent = {
+    shouldBroadcast: () => true,
+    broadcastOn: () => channels,
+    broadcastAs: () => eventName,
+    broadcastWith: () => data,
+  }
+
+  await server.broadcaster.broadcast(event)
+}
+
+/**
+ * Alias for runBroadcast.
+ *
+ * @example
+ * await broadcast('OrderCreated', { orderId: 123 })
+ */
+export async function broadcast(name: string, payload?: any): Promise<void> {
+  // Validate the event name eagerly — empty / non-string names go through
+  // ts-broadcasting and surface as confusing wire-format errors deep
+  // inside the channel multiplexer instead of where the bug originated.
+  if (typeof name !== 'string' || name.trim().length === 0) {
+    throw new Error('[realtime] broadcast() requires a non-empty event name')
+  }
+  await runBroadcast(name, payload)
+}

package/src/channel.ts

@@ -0,0 +1,103 @@
+import type { ChannelType } from 'ts-broadcasting'
+import { getServer } from './server-instance'
+
+/**
+ * Strip any well-known channel-type prefix from `name` so the
+ * type-specific methods can apply their own prefix without the user
+ * accidentally producing `private-presence-foo` etc. when the name
+ * was passed in already prefixed (or with the wrong prefix).
+ *
+ * The previous implementation only guarded against the *matching*
+ * prefix being doubled — `channel('presence-x').private(...)` would
+ * incorrectly emit on `private-presence-x` instead of `private-x`.
+ */
+const KNOWN_CHANNEL_PREFIXES = ['private-', 'presence-'] as const
+
+function stripPrefix(name: string): string {
+  for (const p of KNOWN_CHANNEL_PREFIXES) {
+    if (name.startsWith(p)) return name.slice(p.length)
+  }
+  return name
+}
+
+/**
+ * Stacks Channel class for backward compatibility
+ * Provides a fluent API for broadcasting to channels
+ */
+export class Channel {
+  private channelName: string
+
+  constructor(channel: string) {
+    this.channelName = channel
+  }
+
+  /**
+   * Broadcast to a private channel
+   */
+  async private(event: string, data?: any): Promise<void> {
+    const server = getServer()
+    if (!server) {
+      throw new Error('Broadcast server not initialized')
+    }
+
+    await server.broadcast(`private-${stripPrefix(this.channelName)}`, event, data)
+  }
+
+  /**
+   * Broadcast to a public channel
+   */
+  async public(event: string, data?: any): Promise<void> {
+    const server = getServer()
+    if (!server) {
+      throw new Error('Broadcast server not initialized')
+    }
+
+    // Public channels never use a prefix. If the caller passed in a
+    // type-prefixed name by mistake, strip it so the broadcast actually
+    // lands on the public bus rather than colliding with a private one.
+    await server.broadcast(stripPrefix(this.channelName), event, data)
+  }
+
+  /**
+   * Broadcast to a presence channel
+   */
+  async presence(event: string, data?: any): Promise<void> {
+    const server = getServer()
+    if (!server) {
+      throw new Error('Broadcast server not initialized')
+    }
+
+    await server.broadcast(`presence-${stripPrefix(this.channelName)}`, event, data)
+  }
+
+  /**
+   * Broadcast to a channel with explicit type
+   */
+  async broadcast(event: string, data?: any, type: ChannelType = 'public'): Promise<void> {
+    switch (type) {
+      case 'private':
+        return this.private(event, data)
+      case 'presence':
+        return this.presence(event, data)
+      default:
+        return this.public(event, data)
+    }
+  }
+}
+
+/**
+ * Create a new channel instance
+ *
+ * @example
+ * // Broadcast to a public channel
+ * await channel('orders').public('created', { id: 1 })
+ *
+ * // Broadcast to a private channel
+ * await channel('orders.123').private('updated', { status: 'shipped' })
+ *
+ * // Broadcast to a presence channel
+ * await channel('chat.room.1').presence('message', { text: 'Hello' })
+ */
+export function channel(name: string): Channel {
+  return new Channel(name)
+}

package/src/emit.ts

@@ -0,0 +1,95 @@
+import type { ChannelType } from 'ts-broadcasting'
+import { getServer } from './server-instance'
+
+export interface EmitOptions {
+  private?: boolean
+  presence?: boolean
+  exclude?: string | string[]
+  driver?: string
+}
+
+/**
+ * Emit an event to a channel
+ *
+ * @example
+ * // Simple emit to public channel
+ * emit('orders', 'created', { id: 1, total: 99.99 })
+ *
+ * // Emit to private channel
+ * emit('orders.123', 'updated', { status: 'shipped' }, { private: true })
+ *
+ * // Emit to presence channel
+ * emit('chat.room.1', 'message', { text: 'Hello' }, { presence: true })
+ *
+ * // Exclude specific users
+ * emit('chat.room.1', 'message', { text: 'Hello' }, { exclude: 'user-123' })
+ */
+export function emit<T = unknown>(
+  channel: string,
+  event: string,
+  data?: T,
+  options?: EmitOptions,
+): void {
+  const server = getServer()
+
+  if (!server) {
+    console.warn('[realtime] Server not initialized, cannot emit event')
+    return
+  }
+
+  // Determine channel type and prefix
+  let channelName = channel
+
+  if (options?.presence) {
+    if (!channel.startsWith('presence-')) {
+      channelName = `presence-${channel}`
+    }
+  }
+  else if (options?.private) {
+    if (!channel.startsWith('private-')) {
+      channelName = `private-${channel}`
+    }
+  }
+
+  // Get exclude socket ID
+  const excludeSocketId = options?.exclude
+    ? Array.isArray(options.exclude)
+      ? options.exclude[0] // BroadcastServer only supports single socket exclusion
+      : options.exclude
+    : undefined
+
+  // Broadcast the event
+  server.broadcast(channelName, event, data, excludeSocketId)
+}
+
+/**
+ * Emit an event to a specific user
+ *
+ * @example
+ * emitToUser('user-123', 'notification', { message: 'You have a new order!' })
+ */
+export function emitToUser<T = unknown>(
+  userId: string | number,
+  event: string,
+  data?: T,
+  options?: Omit<EmitOptions, 'private'>,
+): void {
+  emit(`private-user.${userId}`, event, data, { ...options, private: true })
+}
+
+/**
+ * Emit an event to multiple users
+ *
+ * @example
+ * emitToUsers(['user-1', 'user-2'], 'announcement', { message: 'Server maintenance!' })
+ */
+export function emitToUsers<T = unknown>(
+  userIds: (string | number)[],
+  event: string,
+  data?: T,
+  options?: Omit<EmitOptions, 'private'>,
+): void {
+  for (const userId of userIds) {
+    emitToUser(userId, event, data, options)
+  }
+}

package/src/heartbeat.ts

@@ -0,0 +1,184 @@
+/**
+ * Server-side WebSocket heartbeat (stacksjs/stacks#1877 R-5).
+ *
+ * Background: a half-closed socket (network cable pulled, idle NAT
+ * timeout, mobile client lost connection without sending FIN) lingers
+ * in the server's memory until the OS surfaces the close. On long-running
+ * servers behind NAT — exactly the production deployment shape — these
+ * accumulate as "ghost" subscribers that the broadcast loop still tries
+ * to write to.
+ *
+ * Fix: opt-in heartbeat that pings every `intervalMs`, tracks the last
+ * pong timestamp per socket, and closes any socket that misses
+ * `maxMissedPongs` consecutive cycles. Defaults: 30s interval, 2 missed
+ * pongs = 90s effective deadline. Apps install via
+ * `setHeartbeatConfig({...})` once at boot.
+ *
+ * Limitation: ts-broadcasting owns the socket lifecycle. We can detect
+ * dead sockets but the underlying server has to honor a close call.
+ * The default `onDead` handler tries `socket.close()` if available;
+ * apps can override to do harder cleanup.
+ */
+
+import { log } from '@stacksjs/logging'
+import { getServer } from './server-instance'
+
+export interface HeartbeatConfig {
+  /** Ping interval in milliseconds. Default: 30s. */
+  intervalMs?: number
+  /**
+   * Maximum consecutive missed pongs before declaring the socket
+   * dead and calling `onDead`. Default: 2.
+   */
+  maxMissedPongs?: number
+  /**
+   * Called when a socket misses `maxMissedPongs` pings in a row.
+   * Default action: try `socket.close()`. Install a custom handler
+   * to drop the socket from per-channel sets, emit a metric, etc.
+   */
+  onDead?: (socket: unknown) => void
+}
+
+interface HeartbeatState {
+  intervalMs: number
+  maxMissedPongs: number
+  onDead: (socket: unknown) => void
+  /** Map<socket, missed-pong-count> */
+  missed: WeakMap<object, number>
+  timer: ReturnType<typeof setInterval> | null
+}
+
+let state: HeartbeatState | null = null
+
+/**
+ * Install (or replace) the heartbeat config. Pass `null` to stop
+ * the heartbeat loop. Safe to call multiple times — the previous
+ * timer is cleared before the new one starts.
+ */
+export function setHeartbeatConfig(cfg: HeartbeatConfig | null): void {
+  if (state?.timer) {
+    clearInterval(state.timer)
+    state.timer = null
+  }
+  if (!cfg) {
+    state = null
+    return
+  }
+
+  const intervalMs = cfg.intervalMs ?? 30_000
+  const maxMissedPongs = cfg.maxMissedPongs ?? 2
+  const onDead = cfg.onDead ?? defaultOnDead
+
+  state = {
+    intervalMs,
+    maxMissedPongs,
+    onDead,
+    missed: new WeakMap(),
+    timer: null,
+  }
+
+  state.timer = setInterval(() => {
+    if (!state) return
+    runOneTick()
+  }, intervalMs)
+  ;(state.timer as ReturnType<typeof setInterval> & { unref?: () => void }).unref?.()
+}
+
+/** Read the current config — useful for tests. */
+export function getHeartbeatConfig(): Readonly<HeartbeatState> | null {
+  return state
+}
+
+/**
+ * Manually fire a single heartbeat tick. Exposed for tests; in
+ * production it's invoked by the internal interval.
+ */
+export function runOneTick(): void {
+  if (!state) return
+  const server = getServer()
+  if (!server) return
+
+  // Collect every active socket across all channels. ts-broadcasting
+  // exposes them under different property names by version; probe
+  // both `channels` and `clients` (already done by hasSubscribers and
+  // checkBackpressure — same iteration pattern).
+  const allSockets = collectSockets(server)
+
+  for (const socket of allSockets) {
+    const ws = socket as { send?: (data: string) => void, ping?: () => void, close?: (code?: number, reason?: string) => void }
+    const missed = state.missed.get(socket) ?? 0
+
+    if (missed >= state.maxMissedPongs) {
+      log.warn(`[realtime] socket missed ${missed} pongs — declaring dead`)
+      try {
+        state.onDead(socket)
+      }
+      catch (err) {
+        log.warn(`[realtime] heartbeat onDead handler threw: ${err instanceof Error ? err.message : String(err)}`)
+      }
+      state.missed.delete(socket as object)
+      continue
+    }
+
+    // Bump the missed counter BEFORE sending the ping — when the
+    // client pongs back, `markPong` resets it to 0. If the client
+    // never replies, the counter grows tick-by-tick until we
+    // declare it dead above.
+    state.missed.set(socket as object, missed + 1)
+
+    try {
+      if (typeof ws.ping === 'function') {
+        ws.ping()
+      }
+      else if (typeof ws.send === 'function') {
+        // Fallback for sockets without a native ping helper —
+        // send an application-level heartbeat frame the client
+        // can pong via the same mechanism.
+        ws.send('__stacks_ping__')
+      }
+    }
+    catch {
+      // Send threw — socket is likely already broken. Mark dead next tick.
+    }
+  }
+}
+
+/**
+ * Called from the server's pong handler (or message handler when
+ * fallback `__stacks_ping__` text frames are in use). Resets the
+ * missed-pong counter for the given socket so it doesn't get
+ * declared dead.
+ */
+export function markPong(socket: object): void {
+  if (!state) return
+  state.missed.delete(socket)
+}
+
+function collectSockets(server: unknown): object[] {
+  const out = new Set<object>()
+  try {
+    const channels = (server as { channels?: unknown, clients?: unknown }).channels
+      ?? (server as { channels?: unknown, clients?: unknown }).clients
+    if (channels && typeof (channels as { values?: () => Iterable<unknown> }).values === 'function') {
+      for (const set of (channels as { values: () => Iterable<unknown> }).values()) {
+        if (set && typeof (set as { [Symbol.iterator]: unknown })[Symbol.iterator] === 'function') {
+          for (const entry of set as Iterable<unknown>) {
+            const ws = (entry && typeof entry === 'object' && 'ws' in entry) ? (entry as { ws: object }).ws : entry
+            if (ws && typeof ws === 'object') out.add(ws as object)
+          }
+        }
+      }
+    }
+  }
+  catch {
+    // Introspection failed — same fallthrough policy as backpressure
+    // guard / hasSubscribers. Heartbeat is best-effort.
+  }
+  return [...out]
+}
+
+function defaultOnDead(socket: unknown): void {
+  const ws = socket as { close?: (code?: number, reason?: string) => void }
+  if (typeof ws.close === 'function')
+    ws.close(1011, 'heartbeat timeout')
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Stacks Realtime Module
+ *
+ * This module provides real-time broadcasting capabilities for Stacks applications.
+ * It's built on top of ts-broadcasting and provides a familiar Laravel-like API.
+ */
+
+// Re-export everything from ts-broadcasting
+export * from 'ts-broadcasting'
+
+// Note: all exports are already provided by `export * from 'ts-broadcasting'` above.
+// Aliases are provided below for convenience.
+
+// Server instance management
+export { getServer, setServer, createServer, stopServer } from './server-instance'
+
+// Stacks-specific exports
+export { emit, emitToUser, emitToUsers } from './emit'
+export type { EmitOptions } from './emit'
+export { channel as createChannel, Channel as StacksChannel } from './channel'
+export { broadcast as dispatchBroadcast, runBroadcast, Broadcast as LegacyBroadcast } from './broadcast'
+export type { BroadcastInstance } from './broadcast'
+// Backpressure guard for slow consumers (stacksjs/stacks#1877 R-2).
+// Opt-in via setBackpressureGuard; default is no-op.
+export { setBackpressureGuard, getBackpressureGuard } from './broadcast'
+export type { BackpressureGuardConfig } from './broadcast'
+
+// Heartbeat ping/pong for detecting half-closed sockets
+// (stacksjs/stacks#1877 R-5). Opt-in via setHeartbeatConfig.
+export { getHeartbeatConfig, markPong, runOneTick, setHeartbeatConfig } from './heartbeat'
+export type { HeartbeatConfig } from './heartbeat'
+
+// At-least-once replay buffer for reconnect (stacksjs/stacks#1877 R-3).
+// Opt-in via setReplayBuffer. Apps wire `replaySince(channel, seq)`
+// into their reconnect handler to re-send missed messages.
+export { debugSnapshot, getReplayBuffer, pruneExpired, recordBroadcast, replaySince, setReplayBuffer } from './replay-buffer'
+export type { BufferedMessage, ReplayBufferConfig } from './replay-buffer'
+export { setBunSocket, handleWebSocketRequest, storeWebSocketEvent } from './ws'
+// WebSocket authenticator wiring (stacksjs/stacks#1877 R-1). Install
+// once at server boot to require a valid token / cookie at the
+// handshake boundary — without it, the upgrade proceeds unauthed.
+export { setWsAuthenticator, getWsAuthenticator } from './ws'
+export type { WsAuthenticator, WsAuthResult } from './ws'

package/src/replay-buffer.ts

@@ -0,0 +1,201 @@
+/**
+ * Per-channel message replay buffer (stacksjs/stacks#1877 R-3).
+ *
+ * Background: ts-broadcasting delivers messages at-most-once — a client
+ * that drops between two broadcasts loses everything in flight. For
+ * channels where the app needs every message (chat, presence, order
+ * updates), reconnect-after-network-blip becomes a silent data loss.
+ *
+ * Fix: opt-in per-channel ring buffer that retains the most-recent N
+ * messages with monotonic sequence IDs. On reconnect, the client sends
+ * its last-seen seq; the server replays everything stored after that
+ * point. Apps install via `setReplayBuffer({ channels, maxPerChannel,
+ * ttlMs })`. Buffer is in-process — for cross-instance replay, route
+ * through a shared store (Redis Streams, Postgres LISTEN/NOTIFY, etc.).
+ *
+ * Memory shape: `Map<channel, RingBuffer<BufferedMessage>>`. Bounded by
+ * `maxPerChannel` (default 100) so a chatty channel can't OOM the
+ * server. Entries past `ttlMs` are evicted lazily on read — apps that
+ * want eager eviction can call `pruneExpired()` from their own timer.
+ */
+
+export interface ReplayBufferConfig {
+  /**
+   * Glob-ish channel-name patterns to buffer. `'*'` buffers every
+   * channel; `'orders.*'` buffers channels matching that prefix. The
+   * empty array (default) disables buffering for all channels.
+   */
+  channels?: string[]
+  /**
+   * Maximum messages retained per channel. Older entries are evicted
+   * FIFO. Default: 100.
+   */
+  maxPerChannel?: number
+  /**
+   * Max age (milliseconds) of any buffered message. Entries older
+   * than this are evicted lazily on read. Default: 5 minutes.
+   */
+  ttlMs?: number
+}
+
+export interface BufferedMessage {
+  /** Monotonic per-channel sequence id. Starts at 1. */
+  seq: number
+  /** Wall-clock timestamp when the message was recorded. */
+  ts: number
+  /** Event name from `server.broadcast(channel, event, data)`. */
+  event: string
+  /** Payload from the broadcast — opaque to the buffer. */
+  data: unknown
+}
+
+interface ChannelState {
+  /** Ring buffer of recent messages (head = oldest). */
+  messages: BufferedMessage[]
+  /** Next sequence id to assign. */
+  nextSeq: number
+}
+
+interface BufferRegistry {
+  channels: string[]
+  maxPerChannel: number
+  ttlMs: number
+  state: Map<string, ChannelState>
+}
+
+let registry: BufferRegistry | null = null
+
+/**
+ * Install (or replace) the replay-buffer config. Pass `null` to disable
+ * and drop all buffered state. Safe to call multiple times.
+ */
+export function setReplayBuffer(cfg: ReplayBufferConfig | null): void {
+  if (!cfg) {
+    registry = null
+    return
+  }
+  registry = {
+    channels: cfg.channels ?? [],
+    maxPerChannel: cfg.maxPerChannel ?? 100,
+    ttlMs: cfg.ttlMs ?? 5 * 60_000,
+    state: new Map(),
+  }
+}
+
+/** Read the current config — useful for tests. */
+export function getReplayBuffer(): Readonly<BufferRegistry> | null {
+  return registry
+}
+
+/**
+ * Returns true if the configured patterns cover `channel`. Pattern
+ * matching is glob-ish: `*` matches any channel; otherwise a literal
+ * prefix ending in `.*` (e.g. `orders.*`) matches any channel
+ * starting with that prefix.
+ */
+function shouldBuffer(channel: string): boolean {
+  if (!registry || registry.channels.length === 0) return false
+  for (const pattern of registry.channels) {
+    if (pattern === '*') return true
+    if (pattern === channel) return true
+    if (pattern.endsWith('.*') && channel.startsWith(pattern.slice(0, -1))) return true
+  }
+  return false
+}
+
+/**
+ * Called by the broadcast wrapper for every outbound message on a
+ * matched channel. Records the message and assigns a monotonic seq.
+ * Returns the seq for the caller to optionally include in the
+ * outbound payload — clients store the latest seq locally and send
+ * it back on reconnect via `replaySince`.
+ */
+export function recordBroadcast(channel: string, event: string, data: unknown): number | null {
+  if (!registry || !shouldBuffer(channel)) return null
+
+  let state = registry.state.get(channel)
+  if (!state) {
+    state = { messages: [], nextSeq: 1 }
+    registry.state.set(channel, state)
+  }
+
+  const msg: BufferedMessage = {
+    seq: state.nextSeq++,
+    ts: Date.now(),
+    event,
+    data,
+  }
+  state.messages.push(msg)
+
+  // FIFO eviction past the size cap. Splicing from the front is O(n)
+  // but maxPerChannel is bounded (default 100) so this stays cheap.
+  if (state.messages.length > registry.maxPerChannel)
+    state.messages.splice(0, state.messages.length - registry.maxPerChannel)
+
+  return msg.seq
+}
+
+/**
+ * Replay every buffered message on `channel` with `seq > sinceSeq`.
+ * Stale entries (older than `ttlMs`) are evicted on the way through
+ * so callers don't see them. Returns the array of messages the
+ * caller should re-send to the reconnecting client.
+ *
+ * @example
+ * ```ts
+ * // Inside the reconnect handler:
+ * const missed = replaySince('orders', lastSeenSeq)
+ * for (const msg of missed) {
+ *   socket.send(JSON.stringify({ event: msg.event, data: msg.data, seq: msg.seq }))
+ * }
+ * ```
+ */
+export function replaySince(channel: string, sinceSeq: number): BufferedMessage[] {
+  if (!registry) return []
+  const state = registry.state.get(channel)
+  if (!state) return []
+
+  const now = Date.now()
+  const ttl = registry.ttlMs
+  // Lazy TTL eviction — drop expired messages from the head.
+  while (state.messages.length > 0 && now - state.messages[0]!.ts > ttl)
+    state.messages.shift()
+
+  if (state.messages.length === 0) return []
+  // Binary-search would be marginally faster; linear is fine at
+  // maxPerChannel=100 and clearer for the buffer's volume.
+  return state.messages.filter(m => m.seq > sinceSeq)
+}
+
+/**
+ * Drop expired entries across every tracked channel. Called by apps
+ * that want eager memory reclaim — the default lazy-on-read path is
+ * adequate for most workloads.
+ */
+export function pruneExpired(): void {
+  if (!registry) return
+  const now = Date.now()
+  const ttl = registry.ttlMs
+  for (const state of registry.state.values()) {
+    while (state.messages.length > 0 && now - state.messages[0]!.ts > ttl)
+      state.messages.shift()
+  }
+}
+
+/**
+ * Snapshot the buffer state — debugging only. Don't depend on this
+ * shape in production code; the internals may change.
+ */
+export function debugSnapshot(): Record<string, { count: number, firstSeq: number | null, lastSeq: number | null }> {
+  const out: Record<string, { count: number, firstSeq: number | null, lastSeq: number | null }> = {}
+  if (!registry) return out
+  for (const [ch, state] of registry.state) {
+    out[ch] = {
+      count: state.messages.length,
+      firstSeq: state.messages[0]?.seq ?? null,
+      lastSeq: state.messages[state.messages.length - 1]?.seq ?? null,
+    }
+  }
+  return out
+}
+

package/src/server-instance.ts

@@ -0,0 +1,39 @@
+import type { BroadcastServer, ServerConfig } from 'ts-broadcasting'
+
+let serverInstance: BroadcastServer | null = null
+
+/**
+ * Set the global broadcast server instance
+ */
+export function setServer(server: BroadcastServer): void {
+  serverInstance = server
+}
+
+/**
+ * Get the global broadcast server instance
+ */
+export function getServer(): BroadcastServer | null {
+  return serverInstance
+}
+
+/**
+ * Create and start a new broadcast server
+ */
+export async function createServer(config: ServerConfig): Promise<BroadcastServer> {
+  const broadcasting = await import('ts-broadcasting')
+  const Server = (broadcasting as any).BroadcastServer
+  const server = new Server(config)
+  await server.start()
+  setServer(server)
+  return server
+}
+
+/**
+ * Stop the current broadcast server
+ */
+export async function stopServer(): Promise<void> {
+  if (serverInstance) {
+    await serverInstance.stop()
+    serverInstance = null
+  }
+}

package/src/ws.ts

@@ -0,0 +1,110 @@
+import type { Server } from 'bun'
+import type { BroadcastServer } from 'ts-broadcasting'
+import { getServer, setServer } from './server-instance'
+
+/**
+ * Set the broadcast server instance
+ * @deprecated Use setServer from './server-instance' instead
+ */
+export function setBunSocket(server: BroadcastServer | null): void {
+  if (server) {
+    setServer(server)
+  }
+}
+
+/**
+ * Store WebSocket event in the database
+ * Note: This function is now a no-op. WebSocket events are tracked internally by ts-broadcasting.
+ */
+export async function storeWebSocketEvent(
+  _type: 'disconnection' | 'error' | 'success',
+  _socket: string,
+  _details: string,
+): Promise<void> {
+  // WebSocket events are tracked internally by ts-broadcasting's monitoring system
+  // This function is kept for backward compatibility
+}
+
+/**
+ * Optional authenticator invoked at WebSocket handshake time.
+ *
+ * Apps install one via `setWsAuthenticator(fn)` to require a valid
+ * token / cookie / signed query param BEFORE the upgrade goes through
+ * (stacksjs/stacks#1877 R-1). Without an authenticator, the upgrade
+ * proceeds as before — useful for local-dev / public-broadcast apps,
+ * but production apps should always install one.
+ *
+ * The returned `data` is attached to the upgraded socket as `ws.data`
+ * so per-message authorization can read it back without re-parsing
+ * the auth token on every frame.
+ */
+export type WsAuthenticator = (req: Request) => Promise<WsAuthResult> | WsAuthResult
+
+/** Result returned from a `WsAuthenticator`. */
+export type WsAuthResult =
+  | { ok: true, data?: Record<string, unknown> }
+  | { ok: false, status?: number, message?: string }
+
+let wsAuthenticator: WsAuthenticator | null = null
+
+/**
+ * Install (or clear) the global WebSocket authenticator. Called once
+ * at server boot; pass `null` to disable auth (the unauthed default).
+ */
+export function setWsAuthenticator(fn: WsAuthenticator | null): void {
+  wsAuthenticator = fn
+}
+
+/** Read the currently-installed authenticator. Useful for tests. */
+export function getWsAuthenticator(): WsAuthenticator | null {
+  return wsAuthenticator
+}
+
+/**
+ * Handle WebSocket request upgrade. If an authenticator is installed
+ * (see `setWsAuthenticator`), it runs FIRST and a 401 is returned on
+ * failure (stacksjs/stacks#1877 R-1). Without an authenticator the
+ * upgrade proceeds for backwards-compat — the function still works
+ * the same way it did before.
+ */
+export async function handleWebSocketRequest(req: Request, server: Server<any>): Promise<Response | undefined> {
+  const broadcastServer = getServer()
+
+  if (!broadcastServer) {
+    return new Response('WebSocket server not initialized', { status: 500 })
+  }
+
+  // Authentication at the upgrade boundary, BEFORE the socket is
+  // established. Without this, ts-broadcasting's per-channel auth
+  // ran only after the connection was open — meaning an attacker
+  // could establish a socket, subscribe to public channels, and
+  // burn server resources without ever presenting a credential.
+  if (wsAuthenticator) {
+    try {
+      const result = await wsAuthenticator(req)
+      if (!result.ok) {
+        return new Response(
+          result.message ?? 'Unauthorized',
+          { status: result.status ?? 401 },
+        )
+      }
+      // Pass the auth data through to the upgraded socket so
+      // downstream handlers (channel auth callbacks, presence
+      // tracking) can read it via `ws.data` without re-parsing.
+      const upgraded = server.upgrade(req, result.data ? { data: result.data } : undefined)
+      if (upgraded) return undefined
+      return new Response('WebSocket upgrade failed', { status: 400 })
+    }
+    catch (err) {
+      // Don't expose internals to the client — log and 500.
+      // eslint-disable-next-line no-console
+      console.error('[realtime] WebSocket authenticator threw:', err)
+      return new Response('WebSocket auth error', { status: 500 })
+    }
+  }
+
+  // No authenticator installed — preserve the original behavior.
+  const success = server.upgrade(req)
+  if (success) return undefined
+  return new Response('WebSocket upgrade failed', { status: 400 })
+}