cross-tab-worker-databus 0.20.86 → 0.20.88

package/dist/cjs/centrifuge.cjs

@@ -2331,7 +2331,7 @@ var DedupManager = class {
 };
 
 // src/core/version.ts
-var SDK_VERSION = true ? "0.20.86" : "";
+var SDK_VERSION = true ? "0.20.88" : "";
 
 // src/core/data-bus.ts
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
@@ -2356,6 +2356,11 @@ var CrossTabDataBus = class {
   started = false;
   stopping = false;
   transportReady = false;
+  // Whether the installed transport has reported `connected` at least once
+  // since the current open began. A clean `disconnected` after this point is
+  // a lost working connection, not the pre-connect window of a worker-style
+  // backend whose start() resolves before it reports the connection.
+  transportHasConnected = false;
   // Last transport failure, retained so ready() can surface it to callers who
   // never awaited start() directly. Cleared on the next successful start.
   lastError = null;
@@ -2394,6 +2399,19 @@ var CrossTabDataBus = class {
   // a transport reopen succeeds so traces can correlate repeated failures.
   recoveryAttempt = 0;
   recoveryExhausted = false;
+  // Gate that holds transport operations issued after a runtime `error` until
+  // the scheduled recovery attempt has actually run. Without it, a dead
+  // transport still has `transportReady === true` during the cooldown, so
+  // publishes/subscribes would be written to the failed connection and lost.
+  recoveryGate = null;
+  recoveryGateRelease = null;
+  recoveryTimer = null;
+  recoveryTimerToken = 0;
+  // Once an automatic attempt fails, an explicit transport operation may
+  // recover immediately instead of waiting for the next paced attempt. The
+  // gate still stays closed so the operation cannot reach the failed
+  // transport; it is released by the successful on-demand reopen.
+  recoveryDemandAllowed = false;
   /** Monotonic generation incremented on every successful transport open.
    * Stays in lockstep with `lastSuccessAt` so callers can detect that the
    * transport has been reopened even if the timestamp window is short. */
@@ -2507,10 +2525,7 @@ var CrossTabDataBus = class {
           this.suspendTransport();
         },
         onResume: () => {
-          this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.RESUME });
-          this.trace.start();
-          this.startDedupSweep();
-          this.replayManager.start();
+          this.resumeSuspendedResources();
           this.resumeTransport();
         },
         onDiagnostic: (event) => {
@@ -2540,7 +2555,11 @@ var CrossTabDataBus = class {
       if (!transportDown) return Promise.resolve();
       this.activeConfig = config;
       this.resetFailureState();
-      return this.reopenTransport();
+      const resumingFromSuspend = this.suspended;
+      if (resumingFromSuspend) this.resumeSuspendedResources();
+      const opening2 = this.reopenTransport();
+      if (resumingFromSuspend) this.cluster.start();
+      return opening2;
     }
     this.started = true;
     this.stopping = false;
@@ -2612,8 +2631,38 @@ var CrossTabDataBus = class {
     this.queuedStart = queued;
     return queued;
   }
+  /** Release every operation waiting on the scheduled recovery attempt. */
+  releaseRecoveryGate() {
+    const release = this.recoveryGateRelease;
+    this.recoveryGate = null;
+    this.recoveryGateRelease = null;
+    this.recoveryDemandAllowed = false;
+    release?.();
+  }
+  /** Cancel a pending automatic retry when an explicit lifecycle transition
+   * supersedes it. The released gate re-enters runTransport(), which then
+   * follows the newest start/stop/suspend intent. */
+  cancelScheduledRecovery() {
+    this.recoveryTimerToken += 1;
+    if (this.recoveryTimer !== null) {
+      clearTimeout(this.recoveryTimer);
+      this.recoveryTimer = null;
+    }
+    this.releaseRecoveryGate();
+  }
+  /** Keep the recovery gate closed after a failed attempt while allowing the
+   * next explicit transport operation to start an immediate on-demand reopen.
+   * If no gate/successor retry remains, release any waiters. */
+  allowDemandRecovery() {
+    if (this.recoveryGate !== null && this.started && !this.stopping && !this.suspended && this.status === WORKER_STATUS.ERROR) {
+      this.recoveryDemandAllowed = true;
+      return;
+    }
+    this.releaseRecoveryGate();
+  }
   /** Reset failure and recovery diagnostics for a new explicit start session. */
   resetFailureState() {
+    this.cancelScheduledRecovery();
     this.lastError = null;
     this.lastErrorAt = null;
     this.lastFailure = null;
@@ -2633,22 +2682,27 @@ var CrossTabDataBus = class {
     this.transportReady = false;
     const chainedPendingStop = this.pendingStop;
     const isCurrentLifecycle = () => lifecycleEpoch === this.lifecycleEpoch;
+    let startupInProgress = true;
     return before.catch(() => void 0).then(() => {
       if (!isCurrentLifecycle() || this.stopping || this.suspended) return;
       if (this.pendingStop === chainedPendingStop) this.pendingStop = null;
+      this.transportHasConnected = false;
       return Promise.resolve(
         this.transport.start(config, {
           onMessage: (message) => {
             if (isCurrentLifecycle()) this.handleTransportMessage(message);
           },
           onStatus: (status) => {
-            if (isCurrentLifecycle()) this.updateStatus(status);
+            if (isCurrentLifecycle()) {
+              this.updateStatus(status, status !== WORKER_STATUS.ERROR || !startupInProgress);
+            }
           },
           onError: (error) => {
             if (isCurrentLifecycle()) this.reportError(error);
           }
         })
       ).then(() => {
+        startupInProgress = false;
         if (!isCurrentLifecycle()) return;
         if (this.status === WORKER_STATUS.ERROR) {
           throw new Error("Transport failed during startup.");
@@ -2657,24 +2711,26 @@ var CrossTabDataBus = class {
           this.recoveryGeneration += 1;
           this.lastSuccessAt = this.now();
           this.transportReady = true;
+          this.releaseRecoveryGate();
         }
       });
     }).catch((error) => {
       if (!isCurrentLifecycle()) throw error;
+      startupInProgress = false;
       if (stopClusterOnFailure) this.started = false;
       if (!this.pendingStop) {
         this.pendingStop = this.createStopPromise();
       }
-      this.updateStatus(WORKER_STATUS.ERROR);
-      this.reportError(error);
-      this.lastError = error;
-      this.lastErrorAt = this.now();
       this.transportReady = false;
       if (stopClusterOnFailure) {
         this.stopping = true;
         this.cluster.stop();
         this.stopping = false;
       }
+      this.recordError(error);
+      this.startPromise = null;
+      this.updateStatus(WORKER_STATUS.ERROR);
+      this.notifyError(error);
       throw error;
     });
   }
@@ -2683,7 +2739,10 @@ var CrossTabDataBus = class {
    * Returns a rejected promise when the transport has failed and no start is in
    * flight — the caller can retry by calling start() or ready() again. While an
    * explicit stop() is settling, this rejects unless a restart is queued behind
-   * it; false readiness during teardown is never reported.
+   * it; false readiness during teardown is never reported. While the tab is
+   * BFCache-suspended (pagehide without a following pageshow), this also
+   * rejects: the suspended start promise is the transport-stop gate, not a
+   * readiness signal.
    */
   ready() {
     if (this.queuedStart) return this.getQueuedStartReady();
@@ -2692,6 +2751,11 @@ var CrossTabDataBus = class {
         "CrossTabDataBus is stopping; ready() cannot report readiness until stop() resolves. Wait for stop() to resolve, then call start() before awaiting ready()."
       ));
     }
+    if (this.suspended) {
+      return Promise.reject(new Error(
+        "CrossTabDataBus is suspended; ready() cannot report readiness until pageshow resumes the transport."
+      ));
+    }
     if (!this.started && !this.hasInitialConfig && this.lastError !== null) {
       return Promise.reject(this.lastError);
     }
@@ -2827,11 +2891,15 @@ var CrossTabDataBus = class {
   getStatus() {
     return this.status;
   }
-  /** Return the current automatic transport recovery state. `hasError` means a transport error is currently retained. */
   /** Return the current automatic transport recovery state plus diagnostics.
-   * `generation` increments on every successful transport open (initial start
-   * and every recovery); `lastSuccessAt` is the timestamp of the most recent
-   * successful open, or `null` until the transport reaches `ready`. */
+   * `hasError`/`errorMessage`/`errorAt` describe the most recent retained
+   * *transport* failure — from a transport open or a runtime `onError`. They
+   * share the lifetime of the unified `lastFailure` ledger: a successful
+   * recovery keeps the last failure visible, and only an explicit `start()`
+   * clears it. `generation` increments on every successful transport open
+   * (initial start and every recovery); `lastSuccessAt` is the timestamp of
+   * the most recent successful open, or `null` until the transport reaches
+   * `ready`. */
   getRecoveryStats() {
     const errorMessage = this.lastError instanceof Error ? this.lastError.message : this.lastError === null ? null : String(this.lastError);
     return {
@@ -2858,7 +2926,7 @@ var CrossTabDataBus = class {
    * unified failure ledger and recovery context that explains the verdict. */
   getHealthSummary() {
     const transport = this.transport;
-    const transportDown = !this.transportReady || this.status === WORKER_STATUS.ERROR || this.status === WORKER_STATUS.DISCONNECTED;
+    const transportDown = this.status !== WORKER_STATUS.CONNECTED;
     const state = !this.started ? HEALTH_STATE.STOPPED : this.suspended ? HEALTH_STATE.SUSPENDED : transportDown ? this.recoveryExhausted ? HEALTH_STATE.DEGRADED : this.status === WORKER_STATUS.CONNECTING && this.recoveryAttempt === 0 ? HEALTH_STATE.STARTING : HEALTH_STATE.RECOVERING : HEALTH_STATE.HEALTHY;
     return {
       healthy: state === HEALTH_STATE.HEALTHY,
@@ -2949,6 +3017,7 @@ var CrossTabDataBus = class {
   async performStop() {
     this.lifecycleEpoch += 1;
     this.stopping = true;
+    this.cancelScheduledRecovery();
     this.replayManager.suspend();
     this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.STOP });
     this.trace.stop();
@@ -2961,6 +3030,8 @@ var CrossTabDataBus = class {
       const pendingStop = this.pendingStop;
       if (pendingStop) await pendingStop.catch(() => void 0);
       else await this.transport.stop();
+    } catch (error) {
+      this.reportError(error);
     } finally {
       this.transportSubscribedTopics.clear();
       this.resetDedup();
@@ -3023,13 +3094,15 @@ var CrossTabDataBus = class {
    * Propagate a status change to the cluster, trace, and all registered
    * status handlers. On reconnect, re-subscribe any topics assigned to us.
    */
-  updateStatus(status) {
+  updateStatus(status, notifyHandlers = true) {
     const previousStatus = this.status;
     this.status = status;
+    if (status === WORKER_STATUS.CONNECTED) this.transportHasConnected = true;
     if (previousStatus !== status) this.trace.event({ type: TRACE_EVENT_TYPE.STATUS, status });
     this.cluster.setStatus(status);
     if (status === WORKER_STATUS.DISCONNECTED || status === WORKER_STATUS.ERROR) this.transportSubscribedTopics.clear();
     if (status === WORKER_STATUS.CONNECTED && previousStatus !== WORKER_STATUS.CONNECTED) {
+      if (this.transportReady) this.releaseRecoveryGate();
       for (const topic of this.cluster.getSnapshot().assignedTopics) this.subscribeTransport(topic);
     }
     if (status === WORKER_STATUS.ERROR && this.started && !this.stopping) {
@@ -3042,23 +3115,49 @@ var CrossTabDataBus = class {
             this.recoveryExhausted = true;
             this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt: this.recoveryMaxAttempts, outcome: RECOVERY_OUTCOME.EXHAUSTED });
           }
+          this.releaseRecoveryGate();
           return;
         }
         this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt, outcome: RECOVERY_OUTCOME.SCHEDULED });
-        setTimeout(() => {
-          if (this.stopping || !this.started || this.suspended) return;
-          if (this.status !== WORKER_STATUS.ERROR) return;
-          void this.reopenTransport(attempt);
+        if (this.recoveryGate === null) {
+          let release;
+          this.recoveryGate = new Promise((resolve) => {
+            release = resolve;
+          });
+          this.recoveryGateRelease = release;
+        }
+        this.recoveryDemandAllowed = false;
+        const timerToken = ++this.recoveryTimerToken;
+        this.recoveryTimer = setTimeout(() => {
+          if (timerToken !== this.recoveryTimerToken) return;
+          this.recoveryTimer = null;
+          if (this.stopping || !this.started || this.suspended || this.status !== WORKER_STATUS.ERROR) {
+            this.releaseRecoveryGate();
+            return;
+          }
+          this.recoveryDemandAllowed = false;
+          const opening = this.reopenTransport(attempt);
+          void opening.then(
+            () => this.releaseRecoveryGate(),
+            () => this.allowDemandRecovery()
+          );
         }, this.recoveryCooldownMs);
       }
+    } else if (status === WORKER_STATUS.ERROR) {
+      this.releaseRecoveryGate();
     }
-    this.invokeHandlers(this.statusHandlers, (handler) => handler(status));
+    if (notifyHandlers) this.invokeHandlers(this.statusHandlers, (handler) => handler(status));
   }
-  reportError(error, source = FAILURE_SOURCE.TRANSPORT) {
+  recordError(error, source = FAILURE_SOURCE.TRANSPORT) {
+    const at = this.now();
+    if (source === FAILURE_SOURCE.TRANSPORT) {
+      this.lastError = error;
+      this.lastErrorAt = at;
+    }
     this.lastFailure = {
       source,
       message: error instanceof Error ? error.message : String(error),
-      at: this.now()
+      at
     };
     if (source === FAILURE_SOURCE.PERSISTENCE) {
       this.persistenceFailureCount += 1;
@@ -3069,8 +3168,14 @@ var CrossTabDataBus = class {
       type: TRACE_EVENT_TYPE.ERROR,
       source: source === FAILURE_SOURCE.TRANSPORT ? TRACE_ERROR_SOURCE.TRANSPORT : TRACE_ERROR_SOURCE.OPERATION
     });
+  }
+  notifyError(error) {
     this.invokeHandlers(this.errorHandlers, (handler) => handler(error), INVOKE_LABEL.ERROR_HANDLER);
   }
+  reportError(error, source = FAILURE_SOURCE.TRANSPORT) {
+    this.recordError(error, source);
+    this.notifyError(error);
+  }
   /** Report a persistence failure to the trace and the unified failure ledger,
    * unless it is a {@link PersistenceRetryCancelledError} cancellation from a
    * lifecycle transition (teardown should stay quiet). */
@@ -3133,6 +3238,15 @@ var CrossTabDataBus = class {
       }
     }
   }
+  /** Resume the resources paused by a pagehide suspension. Both the native
+   * pageshow path and explicit start() must run this so an explicit resume
+   * cannot leave trace metrics and periodic cleanup timers permanently off. */
+  resumeSuspendedResources() {
+    this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.RESUME });
+    this.trace.start();
+    this.startDedupSweep();
+    this.replayManager.start();
+  }
   /**
    * Suspend the transport when the tab goes hidden. Stops the transport and
    * clears subscription state so it will be re-established on resume.
@@ -3141,11 +3255,15 @@ var CrossTabDataBus = class {
     if (this.stopping) return;
     this.lifecycleEpoch += 1;
     this.suspended = true;
+    this.cancelScheduledRecovery();
     this.transportReady = false;
     this.transportSubscribedTopics.clear();
     this.updateStatus(WORKER_STATUS.DISCONNECTED);
-    if (this.pendingStop) return;
-    const pending = this.startPromise ?? Promise.resolve();
+    if (this.pendingStop && (this.startPromise === null || this.startPromise === this.pendingStop)) {
+      this.startPromise = this.pendingStop;
+      return;
+    }
+    const pending = this.startPromise ?? this.pendingStop ?? Promise.resolve();
     const stopping = pending.catch(() => void 0).then(() => this.transport.stop()).catch((error) => this.reportError(error));
     this.startPromise = stopping;
     this.pendingStop = stopping;
@@ -3210,7 +3328,24 @@ var CrossTabDataBus = class {
    */
   runTransport(operation) {
     if (this.suspended) return;
-    if (this.transportReady && !this.stopping) {
+    if (this.recoveryGate && !this.stopping) {
+      if (this.recoveryDemandAllowed && this.status === WORKER_STATUS.ERROR && !this.suspended) {
+        this.recoveryDemandAllowed = false;
+        const opening = this.reopenTransport();
+        void opening.then(
+          () => this.releaseRecoveryGate(),
+          () => this.allowDemandRecovery()
+        );
+      }
+      const gate = this.recoveryGate;
+      void gate.then(() => {
+        if (this.stopping || this.suspended) return;
+        this.runTransport(operation);
+      });
+      return;
+    }
+    const droppedAfterConnect = this.transportHasConnected && this.status === WORKER_STATUS.DISCONNECTED;
+    if (this.transportReady && this.status !== WORKER_STATUS.ERROR && !droppedAfterConnect && !this.stopping) {
       try {
         void Promise.resolve(operation()).catch((error) => this.reportError(error));
       } catch (error) {
@@ -3223,10 +3358,17 @@ var CrossTabDataBus = class {
       ready = this.reopenTransport();
     }
     if (!ready || this.stopping) return;
-    void ready.then(() => {
-      if (!this.started || this.stopping || this.suspended) return;
-      return operation();
-    }).catch((error) => this.reportError(error));
+    void ready.then(
+      () => {
+        if (!this.started || this.stopping || this.suspended) return;
+        return operation();
+      },
+      // The opening promise reports its own lifecycle failure through
+      // openTransport(). Swallowing it here prevents a stale startup
+      // rejection from being recorded again after an onStatus/onError
+      // callback has already started and reset the ledger for a retry.
+      () => void 0
+    ).catch((error) => this.reportError(error));
   }
   /**
    * Publications started after teardown begins cannot reach any transport.