cross-tab-worker-databus 0.20.86 → 0.20.87

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [Unreleased]
+
+## [0.20.87] - 2026-09-16
+
+### Fixed
+- Transport operations issued after a runtime `error` no longer reach the connection that just failed. While an automatic or demand-driven reopen is pending, `runTransport()` parks `subscribe()` / `publish()` behind a recovery gate and releases them only after a reopen succeeds (or the transport self-heals to `connected`). `transportReady` deliberately stays true through the error so `ready()` keeps tracking the installed transport, which meant a subscribe or publish inside the cooldown window was written to the dead connection and lost. A failed automatic attempt keeps the gate closed but now lets the next explicit operation start an immediate on-demand reopen instead of waiting out another cooldown, and parked operations flush behind that success; exhausting `recovery.maxAttempts`, or superseding the wait with `stop()` / page hide, releases the gate so the explicit-retry path and the documented suspend-drop semantics are unchanged. A clean `disconnected` still never schedules automatic recovery.
+- An operation issued after a clean transport `disconnected` now reopens the transport on demand instead of being written to the closed connection. `runTransport()` previously exempted only `error`, so a `subscribe()` / `publish()` arriving after a clean `close` took the ready fast path and the backend dropped it (the WebSocket send guard reports dropped frames but never sends them). The fast path is now refused once the transport has actually reached `connected` and then reports `disconnected`: the clean close still schedules no background recovery, but the next explicit operation demands exactly one reopen and flushes the parked operation behind it. A transport that resolves `start()` before its first `connected` (worker-style backends report the connection asynchronously) keeps the previous behaviour, so the pre-connect window does not trigger a redundant reopen.
+- `createWebSocketDataBus()` automatic recovery now actually reopens a failed WebSocket. `WebSocketTransport.start()` previously returned whenever `this.socket` was non-null, and an error/close left that reference in place, so every post-cooldown `reopenTransport()` was a no-op against the dead socket. The transport now tracks whether the current socket is active, replaces the stale connection on the next `start()`, re-sends subscriptions after the replacement opens, and ignores late callbacks from the superseded socket. An error followed by close also keeps the `error` status that schedules recovery.
+- React and Vue `useCrossTabHealth` bindings now apply `intervalMs` changes without recreating the bus. React previously ignored an option change unless the bus identity changed, and the Vue composable ignored changes to a reactive options object; switching to `0` therefore left polling active, while changing a positive cadence kept the old timer. Both adapters now tear down the old listener/timer set and install the new cadence.
+- `stop()` now resolves once the bus is torn down even when the transport's own `stop()` rejects or throws. The failure is routed through the same `onError` / unified `lastFailure` channel that page-hide suspension and open-failure cleanup already use, so the fire-and-forget `void bus.stop()` teardown in the React and Vue adapters can no longer surface as an unhandled rejection. The instance stays restartable either way.
+- A failed transport open is now stamped once: `getRecoveryStats().errorAt` and the `lastFailure.at` of the same failure are equal instead of differing by a clock re-read. The open-failure path called the injected clock twice for one failure, so a consumer correlating the two ledgers (or a test using an advancing clock) saw two timestamps for one event. The open-failure path also clears `transportReady` before notifying status/error handlers, keeping the "transport is not accepting operations" verdict local to the failure block.
+- `ready()` no longer reports a BFCache-suspended bus as ready. After `pagehide`, `suspendTransport()` chains `transport.stop()` and reuses `startPromise` as the stop gate; `ready()` previously returned that gate, so it resolved the moment cleanup finished even though the transport was intentionally stopped and publications were dropped. Readiness now rejects with a clear suspended-state error while hidden; `pageshow` (or an explicit `start()`) clears the flag and installs a real reopen promise, after which `ready()` resolves as before. This restores the documented invariant that `ready()` never resolves for a transport that cannot carry data.
+- A runtime transport failure reported through `onError` now lands in the transport recovery ledger, not only in the unified `lastFailure` record. `getRecoveryStats().hasError` / `errorMessage` / `errorAt` were written exclusively by the transport-*open* failure path, so a failure raised after a successful open produced a self-contradicting health snapshot: `state: 'recovering'` and a retained `lastFailure` alongside `recovery.hasError: false, errorMessage: null`. The recovery ledger now tracks every transport-sourced failure (open or runtime) and still keeps non-transport failures (`persistence`, `dispatch`) out of it, where they remain visible through `lastFailure` and `getPersistenceStats()`.
+- The native WebSocket backend now honors the `DataBusTransport.start()` contract: it resolves only after the socket `open` and rejects when the handshake errors, closes before opening, or exceeds the new `connectTimeoutMs` (default 30s). Previously `start()` returned while the socket was still `CONNECTING`, so `await bus.ready()` resolved before the connection was usable and an immediately following `publish()` was dropped by the not-open guard. A timed-out attempt now closes its half-open socket and ignores a late `open`; an in-place re-open after a successful handshake still re-asserts subscriptions.
+- `getHealthSummary()` now treats a live `connected` transport as healthy even during the brief window before `start()` settles and `transportReady` flips to true. With a handshake-gated WebSocket start, the `connected` status event fires while `transportReady` is still false, so an event-driven `useCrossTabHealth` snapshot with `intervalMs: 0` could remain stuck in `starting`/`recovering`. `transportReady` remains a diagnostic field; operations are queued behind the in-flight start rather than dropped.
+
+
 ## [0.20.86] - 2026-09-16
 
 ### Added

package/dist/centrifuge.js

@@ -5,7 +5,7 @@ import {
   parseDataBusPublication,
   publicationMetadata,
   selectWorkerBackend
-} from "./chunk-SDOV3UHG.js";
+} from "./chunk-ZNHJ5OMY.js";
 import {
   CENTRIFUGE_INPUT_TYPE,
   CENTRIFUGE_OUTPUT_TYPE,

package/dist/{chunk-SDOV3UHG.js → chunk-ZNHJ5OMY.js}

@@ -2203,7 +2203,7 @@ var DedupManager = class {
 };
 
 // src/core/version.ts
-var SDK_VERSION = true ? "0.20.86" : "";
+var SDK_VERSION = true ? "0.20.87" : "";
 
 // src/core/data-bus.ts
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
@@ -2228,6 +2228,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;
@@ -2266,6 +2271,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. */
@@ -2484,8 +2502,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;
@@ -2508,6 +2556,7 @@ var CrossTabDataBus = class {
     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) => {
@@ -2529,6 +2578,7 @@ var CrossTabDataBus = class {
           this.recoveryGeneration += 1;
           this.lastSuccessAt = this.now();
           this.transportReady = true;
+          this.releaseRecoveryGate();
         }
       });
     }).catch((error) => {
@@ -2537,11 +2587,9 @@ var CrossTabDataBus = class {
       if (!this.pendingStop) {
         this.pendingStop = this.createStopPromise();
       }
+      this.transportReady = false;
       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();
@@ -2555,7 +2603,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();
@@ -2564,6 +2615,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);
     }
@@ -2699,11 +2755,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 {
@@ -2730,7 +2790,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,
@@ -2821,6 +2881,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();
@@ -2833,6 +2894,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();
@@ -2898,10 +2961,12 @@ var CrossTabDataBus = class {
   updateStatus(status) {
     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) {
@@ -2914,23 +2979,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));
   }
   reportError(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;
@@ -3013,6 +3104,7 @@ 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);
@@ -3082,7 +3174,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) {
@@ -3193,4 +3302,4 @@ export {
   parseDataBusPublication,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-SDOV3UHG.js.map
+//# sourceMappingURL=chunk-ZNHJ5OMY.js.map