@dojo-ng/websocket 0.1.3 → 0.2.0

package/README.md

@@ -46,6 +46,30 @@ bus.publish("notify:event", { event: "chat:message", params: { text: "Hi" } });
   after it is sent, so a failed send does not lose it.
 - After a lost connection, the client waits longer before each new try (Fibonacci backoff). A
   successful connect resets the delay. After `close()`, it does not reconnect.
+- `reconnectBase` (seconds, default 15) is added to every reconnect delay. Lower it when the
+  server is on the same machine, where a disconnect is usually a quick restart. Keep it high for
+  a public site, so a server restart is not met by every tab at once.
+- `url` can be a function (sync or async) instead of a string. It is called before every open,
+  the first connect and each reconnect, and what it returns is the URL for that attempt only.
+  Use it when the URL carries a single-use credential, such as a ticket in the query string
+  (a browser cannot set a header on a WebSocket). If the function throws or rejects, that counts
+  as a failed attempt and is retried through the backoff. To stop for good, call `close()` and
+  then throw. A string `url` works exactly as before.
+
+```js
+const server = new WSDispatcher({
+  reconnectBase: 2,
+  url: async () => {
+    const res = await fetch("/api/ws-ticket", { method: "POST" });
+    if (res.status === 401) {
+      server.close(); // the credential was refused; do not retry
+      throw new Error("not authorized");
+    }
+    const { ticket } = await res.json();
+    return `wss://example.com/ws?ticket=${ticket}`;
+  },
+});
+```
 - When the server sends `ping` messages, the client expects one at least every 40 seconds. If
   none arrives, it closes and reconnects through the same backoff. A server that never sends a
   ping turns this check off.

package/dist/wsdispatcher.d.ts

@@ -1,7 +1,28 @@
 import { type PubSub } from "@dojo-ng/pubsub";
 import { WSocket } from "./wsocket.js";
 export interface WSDispatcherOptions {
-    url: string;
+    /**
+     * The socket URL, or a function returning it (sync or async). A function is called before every
+     * open, first connect and every reconnect alike, and its result is the URL for that attempt only
+     * — use it when the URL carries a single-use credential such as a ticket. A function that throws
+     * or rejects counts as a failed attempt and is retried through the reconnect backoff. To stop
+     * for good (say the credential was refused), call `close()` and then throw.
+     *
+     * ```ts
+     * url: async () => {
+     *   const res = await fetch("/api/ws-ticket", { method: "POST" });
+     *   if (res.status === 401) { dispatcher.close(); throw new Error("not authorized"); }
+     *   return `wss://example.com/ws?ticket=${(await res.json()).ticket}`;
+     * }
+     * ```
+     */
+    url: string | (() => string | Promise<string>);
+    /**
+     * Seconds added to every reconnect delay, on top of the Fibonacci step. Default 15. Lower it for
+     * a client on the same machine as its server (a daemon restart); keep it high for a public site
+     * so a server restart is not met by every tab at once.
+     */
+    reconnectBase?: number;
     /** Frames to send first on every (re)connect, before the offline queue flushes. */
     onConnect?: () => unknown[];
     /** Shared with the rest of the app if given; otherwise a private instance is created. */
@@ -16,6 +37,7 @@ export interface WSDispatcherOptions {
 export declare class WSDispatcher {
     #private;
     constructor(options: WSDispatcherOptions);
+    /** The most recent URL opened; empty until a URL provider has resolved once. */
     get url(): string;
     /** The underlying `WSocket`, for connection-state inspection. */
     get socket(): WSocket;

package/dist/wsdispatcher.js

@@ -7,8 +7,14 @@
 // - Offline send queue (`#drain`): peeks and sends, dequeuing only on a confirmed OKAY send, so a
 //   failed send never drops the message. BUFFERING retries at 50ms; a confirmed send immediately
 //   tries the next one.
