cross-tab-worker-databus 0.20.57 → 0.20.59

package/CHANGELOG.md

@@ -1,4 +1,21 @@
 # Changelog
+## [0.20.59] - 2026-09-04
+
+### Added
+- Extended `CrossTabDataBus.getRecoveryStats()` with `generation` (monotonic counter incremented on every successful transport open) and `lastSuccessAt` (timestamp of the most recent successful open, or `null` until the transport reaches `ready`).
+- Added a unit test asserting generation/lastSuccessAt advance on the initial start and after a recovery, and stay stable across failed recovery attempts.
+
+## [0.20.58] - 2026-09-04
+
+### Changed
+- Bounded the publish route-owner cache to a configurable LRU cap (default 256), evicting the oldest entry on overflow.
+- Surfaced route-owner cache diagnostics (`size`, `max`, `hits`, `misses`) on `WorkerClusterRuntime.getSnapshot()` so callers can observe warm vs. cold route resolution.
+- Fixed a correctness bug where `wildcardPublishCache`'s `null` entry short-circuited the remote-owner publish path; topics with no local wildcard subscription now still consult the route-owner cache and forward to the remote owner.
+
+### Added
+- Added `routeOwnerCacheMax` to `WorkerClusterOptions` for tuning the route-owner cache size per workload.
+- Added unit tests for LRU eviction, TTL-based cache invalidation, owner migration, and remote-owner cache hits.
+
 ## [0.20.57] - 2026-09-04
 
 ### Added
@@ -26,8 +43,6 @@
 
 - Extended `getRecoveryStats()` with a safe `errorMessage` summary for diagnostics without exposing the raw error object.
 
-## [Unreleased]
-
 ## [0.20.52] - 2026-09-04
 
 ### Added

package/dist/centrifuge.js

@@ -2,7 +2,7 @@ import {
   CrossTabDataBus,
   parseDataBusPublication,
   selectWorkerBackend
-} from "./chunk-WAQJT3EE.js";
+} from "./chunk-RAUX7RZC.js";
 
 // src/centrifuge-session.ts
 import { Centrifuge } from "centrifuge";

package/dist/{chunk-WAQJT3EE.js → chunk-RAUX7RZC.js}

