@steve31415/baselib 3.25.0 → 3.26.0

package/dist/sync-browser/client.d.ts

@@ -145,6 +145,7 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private halted;
     private refetchInFlight;
     private probeInFlight;
+    private probeRequested;
     private resyncTimes;
     /** Forward-gap events delivered while a resync is reconciling; drained
      * after the bootstrap installs. Non-null exactly while reconciling. */
@@ -200,6 +201,7 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private onBecameVisible;
     private onOnline;
     private wakeConnection;
+    private logConnectTimeout;
     /** Drops the current socket, if any, without treating it as an outage, and
      * connects at once. */
     private replaceSocket;
@@ -226,6 +228,12 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
      * (once per return); anything else takes the ladder. */
     private takeQuickRetry;
     private scheduleReconnect;
+    /** One HTTP round trip while the visible socket is down: delivers pending
+     * events (`postEvents`), then catches up — which applies their echoes, so
+     * the writes confirm — and doubles as the session probe (an expired
+     * session halts through the auth state). A WebSocket handshake can be
+     * stuck for minutes behind another one in the browser's per-IP queue while
+     * HTTP works at once (notes, 2026-10-01), so writes must not wait for it. */
     private probeSession;
     private startOutage;
     /** ERROR only after OUTAGE_ESCALATE_MS of visible, on-time outage; re-armed

package/dist/sync-browser/client.js

@@ -27,6 +27,14 @@ const RETURN_REPORT_TIMEOUT_MS = 15_000;
  * without reaching the server, while HTTP works at once; the ladder's 1 s
  * step then made every such return take 1.5-2 s (reader, 2026-09-26). */
 const RETURN_QUICK_RETRY_MS = 250;