-// - Reconnect with Fibonacci backoff (`#scheduleReopen`): `TIMEOUT_BASE` 15s plus the step table,
-//   counter reset only on a successful open, suppressed entirely while `#closing` is true.
+// - Reconnect with Fibonacci backoff (`#scheduleReopen`): `reconnectBase` (default 15s) plus the
+//   step table, counter reset only on a successful open, suppressed entirely while `#closing` is
+//   true.
+// - URL provider: `url` may be a function, called before EVERY open (first connect and each
+//   reconnect) so a single-use ticket in the query string is fresh each time. A provider that
+//   throws or rejects is a failed attempt and goes through `#scheduleReopen`; one that wants to stop
+//   for good calls `close()` before throwing. `#closing` is rechecked after the provider resolves,
+//   so a `close()` that lands mid-await wins.
 // - Heartbeat watchdog (`#armHeartbeat`): each inbound "ping" frame arms a 40s timer. On expiry:
 //   close, wait 2s, then go through the SAME backoff-aware reopen path as any other reconnect —
 //   not a bypass. `TIMEOUT_STEP`'s reset-only-on-success rule means a heartbeat failure right after
@@ -42,11 +48,11 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _WSDispatcher_instances, _WSDispatcher_url, _WSDispatcher_ws, _WSDispatcher_pubsub, _WSDispatcher_onConnect, _WSDispatcher_msgQueue, _WSDispatcher_cbqueue, _WSDispatcher_closing, _WSDispatcher_reopenCount, _WSDispatcher_nextId, _WSDispatcher_pingTimer, _WSDispatcher_scheduleReopen, _WSDispatcher_flushQueue, _WSDispatcher_enqueue, _WSDispatcher_drain, _WSDispatcher_dispatch, _WSDispatcher_armHeartbeat;
+var _WSDispatcher_instances, _WSDispatcher_urlSource, _WSDispatcher_reconnectBase, _WSDispatcher_ws, _WSDispatcher_pubsub, _WSDispatcher_onConnect, _WSDispatcher_msgQueue, _WSDispatcher_cbqueue, _WSDispatcher_closing, _WSDispatcher_resolvingUrl, _WSDispatcher_reopenCount, _WSDispatcher_nextId, _WSDispatcher_pingTimer, _WSDispatcher_openResolved, _WSDispatcher_scheduleReopen, _WSDispatcher_flushQueue, _WSDispatcher_enqueue, _WSDispatcher_drain, _WSDispatcher_dispatch, _WSDispatcher_armHeartbeat;
 import { createPubSub } from "@dojo-ng/pubsub";
 import { Queue } from "./queue.js";
 import { WSocket, SendState } from "./wsocket.js";
-const TIMEOUT_BASE = 15;
+const DEFAULT_RECONNECT_BASE = 15;
 const TIMEOUT_STEP = [0, 0, 0, 0, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233];
 const PING_TIMEOUT_MS = 40000;
 const PING_RECOVERY_DELAY_MS = 2000;