@@ -337,6 +337,18 @@ var WorkerClusterRuntime = class {
   // (or local self-subscribe), never via the reverse cache.
   assignedTopics = /* @__PURE__ */ new Map();
   routeOwnerCache = /* @__PURE__ */ new Map();
+  routeOwnerCacheMax;
+  routeOwnerCacheHits = 0;
+  routeOwnerCacheMisses = 0;
+  touchRouteOwnerCache(topicKey, value) {
+    if (this.routeOwnerCache.has(topicKey)) this.routeOwnerCache.delete(topicKey);
+    this.routeOwnerCache.set(topicKey, value);
+    while (this.routeOwnerCache.size > this.routeOwnerCacheMax) {
+      const oldest = this.routeOwnerCache.keys().next().value;
+      if (oldest === void 0) break;
+      this.routeOwnerCache.delete(oldest);
+    }
+  }
   wildcardPublishCache = /* @__PURE__ */ new Map();
   // Reverse mapping: opaque topicKey → plaintext topic. A bounded cache with
   // FIFO eviction — NOT authoritative. It can hold a topicKey that is also in
@@ -355,6 +367,7 @@ var WorkerClusterRuntime = class {
     this.handlers = options.handlers;
     this.maxActiveWorkers = options.maxActiveWorkers ?? DEFAULT_MAX_ACTIVE_WORKERS;
     this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.routeOwnerCacheMax = options.routeOwnerCacheMax ?? 256;
     this.workerTtlMs = options.workerTtlMs ?? DEFAULT_WORKER_TTL_MS;
     const clusterHash = createOpaqueKey(options.clusterKey || "__default__");
     const prefix = options.storagePrefix ?? DEFAULT_STORAGE_PREFIX;
@@ -547,25 +560,26 @@ var WorkerClusterRuntime = class {
       return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
     }
     const cachedPattern = this.wildcardPublishCache.get(topic);
-    if (cachedPattern !== void 0) {
-      if (cachedPattern === null || this.assignedTopics.has(cachedPattern)) {
-        return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
-      }
-      this.wildcardPublishCache.delete(topic);
+    if (cachedPattern !== void 0 && cachedPattern !== null && this.assignedTopics.has(cachedPattern)) {
+      return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
     }
-    for (const pattern of this.assignedTopics.values()) {
-      if (pattern !== topic && topicMatchesPattern(pattern, topic)) {
-        this.wildcardPublishCache.set(topic, pattern);
-        return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
+    if (cachedPattern === void 0) {
+      for (const pattern of this.assignedTopics.values()) {
+        if (pattern !== topic && topicMatchesPattern(pattern, topic)) {
+          this.wildcardPublishCache.set(topic, pattern);
+          return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
+        }
       }
+      this.wildcardPublishCache.set(topic, null);
     }
-    this.wildcardPublishCache.set(topic, null);
     const workers = this.readWorkers();
     const route = this.readRoute(topicKey);
     const cached = this.routeOwnerCache.get(topicKey);
     const cachedLive = cached && route && route.generation === cached.generation && route.workerId === cached.workerId && workers.some((worker) => worker.workerId === cached.workerId);
+    if (cachedLive) this.routeOwnerCacheHits += 1;
+    else this.routeOwnerCacheMisses += 1;
     const target = cachedLive ? cached.workerId : this.routeOwnerIsLive(route, workers) ? route?.workerId ?? this.workerId : this.workerId;
-    if (route && target === route.workerId) this.routeOwnerCache.set(topicKey, { workerId: route.workerId, generation: route.generation });
+    if (route && target === route.workerId) this.touchRouteOwnerCache(topicKey, { workerId: route.workerId, generation: route.generation });
     else this.routeOwnerCache.delete(topicKey);
     return this.sendControl(target, "PUBLISH", topic, topicKey, data, metadata);
   }
@@ -622,7 +636,8 @@ var WorkerClusterRuntime = class {
       routes,
       subscribedTopics: Array.from(this.subscribedTopics),
       assignedTopics: Array.from(this.assignedTopics.values()),
-      knownTopics: Array.from(this.knownTopics.entries(), ([topicKey, topic]) => ({ topicKey, topic }))
+      knownTopics: Array.from(this.knownTopics.entries(), ([topicKey, topic]) => ({ topicKey, topic })),
+      routeOwnerCache: { size: this.routeOwnerCache.size, max: this.routeOwnerCacheMax, hits: this.routeOwnerCacheHits, misses: this.routeOwnerCacheMisses }
     };
   }
   handlePageHide = () => this.pause();
@@ -1301,6 +1316,13 @@ var CrossTabDataBus = class {
   // a transport reopen succeeds so traces can correlate repeated failures.
   recoveryAttempt = 0;
   recoveryExhausted = 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. */
+  recoveryGeneration = 0;
+  /** Timestamp of the most recent successful transport open. Null until the
+   * transport has reached the `ready` state at least once. */
+  lastSuccessAt = null;
   // True while the tab is hidden so an in-flight transport start does not mark
   // the transport ready after suspendTransport() has stopped it.
   suspended = false;
@@ -1494,7 +1516,11 @@ var CrossTabDataBus = class {
         if (this.status === "error") {
           throw new Error("Transport failed during startup.");
         }
-        if (!this.suspended && !this.stopping) this.transportReady = true;
+        if (!this.suspended && !this.stopping) {
+          this.recoveryGeneration += 1;
+          this.lastSuccessAt = this.now();
+          this.transportReady = true;
+        }
       });
     }).catch((error) => {
       if (stopClusterOnFailure) this.started = false;
@@ -1664,9 +1690,22 @@ var CrossTabDataBus = class {
     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`. */
   getRecoveryStats() {
     const errorMessage = this.lastError instanceof Error ? this.lastError.message : this.lastError === null ? null : String(this.lastError);
-    return { attempt: this.recoveryAttempt, exhausted: this.recoveryExhausted, maxAttempts: this.recoveryMaxAttempts, hasError: this.lastError !== null, errorMessage, errorAt: this.lastErrorAt };
+    return {
+      attempt: this.recoveryAttempt,
+      exhausted: this.recoveryExhausted,
+      maxAttempts: this.recoveryMaxAttempts,
+      hasError: this.lastError !== null,
+      errorMessage,
+      errorAt: this.lastErrorAt,
+      generation: this.recoveryGeneration,
+      lastSuccessAt: this.lastSuccessAt
+    };
   }
   /** Snapshot of the cluster state (workers, routes, assignments).
    * For diagnostics only — the returned object is a shallow copy but
@@ -2143,4 +2182,4 @@ export {
   parseDataBusPublication,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-WAQJT3EE.js.map
+//# sourceMappingURL=chunk-RAUX7RZC.js.map