@gwakko/shared-websocket 0.13.0 → 0.14.5

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
@@ -266,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 |
@@ -274,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>;

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;
@@ -154,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;
@@ -163,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). */
@@ -265,9 +323,87 @@ 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;
+    /**
+     * Human-readable headline for log lines — picks the most relevant field
+     * out of the structured payload so log scanners aren't reading objects:
+     *   - event       → event name
+     *   - subscribe   → channel
+     *   - topic-*     → topic
+     *   - auth-*      → '(redacted)' / ''
+     */
+    private frameLabel;
     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,6 +38,7 @@ export declare class WorkerSocket implements Disposable {
         pingPayload?: unknown;
     });
     get state(): SocketState;
+    private setState;
     connect(): Promise<void>;
     private buildUrl;
     send(data: unknown): void;

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.

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.
  *