@@ -57,20 +63,23 @@ const PING_RECOVERY_DELAY_MS = 2000;
 export class WSDispatcher {
     constructor(options) {
         _WSDispatcher_instances.add(this);
-        _WSDispatcher_url.set(this, void 0);
+        _WSDispatcher_urlSource.set(this, void 0);
+        _WSDispatcher_reconnectBase.set(this, void 0);
         _WSDispatcher_ws.set(this, void 0);
         _WSDispatcher_pubsub.set(this, void 0);
         _WSDispatcher_onConnect.set(this, void 0);
         _WSDispatcher_msgQueue.set(this, new Queue());
         _WSDispatcher_cbqueue.set(this, new Map());
         _WSDispatcher_closing.set(this, false);
+        _WSDispatcher_resolvingUrl.set(this, false);
         _WSDispatcher_reopenCount.set(this, 0);
         _WSDispatcher_nextId.set(this, 1);
         _WSDispatcher_pingTimer.set(this, null);
-        __classPrivateFieldSet(this, _WSDispatcher_url, options.url, "f");
+        __classPrivateFieldSet(this, _WSDispatcher_urlSource, options.url, "f");
+        __classPrivateFieldSet(this, _WSDispatcher_reconnectBase, options.reconnectBase ?? DEFAULT_RECONNECT_BASE, "f");
         __classPrivateFieldSet(this, _WSDispatcher_onConnect, options.onConnect, "f");
         __classPrivateFieldSet(this, _WSDispatcher_pubsub, options.pubsub ?? createPubSub(), "f");
-        __classPrivateFieldSet(this, _WSDispatcher_ws, new WSocket(__classPrivateFieldGet(this, _WSDispatcher_url, "f")), "f");
+        __classPrivateFieldSet(this, _WSDispatcher_ws, new WSocket(typeof __classPrivateFieldGet(this, _WSDispatcher_urlSource, "f") === "string" ? __classPrivateFieldGet(this, _WSDispatcher_urlSource, "f") : ""), "f");
         __classPrivateFieldGet(this, _WSDispatcher_ws, "f").addEventListener("message", (event) => {
             __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_dispatch).call(this, event.detail.data);
         });
@@ -84,8 +93,9 @@ export class WSDispatcher {
         const outboundTopic = options.outboundTopic ?? "notify:event";
         __classPrivateFieldGet(this, _WSDispatcher_pubsub, "f").subscribe(outboundTopic, (payload) => __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_enqueue).call(this, { action: "event", id: 0, data: payload }), { replay: false });
     }
+    /** The most recent URL opened; empty until a URL provider has resolved once. */
     get url() {
-        return __classPrivateFieldGet(this, _WSDispatcher_url, "f");
+        return __classPrivateFieldGet(this, _WSDispatcher_ws, "f").url;
     }
     /** The underlying `WSocket`, for connection-state inspection. */
     get socket() {
@@ -100,7 +110,14 @@ export class WSDispatcher {
     }
     open(force = false) {
         __classPrivateFieldSet(this, _WSDispatcher_closing, false, "f");
-        __classPrivateFieldGet(this, _WSDispatcher_ws, "f").open(force);
+        if (typeof __classPrivateFieldGet(this, _WSDispatcher_urlSource, "f") === "string") {
+            __classPrivateFieldGet(this, _WSDispatcher_ws, "f").open(force);
+            return;
+        }
+        // A second open while the provider is pending would spend a second single-use URL.
+        if (__classPrivateFieldGet(this, _WSDispatcher_resolvingUrl, "f"))
+            return;
+        void __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_openResolved).call(this, __classPrivateFieldGet(this, _WSDispatcher_urlSource, "f"), force);
     }
     close() {
         __classPrivateFieldSet(this, _WSDispatcher_closing, true, "f");
@@ -126,12 +143,28 @@ export class WSDispatcher {
         }
     }
 }
