cross-tab-worker-databus 0.21.56 → 0.21.57

package/dist/cjs/index.cjs

@@ -288,12 +288,13 @@ function canUseStorage(storage, probeKey) {
     return false;
   }
 }
-function getOrCreateTabId(environment, key = TAB_ID_STORAGE_KEY) {
+function getOrCreateTabId(environment, key = TAB_ID_STORAGE_KEY, options) {
   const storage = environment.sessionStorage;
   try {
     const existing = storage?.getItem(key);
     const hasOpener = typeof window !== "undefined" && Boolean(window.opener);
-    if (existing && (!hasOpener || tabIdentityInitialized)) {
+    const claimedByPeer = existing !== null && existing !== void 0 && existing !== "" && !hasOpener && !tabIdentityInitialized && options?.isIdentityClaimedByPeer?.(existing) === true;
+    if (existing && (!hasOpener || tabIdentityInitialized) && !claimedByPeer) {
       tabIdentityInitialized = true;
       cachedTabId = existing;
       return existing;
@@ -811,7 +812,21 @@ var WorkerClusterRuntime = class {
     this.subscriberPrefix = `${baseKey}:subscriber:`;
     this.channelName = `${prefix}:bus:${clusterHash}`;
     this.storage = canUseStorage(this.environment.storage, `${baseKey}:probe`) ? new BatchingStorageWriter(this.environment.storage) : null;
-    this.tabId = options.tabId ?? getOrCreateTabId(this.environment, `${prefix}:tab-id`);
+    this.tabId = options.tabId ?? getOrCreateTabId(this.environment, `${prefix}:tab-id`, {
+      // A browser-duplicated tab inherits sessionStorage without an opener, so
+      // `getOrCreateTabId()`'s opener guard cannot see it. A live Worker
+      // record carrying that id is the evidence the copy cannot carry: it
+      // lives in localStorage under a random `workerId`, and this probe runs
+      // in the constructor, before this Runtime has written a record of its
+      // own — so every match belongs to a different live document. A refresh
+      // removes its record in `pause()` and flushes that removal before the
+      // document goes away, so the refresh path keeps the stored id. The one
+      // case that does not is an abnormal exit, whose record survives for up
+      // to `workerTtlMs`; a reload inside that window takes a fresh identity,
+      // which costs one observer a changed `tabId` and nothing else — the
+      // stale record is pruned by the normal TTL path.
+      isIdentityClaimedByPeer: (candidate) => this.isTabIdLiveElsewhere(candidate)
+    });
     this.workerId = options.workerId ?? `worker-${this.tabId}-${this.environment.randomId()}`;
     const now = this.nowMs();
     this.currentRecord = {
@@ -1005,12 +1020,12 @@ var WorkerClusterRuntime = class {
     const topicKey = this.releaseSubscription(topic);
     if (topicKey && !this.assignedTopics.has(topicKey)) this.knownTopics.delete(topicKey);
   }
-  /** Remove this tab's subscriber record and, when it was the last one, delete
+  /** Remove this Runtime's subscriber record and, when it was the last one, delete
    * the route. Returns the topicKey (so callers like `unsubscribe` can reuse
    * it instead of re-hashing the topic to evict the reverse cache). */
   releaseSubscription(topic, notifyOwner = true) {
     const topicKey = this.rememberTopic(topic);
-    this.removeStorage(this.subscriberStorageKey(topicKey, this.tabId));
+    this.removeStorage(this.subscriberStorageKey(topicKey, this.workerId));
     const route = this.readRoute(topicKey);
     if (!route) return topicKey;
     const subscribers = this.readSubscriberTabIds(topicKey, this.readWorkers());
@@ -1452,11 +1467,7 @@ var WorkerClusterRuntime = class {
           ) ?? this.currentRecord;
           recoveryProjectedLoads.set(owner.workerId, (recoveryProjectedLoads.get(owner.workerId) ?? owner.load) + 1);
           if (owner.workerId !== this.workerId) {
-            const subscriberTabIds = new Set(this.readSubscriberTabIds(topicKey, workers));
-            const ownerSubscribed = workers.some(
-              (worker) => worker.workerId === owner.workerId && subscriberTabIds.has(worker.tabId)
-            );
-            if (ownerSubscribed) continue;
+            if (this.readSubscriberIds(topicKey, workers).workerIds.has(owner.workerId)) continue;
           }
           this.writeRoute(topicKey, owner, void 0, route.generation + 1);
           this.sendControl(owner.workerId, CONTROL_ACTION.SUBSCRIBE, topic, topicKey);
@@ -1577,6 +1588,38 @@ var WorkerClusterRuntime = class {
       return false;
     }
   }
+  /**
+   * Whether any other live Worker record already carries `tabId`.
+   *
+   * Used once per document, from the constructor, to tell a browser-duplicated
+   * tab from this tab's own refresh: the copy inherits `sessionStorage` but not
+   * the opener, so the identity stored there is the only shared state and the
+   * Worker records are the only evidence that another live document holds it.
+   * Liveness is the same heartbeat window `readWorkers()` prunes by, so a record
+   * left behind by an abnormal exit is reported as live until it expires — the
+   * only false positive, and it re-mints one identity instead of letting two
+   * live tabs share one.
+   *
+   * The `!this.storage` leg is the degraded mode, and it earns its line for two
+   * reasons rather than one. It is what narrows the field for the scan below
+   * (`StorageLike | null` is rejected by `readAllByPrefix`), so the compiler
+   * holds it; and it is *not* what decides the verdict, because `listKeys()`
+   * catches its own failure and returns no records either way — measured by
+   * emptying this consequent, which leaves the suite green. What the inverted
+   * return does prove is the behaviour, not the deletion: returning `true` here
+   * fails 'keeps the inherited id when there is no storage to probe', since
+   * without `localStorage` there is no second document to collide with.
+   */
+  isTabIdLiveElsewhere(tabId) {
+    if (!this.storage) return false;
+    const now = this.nowMs();
+    for (const { value: worker } of readAllByPrefix(this.storage, this.workerPrefix)) {
+      if (worker.tabId !== tabId) continue;
+      if (now - worker.heartbeatAt > this.workerTtlMs) continue;
+      return true;
+    }
+    return false;
+  }
   /** Read all live worker records from storage, pruning stale entries past the TTL. */
   readWorkers() {
     if (!this.storage) return [this.currentRecord];
@@ -1594,23 +1637,61 @@ var WorkerClusterRuntime = class {
   }
   /** Enumerate all tab IDs that have a subscriber record for `topicKey`. */
   readSubscriberTabIds(topicKey, workers) {
+    return Array.from(this.readSubscriberIds(topicKey, workers).tabIds);
+  }
+  /**
+   * One scan of `topicKey`'s subscriber records, answering the two questions
+   * callers ask: which Tabs hold a subscription (emptiness checks, orphan-route
+   * pruning) and which **Runtimes** do (the stranded-handoff re-election).
+   *
+   * The second answer is the finer one and the reason this is one method rather
+   * than two scans: a tab-level answer lets a leftover record from a sibling
+   * Runtime speak for a Worker that never subscribed to the topic, and standing
+   * down on that proof stalls the recovery forever (see the call site).
+   *
+   * A legacy record — written before records carried `workerId` — proves only
+   * that *some* Runtime in its tab subscribes, so it contributes to the tab set
+   * and **not** to the worker set. Treating it as the whole tab, which is what
+   * the tab-level reader effectively did, is the conservative-looking choice
+   * that can stall; the cost of the other direction is one redundant
+   * `CONTROL/SUBSCRIBE` to a peer that is about to confirm anyway.
+   */
+  readSubscriberIds(topicKey, workers) {
+    const tabIds = /* @__PURE__ */ new Set();
+    const workerIds = /* @__PURE__ */ new Set();
     if (!this.storage) {
       const topic = this.knownTopics.get(topicKey);
-      return topic && this.subscribedTopics.has(topic) ? [this.tabId] : [];
+      if (topic && this.subscribedTopics.has(topic)) {
+        tabIds.add(this.tabId);
+        workerIds.add(this.workerId);
+      }
+      return { tabIds, workerIds };
     }
     const activeTabIds = new Set(workers.map((worker) => worker.tabId));
-    const subscribers = /* @__PURE__ */ new Set();
+    const activeWorkerIds = new Set(workers.map((worker) => worker.workerId));
     for (const { key, value: record } of readAllByPrefix(
       this.storage,
       `${this.subscriberPrefix}${topicKey}:`
     )) {
-      if (!activeTabIds.has(record.tabId)) {
+      if (!this.isSubscriberRecordLive(record, activeTabIds, activeWorkerIds)) {
         this.removeStorage(key);
         continue;
       }
-      subscribers.add(record.tabId);
+      tabIds.add(record.tabId);
+      if (record.workerId !== void 0) workerIds.add(record.workerId);
     }
-    return Array.from(subscribers);
+    return { tabIds, workerIds };
+  }
+  /** Whether a subscriber record still belongs to a live Runtime.
+   *
+   * A record written by this version names its `workerId`, so liveness is the
+   * Worker set the reconcile pass already prunes by — which is what keeps two
+   * Runtimes in one tab independent. A record from an older version carries no
+   * `workerId`; it is honoured while its *tab* lives, the finest identity it
+   * has, and each Runtime replaces its own with a worker-keyed record on its
+   * next write. */
+  isSubscriberRecordLive(record, activeTabIds, activeWorkerIds) {
+    return record.workerId === void 0 ? activeTabIds.has(record.tabId) : activeWorkerIds.has(record.workerId);
   }
   /** Read the current route for `topicKey`. With a storage layer this returns
    * the durable route, or null when none is recorded. Without one (degraded
@@ -1676,19 +1757,31 @@ var WorkerClusterRuntime = class {
       this.removeStorage(key);
     }
   }
-  /** Remove subscriber records for tabs that are no longer active. */
+  /** Remove subscriber records whose owning Runtime (or, for a legacy record,
+   * whose tab) is no longer active. */
   cleanupOrphanedSubscribers(workers) {
     if (!this.storage) return;
     const activeTabIds = new Set(workers.map((worker) => worker.tabId));
+    const activeWorkerIds = new Set(workers.map((worker) => worker.workerId));
     for (const { key, value: record } of readAllByPrefix(this.storage, this.subscriberPrefix)) {
-      if (!activeTabIds.has(record.tabId)) this.removeStorage(key);
+      if (!this.isSubscriberRecordLive(record, activeTabIds, activeWorkerIds)) this.removeStorage(key);
     }
   }
-  /** Persist a subscriber record for this tab on `topicKey`. */
+  /** Persist a subscriber record for this Runtime on `topicKey`.
+   *
+   * Keyed by `workerId`, not `tabId`. A document may run several Runtimes that
+   * share one `tabId` on purpose (the market + notice pattern), and a tab-keyed
+   * record belonged to all of them at once: whichever unsubscribed first deleted
+   * the others' intent, the route then looked orphaned, and the owner dropped a
+   * transport subscription its surviving sibling still needed — a delivery gap
+   * until that sibling's next reconcile tick re-elected an owner. Duplicated
+   * tabs get the same protection even when the identity probe cannot see them,
+   * which is why the fix is here as well as in `isTabIdLiveElsewhere()`. */
   writeSubscriber(topicKey) {
     if (!this.storage) return;
-    writeJson(this.storage, this.subscriberStorageKey(topicKey, this.tabId), {
+    writeJson(this.storage, this.subscriberStorageKey(topicKey, this.workerId), {
       tabId: this.tabId,
+      workerId: this.workerId,
       updatedAt: this.nowMs()
     });
   }
@@ -1762,8 +1855,9 @@ var WorkerClusterRuntime = class {
   routeStorageKey(topicKey) {
     return `${this.routePrefix}${topicKey}`;
   }
-  subscriberStorageKey(topicKey, tabId) {
-    return `${this.subscriberPrefix}${topicKey}:${tabId}`;
+  /** `ownerId` is the Runtime's `workerId`; older versions used the `tabId`. */
+  subscriberStorageKey(topicKey, ownerId) {
+    return `${this.subscriberPrefix}${topicKey}:${ownerId}`;
   }
   removeStorage(key) {
     try {
@@ -2643,7 +2737,7 @@ var SDK_VERSION = (
   // declaration's type is `string | undefined` and the export's is `string`
   // (dropping the conditional is TS2322, measured). Recorded here so the leg reads
   // as a shape the harness cannot reach rather than as a case nobody exercised.
-  true ? "0.21.56" : ""
+  true ? "0.21.57" : ""
 );
 
 // src/core/data-bus.ts