@stacksjs/realtime 0.75.72 → 0.75.74

package/dist/broadcast.d.ts

@@ -1,12 +1,4 @@
 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
  *
@@ -21,24 +13,6 @@ export declare function runBroadcast(name: string, payload?: any): Promise<void>
  * 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[]

package/dist/broadcast.js

@@ -1 +1 @@
-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}' - 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=[...new bun.Glob("Broadcasts/**/*.ts").scanSync({cwd:appPath(),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)}
+import{log}from"@stacksjs/logging";import{getServer}from"./server-instance";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}`;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=[...new bun.Glob("Broadcasts/**/*.ts").scanSync({cwd:appPath(),absolute:!0})]}catch(error){throw Error(`Failed to scan broadcast files: ${error instanceof Error?error.message:String(error)}`)}const root=appPath("Broadcasts"),nameOf=(file)=>file.slice(root.length+1,-3).split("\\").join("/"),exact=broadcastFiles.filter((file)=>nameOf(file)===name),byBasename=name.includes("/")?[]:broadcastFiles.filter((file)=>nameOf(file).split("/").pop()===name),candidates=exact.length>0?exact:byBasename;if(candidates.length>1)throw Error(`Broadcast ${name} is ambiguous: ${candidates.map(nameOf).join(", ")}. Name it by its path under app/Broadcasts.`);const broadcastFile=candidates[0];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/emit.d.ts

@@ -11,8 +11,8 @@
  * // 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' })
+ * // Leave out the sender's socket (its socket ID, from the request)
+ * emit('chat.room.1', 'message', { text: 'Hello' }, { exclude: request.header('X-Socket-ID') })
  */
 export declare function emit<T = unknown>(channel: string, event: string, data?: T, options?: EmitOptions): void;
 /**

package/dist/emit.js

@@ -1 +1 @@
-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)}
+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}`}server.broadcast(channelName,event,data,options?.exclude)}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/index.d.ts

@@ -1,7 +1,5 @@
 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';
 /**
@@ -20,18 +18,16 @@ export { getServer, setServer, createServer, stopServer } from './server-instanc
 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';
+// Dead-socket detection and slow-consumer handling are the broadcast
+// server's own: pass `websocket: { idleTimeout, sendPings,
+// backpressureLimit, closeOnBackpressureLimit }` to `createServer()`.
 // 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.
+// Opt-in via setReplayBuffer. Every broadcast on a buffered channel is
+// recorded and carries a top-level `seq`; apps wire `replaySince(channel,
+// seq)` into their reconnect handling to re-send missed messages.
 export { debugSnapshot, getReplayBuffer, pruneExpired, recordBroadcast, replaySince, setReplayBuffer } from './replay-buffer';
-export { 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 { storeWebSocketEvent } from './ws';
+// WebSocket authenticator (stacksjs/stacks#1877 R-1). Gates every upgrade
+// on the server `createServer()` starts; without one, upgrades proceed
+// unauthed.
 export { setWsAuthenticator, getWsAuthenticator } from './ws';

package/dist/index.js

@@ -1 +1 @@
-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{handleWebSocketRequest,storeWebSocketEvent}from"./ws";export{setWsAuthenticator,getWsAuthenticator}from"./ws";
+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{debugSnapshot,getReplayBuffer,pruneExpired,recordBroadcast,replaySince,setReplayBuffer}from"./replay-buffer";export{storeWebSocketEvent}from"./ws";export{setWsAuthenticator,getWsAuthenticator}from"./ws";

package/dist/replay-buffer.d.ts

@@ -6,26 +6,26 @@ 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`.
+ * Called for every outbound broadcast by the hook `setServer()`
+ * installs. Records the message under its full channel name (the one
+ * clients subscribe to) and assigns a monotonic seq, which the hook
+ * stamps onto the outbound frame as `seq`. Returns null for a channel
+ * no pattern covers.
  */
 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.