-_WSDispatcher_url = new WeakMap(), _WSDispatcher_ws = new WeakMap(), _WSDispatcher_pubsub = new WeakMap(), _WSDispatcher_onConnect = new WeakMap(), _WSDispatcher_msgQueue = new WeakMap(), _WSDispatcher_cbqueue = new WeakMap(), _WSDispatcher_closing = new WeakMap(), _WSDispatcher_reopenCount = new WeakMap(), _WSDispatcher_nextId = new WeakMap(), _WSDispatcher_pingTimer = new WeakMap(), _WSDispatcher_instances = new WeakSet(), _WSDispatcher_scheduleReopen = function _WSDispatcher_scheduleReopen() {
+_WSDispatcher_urlSource = new WeakMap(), _WSDispatcher_reconnectBase = new WeakMap(), _WSDispatcher_ws = new WeakMap(), _WSDispatcher_pubsub = new WeakMap(), _WSDispatcher_onConnect = new WeakMap(), _WSDispatcher_msgQueue = new WeakMap(), _WSDispatcher_cbqueue = new WeakMap(), _WSDispatcher_closing = new WeakMap(), _WSDispatcher_resolvingUrl = new WeakMap(), _WSDispatcher_reopenCount = new WeakMap(), _WSDispatcher_nextId = new WeakMap(), _WSDispatcher_pingTimer = new WeakMap(), _WSDispatcher_instances = new WeakSet(), _WSDispatcher_openResolved = async function _WSDispatcher_openResolved(provider, force) {
+    __classPrivateFieldSet(this, _WSDispatcher_resolvingUrl, true, "f");
+    let url;
+    try {
+        url = await provider();
+    }
+    catch {
+        __classPrivateFieldSet(this, _WSDispatcher_resolvingUrl, false, "f");
+        __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_scheduleReopen).call(this);
+        return;
+    }
+    __classPrivateFieldSet(this, _WSDispatcher_resolvingUrl, false, "f");
+    // A close() that landed while the provider was pending must win.
+    if (__classPrivateFieldGet(this, _WSDispatcher_closing, "f"))
+        return;
+    __classPrivateFieldGet(this, _WSDispatcher_ws, "f").open(force, url);
+}, _WSDispatcher_scheduleReopen = function _WSDispatcher_scheduleReopen() {
     var _a;
     if (__classPrivateFieldGet(this, _WSDispatcher_closing, "f"))
         return;
     const step = Math.min(__classPrivateFieldGet(this, _WSDispatcher_reopenCount, "f"), TIMEOUT_STEP.length - 1);
-    const timeoutSeconds = TIMEOUT_STEP[step] + TIMEOUT_BASE;
+    const timeoutSeconds = TIMEOUT_STEP[step] + __classPrivateFieldGet(this, _WSDispatcher_reconnectBase, "f");
     __classPrivateFieldSet(this, _WSDispatcher_reopenCount, (_a = __classPrivateFieldGet(this, _WSDispatcher_reopenCount, "f"), _a++, _a), "f");
     setTimeout(() => {
         this.open();

package/dist/wsocket.d.ts

@@ -33,8 +33,11 @@ export declare class WSocket extends EventTarget {
     get socket(): WebSocket | null;
     /** Our own tracked state, not a live re-check of `socket.readyState` — see `send()` for why. */
     isOpen(): boolean;
-    /** With no existing socket, or `force: true`, tears down any prior socket and opens a fresh one. */
-    open(force?: boolean): void;
+    /**
+     * With no existing socket, or `force: true`, tears down any prior socket and opens a fresh one.
+     * A `url` replaces the stored one for this socket and onward, so `url` reports the latest.
+     */
+    open(force?: boolean, url?: string): void;
     close(code?: number, reason?: string): void;
     send(message: string | Blob | BufferSource): SendState;
 }

package/dist/wsocket.js

@@ -73,8 +73,11 @@ export class WSocket extends EventTarget {
     isOpen() {
         return __classPrivateFieldGet(this, _WSocket_socket, "f") !== null && __classPrivateFieldGet(this, _WSocket_state, "f") === ReadyState.OPEN;
     }
-    /** With no existing socket, or `force: true`, tears down any prior socket and opens a fresh one. */
-    open(force = false) {
+    /**
+     * With no existing socket, or `force: true`, tears down any prior socket and opens a fresh one.
+     * A `url` replaces the stored one for this socket and onward, so `url` reports the latest.
+     */
+    open(force = false, url) {
         if (__classPrivateFieldGet(this, _WSocket_socket, "f")) {
             if (!force)
                 return;
@@ -86,6 +89,8 @@ export class WSocket extends EventTarget {
                 stale.close();
             __classPrivateFieldSet(this, _WSocket_socket, null, "f");
         }
+        if (url !== undefined)
+            __classPrivateFieldSet(this, _WSocket_url, url, "f");
         __classPrivateFieldSet(this, _WSocket_state, ReadyState.CONNECTING, "f");
         const socket = (__classPrivateFieldSet(this, _WSocket_socket, new WebSocket(__classPrivateFieldGet(this, _WSocket_url, "f")), "f"));
         // Pre-open error: straight to close, no `error` event — see the file header.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dojo-ng/websocket",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Dojo NG WebSocket client that reconnects, queues messages while offline, and matches responses to requests",
   "type": "module",
   "main": "./dist/index.js",