@owlmeans/client-socket 0.1.18-rc.5 → 0.1.18-rc.50

package/build/utils/connection.js

@@ -1,19 +1,272 @@
-import { createBasicConnection, MessageType } from '@owlmeans/socket';
-export const makeConnection = (conn, _context) => {
+import { createBasicConnection, MessageType, SocketConnectionError, SocketSystemEvent, SOCKET_HEARTBEAT_TIMEOUT_CODE } from '@owlmeans/socket';
+import { AuthenticationStage } from '@owlmeans/auth';
+import { logger } from '@owlmeans/log';
+import { TERMINAL_CLOSE_CODES } from './consts.local.js';
+const log = logger('client-socket');
+/**
+ * Build a `Connection` whose transport survives a dropped WebSocket.
+ *
+ * The connection MODEL (`createBasicConnection()`) is created exactly once and never replaced —
+ * every `observe`/`listen` a caller registered keeps firing across a reconnect, because only the
+ * underlying `WebSocket` is swapped underneath it. A server's own subscriptions do NOT survive a
+ * new TCP connection, so a caller whose server sets up state only after an in-band
+ * `authenticated` frame (as this platform's handlers do) must replay that frame itself on
+ * `SocketSystemEvent.Reconnected` — this carrier only re-opens the pipe.
+ */
+export const makeConnection = (opts) => {
+    const { policy, retry, open, onStatus } = opts;
     const model = createBasicConnection();
+    let current = null;
+    let closedByClient = false;
+    let finished = false;
+    // Gave up after the budget, but still revivable — unlike `finished`, nothing here is final.
+    let lost = false;
+    let attempts = 0;
+    let outageStartedAt = null;
+    let outageBudget = policy.budget;
+    let stableTimer = null;
+    let retryTimer = null;
+    let heartbeatTimer = null;
+    // When the ping still waiting for an answer was sent, or null once anything came back.
+    let pingSentAt = null;
+    let resolveReady = () => void 0;
+    let rejectReady = () => void 0;
+    const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+    let settled = false;
+    const settle = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        if (error != null)
+            rejectReady(error);
+        else
+            resolveReady();
+    };
+    const emitSystem = async (event, payload) => {
+        const msg = { type: MessageType.System, event, payload };
+        model.prepare?.(msg);
+        await Promise.all(model.getListeners().map(async (listener) => {
+            try {
+                await listener(msg);
+            }
+            catch (error) {
+                log.error('Socket system listener failed', { error });
+            }
+        }));
+    };
+    const clearHeartbeat = () => {
+        if (heartbeatTimer != null) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = null;
+        }
+    };
+    const clearTimers = () => {
+        if (retryTimer != null) {
+            clearTimeout(retryTimer);
+            retryTimer = null;
+        }
+        if (stableTimer != null) {
+            clearTimeout(stableTimer);
+            stableTimer = null;
+        }
+        clearHeartbeat();
+    };
+    const startHeartbeat = (socket) => {
+        pingSentAt = null;
+        heartbeatTimer = setInterval(() => {
+            if (socket.readyState !== WebSocket.OPEN)
+                return;
+            if (pingSentAt != null && Date.now() - pingSentAt > policy.pongTimeout) {
+                // Silent half-open TCP: the ping this socket owes an answer to went out long enough ago
+                // that any live peer would have replied — force the close its own stack would eventually
+                // notice on its own, minutes later.
+                socket.close(SOCKET_HEARTBEAT_TIMEOUT_CODE);
+                return;
+            }
+            // Measured from the PING rather than from the last frame: a hidden tab's timers are
+            // throttled to about one wake-up a minute, so "nothing has arrived for longer than a
+            // heartbeat interval" is what throttling looks like, not what a dead socket looks like —
+            // it used to kill a perfectly healthy backgrounded connection on every wake-up.
+            pingSentAt = Date.now();
+            socket.send(JSON.stringify({ type: 'ping' }));
+        }, policy.heartbeat);
+    };
+    const computeDelay = (attempt) => {
+        const raw = Math.min(policy.maxDelay, policy.minDelay * Math.pow(policy.factor, attempt - 1));
+        const span = raw * policy.jitter;
+        const jittered = raw + (Math.random() * 2 - 1) * span;
+        return Math.max(policy.minDelay, Math.min(policy.maxDelay, Math.round(jittered)));
+    };
+    const finish = async (code) => {
+        if (finished)
+            return;
+        finished = true;
+        closedByClient = true;
+        clearTimers();
+        onStatus?.('lost');
+        await emitSystem(SocketSystemEvent.Close, { code });
+        settle(new SocketConnectionError('lost'));
+    };
+    // No `Close` frame here: the connection stays revivable, and `close` means gone for good.
+    const giveUp = async () => {
+        lost = true;
+        clearTimers();
+        onStatus?.('lost');
+        await emitSystem(SocketSystemEvent.Lost, {});
+        settle(new SocketConnectionError('lost'));
+    };
+    const scheduleReconnect = () => {
+        if (outageStartedAt == null)
+            outageStartedAt = Date.now();
+        if (Date.now() - outageStartedAt >= outageBudget) {
+            void giveUp();
+            return;
+        }
+        attempts += 1;
+        const delay = computeDelay(attempts);
+        onStatus?.('reconnecting');
+        void emitSystem(SocketSystemEvent.Reconnecting, { attempt: attempts, delay });
+        retryTimer = setTimeout(() => { retryTimer = null; void attemptConnect(); }, delay);
+    };
+    const attemptConnect = async () => {
+        if (closedByClient)
+            return;
+        let socket;
+        try {
+            socket = await open();
+        }
+        catch {
+            if (retry)
+                scheduleReconnect();
+            else
+                void finish(1006);
+            return;
+        }
+        if (closedByClient) {
+            // Closed while this handshake was in flight — nobody is left to own the socket.
+            socket.close(1000);
+            return;
+        }
+        onOpened(socket);
+    };
+    const revive = () => {
+        if (finished)
+            return;
+        if (lost) {
+            lost = false;
+            attempts = 1;
+            outageStartedAt = Date.now();
+            outageBudget = policy.reviveBudget;
+            onStatus?.('reconnecting');
+            void emitSystem(SocketSystemEvent.Reconnecting, { attempt: attempts, delay: 0 });
+            void attemptConnect();
+            return;
+        }
+        // Still retrying: never give up sooner than a revived connection would — otherwise a retry of
+        // its lost siblings is undone moments later when this one's older budget runs out, even by an
+        // attempt already in flight — and attempt now rather than after the backoff.
+        if (current != null)
+            return;
+        const now = Date.now();
+        if (outageStartedAt != null && outageBudget - (now - outageStartedAt) < policy.reviveBudget) {
+            outageStartedAt = now;
+            outageBudget = policy.reviveBudget;
+        }
+        if (retryTimer == null)
+            return;
+        clearTimeout(retryTimer);
+        retryTimer = null;
+        void attemptConnect();
+    };
+    const onOpened = (socket) => {
+        current = socket;
+        const wasRetry = attempts > 0;
+        const receiveMessage = async (event) => {
+            // Any frame at all answers the outstanding ping — the point is liveness, not pongs.
+            pingSentAt = null;
+            if (typeof event.data === 'string') {
+                try {
+                    if (JSON.parse(event.data)?.type === 'pong')
+                        return;
+                }
+                catch {
+                    // The shared parser below reports malformed JSON consistently.
+                }
+            }
+            await model.receive(event.data);
+        };
+        const messageHandler = (event) => {
+            void receiveMessage(event).catch(error => {
+                log.warn('WebSocket message rejected', { error });
+                socket.close(1008);
+            });
+        };
+        const errorHandler = () => {
+            // The close event that always follows carries the code; nothing actionable here beyond
+            // keeping the browser's own unhandled-error reporting quiet for it.
+        };
+        const closeHandler = async (event) => {
+            if (current !== socket)
+                return;
+            socket.removeEventListener('message', messageHandler);
+            socket.removeEventListener('close', closeHandler);
+            socket.removeEventListener('error', errorHandler);
+            clearHeartbeat();
+            current = null;
+            if (closedByClient) {
+                await emitSystem(SocketSystemEvent.Close, { code: event.code });
+                return;
+            }
+            if (!retry || TERMINAL_CLOSE_CODES.has(event.code)) {
+                await finish(event.code);
+                return;
+            }
+            if (model._authSequence != null) {
+                model._authSequence.reject(new SocketConnectionError('disconnected'));
+                model._authSequence = undefined;
+            }
+            model.stage = AuthenticationStage.Init;
+            await emitSystem(SocketSystemEvent.Disconnected, { code: event.code });
+            scheduleReconnect();
+        };
+        socket.addEventListener('message', messageHandler);
+        socket.addEventListener('close', closeHandler);
+        socket.addEventListener('error', errorHandler);
+        startHeartbeat(socket);
+        if (stableTimer != null)
+            clearTimeout(stableTimer);
+        stableTimer = setTimeout(() => {
+            attempts = 0;
+            outageStartedAt = null;
+            outageBudget = policy.budget;
+        }, policy.stableAfter);
+        onStatus?.('online');
+        settle();
+        if (wasRetry)
+            void emitSystem(SocketSystemEvent.Reconnected, { attempts });
+    };
     model.send = async (message) => {
-        if (typeof message !== 'string') {
+        if (typeof message !== 'string')
             model.prepare?.(message);
-        }
-        if (conn.readyState === WebSocket.OPEN) {
-            conn.send(typeof message === 'string' ? message : JSON.stringify(message));
+        if (current?.readyState === WebSocket.OPEN) {
+            current.send(typeof message === 'string' ? message : JSON.stringify(message));
         }
     };
     model.close = async () => {
-        if (conn.readyState === WebSocket.OPEN || conn.readyState === WebSocket.CONNECTING) {
-            conn.close();
+        if (finished)
+            return;
+        finished = true;
+        closedByClient = true;
+        clearTimers();
+        if (current != null && (current.readyState === WebSocket.OPEN || current.readyState === WebSocket.CONNECTING)) {
+            current.close(1000);
         }
-        // @TODO Make sure it trigger close observers
+        else {
+            // No live socket to fire a close event from — mid-retry, or closed before the first open
+            // ever resolved — so report the same frame directly.
+            await emitSystem(SocketSystemEvent.Close, { code: 1000 });
+        }
+        settle(new SocketConnectionError('closed'));
     };
     model.authenticate = async (_stage, _payload) => {
         // @TODO Provide authentication flow logic here
@@ -24,24 +277,7 @@ export const makeConnection = (conn, _context) => {
         message.dt = message.dt ?? Date.now();
         return message;
     };
-    const messageHandler = async (message) => {
-        await model.receive(message.data);
-    };
-    const closeHandler = async (event) => {
-        const msg = {
-            type: MessageType.System,
-            event: 'close',
-            payload: { code: event.code }
-        };
-        if (model.prepare != null) {
-            model.prepare(msg);
-        }
-        await Promise.all(model.getListeners().map(async (listener) => listener(msg)));
-        conn.removeEventListener('message', messageHandler);
-        conn.removeEventListener('close', closeHandler);
-    };
-    conn.addEventListener('message', messageHandler);
-    conn.addEventListener('close', closeHandler);
-    return model;
+    void attemptConnect();
+    return { connection: model, ready, revive };
 };
 //# sourceMappingURL=connection.js.map

package/build/utils/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAErE,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,IAAe,EAAE,QAAW,EAChB,EAAE;IACd,MAAM,KAAK,GAAG,qBAAqB,EAAE,CAAA;IAErC,KAAK,CAAC,IAAI,GAAG,KAAK,EAAC,OAAO,EAAC,EAAE;QAC3B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,KAAK,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAA;QAC1B,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;QAC5E,CAAC;IACH,CAAC,CAAA;IAED,KAAK,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE;QACvB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,UAAU,EAAE,CAAC;YACnF,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;QACD,6CAA6C;IAC/C,CAAC,CAAA;IAED,KAAK,CAAC,YAAY,GAAG,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;QAC9C,+CAA+C;QAC/C,OAAO,EAAS,CAAA;IAClB,CAAC,CAAA;IAED,KAAK,CAAC,OAAO,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE;QACtC,wCAAwC;QACxC,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAA;QACrC,OAAO,OAAO,CAAA;IAChB,CAAC,CAAA;IAED,MAAM,cAAc,GAAG,KAAK,EAAE,OAAqB,EAAE,EAAE;QACrD,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,CAAC,CAAA;IACD,MAAM,YAAY,GAAG,KAAK,EAAE,KAAiB,EAAE,EAAE;QAC/C,MAAM,GAAG,GAA+B;YACtC,IAAI,EAAE,WAAW,CAAC,MAAM;YACxB,KAAK,EAAE,OAAO;YACd,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;SAC9B,CAAA;QACD,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;YAC1B,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QACpB,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,KAAK,EAAC,QAAQ,EAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QAC5E,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE,cAAc,CAAC,CAAA;QACnD,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;IACjD,CAAC,CAAA;IACD,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE,cAAc,CAAC,CAAA;IAChD,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;IAE5C,OAAO,KAAK,CAAA;AACd,CAAC,CAAA"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,qBAAqB,EAAE,WAAW,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAA;AAC7K,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAGxD,MAAM,GAAG,GAAG,MAAM,CAAC,eAAe,CAAC,CAAA;AAEnC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAA8B,EAAqB,EAAE;IAClF,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;IAC9C,MAAM,KAAK,GAAG,qBAAqB,EAAE,CAAA;IAErC,IAAI,OAAO,GAAqB,IAAI,CAAA;IACpC,IAAI,cAAc,GAAG,KAAK,CAAA;IAC1B,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,4FAA4F;IAC5F,IAAI,IAAI,GAAG,KAAK,CAAA;IAChB,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,IAAI,eAAe,GAAkB,IAAI,CAAA;IACzC,IAAI,YAAY,GAAG,MAAM,CAAC,MAAM,CAAA;IAChC,IAAI,WAAW,GAAyC,IAAI,CAAA;IAC5D,IAAI,UAAU,GAAyC,IAAI,CAAA;IAC3D,IAAI,cAAc,GAA0C,IAAI,CAAA;IAChE,uFAAuF;IACvF,IAAI,UAAU,GAAkB,IAAI,CAAA;IAEpC,IAAI,YAAY,GAAe,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;IAC3C,IAAI,WAAW,GAA2B,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;IACtD,MAAM,KAAK,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,YAAY,GAAG,OAAO,CAAC,CAAC,WAAW,GAAG,MAAM,CAAA,CAAC,CAAC,CAAC,CAAA;IACtG,IAAI,OAAO,GAAG,KAAK,CAAA;IAEnB,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,EAAE;QAC/B,IAAI,OAAO;YAAE,OAAM;QACnB,OAAO,GAAG,IAAI,CAAA;QACd,IAAI,KAAK,IAAI,IAAI;YAAE,WAAW,CAAC,KAAK,CAAC,CAAA;;YAChC,YAAY,EAAE,CAAA;IACrB,CAAC,CAAA;IAED,MAAM,UAAU,GAAG,KAAK,EAAM,KAAwB,EAAE,OAAU,EAAiB,EAAE;QACnF,MAAM,GAAG,GAAgB,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;QACrE,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAA;QACpB,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,KAAK,EAAC,QAAQ,EAAC,EAAE;YAC1D,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAA;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,GAAG,CAAC,KAAK,CAAC,+BAA+B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;YACvD,CAAC;QACH,CAAC,CAAC,CAAC,CAAA;IACL,CAAC,CAAA;IAED,MAAM,cAAc,GAAG,GAAG,EAAE;QAC1B,IAAI,cAAc,IAAI,IAAI,EAAE,CAAC;YAAC,aAAa,CAAC,cAAc,CAAC,CAAC;YAAC,cAAc,GAAG,IAAI,CAAA;QAAC,CAAC;IACtF,CAAC,CAAA;IAED,MAAM,WAAW,GAAG,GAAG,EAAE;QACvB,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;YAAC,YAAY,CAAC,UAAU,CAAC,CAAC;YAAC,UAAU,GAAG,IAAI,CAAA;QAAC,CAAC;QACvE,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;YAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAAC,WAAW,GAAG,IAAI,CAAA;QAAC,CAAC;QAC1E,cAAc,EAAE,CAAA;IAClB,CAAC,CAAA;IAED,MAAM,cAAc,GAAG,CAAC,MAAiB,EAAE,EAAE;QAC3C,UAAU,GAAG,IAAI,CAAA;QACjB,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;YAChC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI;gBAAE,OAAM;YAChD,IAAI,UAAU,IAAI,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;gBACvE,wFAAwF;gBACxF,yFAAyF;gBACzF,oCAAoC;gBACpC,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAA;gBAC3C,OAAM;YACR,CAAC;YACD,oFAAoF;YACpF,qFAAqF;YACrF,yFAAyF;YACzF,gFAAgF;YAChF,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YACvB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;QAC/C,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAA;IACtB,CAAC,CAAA;IAED,MAAM,YAAY,GAAG,CAAC,OAAe,EAAU,EAAE;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;QAC7F,MAAM,IAAI,GAAG,GAAG,GAAG,MAAM,CAAC,MAAM,CAAA;QAChC,MAAM,QAAQ,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAA;QACrD,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IACnF,CAAC,CAAA;IAED,MAAM,MAAM,GAAG,KAAK,EAAE,IAAY,EAAE,EAAE;QACpC,IAAI,QAAQ;YAAE,OAAM;QACpB,QAAQ,GAAG,IAAI,CAAA;QACf,cAAc,GAAG,IAAI,CAAA;QACrB,WAAW,EAAE,CAAA;QACb,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAA;QAClB,MAAM,UAAU,CAAC,iBAAiB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;QACnD,MAAM,CAAC,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAA;IAC3C,CAAC,CAAA;IAED,0FAA0F;IAC1F,MAAM,MAAM,GAAG,KAAK,IAAI,EAAE;QACxB,IAAI,GAAG,IAAI,CAAA;QACX,WAAW,EAAE,CAAA;QACb,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAA;QAClB,MAAM,UAAU,CAAC,iBAAiB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QAC5C,MAAM,CAAC,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAA;IAC3C,CAAC,CAAA;IAED,MAAM,iBAAiB,GAAG,GAAG,EAAE;QAC7B,IAAI,eAAe,IAAI,IAAI;YAAE,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACzD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,IAAI,YAAY,EAAE,CAAC;YACjD,KAAK,MAAM,EAAE,CAAA;YACb,OAAM;QACR,CAAC;QACD,QAAQ,IAAI,CAAC,CAAA;QACb,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;QACpC,QAAQ,EAAE,CAAC,cAAc,CAAC,CAAA;QAC1B,KAAK,UAAU,CAAC,iBAAiB,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;QAC7E,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC,KAAK,cAAc,EAAE,CAAA,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;IACpF,CAAC,CAAA;IAED,MAAM,cAAc,GAAG,KAAK,IAAI,EAAE;QAChC,IAAI,cAAc;YAAE,OAAM;QAC1B,IAAI,MAAiB,CAAA;QACrB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,EAAE,CAAA;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,KAAK;gBAAE,iBAAiB,EAAE,CAAA;;gBACzB,KAAK,MAAM,CAAC,IAAI,CAAC,CAAA;YACtB,OAAM;QACR,CAAC;QACD,IAAI,cAAc,EAAE,CAAC;YACnB,gFAAgF;YAChF,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAClB,OAAM;QACR,CAAC;QACD,QAAQ,CAAC,MAAM,CAAC,CAAA;IAClB,CAAC,CAAA;IAED,MAAM,MAAM,GAAG,GAAG,EAAE;QAClB,IAAI,QAAQ;YAAE,OAAM;QACpB,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,GAAG,KAAK,CAAA;YACZ,QAAQ,GAAG,CAAC,CAAA;YACZ,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YAC5B,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;YAClC,QAAQ,EAAE,CAAC,cAAc,CAAC,CAAA;YAC1B,KAAK,UAAU,CAAC,iBAAiB,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA;YAChF,KAAK,cAAc,EAAE,CAAA;YACrB,OAAM;QACR,CAAC;QACD,8FAA8F;QAC9F,8FAA8F;QAC9F,6EAA6E;QAC7E,IAAI,OAAO,IAAI,IAAI;YAAE,OAAM;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,IAAI,eAAe,IAAI,IAAI,IAAI,YAAY,GAAG,CAAC,GAAG,GAAG,eAAe,CAAC,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC;YAC5F,eAAe,GAAG,GAAG,CAAA;YACrB,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;QACpC,CAAC;QACD,IAAI,UAAU,IAAI,IAAI;YAAE,OAAM;QAC9B,YAAY,CAAC,UAAU,CAAC,CAAA;QACxB,UAAU,GAAG,IAAI,CAAA;QACjB,KAAK,cAAc,EAAE,CAAA;IACvB,CAAC,CAAA;IAED,MAAM,QAAQ,GAAG,CAAC,MAAiB,EAAE,EAAE;QACrC,OAAO,GAAG,MAAM,CAAA;QAChB,MAAM,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAA;QAE7B,MAAM,cAAc,GAAG,KAAK,EAAE,KAAmB,EAAE,EAAE;YACnD,oFAAoF;YACpF,UAAU,GAAG,IAAI,CAAA;YACjB,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,MAAM;wBAAE,OAAM;gBACrD,CAAC;gBAAC,MAAM,CAAC;oBACP,+DAA+D;gBACjE,CAAC;YACH,CAAC;YACD,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACjC,CAAC,CAAA;QACD,MAAM,cAAc,GAAG,CAAC,KAAmB,EAAE,EAAE;YAC7C,KAAK,cAAc,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;gBACvC,GAAG,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;gBACjD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACpB,CAAC,CAAC,CAAA;QACJ,CAAC,CAAA;QACD,MAAM,YAAY,GAAG,GAAG,EAAE;YACxB,uFAAuF;YACvF,oEAAoE;QACtE,CAAC,CAAA;QACD,MAAM,YAAY,GAAG,KAAK,EAAE,KAAiB,EAAE,EAAE;YAC/C,IAAI,OAAO,KAAK,MAAM;gBAAE,OAAM;YAC9B,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,cAAc,CAAC,CAAA;YACrD,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;YACjD,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;YACjD,cAAc,EAAE,CAAA;YAChB,OAAO,GAAG,IAAI,CAAA;YAEd,IAAI,cAAc,EAAE,CAAC;gBACnB,MAAM,UAAU,CAAC,iBAAiB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;gBAC/D,OAAM;YACR,CAAC;YACD,IAAI,CAAC,KAAK,IAAI,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnD,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBACxB,OAAM;YACR,CAAC;YAED,IAAI,KAAK,CAAC,aAAa,IAAI,IAAI,EAAE,CAAC;gBAChC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,qBAAqB,CAAC,cAAc,CAAC,CAAC,CAAA;gBACrE,KAAK,CAAC,aAAa,GAAG,SAAS,CAAA;YACjC,CAAC;YACD,KAAK,CAAC,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAA;YACtC,MAAM,UAAU,CAAC,iBAAiB,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;YACtE,iBAAiB,EAAE,CAAA;QACrB,CAAC,CAAA;QAED,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,cAAc,CAAC,CAAA;QAClD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;QAC9C,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;QAC9C,cAAc,CAAC,MAAM,CAAC,CAAA;QAEtB,IAAI,WAAW,IAAI,IAAI;YAAE,YAAY,CAAC,WAAW,CAAC,CAAA;QAClD,WAAW,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,QAAQ,GAAG,CAAC,CAAA;YACZ,eAAe,GAAG,IAAI,CAAA;YACtB,YAAY,GAAG,MAAM,CAAC,MAAM,CAAA;QAC9B,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;QAEtB,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAA;QACpB,MAAM,EAAE,CAAA;QACR,IAAI,QAAQ;YAAE,KAAK,UAAU,CAAC,iBAAiB,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC5E,CAAC,CAAA;IAED,KAAK,CAAC,IAAI,GAAG,KAAK,EAAC,OAAO,EAAC,EAAE;QAC3B,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,KAAK,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAA;QACzD,IAAI,OAAO,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YAC3C,OAAO,CAAC,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;QAC/E,CAAC;IACH,CAAC,CAAA;IAED,KAAK,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE;QACvB,IAAI,QAAQ;YAAE,OAAM;QACpB,QAAQ,GAAG,IAAI,CAAA;QACf,cAAc,GAAG,IAAI,CAAA;QACrB,WAAW,EAAE,CAAA;QACb,IAAI,OAAO,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9G,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACrB,CAAC;aAAM,CAAC;YACN,yFAAyF;YACzF,qDAAqD;YACrD,MAAM,UAAU,CAAC,iBAAiB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QAC3D,CAAC;QACD,MAAM,CAAC,IAAI,qBAAqB,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC7C,CAAC,CAAA;IAED,KAAK,CAAC,YAAY,GAAG,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;QAC9C,+CAA+C;QAC/C,OAAO,EAAS,CAAA;IAClB,CAAC,CAAA;IAED,KAAK,CAAC,OAAO,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE;QACtC,wCAAwC;QACxC,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAA;QACrC,OAAO,OAAO,CAAA;IAChB,CAAC,CAAA;IAED,KAAK,cAAc,EAAE,CAAA;IAErB,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAC7C,CAAC,CAAA"}

package/build/utils/consts.local.d.ts

@@ -0,0 +1,6 @@
+/** Close codes that mean "this connection is finished on purpose" — never worth retrying: a
+ *  normal closure the SERVER initiated (1000, e.g. the protocol's own one-shot completion) and a
+ *  policy violation (1008, e.g. the guard rejected the frame that opened it). A client-initiated
+ *  close is handled separately, through `closedByClient`. */
+export declare const TERMINAL_CLOSE_CODES: ReadonlySet<number>;
+//# sourceMappingURL=consts.local.d.ts.map

package/build/utils/consts.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.d.ts","sourceRoot":"","sources":["../../src/utils/consts.local.ts"],"names":[],"mappings":"AAAA;;;6DAG6D;AAC7D,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAAyB,CAAA"}

package/build/utils/consts.local.js

@@ -0,0 +1,6 @@
+/** Close codes that mean "this connection is finished on purpose" — never worth retrying: a
+ *  normal closure the SERVER initiated (1000, e.g. the protocol's own one-shot completion) and a
+ *  policy violation (1008, e.g. the guard rejected the frame that opened it). A client-initiated
+ *  close is handled separately, through `closedByClient`. */
+export const TERMINAL_CLOSE_CODES = new Set([1000, 1008]);
+//# sourceMappingURL=consts.local.js.map

package/build/utils/consts.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.js","sourceRoot":"","sources":["../../src/utils/consts.local.ts"],"names":[],"mappings":"AAAA;;;6DAG6D;AAC7D,MAAM,CAAC,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA"}

package/build/utils/index.d.ts

@@ -1,2 +1,3 @@
 export * from './connection.js';
+export type * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/build/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,cAAc,iBAAiB,CAAA;AAC/B,mBAAmB,YAAY,CAAA"}

package/build/utils/types.d.ts

@@ -0,0 +1,31 @@
+import type { ReconnectPolicy, SocketConnectionState } from '../types.js';
+import type { Connection } from '@owlmeans/socket';
+export interface ConnectionOpener {
+    (): Promise<WebSocket>;
+}
+export interface ManagedConnectionOptions {
+    policy: ReconnectPolicy;
+    /** Whether a drop schedules a retry at all. `false` keeps the pre-reconnect-support
+     *  behaviour — one attempt, report and stop — while the heartbeat/liveness check below still
+     *  runs exactly as it always did. */
+    retry: boolean;
+    /** Opens a fresh socket for the first attempt and every retry — already reflecting whatever a
+     *  caller's `beforeConnect` refreshed (a token, most often). Resolves once the socket is OPEN,
+     *  rejects on a handshake failure. */
+    open: ConnectionOpener;
+    /** Told this connection's coarse health, if a caller wants to aggregate it — the status
+     *  service `@owlmeans/web-panel`'s reload dialog reads. */
+    onStatus?: (state: SocketConnectionState) => void;
+}
+export interface ManagedConnection {
+    connection: Connection;
+    /** Settles once the first socket opens; rejects with `SocketConnectionError('lost')` once the
+     *  retry budget elapses first (or the single attempt fails, with `retry: false`). */
+    ready: Promise<void>;
+    /** Restart retrying a connection that gave up after its budget: one attempt at once, then the
+     *  usual backoff within `policy.reviveBudget`. On a connection still waiting out a backoff
+     *  delay: attempt at once, and leave it at least `reviveBudget`. A no-op otherwise — a terminal
+     *  close (client close, 1000/1008, `retry: false`) is never revived. */
+    revive: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/utils/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,OAAO,CAAC,SAAS,CAAC,CAAA;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,eAAe,CAAA;IACvB;;yCAEqC;IACrC,KAAK,EAAE,OAAO,CAAA;IACd;;0CAEsC;IACtC,IAAI,EAAE,gBAAgB,CAAA;IACtB;+DAC2D;IAC3D,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAClD;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,UAAU,CAAA;IACtB;yFACqF;IACrF,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACpB;;;4EAGwE;IACxE,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB"}

package/build/utils/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/utils/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/client-socket",
-  "version": "0.1.18-rc.5",
+  "version": "0.1.18-rc.50",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 132 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -25,19 +26,22 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/react": "^19.2.17",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.3.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.5",
-    "@owlmeans/basic-envelope": "^0.1.18-rc.5",
-    "@owlmeans/client": "^0.1.18-rc.5",
-    "@owlmeans/client-context": "^0.1.18-rc.5",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.5",
-    "@owlmeans/context": "^0.1.18-rc.5",
-    "@owlmeans/entrypoint": "^0.1.18-rc.5",
-    "@owlmeans/socket": "^0.1.18-rc.5"
+    "@owlmeans/auth": "^0.1.18-rc.40",
+    "@owlmeans/basic-envelope": "^0.1.18-rc.47",
+    "@owlmeans/basic-ids": "^0.1.18-rc.38",
+    "@owlmeans/client": "^0.1.18-rc.52",
+    "@owlmeans/client-context": "^0.1.18-rc.49",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.48",
+    "@owlmeans/context": "^0.1.18-rc.34",
+    "@owlmeans/entrypoint": "^0.1.18-rc.41",
+    "@owlmeans/log": "^0.1.18-rc.2",
+    "@owlmeans/socket": "^0.1.18-rc.41"
   },
   "publishConfig": {
     "access": "public"

package/src/consts.local.ts

@@ -0,0 +1,3 @@
+import type { SocketConnectionState } from './types.js'
+
+export const RANK: Record<SocketConnectionState, number> = { online: 0, reconnecting: 1, lost: 2 }

package/src/consts.ts

@@ -0,0 +1,20 @@
+
+import type { ReconnectPolicy } from './types.js'
+
+/**
+ * 0.2s → 3s geometric backoff, retried for up to 10 minutes before the carrier gives up and
+ * reports the connection lost. See the client-socket skill's "Disconnects" section.
+ */
+export const DEFAULT_RECONNECT_POLICY: ReconnectPolicy = {
+  minDelay: 200,
+  maxDelay: 3_000,
+  factor: 2,
+  jitter: 0.1,
+  budget: 600_000,
+  reviveBudget: 15_000,
+  stableAfter: 10_000,
+  heartbeat: 30_000,
+  pongTimeout: 10_000,
+}
+
+export const SOCKET_STATUS = 'socket-status'

package/src/helper/types.ts

@@ -0,0 +1,20 @@
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { Connection } from '@owlmeans/socket'
+import type { ConnectOptions, Context, WsOptions } from '../types.js'
+
+/** Opens managed sockets that restore themselves after a network failure. */
+export interface SocketClientHelper {
+  /**
+   * Open a socket with no declared entrypoint behind it — the primitive `ws()` builds on, and what
+   * a test drives directly against a bare WebSocket server.
+   */
+  connect: (address: () => Promise<string> | string, ctx: Context, options?: ConnectOptions) => Promise<Connection>
+  /**
+   * Open a socket through a declared entrypoint protocol, restoring it on its own after a network
+   * failure — see the client-socket skill's "Disconnects" section for the full policy. Resolves
+   * once the first attempt opens; rejects with `SocketConnectionError('lost')` if the retry budget
+   * elapses before that ever happens (or the single attempt fails, with `reconnect: false`).
+   */
+  ws: (module: ClientEntrypoint<string>, request?: AbstractRequest<{ token?: string }>, options?: WsOptions) => Promise<Connection>
+}