+ * Replay every buffered message on `channel` (the full name, e.g.
+ * `private-orders.1`) 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 }))
- * }
+ * // The client kept `message.seq` from the last frame it received on
+ * // the channel and sends it back after reconnecting, e.g. to a route:
+ * const missed = replaySince('private-orders.1', lastSeenSeq)
+ * return missed.map(msg => ({ event: msg.event, channel: 'private-orders.1', data: msg.data, seq: msg.seq }))
  * ```
  */
 export declare function replaySince(channel: string, sinceSeq: number): BufferedMessage[];
@@ -49,11 +49,17 @@ export declare function debugSnapshot(): Record<string, { count: number, firstSe
  * 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.).
+ * messages with monotonic sequence IDs. Every broadcast on a buffered
+ * channel - whichever API sent it - is recorded through the hook
+ * `setServer()` installs on the server, and reaches clients with its
+ * sequence number as a top-level field: `{ event, channel, data, seq }`.
+ * A client keeps the last `seq` it saw per channel; on reconnect it
+ * sends that back (through a route or action of the app's), and the app
+ * re-sends `replaySince(channel, seq)`. Apps install via
+ * `setReplayBuffer({ channels, maxPerChannel, ttlMs })`. Buffer is
+ * in-process, and so are the sequence numbers - with several instances
+ * behind Redis each numbers its own copy, so route replay through a
+ * shared store (Redis Streams, Postgres LISTEN/NOTIFY, etc.) there.
  *
  * Memory shape: `Map<channel, RingBuffer<BufferedMessage>>`. Bounded by
  * `maxPerChannel` (default 100) so a chatty channel can't OOM the

package/dist/replay-buffer.js

@@ -1 +1 @@
-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}
+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 matches(pattern,channel){if(pattern==="*"||pattern===channel)return!0;return pattern.endsWith(".*")&&channel.startsWith(pattern.slice(0,-1))}function shouldBuffer(channel){if(!registry||registry.channels.length===0)return!1;const bare=channel.replace(/^(?:private|presence)-/,"");return registry.channels.some((pattern)=>matches(pattern,channel)||matches(pattern,bare))}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

@@ -1,6 +1,20 @@
 import type { BroadcastServer, ServerConfig } from 'ts-broadcasting';
 /**
- * Set the global broadcast server instance
+ * Set the global broadcast server instance.
+ *
+ * ts-broadcasting's own facade is pointed at it too. `@stacksjs/realtime`
+ * re-exports ts-broadcasting, so `broadcast()`, `broadcastToUser()` and
+ * `Broadcast.send()` from this package are ts-broadcasting's, and they read
+ * the server from `Broadcast.setServer()`, which nothing called. Every one of
+ * them threw "Broadcast server not initialized" against a running server -
+ * including the ORM, which broadcasts model events through `broadcast()` and
+ * logs that error, so no model event ever reached a socket.
+ *
+ * The replay buffer is installed on the server as a broadcast hook, so
+ * every broadcast - `emit()`, `channel()`, `runBroadcast()`, the facade, the
+ * legacy `Broadcast` class - is recorded and carries its sequence number to
+ * clients as a top-level `seq` field. Recording used to happen only in the
+ * legacy class, and the number never left the server.
  */
 export declare function setServer(server: BroadcastServer | null): void;
 /**
@@ -8,7 +22,13 @@ export declare function setServer(server: BroadcastServer | null): void;
  */
 export declare function getServer(): BroadcastServer | null;
 /**
- * Create and start a new broadcast server
+ * Create and start a new broadcast server.
+ *
+ * This is the WebSocket endpoint Stacks apps serve (`/app` and `/ws` on the
+ * configured host/port), and the authenticator installed with
+ * `setWsAuthenticator()` now gates it: it used to be consulted only by
+ * `handleWebSocketRequest()`, which nothing called, while this server
+ * upgraded every request it got.
  */
 export declare function createServer(config: ServerConfig): Promise<BroadcastServer>;
 /**

package/dist/server-instance.js

@@ -1 +1 @@
-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}}
+import{Broadcast}from"ts-broadcasting";import{recordBroadcast}from"./replay-buffer";import{getWsAuthenticator}from"./ws";let serverInstance=null,removeReplayHook=null;export function setServer(server){removeReplayHook?.();removeReplayHook=null;serverInstance=server;Broadcast.setServer(server);if(server)removeReplayHook=server.addBroadcastHook(({channel,event,data})=>{const seq=recordBroadcast(channel,event,data);return seq===null?void 0:{seq}})}export function getServer(){return serverInstance}function stacksConnectionAuthorizer(config){return async(req,user)=>{let accepted={};const authenticate=getWsAuthenticator();if(authenticate){const result=await authenticate(req);if(!result.ok)return{ok:!1,status:result.status,message:result.message};accepted={user:result.user,data:result.data}}const resolvedUser=accepted.user!==void 0?accepted.user:user;if(config.authorizeConnection){const result=await config.authorizeConnection(req,resolvedUser);if(result===!0)return{ok:!0,user:resolvedUser,data:accepted.data};return result}return{ok:!0,user:resolvedUser,data:accepted.data}}}export async function createServer(config){const server=new(await import("ts-broadcasting")).BroadcastServer({...config,authorizeConnection:stacksConnectionAuthorizer(config)});await server.start();setServer(server);return server}export async function stopServer(){if(serverInstance){await serverInstance.stop();setServer(null)}}

package/dist/ws.d.ts

@@ -1,38 +1,38 @@
-import type { Server } from 'bun';
+import type { User } from 'ts-broadcasting';
 /**
  * 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).
+ * Install (or clear) the global WebSocket authenticator. Pass `null`
+ * to disable auth (the unauthed default). A refusal answers the
+ * upgrade with `status` (default 401) and `message` (default
+ * 'Unauthorized'); an authenticator that throws refuses it with a 500
+ * and the error is logged, never sent to the client.
  */
 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.
+ * (stacksjs/stacks#1877 R-1). It gates the broadcast server
+ * `createServer()` starts, and is read on every upgrade, so it applies
+ * whether it is installed before or after the server starts. Without
+ * one, every upgrade proceeds - fine for local dev or public-only
+ * broadcasting, but production apps should 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.
+ * On success, `user` becomes `socket.data.user` and `data` becomes
+ * `socket.data.data` on the upgraded socket, which is what channel
+ * authorization callbacks (`Broadcast.channel('private-orders.{id}',
+ * (socket, params) => ...)`) read. Channel authorization still decides
+ * who may join each private/presence channel; this decides who may
+ * connect at all.
  */
 export type WsAuthenticator = (req: Request) => Promise<WsAuthResult> | WsAuthResult;
 /** Result returned from a `WsAuthenticator`. */
-export type WsAuthResult = | { ok: true, data?: Record<string, unknown> }
+export type WsAuthResult = | { ok: true, user?: User, data?: Record<string, unknown> }
   | { ok: false, status?: number, message?: string }

package/dist/ws.js

@@ -1 +1 @@
-import{getServer}from"./server-instance";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})}
+export async function storeWebSocketEvent(_type,_socket,_details){}let wsAuthenticator=null;export function setWsAuthenticator(fn){wsAuthenticator=fn}export function getWsAuthenticator(){return wsAuthenticator}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/realtime",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.72",
+  "version": "0.75.74",
   "description": "The Stacks realtime integration. Built on top of ts-broadcasting.",
   "author": "Chris Breuer",
   "contributors": [
@@ -58,9 +58,9 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/logging": "0.75.72",
-    "@stacksjs/path": "0.75.72",
-    "ts-broadcasting": "^0.0.10"
+    "@stacksjs/logging": "0.75.74",
+    "@stacksjs/path": "0.75.74",
+    "ts-broadcasting": "^0.0.11"
   },
   "devDependencies": {
     "better-dx": "^0.2.24"

package/dist/heartbeat.d.ts

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

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