@stacksjs/realtime 0.70.55 → 0.70.56

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/realtime",
   "type": "module",
-  "version": "0.70.55",
+  "version": "0.70.56",
   "description": "The Stacks realtime integration. Built on top of ts-broadcasting.",
   "author": "Chris Breuer",
   "contributors": [
@@ -28,20 +28,23 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "bun": "./src/index.ts",
-      "import": "./dist/index.js"
+      "development": "./src/index.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./*": {
-      "bun": "./src/*",
-      "import": "./dist/*"
+      "development": "./src/*",
+      "bun": "./dist/*",
+      "import": "./dist/*",
+      "default": "./dist/*"
     }
   },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "README.md",
-    "dist",
-    "src"
+    "dist"
   ],
   "scripts": {
     "build": "bun build.ts",

package/src/broadcast.ts

@@ -1,303 +0,0 @@
-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

@@ -1,103 +0,0 @@
-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

@@ -1,95 +0,0 @@
-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

@@ -1,184 +0,0 @@
-/**
- * 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

@@ -1,43 +0,0 @@
-/**
- * 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

@@ -1,201 +0,0 @@
-/**
- * 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

@@ -1,39 +0,0 @@
-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

@@ -1,110 +0,0 @@
-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 })
-}