@gwakko/shared-websocket 0.13.0 → 0.14.5

package/src/SubscriptionManager.ts

@@ -16,9 +16,9 @@ export class SubscriptionManager implements Disposable {
   }
 
   once(event: string, handler: EventHandler): Unsubscribe {
-    const wrapper: EventHandler = (data) => {
+    const wrapper: EventHandler = (data, raw) => {
       unsub();
-      handler(data);
+      handler(data, raw);
     };
     const unsub = this.on(event, wrapper);
     return unsub;
@@ -32,11 +32,11 @@ export class SubscriptionManager implements Disposable {
     }
   }
 
-  emit(event: string, data: unknown): void {
+  emit(event: string, data: unknown, raw?: unknown): void {
     this.lastMessages.set(event, data);
     const set = this.handlers.get(event);
     if (set) {
-      for (const fn of set) fn(data);
+      for (const fn of set) fn(data, raw);
     }
   }
 

package/src/WorkerSocket.ts

@@ -31,6 +31,7 @@ export class WorkerSocket implements Disposable {
       reconnect?: boolean;
       reconnectMaxDelay?: number;
       reconnectMaxRetries?: number;
+      authFailureCloseCodes?: number[];
       heartbeatInterval?: number;
       sendBuffer?: number;
       workerUrl?: string | URL;
@@ -45,11 +46,27 @@ export class WorkerSocket implements Disposable {
     return this._state;
   }
 
+  private setState(s: SocketState): void {
+    this._state = s;
+    for (const fn of this.onStateChangeFns) fn(s);
+  }
+
   async connect(): Promise<void> {
     // Resolve auth token before sending to worker (functions can't cross worker boundary)
     let authToken: string | undefined;
     if (this.options.auth) {
-      authToken = await this.options.auth();
+      try {
+        authToken = await this.options.auth();
+      } catch {
+        // auth() threw — pause reconnect until user provides fresh creds.
+        this.setState('failed');
+        return;
+      }
+      if (!authToken) {
+        // Configured auth callback returned nothing — same fail-closed behavior.
+        this.setState('failed');
+        return;
+      }
     } else if (this.options.authToken) {
       authToken = this.options.authToken;
     }
@@ -95,6 +112,7 @@ export class WorkerSocket implements Disposable {
       reconnect: this.options.reconnect ?? true,
       reconnectMaxDelay: this.options.reconnectMaxDelay ?? 30_000,
       reconnectMaxRetries: this.options.reconnectMaxRetries ?? Infinity,
+      authFailureCloseCodes: this.options.authFailureCloseCodes ?? [1008],
       heartbeatInterval: this.options.heartbeatInterval ?? 30_000,
       bufferSize: this.options.sendBuffer ?? 100,
       pingPayload: this.options.pingPayload,
@@ -145,6 +163,7 @@ export class WorkerSocket implements Disposable {
       let heartbeatTimer = null, reconnectTimer = null;
       let url = '', protocols = [], shouldReconnect = true;
       let maxDelay = 30000, maxRetries = Infinity, hbInterval = 30000, maxBuf = 100;
+      let authFailCodes = new Set([1008]);
       let delay = 1000, attempts = 0, pingPayload = '{"type":"ping"}';
 
       function setState(s) { state = s; self.postMessage({ type: 'state', state: s }); }
@@ -154,7 +173,12 @@ export class WorkerSocket implements Disposable {
         ws = new WebSocket(url, protocols);
         ws.onopen = () => { attempts = 0; delay = 1000; setState('connected'); self.postMessage({ type: 'open' }); flush(); startHB(); };
         ws.onmessage = (e) => { let d; try { d = JSON.parse(e.data); } catch { d = e.data; } self.postMessage({ type: 'message', data: d }); };
-        ws.onclose = (e) => { stopHB(); self.postMessage({ type: 'close', code: e.code, reason: e.reason }); if (!disposed && shouldReconnect && e.code !== 1000) reconnect(); else setState('closed'); };
+        ws.onclose = (e) => {
+          stopHB();
+          self.postMessage({ type: 'close', code: e.code, reason: e.reason });
+          if (authFailCodes.has(e.code)) { setState('failed'); return; }
+          if (!disposed && shouldReconnect && e.code !== 1000) reconnect(); else setState('closed');
+        };
         ws.onerror = () => { self.postMessage({ type: 'error', message: 'error' }); };
       }
       function send(d) { if (state === 'connected' && ws?.readyState === 1) ws.send(JSON.stringify(d)); else if (buffer.length < maxBuf) buffer.push(d); }
@@ -178,7 +202,7 @@ export class WorkerSocket implements Disposable {
       }
       self.onmessage = (e) => {
         const c = e.data;
-        if (c.type === 'connect') { url = c.url; protocols = c.protocols || []; shouldReconnect = c.reconnect ?? true; maxDelay = c.reconnectMaxDelay || 30000; maxRetries = c.reconnectMaxRetries ?? Infinity; hbInterval = c.heartbeatInterval || 30000; maxBuf = c.bufferSize || 100; if (c.pingPayload) pingPayload = JSON.stringify(c.pingPayload); connect(); }
+        if (c.type === 'connect') { url = c.url; protocols = c.protocols || []; shouldReconnect = c.reconnect ?? true; maxDelay = c.reconnectMaxDelay || 30000; maxRetries = c.reconnectMaxRetries ?? Infinity; if (c.authFailureCloseCodes) authFailCodes = new Set(c.authFailureCloseCodes); hbInterval = c.heartbeatInterval || 30000; maxBuf = c.bufferSize || 100; if (c.pingPayload) pingPayload = JSON.stringify(c.pingPayload); connect(); }
         if (c.type === 'send') send(c.data);
         if (c.type === 'reconnect') manualReconnect();
         if (c.type === 'disconnect') { disposed = true; stopHB(); if (reconnectTimer) clearTimeout(reconnectTimer); if (ws) { ws.onclose = null; if (ws.readyState < 2) ws.close(1000); ws = null; } buffer = []; setState('closed'); }

package/src/adapters/react.ts

@@ -149,13 +149,13 @@ export function useSocketAuth(): {
  *   setOrders(prev => [order, ...prev].slice(0, 50)); // keep last 50
  * });
  */
-export function useSocketEvent<T>(event: string, callback?: (data: T) => void): T | undefined {
+export function useSocketEvent<T>(event: string, callback?: (data: T, raw?: unknown) => void): T | undefined {
   const socket = useSharedWebSocket();
   const [value, setValue] = useState<T | undefined>(undefined);
 
-  const onEvent = useEffectEvent((data: T) => {
+  const onEvent = useEffectEvent((data: T, raw?: unknown) => {
     if (callback) {
-      callback(data);
+      callback(data, raw);
     } else {
       setValue(data);
     }
@@ -192,13 +192,13 @@ export function useSocketEvent<T>(event: string, callback?: (data: T) => void):
  *   if (entry.level === 'error') setErrors(prev => [...prev, entry]);
  * });
  */
-export function useSocketStream<T>(event: string, callback?: (data: T) => void): T[] {
+export function useSocketStream<T>(event: string, callback?: (data: T, raw?: unknown) => void): T[] {
   const socket = useSharedWebSocket();
   const [items, setItems] = useState<T[]>([]);
 
-  const onEvent = useEffectEvent((data: T) => {
+  const onEvent = useEffectEvent((data: T, raw?: unknown) => {
     if (callback) {
-      callback(data);
+      callback(data, raw);
     } else {
       setItems((prev) => [...prev, data]);
     }
@@ -276,11 +276,11 @@ export function useSocketSync<T>(
  *   }
  * });
  */
-export function useSocketCallback<T>(event: string, callback: (data: T) => void): void {
+export function useSocketCallback<T>(event: string, callback: (data: T, raw?: unknown) => void): void {
   const socket = useSharedWebSocket();
 
-  const handler = useEffectEvent((data: T) => {
-    callback(data);
+  const handler = useEffectEvent((data: T, raw?: unknown) => {
+    callback(data, raw);
   });
 
   useEffect(() => {

package/src/adapters/vue.ts

@@ -110,14 +110,14 @@ export function useSocketAuth(): {
  *   analytics.track('order_received', order);
  * });
  */
-export function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined> {
+export function useSocketEvent<T>(event: string, callback?: (data: T, raw?: unknown) => void): Ref<T | undefined> {
   const socket = useSharedWebSocket();
   const value = ref<T | undefined>(undefined) as Ref<T | undefined>;
 
-  const handler = (data: unknown) => {
+  const handler = (data: unknown, raw?: unknown) => {
     const typed = data as T;
     if (callback) {
-      callback(typed);
+      callback(typed, raw);
     } else {
       value.value = typed;
     }
@@ -151,14 +151,14 @@ export function useSocketEvent<T>(event: string, callback?: (data: T) => void):
  *   if (entry.level === 'error') errors.value = [...errors.value, entry];
  * });
  */
-export function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {
+export function useSocketStream<T>(event: string, callback?: (data: T, raw?: unknown) => void): Ref<T[]> {
   const socket = useSharedWebSocket();
   const items = ref<T[]>([]) as Ref<T[]>;
 
-  const handler = (data: unknown) => {
+  const handler = (data: unknown, raw?: unknown) => {
     const typed = data as T;
     if (callback) {
-      callback(typed);
+      callback(typed, raw);
     } else {
       items.value = [...items.value, typed];
     }
@@ -215,11 +215,11 @@ export function useSocketSync<T>(key: string, initialValue: T, callback?: (value
  *   showToast(n.title);
  * });
  */
-export function useSocketCallback<T>(event: string, callback: (data: T) => void): void {
+export function useSocketCallback<T>(event: string, callback: (data: T, raw?: unknown) => void): void {
   const socket = useSharedWebSocket();
 
-  const unsub = socket.on(event, (data: unknown) => {
-    callback(data as T);
+  const unsub = socket.on(event, (data: unknown, raw?: unknown) => {
+    callback(data as T, raw);
   });
 
   onUnmounted(unsub);

package/src/index.ts

@@ -29,4 +29,7 @@ export type {
   Middleware,
   PushNotificationOptions,
   Codec,
+  FrameKind,
+  FramePayload,
+  ChannelAckResult,
 } from './types';

package/src/types.ts

@@ -1,7 +1,12 @@
 export type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'failed';
 export type TabRole = 'leader' | 'follower';
 export type Unsubscribe = () => void;
-export type EventHandler<T = unknown> = (data: T) => void;
+/**
+ * Event handler. Receives the extracted `data` (per `dataField`) plus the
+ * full raw envelope as a second argument. Use `raw` to access top-level
+ * fields outside `dataField` (e.g. `id`, `kind`, `channel`, `type`).
+ */
+export type EventHandler<T = unknown> = (data: T, raw?: unknown) => void;
 
 /** Type-safe event map. Keys are event names, values are payload types. */
 export type EventMap = Record<string, unknown>;
@@ -48,12 +53,61 @@ export interface Logger {
 /** Middleware function — transform or inspect messages. Return null to drop. */
 export type Middleware<T = unknown> = (message: T) => T | null;
 
+/**
+ * Kinds of frames the library emits. Lets `EventProtocol.frameBuilder`
+ * take full control over the wire shape per kind — e.g. produce flat
+ * `{ type, channel, event, data }` envelopes for Pusher/Reverb/custom
+ * servers instead of the default `{ event, data }` two-key wrapper.
+ */
+export type FrameKind =
+  | 'event'              // user payload via ws.send / Channel.send
+  | 'subscribe'          // channel join
+  | 'unsubscribe'        // channel leave
+  | 'topic-subscribe'    // topic subscribe
+  | 'topic-unsubscribe'  // topic unsubscribe
+  | 'auth-login'         // authenticate(token)
+  | 'auth-logout';       // deauthenticate()
+
+/**
+ * Structured payload passed to `frameBuilder`. Fields are populated
+ * based on `kind`:
+ *
+ *   - `event`              → `{ event, data, channel?, extras? }`
+ *                            `channel` is set when sent via `Channel.send`.
+ *   - `subscribe`/`unsubscribe`        → `{ channel, extras? }`
+ *   - `topic-subscribe`/`topic-unsubscribe` → `{ topic, extras? }`
+ *   - `auth-login`         → `{ data: token, extras? }` (`data` is the raw token)
+ *   - `auth-logout`        → `{ extras? }`
+ */
+export interface FramePayload {
+  /** Channel name. Set for subscribe/unsubscribe and channel-scoped events. */
+  channel?: string;
+  /** Topic name. Set for topic-subscribe/topic-unsubscribe. */
+  topic?: string;
+  /** Bare event name (without channel prefix). Set for `kind: 'event'`. */
+  event?: string;
+  /** Payload — user data, auth token, etc. */
+  data?: unknown;
+  /** Extra top-level fields to merge into the wire envelope. */
+  extras?: Record<string, unknown>;
+}
+
 export interface SharedWebSocketOptions<TEvents extends EventMap = EventMap> {
   protocols?: string[];
   reconnect?: boolean;
   reconnectMaxDelay?: number;
   /** Max reconnect attempts before giving up (default: Infinity — retry forever). */
   reconnectMaxRetries?: number;
+  /**
+   * WebSocket close codes that indicate "auth failed — don't retry."
+   * On these codes the library sets state to 'failed' and stops auto-reconnect
+   * instead of looping with the same expired credentials. Default: `[1008]`
+   * (PolicyViolation). Add 4xxx app-specific codes if your server uses them.
+   *
+   * To recover, call `ws.authenticate(newToken)` (auto-reconnects when
+   * the local tab is the leader) or `ws.reconnect()` directly.
+   */
+  authFailureCloseCodes?: number[];
   heartbeatInterval?: number;
   electionTimeout?: number;
   leaderHeartbeat?: number;
@@ -65,6 +119,42 @@ export interface SharedWebSocketOptions<TEvents extends EventMap = EventMap> {
   authToken?: string;
   /** Query parameter name for the token (default: "token"). */
   authParam?: string;
+  /**
+   * Optional. Periodic token refresh — runs on the leader tab only via
+   * `setInterval(refresh, refreshTokenInterval)`. When the timer fires
+   * and the connection is currently authenticated, the returned token
+   * is passed to `authenticate()` so the server sees the new credentials
+   * before the old one expires. Falls back to `auth` if unset.
+   *
+   * Use this for long-running tabs where the server would otherwise
+   * close with an auth-failure code mid-session. Pair with a sensible
+   * interval — typically ~80% of your token TTL (e.g. 48 minutes for a
+   * 60-minute token).
+   *
+   * If the callback throws, the failure is logged at `warn` and the
+   * timer keeps running for the next interval; the server will still
+   * close on its own when the token expires, at which point
+   * `authFailureCloseCodes` and `ws.authenticate(...)` handle recovery.
+   */
+  refresh?: () => string | Promise<string>;
+  /**
+   * Refresh interval in milliseconds. Disabled when unset or `<= 0`.
+   * No default — opt-in.
+   */
+  refreshTokenInterval?: number;
+  /**
+   * Max number of follower-routed dispatches each tab buffers locally for
+   * replay across leader handover. When the leader dies between receiving
+   * a follower's dispatch and writing it to the socket, the new leader
+   * gathers pending entries from all tabs and replays them. Cap protects
+   * memory; oldest entries are dropped on overflow. Set to `0` to disable
+   * the buffer entirely. Default: 100.
+   *
+   * Note: the replay is at-least-once — a leader that dies AFTER socket
+   * write but BEFORE broadcasting "flushed" will cause a duplicate. Make
+   * server-side handlers idempotent if duplicates would matter.
+   */
+  outboundBufferSize?: number;
   /** Run WebSocket inside a Web Worker (offloads JSON parsing, heartbeat from main thread). */
   useWorker?: boolean;
   /** Custom worker URL (if useWorker is true and you want to provide your own worker file). */
@@ -117,6 +207,56 @@ export interface EventProtocol {
   authLogout: string;
   /** Event name server sends to revoke auth (default: "$auth:revoked"). */
   authRevoked: string;
+  /**
+   * Optional. Takes full control of outgoing frame shape per `FrameKind`.
+   * If unset, the default builder reproduces the legacy two-key envelope:
+   *   `{ ...extras, [eventField]: <event-name>, [dataField]: <data> }`
+   * using `channelJoin` / `channelLeave` / `topicSubscribe` / etc. for
+   * control-frame event names.
+   *
+   * Return-value contract:
+   *   - any concrete value → use as the wire frame
+   *   - `null`              → drop the frame (intentional filter / no-op)
+   *   - `undefined`         → fall back to the library default for this kind
+   *
+   * @example Flat envelope (Pusher / Reverb / custom Go server)
+   * frameBuilder: (kind, p) => {
+   *   switch (kind) {
+   *     case 'subscribe':    return { type: 'subscribe',   channel: p.channel };
+   *     case 'unsubscribe':  return { type: 'unsubscribe', channel: p.channel };
+   *     case 'auth-login':   return { type: 'auth',        token: p.data };
+   *     case 'auth-logout':  return { type: 'logout' };
+   *     case 'event':
+   *       return p.channel
+   *         ? { type: 'event', channel: p.channel, event: p.event, data: p.data, ...p.extras }
+   *         : { type: 'event', event: p.event, data: p.data, ...p.extras };
+   *     default: return undefined; // unknown kind → library default
+   *   }
+   * }
+   */
+  frameBuilder?: (kind: FrameKind, payload: FramePayload) => unknown;
+  /**
+   * Optional. If provided, `channel(name).ready` waits for an incoming
+   * frame this matcher classifies as `'ok'` before resolving. Returns:
+   *   - `'ok'`       → resolve.
+   *   - `'reject'`   → reject with a "subscribe rejected" error.
+   *   - `'pending'`  → keep watching subsequent frames.
+   *
+   * Without a matcher, `Channel.ready` resolves immediately after the
+   * subscribe frame is dispatched — appropriate for fire-and-forget
+   * servers that don't send subscribe acks.
+   *
+   * @example Phoenix `phx_reply`
+   * channelAckMatcher: (frame, channel) => {
+   *   const f = frame as { topic: string; event: string; payload: { status: 'ok' | 'error' } };
+   *   if (f.topic !== channel) return 'pending';
+   *   if (f.event !== 'phx_reply') return 'pending';
+   *   return f.payload.status === 'ok' ? 'ok' : 'reject';
+   * }
+   */
+  channelAckMatcher?: (frame: unknown, channel: string) => ChannelAckResult;
+  /** Timeout in ms for `Channel.ready` when `channelAckMatcher` is set. Default: 5000. */
+  channelAckTimeout?: number;
 }
 
 /** Push notification options. */
@@ -150,9 +290,30 @@ export interface SocketLifecycleHandlers {
   onAuthChange?: (authenticated: boolean) => void;
 }
 
+/**
+ * Result returned by `EventProtocol.channelAckMatcher` for each
+ * incoming frame while a `Channel` is awaiting its subscribe ack.
+ *
+ *   - `'ok'`      → resolve `Channel.ready`, stop watching.
+ *   - `'reject'`  → reject `Channel.ready` with a "subscribe rejected"
+ *                   error, stop watching.
+ *   - `'pending'` → keep watching for subsequent frames.
+ */
+export type ChannelAckResult = 'ok' | 'reject' | 'pending';
+
 /** Scoped channel handle for private/topic-based subscriptions. */
 export interface Channel {
   readonly name: string;
+  /**
+   * Resolves once the server has accepted the subscription. By default
+   * (no `channelAckMatcher` configured) this resolves immediately after
+   * the subscribe frame is dispatched — fire-and-forget servers don't
+   * send acks. Configure `EventProtocol.channelAckMatcher` to wait for
+   * a real ack frame; the promise then rejects on a matched
+   * "rejected" frame, on `channelAckTimeout`, or if `.leave()` is
+   * called before the ack arrives.
+   */
+  readonly ready: Promise<void>;
   on(event: string, handler: EventHandler): Unsubscribe;
   once(event: string, handler: EventHandler): Unsubscribe;
   send(event: string, data: unknown): void;

package/src/worker/socket.worker.ts

@@ -26,6 +26,7 @@ interface WorkerCommand {
   reconnect?: boolean;
   reconnectMaxDelay?: number;
   reconnectMaxRetries?: number;
+  authFailureCloseCodes?: number[];
   heartbeatInterval?: number;
   bufferSize?: number;
 }
@@ -42,6 +43,7 @@ let currentProtocols: string[] = [];
 let shouldReconnect = true;
 let maxDelay = 30_000;
 let maxRetries = Infinity;
+let authFailureCloseCodes: Set<number> = new Set([1008]);
 let heartbeatInterval = 30_000;
 let maxBuffer = 100;
 
@@ -100,6 +102,10 @@ function doConnect() {
     stopHeartbeat();
     self.postMessage({ type: 'close', code: ev.code, reason: ev.reason });
 
+    if (authFailureCloseCodes.has(ev.code)) {
+      setState('failed');
+      return;
+    }
     if (!disposed && shouldReconnect && ev.code !== 1000) {
       scheduleReconnect();
     } else {
@@ -220,6 +226,7 @@ self.onmessage = (ev: MessageEvent<WorkerCommand>) => {
       if (cmd.reconnect !== undefined) shouldReconnect = cmd.reconnect;
       if (cmd.reconnectMaxDelay) maxDelay = cmd.reconnectMaxDelay;
       if (cmd.reconnectMaxRetries !== undefined) maxRetries = cmd.reconnectMaxRetries;
+      if (cmd.authFailureCloseCodes) authFailureCloseCodes = new Set(cmd.authFailureCloseCodes);
       if (cmd.heartbeatInterval) heartbeatInterval = cmd.heartbeatInterval;
       if (cmd.bufferSize) maxBuffer = cmd.bufferSize;
       connect(cmd.url!, cmd.protocols ?? []);