+/** A handshake that takes at least this long to open, or to fail on its own,
+ * is logged (INFO): it either sat in the browser's per-IP handshake queue or
+ * stalled itself. Chrome runs one WebSocket handshake per server IP:port at a
+ * time, across every tab and hostname; all fleet apps share the load
+ * balancer's IP, so one stalled handshake holds every app's sockets until it
+ * resolves (notes, 2026-10-01: four minutes). Fast failures (offline) are
+ * not logged. */
+const SLOW_HANDSHAKE_MS = 3_000;
 const SOCKET_CONNECTING = 0;
 const SOCKET_OPEN = 1;
 class LifecycleAbort {
@@ -71,6 +79,7 @@ export class SyncClient {
     halted = false;
     refetchInFlight = false;
     probeInFlight = false;
+    probeRequested = false;
     resyncTimes = [];
     /** Forward-gap events delivered while a resync is reconciling; drained
      * after the bootstrap installs. Non-null exactly while reconciling. */
@@ -105,6 +114,7 @@ export class SyncClient {
         backgroundCatchups: 0,
         backgroundCatchupFailures: 0,
         backgroundSocketAttempts: 0,
+        httpPostedEvents: 0,
     };
     constructor(options) {
         this.options = options;
@@ -222,6 +232,11 @@ export class SyncClient {
         this.options.store.applyOptimistic(event);
         this.armFailureTimer(event.eventGuid);
         this.trySend(entry);
+        // A visible page in an outage delivers over HTTP at once rather than
+        // waiting for a handshake that may be stuck behind another one.
+        if (!this.isHidden() && this.outageStartedAt !== null && this.socket?.readyState !== SOCKET_OPEN) {
+            void this.probeSession();
+        }
         this.updatePendingState();
         this.options.onSafetyChange?.();
     }
@@ -301,6 +316,7 @@ export class SyncClient {
             backgroundCatchups: now.backgroundCatchups - since.backgroundCatchups,
             backgroundCatchupFailures: now.backgroundCatchupFailures - since.backgroundCatchupFailures,
             backgroundSocketAttempts: now.backgroundSocketAttempts - since.backgroundSocketAttempts,
+            httpPostedEvents: now.httpPostedEvents - since.httpPostedEvents,
         };
     }
     onBecameHidden() {
@@ -379,12 +395,25 @@ export class SyncClient {
         // closing is gone too. Waiting on either routes the returning user
         // through the watchdog's close and a full backoff step (16-30 s of
         // "Reconnecting…" observed on reader, 2026-09-24).
-        if (socket?.readyState === SOCKET_CONNECTING &&
-            this.options.runtime.now() - this.socketCreatedAt < CONNECT_WATCHDOG_MS) {
-            return;
+        if (socket?.readyState === SOCKET_CONNECTING) {
+            const socketAgeMs = this.options.runtime.now() - this.socketCreatedAt;
+            if (socketAgeMs < CONNECT_WATCHDOG_MS)
+                return;
+            // Its watchdog never ran: a throttled or frozen hidden page, the case
+            // that can hold the browser's handshake queue past 10 s.
+            this.logConnectTimeout(socketAgeMs, { replacedOnReturn: true });
         }
         this.replaceSocket();
     }
+    logConnectTimeout(socketAgeMs, extra = {}) {
+        this.options.logger.info('sync connect timeout', {
+            socketAgeMs,
+            lateMs: Math.max(0, socketAgeMs - CONNECT_WATCHDOG_MS),
+            createdHidden: this.socketCreatedHidden,
+            hidden: this.isHidden(),
+            ...extra,
+        });
+    }
     /** Drops the current socket, if any, without treating it as an outage, and
      * connects at once. */
     replaceSocket() {
@@ -422,9 +451,12 @@ export class SyncClient {
         this.socketOpenedAt = null;
         if (this.socketCreatedHidden)
             this.counters.backgroundSocketAttempts++;
+        let killedByWatchdog = false;
         this.watchdogTimer = this.options.runtime.setTimeout(() => {
             if (socket.readyState !== SOCKET_OPEN) {
                 this.counters.watchdogKills++;
+                killedByWatchdog = true;
+                this.logConnectTimeout(this.options.runtime.now() - this.socketCreatedAt);
                 socket.close();
             }
         }, CONNECT_WATCHDOG_MS);
@@ -437,6 +469,14 @@ export class SyncClient {
                 this.options.runtime.clearTimeout(this.watchdogTimer);
             this.watchdogTimer = null;
             this.socketOpenedAt = this.now();
+            const openMs = this.socketOpenedAt - this.socketCreatedAt;
+            if (openMs >= SLOW_HANDSHAKE_MS) {
+                this.options.logger.info('sync connect slow', {
+                    openMs,
+                    createdHidden: this.socketCreatedHidden,
+                    hidden: this.isHidden(),
+                });
+            }
             this.cancelBackgroundTick();
             this.sendConnect();
             this.pingTimer = this.options.runtime.setInterval(() => this.sendRaw({ type: 'ping' }), PING_INTERVAL_MS);
@@ -462,6 +502,15 @@ export class SyncClient {
             this.socket = null;
             if (this.halted || this.disposed)
                 return;
+            const socketAgeMs = this.now() - this.socketCreatedAt;
+            if (this.socketOpenedAt === null && !killedByWatchdog && socketAgeMs >= SLOW_HANDSHAKE_MS) {
+                this.options.logger.info('sync connect failed', {
+                    socketAgeMs,
+                    closeCode: event.code,
+                    createdHidden: this.socketCreatedHidden,
+                    hidden: this.isHidden(),
+                });
+            }
             if (event.code === CLOSE_NO_USER) {
                 this.options.authState.markBlocked();
                 this.halt();
@@ -550,6 +599,8 @@ export class SyncClient {
             if (this.stopBeforeStoreMutation())
                 return;
             for (const outcome of outcomes) {
+                if (outcome.status !== 'rejected')
+                    this.counters.httpPostedEvents++;
                 if (outcome.status === 'rejected') {
                     this.handleRejection({
                         type: 'rejection',
@@ -729,8 +780,9 @@ export class SyncClient {
         const delay = Math.ceil(delayMs / 1000);
         this.reconnectAttempts++;
         this.totalAttempts++;
-        if (this.reconnectAttempts >= PROBE_AFTER_ATTEMPTS)
+        if (this.reconnectAttempts >= PROBE_AFTER_ATTEMPTS || this.unsettledPending().length > 0) {
             void this.probeSession();
+        }
         let remaining = delay;
         this.publish({ kind: 'reconnecting', pending: this.pendingCount(), inSeconds: remaining });
         this.countdownTimer = this.options.runtime.setInterval(() => {
@@ -747,11 +799,25 @@ export class SyncClient {
             this.connect();
         }, delayMs);
     }
+    /** One HTTP round trip while the visible socket is down: delivers pending
+     * events (`postEvents`), then catches up — which applies their echoes, so
+     * the writes confirm — and doubles as the session probe (an expired
+     * session halts through the auth state). A WebSocket handshake can be
+     * stuck for minutes behind another one in the browser's per-IP queue while
+     * HTTP works at once (notes, 2026-10-01), so writes must not wait for it. */
     async probeSession() {
-        if (this.halted || this.disposed || this.probeInFlight)
+        if (this.halted || this.disposed)
             return;
+        if (this.probeInFlight) {
+            this.probeRequested = true;
+            return;
+        }
         this.probeInFlight = true;
+        this.probeRequested = false;
         try {
+            await this.postPendingOverHttp();
+            if (this.stopBeforeStoreMutation())
+                return;
             const result = await this.abortable((signal) => this.options.fetchCatchup(this.options.store.currentSeq(), signal));
             if (this.stopBeforeStoreMutation())
                 return;
@@ -771,6 +837,11 @@ export class SyncClient {
         finally {
             this.probeInFlight = false;
         }
+        // Something was submitted while this probe was in flight; deliver it
+        // too, unless the socket came back in the meantime.
+        if (this.probeRequested && this.socket?.readyState !== SOCKET_OPEN && !this.isHidden()) {
+            void this.probeSession();
+        }
     }
     startOutage(closeCode, wasClean = false) {
         if (this.outageStartedAt !== null)
@@ -1126,6 +1197,7 @@ export class SyncClient {
                 hiddenMs: delta?.hiddenMs,
                 watchdogKills: delta?.watchdogKills,
                 backgroundCatchups: delta?.backgroundCatchups,
+                httpPostedEvents: delta?.httpPostedEvents,
                 freezes: delta?.freezes,
                 resumes: delta?.resumes,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.25.0",
+  "version": "3.26.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",