@gwakko/shared-websocket 0.12.3 → 0.14.3

package/README.md

@@ -16,6 +16,7 @@ Share **one** WebSocket connection across all browser tabs. Leader election via
 - [Processing Pipeline](#processing-pipeline)
 - [Options](#options)
 - [Documentation](#documentation)
+- [Server Compatibility](#server-compatibility)
 - [Browser Support](#browser-support)
 
 ## How It Works
@@ -210,7 +211,8 @@ usePush('notification', {
 | **Custom Serialization** | `serialize`/`deserialize` — JSON, MessagePack, Protobuf |
 | **Per-Event Serializers** | `ws.serializer(event, fn)` — binary for specific events |
 | **Runtime Auth** | `authenticate(token)` / `deauthenticate()` on existing connection |
-| **Lifecycle Hooks** | onConnect, onDisconnect, onActive, onInactive, onLeaderChange, onAuthChange |
+| **Lifecycle Hooks** | onConnect, onDisconnect, onReconnecting, onReconnectFailed, onActive, onInactive, onLeaderChange, onAuthChange |
+| **Manual Reconnect** | `ws.reconnect()` resets retry counter — pair with `onReconnectFailed` for a "Reconnect" snackbar |
 | **Debug/Logger** | `debug: true` + injectable logger (pino, Sentry) |
 | **Event Protocol** | Configurable field names (Socket.IO, Phoenix, Laravel Echo) |
 | **Auth** | URL param (`auth` callback / `authToken`) + runtime `authenticate()`/`deauthenticate()` |
@@ -265,6 +267,25 @@ Incoming: WebSocket.onmessage
 | **[Server Guide](docs/server-guide.md)** | Node.js, Go, PHP examples + system events |
 | **[Types](docs/types.md)** | All exported types with import examples |
 
+## Server Compatibility
+
+| Server | Status | Configuration |
+|---|---|---|
+| **Pusher / Soketi / Reverb** | ✅ Default + small overrides | `events: { channelJoin: 'pusher:subscribe', channelLeave: 'pusher:unsubscribe' }` |
+| **Custom 2-key `{ event, data }` server** | ✅ Default | none |
+| **Custom flat-fields server** (`{ type, channel, event, data }`) | ✅ via `frameBuilder` | [sample](docs/configuration.md#flat-fields-server-eg-custom-go-or-rust-ws) |
+| **Phoenix Channels** (Elixir) | ⚠️ Structural sample provided — verify against your phoenix client version | [sample](docs/configuration.md#phoenix-channels) |
+| **ActionCable** (Rails) | ⚠️ Subscribe/event sample; auth typically via session cookie | [sample](docs/configuration.md#actioncable-rails) |
+| **Centrifugo / GraphQL-over-WS / proprietary binary** | ⚠️ Use `frameBuilder` + custom `serialize`/`deserialize` | Hand-rolled — see [Custom Serialization](docs/configuration.md#custom-serialization) |
+
+The two-key default `{ [eventField]: <event>, [dataField]: <data> }`
+covers the common case. Anything else — extra top-level fields,
+array-form frames, custom control-frame discriminators — is handled
+by the `frameBuilder` hook (`events.frameBuilder` in
+`SharedWebSocketOptions`). Subscribe-acks are handled by
+`channelAckMatcher` so `await channel.ready` rejects on authz failures
+instead of silently never receiving events.
+
 ## Browser Support
 
 | API | Chrome | Firefox | Safari | Edge |
@@ -273,6 +294,23 @@ Incoming: WebSocket.onmessage
 | Web Worker | ✅ | ✅ | ✅ | ✅ |
 | AsyncGenerator | 63+ | 57+ | 12+ | 79+ |
 
+**`BroadcastChannel` is required and has no fallback.** The library
+constructs one synchronously in `new SharedWebSocket(...)`, so an
+unsupported environment throws `ReferenceError: BroadcastChannel is
+not defined`. Practical implications:
+
+- **iOS Safari** — fully works on 15.4+ (March 2022). Older iOS will
+  throw; gate construction behind a feature check if you ship to those
+  versions.
+- **Some Android webviews / older WKWebView** — same caveat.
+- **Node / SSR** — no `BroadcastChannel`. Construct the socket inside
+  `useEffect` (React) / `onMounted` (Vue), or behind a `typeof window
+  !== 'undefined'` guard. Don't instantiate in module scope on the
+  server.
+- **Tests (jsdom)** — recent jsdom (>= 22) implements
+  `BroadcastChannel`. Older jsdom or `happy-dom` may need a polyfill
+  or a stub.
+
 ## License
 
 MIT

package/dist/SharedSocket.d.ts

@@ -6,6 +6,8 @@ interface SharedSocketOptions {
     reconnectMaxDelay?: number;
     /** Max reconnect attempts before giving up (default: Infinity). */
     reconnectMaxRetries?: number;
+    /** Close codes that mean "auth failed — stop reconnect." Default: [1008]. */
+    authFailureCloseCodes?: number[];
     heartbeatInterval?: number;
     sendBuffer?: number;
     auth?: () => string | Promise<string>;
@@ -37,7 +39,14 @@ export declare class SharedSocket implements Disposable {
     send(data: unknown): void;
     onMessage(fn: EventHandler): Unsubscribe;
     onStateChange(fn: (state: SocketState) => void): Unsubscribe;
-    private reconnect;
+    /**
+     * Manually trigger a reconnect. Resets the retry counter and clears any
+     * scheduled backoff so the next attempt happens immediately. Use after
+     * `state === 'failed'` to let the user retry, or any time to force a
+     * fresh connection.
+     */
+    reconnect(): void;
+    private scheduleReconnect;
     private flushBuffer;
     private startHeartbeat;
     private stopHeartbeat;

package/dist/SharedWebSocket.d.ts

@@ -34,6 +34,27 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
     private _isAuthenticated;
     private authChannels;
     private authTopics;
+    /**
+     * Refcount of active channel subscriptions per name. Used to route
+     * incoming events back to channel handlers via `${name}<RS>${event}`
+     * keys without colliding when names/events contain `:`, and as the
+     * source for cross-tab subscription replay on leader change.
+     */
+    private channelRefs;
+    /** All topic subscriptions (auth and non-auth). Replayed on leader change. */
+    private topics;
+    /** Listeners for every raw incoming frame (post-deserialize, post-middleware). */
+    private rawFrameListeners;
+    /**
+     * Local outbound buffer of follower-originated dispatches awaiting flush
+     * confirmation from the leader. Drained when the leader broadcasts
+     * `ws:dispatch-flushed` for the entry's id; replayed by the next leader
+     * after gathering across surviving tabs. Insertion order preserved
+     * (Map) so we drop oldest on overflow.
+     */
+    private pendingOutbound;
+    /** Periodic refresh timer — leader only. Recreated on each leader handover. */
+    private refreshTimer;
     constructor(url: string, options?: SharedWebSocketOptions<TEvents>);
     get connected(): boolean;
     get tabRole(): TabRole;
@@ -49,6 +70,28 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
     onDisconnect(fn: () => void): Unsubscribe;
     /** Called when WebSocket starts reconnecting (broadcast to all tabs). */
     onReconnecting(fn: () => void): Unsubscribe;
+    /**
+     * Called when auto-reconnect gives up after exhausting `reconnectMaxRetries`.
+     * Use this to show a "Reconnect" UI affordance (snackbar, banner, modal)
+     * so the user can call `ws.reconnect()` to try again.
+     *
+     * @example
+     * ws.onReconnectFailed(() => {
+     *   showSnackbar('Connection lost', { action: { label: 'Reconnect', onClick: () => ws.reconnect() } });
+     * });
+     */
+    onReconnectFailed(fn: () => void): Unsubscribe;
+    /**
+     * Manually trigger a reconnect. Resets the retry counter and attempts a
+     * fresh connection. Safe to call from any tab — the leader actually owns
+     * the socket, followers route the request via BroadcastChannel.
+     *
+     * Use after `onReconnectFailed` fires to let the user retry.
+     *
+     * @example
+     * snackbar.action('Reconnect', () => ws.reconnect());
+     */
+    reconnect(): void;
     /** Called when this tab becomes leader or loses leadership. */
     onLeaderChange(fn: (isLeader: boolean) => void): Unsubscribe;
     /** Called on WebSocket or network error (broadcast to all tabs). */
@@ -132,7 +175,20 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
      * ws.deserializer('trading.tick', (data) => TickProto.decode(data as Uint8Array));
      */
     deserializer(event: string, fn: (data: unknown) => unknown): this;
-    /** Subscribe to server events (works in ALL tabs). Type-safe with EventMap. */
+    /**
+     * Subscribe to server events (works in ALL tabs). Type-safe with EventMap.
+     *
+     * The handler receives `(data, raw)`:
+     * - `data` is extracted via `dataField` (default `'data'`)
+     * - `raw` is the full deserialized envelope, useful for protocols with extra
+     *   top-level fields like `id`, `kind`, `channel`, `type`, etc.
+     *
+     * @example
+     * ws.on('msg', (data, raw) => {
+     *   raw.id;    // top-level metadata
+     *   raw.kind;  // discriminator
+     * });
+     */
     on<K extends string & keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): Unsubscribe;
     on(event: string, handler: EventHandler<unknown>): Unsubscribe;
     once<K extends string & keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): Unsubscribe;
@@ -141,9 +197,33 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
     /** Async generator for consuming events. Type-safe with EventMap. */
     stream<K extends string & keyof TEvents>(event: K, signal?: AbortSignal): AsyncGenerator<TEvents[K]>;
     stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown>;
-    /** Send message to server (auto-routed through leader). Type-safe with EventMap. */
-    send<K extends string & keyof TEvents>(event: K, data: TEvents[K]): void;
-    send(event: string, data: unknown): void;
+    /**
+     * Send message to server (auto-routed through leader). Type-safe with EventMap.
+     *
+     * The optional third argument `extras` adds top-level fields to the wire envelope.
+     * Use it for protocols that need extra envelope keys like `type`, `channel`, etc.
+     *
+     * @example
+     * // Default shape: { event, data }
+     * ws.send('chat.message', { text: 'Hello' });
+     * // → { event: 'chat.message', data: { text: 'Hello' } }
+     *
+     * @example
+     * // Pusher/Reverb-style envelope
+     * ws.send('group.member_ready',
+     *   { member_id: 'abc', ready: true },
+     *   { type: 'event', channel: 'public.group.xxx' },
+     * );
+     * // → {
+     * //     type: 'event',
+     * //     channel: 'public.group.xxx',
+     * //     event: 'group.member_ready',
+     * //     data: { member_id: 'abc', ready: true },
+     * //   }
+     */
+    send<K extends string & keyof TEvents>(event: K, data: TEvents[K], extras?: Record<string, unknown>): void;
+    send(event: string, data: unknown, extras?: Record<string, unknown>): void;
+    private assertExtrasReserved;
     /** Request/response through server via leader. */
     request<T>(event: string, data: unknown, timeout?: number): Promise<T>;
     /** Sync state across tabs (no server roundtrip). */
@@ -243,9 +323,78 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
         onClick?: (data: T) => void;
     }): Unsubscribe;
     disconnect(): void;
+    /**
+     * Build the wire frame for a given kind. Honors custom `frameBuilder`.
+     * Return-value contract:
+     *   - any concrete value → use as the frame
+     *   - `null`             → drop the frame (intentional filter)
+     *   - `undefined`        → fall back to the default builder for this kind
+     */
+    private buildFrame;
+    /**
+     * Subscribe to every raw incoming frame (post-deserialize). Used by
+     * `Channel.ready`'s ack matcher. Internal — not part of the public API.
+     */
+    private onRawFrame;
+    /** Legacy two-key builder — preserved as the default for back-compat. */
+    private defaultFrameBuilder;
+    /** Route a structured frame: leader transmits, followers forward via bus. */
+    private dispatch;
+    private enqueuePending;
+    /** Build, run middleware, and write to the socket. Leader-only. */
+    private transmit;
     private createSocket;
     private handleBecomeLeader;
-    private reAuthenticateOnReconnect;
+    /**
+     * Re-establish all server-side state on the freshly connected leader socket:
+     *   1. auth-login (so server accepts subsequent joins on auth channels)
+     *   2. channel-join for the union of channels held by ALL surviving tabs
+     *   3. topic-subscribe for the union of topics held by ALL surviving tabs
+     *
+     * The union covers leader handover: when a follower with handlers is
+     * promoted, no tab's subscriptions get silently dropped. Frames are sent
+     * in FIFO order over the single WebSocket, so auth precedes the joins
+     * that depend on it.
+     */
+    /**
+     * Orchestrate post-connect recovery: replay subscriptions first (so the
+     * server is ready to route events for any channels we still care about),
+     * then drain follower-pending dispatches that didn't reach the previous
+     * leader's socket.
+     */
+    private onConnected;
+    private resubscribeOnConnect;
+    /**
+     * Replay buffered follower dispatches over the freshly connected socket.
+     * Gathers from all tabs (including this one), de-dups by id, transmits,
+     * then signals each originator to drop its local entry. Drops own-tab
+     * entries after transmission since `bus.publish` doesn't echo to self.
+     */
+    private replayPendingDispatches;
+    /**
+     * Cross-tab pending-dispatch gather. Same shape as `gatherSubscriptions`
+     * — broadcasts a one-shot request, collects for a short window, dedups
+     * by id (so multiple tabs holding the same id don't double-replay).
+     */
+    private gatherPendingDispatches;
+    /**
+     * Best-effort cross-tab gather. Broadcasts a request and collects responses
+     * for a short window. Times out gracefully — late responses are dropped.
+     * The leader's own subs are seeded into the result to avoid relying on
+     * BroadcastChannel echo to self.
+     */
+    private gatherSubscriptions;
     private handleLoseLeadership;
+    /**
+     * Start a leader-only periodic refresh of the auth token. The callback
+     * is `options.refresh` (preferred) or `options.auth` (fallback). When
+     * the timer fires and the connection is currently authenticated, the
+     * returned token is fed back through `authenticate()` so subscribers
+     * stay synced and the leader's socket re-issues auth-login.
+     *
+     * Idempotent — calling start while already running is a no-op.
+     */
+    private startRefreshTimer;
+    private stopRefreshTimer;
     [Symbol.dispose](): void;
 }

package/dist/SubscriptionManager.d.ts

@@ -6,7 +6,7 @@ export declare class SubscriptionManager implements Disposable {
     on(event: string, handler: EventHandler): Unsubscribe;
     once(event: string, handler: EventHandler): Unsubscribe;
     off(event: string, handler?: EventHandler): void;
-    emit(event: string, data: unknown): void;
+    emit(event: string, data: unknown, raw?: unknown): void;
     getLastMessage(event: string): unknown | undefined;
     stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown>;
     offAll(): void;

package/dist/WorkerSocket.d.ts

@@ -28,6 +28,7 @@ export declare class WorkerSocket implements Disposable {
         reconnect?: boolean;
         reconnectMaxDelay?: number;
         reconnectMaxRetries?: number;
+        authFailureCloseCodes?: number[];
         heartbeatInterval?: number;
         sendBuffer?: number;
         workerUrl?: string | URL;
@@ -37,9 +38,12 @@ export declare class WorkerSocket implements Disposable {
         pingPayload?: unknown;
     });
     get state(): SocketState;
+    private setState;
     connect(): Promise<void>;
     private buildUrl;
     send(data: unknown): void;
+    /** Manually trigger reconnect: resets retry counter, attempts a fresh connection. */
+    reconnect(): void;
     disconnect(): void;
     onMessage(fn: EventHandler): Unsubscribe;
     onStateChange(fn: (state: SocketState) => void): Unsubscribe;

package/dist/adapters/react.d.ts

@@ -91,7 +91,7 @@ export declare function useSocketAuth(): {
  *   setOrders(prev => [order, ...prev].slice(0, 50)); // keep last 50
  * });
  */
-export declare function useSocketEvent<T>(event: string, callback?: (data: T) => void): T | undefined;
+export declare function useSocketEvent<T>(event: string, callback?: (data: T, raw?: unknown) => void): T | undefined;
 /**
  * Accumulate WebSocket events into an array.
  * - Without callback: returns accumulated array (reactive state).
@@ -115,7 +115,7 @@ export declare function useSocketEvent<T>(event: string, callback?: (data: T) =>
  *   if (entry.level === 'error') setErrors(prev => [...prev, entry]);
  * });
  */
-export declare function useSocketStream<T>(event: string, callback?: (data: T) => void): T[];
+export declare function useSocketStream<T>(event: string, callback?: (data: T, raw?: unknown) => void): T[];
 /**
  * Two-way state sync across browser tabs.
  * - Without callback: returns [value, setter] (like useState but synced).
@@ -152,7 +152,7 @@ export declare function useSocketSync<T>(key: string, initialValue: T, callback?
  *   }
  * });
  */
-export declare function useSocketCallback<T>(event: string, callback: (data: T) => void): void;
+export declare function useSocketCallback<T>(event: string, callback: (data: T, raw?: unknown) => void): void;
 /**
  * Reactive connection status.
  * Uses useEffectEvent to avoid re-creating interval on state change.
@@ -178,6 +178,29 @@ export declare function useSocketStatus(): {
  * });
  */
 export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): void;
+/**
+ * Reactive reconnect state with a manual `reconnect` action. Use this to
+ * power a "Reconnect" snackbar/banner after auto-reconnect gives up.
+ *
+ * `hasFailed` is `true` after `reconnectMaxRetries` are exhausted. It resets
+ * to `false` once the connection succeeds again or the user calls `reconnect()`.
+ *
+ * @example
+ * function ConnectionBanner() {
+ *   const { hasFailed, reconnect } = useSocketReconnect();
+ *   if (!hasFailed) return null;
+ *   return (
+ *     <div className="snackbar">
+ *       Connection lost.
+ *       <button onClick={reconnect}>Reconnect</button>
+ *     </div>
+ *   );
+ * }
+ */
+export declare function useSocketReconnect(): {
+    hasFailed: boolean;
+    reconnect: () => void;
+};
 /**
  * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
  *

package/dist/adapters/vue.d.ts

@@ -59,7 +59,7 @@ export declare function useSocketAuth(): {
  *   analytics.track('order_received', order);
  * });
  */
-export declare function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined>;
+export declare function useSocketEvent<T>(event: string, callback?: (data: T, raw?: unknown) => void): Ref<T | undefined>;
 /**
  * Accumulate WebSocket events.
  * - Without callback: returns reactive array.
@@ -83,7 +83,7 @@ export declare function useSocketEvent<T>(event: string, callback?: (data: T) =>
  *   if (entry.level === 'error') errors.value = [...errors.value, entry];
  * });
  */
-export declare function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]>;
+export declare function useSocketStream<T>(event: string, callback?: (data: T, raw?: unknown) => void): Ref<T[]>;
 /**
  * Two-way state sync across browser tabs.
  * - Without callback: reactive ref synced across tabs.
@@ -110,7 +110,7 @@ export declare function useSocketSync<T>(key: string, initialValue: T, callback?
  *   showToast(n.title);
  * });
  */
-export declare function useSocketCallback<T>(event: string, callback: (data: T) => void): void;
+export declare function useSocketCallback<T>(event: string, callback: (data: T, raw?: unknown) => void): void;
 /**
  * Reactive connection status.
  *
@@ -135,6 +135,29 @@ export declare function useSocketStatus(): {
  * });
  */
 export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): void;
+/**
+ * Reactive reconnect state with a manual `reconnect` action. Use this to
+ * power a "Reconnect" snackbar/banner after auto-reconnect gives up.
+ *
+ * `hasFailed` flips to `true` once `reconnectMaxRetries` are exhausted, and
+ * back to `false` once the connection succeeds or the user calls `reconnect()`.
+ *
+ * @example
+ * <script setup>
+ * const { hasFailed, reconnect } = useSocketReconnect();
+ * </script>
+ *
+ * <template>
+ *   <div v-if="hasFailed" class="snackbar">
+ *     Connection lost.
+ *     <button @click="reconnect">Reconnect</button>
+ *   </div>
+ * </template>
+ */
+export declare function useSocketReconnect(): {
+    hasFailed: Ref<boolean>;
+    reconnect: () => void;
+};
 /**
  * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
  *