@stacksjs/realtime 0.70.88 → 0.70.91

package/dist/broadcast.d.ts

@@ -0,0 +1,62 @@
+import type { ChannelType } from 'ts-broadcasting';
+/**
+ * Install (or clear) the backpressure guard. Pass `null` to disable.
+ */
+export declare function setBackpressureGuard(cfg: BackpressureGuardConfig | null): void;
+/**
+ * Read the currently-installed guard config (useful for tests).
+ */
+export declare function getBackpressureGuard(): Required<BackpressureGuardConfig> | null;
+/**
+ * Run a broadcast from a broadcast file
+ *
+ * @example
+ * await runBroadcast('OrderCreated', { orderId: 123 })
+ */
+export declare function runBroadcast(name: string, payload?: any): Promise<void>;
+/**
+ * Alias for runBroadcast.
+ *
+ * @example
+ * await broadcast('OrderCreated', { orderId: 123 })
+ */
+export declare function broadcast(name: string, payload?: any): Promise<void>;
+/**
+ * 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 declare interface BackpressureGuardConfig {
+  maxPerSocketBytes?: number
+  onSlow?: (info: { channelName: string, backpressure: number, socket: unknown }) => void
+}
+export declare 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 declare class Broadcast {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  subscribe(channel: string, callback: (data: any) => void): void;
+  unsubscribe(channel: string): void;
+  broadcast(channel: string, event: string, data?: any, type?: ChannelType): void;
+  isConnected(): boolean;
+}

package/dist/broadcast.js

@@ -0,0 +1,124 @@
+import { log } from "@stacksjs/logging";
+import { recordBroadcast } from "./replay-buffer";
+import { getServer } from "./server-instance";
+let backpressureConfig = null;
+export function setBackpressureGuard(cfg) {
+  if (!cfg) {
+    backpressureConfig = null;
+    return;
+  }
+  backpressureConfig = {
+    maxPerSocketBytes: cfg.maxPerSocketBytes ?? 1048576,
+    onSlow: cfg.onSlow ?? ((info) => {
+      log.warn(`[realtime] slow consumer on '${info.channelName}': ${info.backpressure} bytes buffered`);
+    })
+  };
+}
+export function getBackpressureGuard() {
+  return backpressureConfig;
+}
+function checkBackpressure(server, channelName) {
+  if (!backpressureConfig)
+    return;
+  try {
+    const channels = server.channels ?? server.clients, 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) {
+      const ws = entry && typeof entry === "object" && "ws" in entry ? entry.ws : entry, bp = ws && typeof ws === "object" && "backpressure" in ws ? ws.backpressure : null;
+      if (typeof bp === "number" && bp > maxPerSocketBytes)
+        onSlow({ channelName, backpressure: bp, socket: ws });
+    }
+  } catch {}
+}
+function hasSubscribers(server, channelName) {
+  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), size = (set && (set.size ?? set.length)) ?? null;
+      if (typeof size === "number")
+        return size > 0;
+    }
+  } catch {}
+  return !0;
+}
+
+export class Broadcast {
+  async connect() {}
+  async disconnect() {}
+  subscribe(channel, callback) {
+    log.warn("Broadcast.subscribe() is a client-side operation. Use BroadcastClient instead.");
+  }
+  unsubscribe(channel) {
+    log.warn("Broadcast.unsubscribe() is a client-side operation. Use BroadcastClient instead.");
+  }
+  broadcast(channel, event, data, type = "public") {
+    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}' \u2014 no subscribers`);
+      return;
+    }
+    checkBackpressure(server, channelName);
+    recordBroadcast(channelName, event, data);
+    try {
+      server.broadcast(channelName, event, data);
+    } catch (err) {
+      log.error(`[Broadcast] Failed to broadcast event '${event}' to channel '${channelName}':`, err);
+    }
+  }
+  isConnected() {
+    return getServer() !== null;
+  }
+}
+export async function runBroadcast(name, payload) {
+  const { appPath } = await import("@stacksjs/path"), bun = await import("bun");
+  let broadcastFiles;
+  try {
+    broadcastFiles = bun.globSync([appPath("Broadcasts/**/*.ts")], { absolute: !0 });
+  } catch (error) {
+    throw Error(`Failed to scan broadcast files: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const broadcastFile = broadcastFiles.find((file) => file.endsWith(`${name}.ts`));
+  if (!broadcastFile)
+    throw Error(`Broadcast ${name} not found`);
+  let broadcastModule;
+  try {
+    broadcastModule = await import(broadcastFile);
+  } catch (error) {
+    throw Error(`Failed to import broadcast '${name}': ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const instance = broadcastModule.default;
+  if (instance.handle) {
+    await instance.handle(payload);
+    return;
+  }
+  const server = getServer();
+  if (!server)
+    throw Error("Broadcast server not initialized");
+  const channels = instance.broadcastOn?.() || instance.channel?.() || [], eventName = instance.broadcastAs?.() || instance.event?.() || name, data = instance.broadcastWith?.() || instance.data?.() || payload, event = {
+    shouldBroadcast: () => !0,
+    broadcastOn: () => channels,
+    broadcastAs: () => eventName,
+    broadcastWith: () => data
+  };
+  await server.broadcaster.broadcast(event);
+}
+export async function broadcast(name, payload) {
+  if (typeof name !== "string" || name.trim().length === 0)
+    throw Error("[realtime] broadcast() requires a non-empty event name");
+  await runBroadcast(name, payload);
+}

package/dist/channel.d.ts

@@ -0,0 +1,24 @@
+import type { ChannelType } from 'ts-broadcasting';
+/**
+ * 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 declare function channel(name: string): Channel;
+/**
+ * Stacks Channel class for backward compatibility
+ * Provides a fluent API for broadcasting to channels
+ */
+export declare class Channel {
+  constructor(channel: string);
+  presence(event: string, data?: any): Promise<void>;
+  broadcast(event: string, data?: any, type?: ChannelType): Promise<void>;
+}

package/dist/channel.js

@@ -0,0 +1,46 @@
+import { getServer } from "./server-instance";
+const KNOWN_CHANNEL_PREFIXES = ["private-", "presence-"];
+function stripPrefix(name) {
+  for (const p of KNOWN_CHANNEL_PREFIXES)
+    if (name.startsWith(p))
+      return name.slice(p.length);
+  return name;
+}
+
+export class Channel {
+  channelName;
+  constructor(channel) {
+    this.channelName = channel;
+  }
+  async private(event, data) {
+    const server = getServer();
+    if (!server)
+      throw Error("Broadcast server not initialized");
+    await server.broadcast(`private-${stripPrefix(this.channelName)}`, event, data);
+  }
+  async public(event, data) {
+    const server = getServer();
+    if (!server)
+      throw Error("Broadcast server not initialized");
+    await server.broadcast(stripPrefix(this.channelName), event, data);
+  }
+  async presence(event, data) {
+    const server = getServer();
+    if (!server)
+      throw Error("Broadcast server not initialized");
+    await server.broadcast(`presence-${stripPrefix(this.channelName)}`, event, data);
+  }
+  async broadcast(event, data, type = "public") {
+    switch (type) {
+      case "private":
+        return this.private(event, data);
+      case "presence":
+        return this.presence(event, data);
+      default:
+        return this.public(event, data);
+    }
+  }
+}
+export function channel(name) {
+  return new Channel(name);
+}

package/dist/emit.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare function emit<T = unknown>(channel: string, event: string, data?: T, options?: EmitOptions): void;
+/**
+ * Emit an event to a specific user
+ *
+ * @example
+ * emitToUser('user-123', 'notification', { message: 'You have a new order!' })
+ */
+export declare function emitToUser<T = unknown>(userId: string | number, event: string, data?: T, options?: Omit<EmitOptions, 'private'>): void;
+/**
+ * Emit an event to multiple users
+ *
+ * @example
+ * emitToUsers(['user-1', 'user-2'], 'announcement', { message: 'Server maintenance!' })
+ */
+export declare function emitToUsers<T = unknown>(userIds: (string | number)[], event: string, data?: T, options?: Omit<EmitOptions, 'private'>): void;
+export declare interface EmitOptions {
+  private?: boolean
+  presence?: boolean
+  exclude?: string | string[]
+  driver?: string
+}

package/dist/emit.js

@@ -0,0 +1,25 @@
+import { getServer } from "./server-instance";
+export function emit(channel, event, data, options) {
+  const server = getServer();
+  if (!server) {
+    console.warn("[realtime] Server not initialized, cannot emit event");
+    return;
+  }
+  let channelName = channel;
+  if (options?.presence) {
+    if (!channel.startsWith("presence-"))
+      channelName = `presence-${channel}`;
+  } else if (options?.private) {
+    if (!channel.startsWith("private-"))
+      channelName = `private-${channel}`;
+  }
+  const excludeSocketId = options?.exclude ? Array.isArray(options.exclude) ? options.exclude[0] : options.exclude : void 0;
+  server.broadcast(channelName, event, data, excludeSocketId);
+}
+export function emitToUser(userId, event, data, options) {
+  emit(`private-user.${userId}`, event, data, { ...options, private: !0 });
+}
+export function emitToUsers(userIds, event, data, options) {
+  for (const userId of userIds)
+    emitToUser(userId, event, data, options);
+}

package/dist/heartbeat.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare function setHeartbeatConfig(cfg: HeartbeatConfig | null): void;
+/** Read the current config — useful for tests. */
+export declare function getHeartbeatConfig(): Readonly<HeartbeatState> | null;
+/**
+ * Manually fire a single heartbeat tick. Exposed for tests; in
+ * production it's invoked by the internal interval.
+ */
+export declare function runOneTick(): void;
+/**
+ * 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 declare function markPong(socket: object): void;
+export declare interface HeartbeatConfig {
+  intervalMs?: number
+  maxMissedPongs?: number
+  onDead?: (socket: unknown) => void
+}
+declare interface HeartbeatState {
+  intervalMs: number
+  maxMissedPongs: number
+  onDead: (socket: unknown) => void
+  missed: WeakMap<object, number>
+  timer: ReturnType<typeof setInterval> | null
+}

package/dist/heartbeat.js

@@ -0,0 +1,84 @@
+import { log } from "@stacksjs/logging";
+import { getServer } from "./server-instance";
+let state = null;
+export function setHeartbeatConfig(cfg) {
+  if (state?.timer) {
+    clearInterval(state.timer);
+    state.timer = null;
+  }
+  if (!cfg) {
+    state = null;
+    return;
+  }
+  const intervalMs = cfg.intervalMs ?? 30000, maxMissedPongs = cfg.maxMissedPongs ?? 2, onDead = cfg.onDead ?? defaultOnDead;
+  state = {
+    intervalMs,
+    maxMissedPongs,
+    onDead,
+    missed: new WeakMap,
+    timer: null
+  };
+  state.timer = setInterval(() => {
+    if (!state)
+      return;
+    runOneTick();
+  }, intervalMs);
+  state.timer.unref?.();
+}
+export function getHeartbeatConfig() {
+  return state;
+}
+export function runOneTick() {
+  if (!state)
+    return;
+  const server = getServer();
+  if (!server)
+    return;
+  const allSockets = collectSockets(server);
+  for (const socket of allSockets) {
+    const ws = socket, missed = state.missed.get(socket) ?? 0;
+    if (missed >= state.maxMissedPongs) {
+      log.warn(`[realtime] socket missed ${missed} pongs \u2014 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);
+      continue;
+    }
+    state.missed.set(socket, missed + 1);
+    try {
+      if (typeof ws.ping === "function")
+        ws.ping();
+      else if (typeof ws.send === "function")
+        ws.send("__stacks_ping__");
+    } catch {}
+  }
+}
+export function markPong(socket) {
+  if (!state)
+    return;
+  state.missed.delete(socket);
+}
+function collectSockets(server) {
+  const out = new Set;
+  try {
+    const channels = server.channels ?? server.clients;
+    if (channels && typeof channels.values === "function") {
+      for (const set of channels.values())
+        if (set && typeof set[Symbol.iterator] === "function")
+          for (const entry of set) {
+            const ws = entry && typeof entry === "object" && "ws" in entry ? entry.ws : entry;
+            if (ws && typeof ws === "object")
+              out.add(ws);
+          }
+    }
+  } catch {}
+  return [...out];
+}
+function defaultOnDead(socket) {
+  const ws = socket;
+  if (typeof ws.close === "function")
+    ws.close(1011, "heartbeat timeout");
+}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+export type { EmitOptions } from './emit';
+export type { BroadcastInstance } from './broadcast';
+export type { BackpressureGuardConfig } from './broadcast';
+export type { HeartbeatConfig } from './heartbeat';
+export type { BufferedMessage, ReplayBufferConfig } from './replay-buffer';
+export type { WsAuthenticator, WsAuthResult } from './ws';
+/**
+ * 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 { channel, channel as createChannel, Channel as StacksChannel } from './channel';
+export { broadcast as dispatchBroadcast, runBroadcast, Broadcast as LegacyBroadcast } 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';
+// Heartbeat ping/pong for detecting half-closed sockets
+// (stacksjs/stacks#1877 R-5). Opt-in via setHeartbeatConfig.
+export { getHeartbeatConfig, markPong, runOneTick, setHeartbeatConfig } 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 { 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';

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "ts-broadcasting";
+export { getServer, setServer, createServer, stopServer } from "./server-instance";
+export { emit, emitToUser, emitToUsers } from "./emit";
+export { channel, channel as createChannel, Channel as StacksChannel } from "./channel";
+export { broadcast as dispatchBroadcast, runBroadcast, Broadcast as LegacyBroadcast } from "./broadcast";
+export { setBackpressureGuard, getBackpressureGuard } from "./broadcast";
+export { getHeartbeatConfig, markPong, runOneTick, setHeartbeatConfig } from "./heartbeat";
+export { debugSnapshot, getReplayBuffer, pruneExpired, recordBroadcast, replaySince, setReplayBuffer } from "./replay-buffer";
+export { setBunSocket, handleWebSocketRequest, storeWebSocketEvent } from "./ws";
+export { setWsAuthenticator, getWsAuthenticator } from "./ws";

package/dist/replay-buffer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Install (or replace) the replay-buffer config. Pass `null` to disable
+ * and drop all buffered state. Safe to call multiple times.
+ */
+export declare function setReplayBuffer(cfg: ReplayBufferConfig | null): void;
+/** Read the current config — useful for tests. */
+export declare function getReplayBuffer(): Readonly<BufferRegistry> | null;
+/**
+ * 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 declare function recordBroadcast(channel: string, event: string, data: unknown): number | null;
+/**
+ * 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 declare function replaySince(channel: string, sinceSeq: number): BufferedMessage[];
+/**
+ * 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 declare function pruneExpired(): void;
+/**
+ * Snapshot the buffer state — debugging only. Don't depend on this
+ * shape in production code; the internals may change.
+ */
+export declare function debugSnapshot(): Record<string, { count: number, firstSeq: number | null, lastSeq: number | null }>;
+/**
+ * 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 declare interface ReplayBufferConfig {
+  channels?: string[]
+  maxPerChannel?: number
+  ttlMs?: number
+}
+export declare interface BufferedMessage {
+  seq: number
+  ts: number
+  event: string
+  data: unknown
+}
+declare interface ChannelState {
+  messages: BufferedMessage[]
+  nextSeq: number
+}
+declare interface BufferRegistry {
+  channels: string[]
+  maxPerChannel: number
+  ttlMs: number
+  state: Map<string, ChannelState>
+}

package/dist/replay-buffer.js

@@ -0,0 +1,81 @@
+let registry = null;
+export function setReplayBuffer(cfg) {
+  if (!cfg) {
+    registry = null;
+    return;
+  }
+  registry = {
+    channels: cfg.channels ?? [],
+    maxPerChannel: cfg.maxPerChannel ?? 100,
+    ttlMs: cfg.ttlMs ?? 300000,
+    state: new Map
+  };
+}
+export function getReplayBuffer() {
+  return registry;
+}
+function shouldBuffer(channel) {
+  if (!registry || registry.channels.length === 0)
+    return !1;
+  for (const pattern of registry.channels) {
+    if (pattern === "*")
+      return !0;
+    if (pattern === channel)
+      return !0;
+    if (pattern.endsWith(".*") && channel.startsWith(pattern.slice(0, -1)))
+      return !0;
+  }
+  return !1;
+}
+export function recordBroadcast(channel, event, data) {
+  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 = {
+    seq: state.nextSeq++,
+    ts: Date.now(),
+    event,
+    data
+  };
+  state.messages.push(msg);
+  if (state.messages.length > registry.maxPerChannel)
+    state.messages.splice(0, state.messages.length - registry.maxPerChannel);
+  return msg.seq;
+}
+export function replaySince(channel, sinceSeq) {
+  if (!registry)
+    return [];
+  const state = registry.state.get(channel);
+  if (!state)
+    return [];
+  const now = Date.now(), ttl = registry.ttlMs;
+  while (state.messages.length > 0 && now - state.messages[0].ts > ttl)
+    state.messages.shift();
+  if (state.messages.length === 0)
+    return [];
+  return state.messages.filter((m) => m.seq > sinceSeq);
+}
+export function pruneExpired() {
+  if (!registry)
+    return;
+  const now = Date.now(), ttl = registry.ttlMs;
+  for (const state of registry.state.values())
+    while (state.messages.length > 0 && now - state.messages[0].ts > ttl)
+      state.messages.shift();
+}
+export function debugSnapshot() {
+  const out = {};
+  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/dist/server-instance.d.ts

@@ -0,0 +1,17 @@
+import type { BroadcastServer, ServerConfig } from 'ts-broadcasting';
+/**
+ * Set the global broadcast server instance
+ */
+export declare function setServer(server: BroadcastServer): void;
+/**
+ * Get the global broadcast server instance
+ */
+export declare function getServer(): BroadcastServer | null;
+/**
+ * Create and start a new broadcast server
+ */
+export declare function createServer(config: ServerConfig): Promise<BroadcastServer>;
+/**
+ * Stop the current broadcast server
+ */
+export declare function stopServer(): Promise<void>;

package/dist/server-instance.js

@@ -0,0 +1,19 @@
+let serverInstance = null;
+export function setServer(server) {
+  serverInstance = server;
+}
+export function getServer() {
+  return serverInstance;
+}
+export async function createServer(config) {
+  const server = new (await import("ts-broadcasting")).BroadcastServer(config);
+  await server.start();
+  setServer(server);
+  return server;
+}
+export async function stopServer() {
+  if (serverInstance) {
+    await serverInstance.stop();
+    serverInstance = null;
+  }
+}

package/dist/ws.d.ts

@@ -0,0 +1,44 @@
+import type { Server } from 'bun';
+import type { BroadcastServer } from 'ts-broadcasting';
+/**
+ * Set the broadcast server instance
+ * @deprecated Use setServer from './server-instance' instead
+ */
+export declare function setBunSocket(server: BroadcastServer | null): void;
+/**
+ * Store WebSocket event in the database
+ * Note: This function is now a no-op. WebSocket events are tracked internally by ts-broadcasting.
+ */
+export declare function storeWebSocketEvent(_type: 'disconnection' | 'error' | 'success', _socket: string, _details: string): Promise<void>;
+/**
+ * Install (or clear) the global WebSocket authenticator. Called once
+ * at server boot; pass `null` to disable auth (the unauthed default).
+ */
+export declare function setWsAuthenticator(fn: WsAuthenticator | null): void;
+/** Read the currently-installed authenticator. Useful for tests. */
+export declare function getWsAuthenticator(): WsAuthenticator | null;
+/**
+ * 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 declare function handleWebSocketRequest(req: Request, server: Server<any>): Promise<Response | undefined>;
+/**
+ * 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 }

package/dist/ws.js

@@ -0,0 +1,32 @@
+import { getServer, setServer } from "./server-instance";
+export function setBunSocket(server) {
+  if (server)
+    setServer(server);
+}
+export async function storeWebSocketEvent(_type, _socket, _details) {}
+let wsAuthenticator = null;
+export function setWsAuthenticator(fn) {
+  wsAuthenticator = fn;
+}
+export function getWsAuthenticator() {
+  return wsAuthenticator;
+}
+export async function handleWebSocketRequest(req, server) {
+  if (!getServer())
+    return new Response("WebSocket server not initialized", { status: 500 });
+  if (wsAuthenticator)
+    try {
+      const result = await wsAuthenticator(req);
+      if (!result.ok)
+        return new Response(result.message ?? "Unauthorized", { status: result.status ?? 401 });
+      if (server.upgrade(req, result.data ? { data: result.data } : void 0))
+        return;
+      return new Response("WebSocket upgrade failed", { status: 400 });
+    } catch (err) {
+      console.error("[realtime] WebSocket authenticator threw:", err);
+      return new Response("WebSocket auth error", { status: 500 });
+    }
+  if (server.upgrade(req))
+    return;
+  return new Response("WebSocket upgrade failed", { status: 400 });
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/realtime",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.88",
+  "version": "0.70.91",
   "description": "The Stacks realtime integration. Built on top of ts-broadcasting.",
   "author": "Chris Breuer",
   "contributors": [