cross-tab-worker-databus 0.21.15 → 0.21.16

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.21.16] - 2026-09-24
+
+### Fixed
+
+- **A transport subscribe deferred behind an opening no longer flushes after the unsubscribe that cancelled it.** `subscribeTransport()` and `unsubscribeTransport()` mutate `transportSubscribedTopics` and then hand the work to `runTransport()` as a captured closure. When the subscribe was parked behind an opening and the release reached the transport immediately — the window between the opening resolving and its own parked continuation running — the connection was left holding a channel that no local handler, cluster assignment, or route record owns. Nothing recovers from that: `subscribeTransport`'s dedupe returns early for a topic already in the set, and the set here says the channel is held, so the tab stays subscribed to a topic it has released and deaf to one it re-takes. `runTransport()` now also takes the desired state as a `stillWanted()` predicate and re-reads it at each place that resumes on a later task (the recovery-gate waiter and the opening flush). The immediate branch keeps no check because every path into it evaluated the set in the same task.
+- Reproduced with one bus and a gated `transport.start()`: subscribe while the open is pending, resolve the open, release one or two microtasks later. At those offsets the transport's *own* subscription set ends as `["topic"]` while both `subscribeCalls` and `unsubscribeCalls` hold one entry — an add and a delete that leave a `Set` non-empty is only reachable in unsubscribe-then-subscribe order, which is what names the defect. Offsets 0, 3 and 4 were clean, so the test asserts the whole window instead of the two values that failed here, and it reads `FakeTransport.subscribed` rather than the bus's bookkeeping, which is the thing that lies.
+- The same cancellation now covers a release whose topic was re-subscribed before its flush, and the measured consequence there is narrower: the old code put `sub, uns, sub` on the wire where the new one puts `sub, sub`. The end state was already correct; a real transport answers that middle `UNSUBSCRIBE` by tearing the channel down and re-establishing it, with a delivery gap in between. The comment at the call site says which half is measured.
+- Each of the two checks earns its keep separately, and that was measured rather than assumed, because the two resume points flush independently: deleting the recovery-gate check fails **1** of 191 tests (the gate case), deleting the opening-flush check fails exactly the **other two**, and reverting the whole change fails exactly those 3 with 188 pre-existing green — so no test in the repository pinned this before. Inverting both guards fails 20, including the pre-existing "starts automatically and queues subscriptions until the transport is ready", which is the assertion that the guard cannot silently swallow a wanted subscribe.
+- `FakeTransport` gained `channelCalls`, one entry per channel call in the order the transport received them. `subscribeCalls` and `unsubscribeCalls` are per-direction and cannot express ordering, and the contract fixed here *is* ordering.
+- **The question 0.21.15 closed on is now answered: the residue was this defect.** That entry recorded six sweep seeds that fail once the test channel delivers asynchronously, as an open product question the experiment "surfaced but did not settle". With the fix in, the same sweep is green; without it, the same six seeds fail again with the same messages. Measured both ways on one branch: `origin/main`'s `data-bus.ts` plus an asynchronous hub fails **seeds 100, 727, 1129, 1487, 1756** (`no subscriber left but owners=[] transportSubscriptions=[a]`) **and 1853** (`1 subscriber(s) need one owner that holds the transport, got owners=[b] transportSubscriptions=[a b]`); the fixed code with the same hub passes all 5,000 seeds; and the *synchronous* hub passes on the pre-fix code, which is exactly why a shipped defect stayed invisible to a harness that exercises it constantly.
+
+### Tests
+
+- `ChannelHub` gained `setAsyncDelivery(true)`, which defers every post by one microtask. A real `BroadcastChannel` delivers in a later task, so no runtime ever reacts to its own post inside one call stack — the hub's synchronous default lets exactly that happen, and the two cases above are what it can hide. The option is opt-in rather than the default because 15 tests in `cluster`, `data-bus` and `stability` post a frame and assert without awaiting: flipping the default was tried and reddens exactly **17** cases, those 15 plus this hub's own two delivery pins. The coordination sweep's per-seed hub is the only consumer that opts in, and its cost is measured as no cost: 8.0–9.5 s for the full sweep against ~10.5 s synchronous on the same machine.
+- The option is pinned directly, on both sides: the default hub must still deliver inside the posting stack, an opted-in hub must deliver nothing until a microtask, a peer that closes before delivery receives nothing, and a sender that closes does not cancel its own frame — which is what the sweep's `forgeSubscribe()` depends on. Which half is load-bearing was measured: forcing the option to a no-op kills the second assertion, while removing the sweep's own opt-in leaves all five cases green on the fixed code. So the fidelity is justified by the six seeds it caught, not by a standing kill, and the pin's comment says so — while the *first* assertion is what makes the 17-case default flip impossible to land quietly.
+- One mechanism in there is recorded as defensive rather than as covered: reading the channel's member set inside the microtask instead of snapshotting it when the frame is posted is **indistinguishable through this fake**, because `FakeChannel.close()` clears the channel's listeners. That mutant was written, run, and survived the whole file; the comment at the site carries the measurement so the next reader does not mistake the assertion for a pin on the mechanism.
+
+### Documentation
+
+- `docs/architecture.md` and its Chinese mirror described both subscription chains in the wrong order and omitted the deferral altogether. The published text read `→ transport.subscribe(topic) → transportSubscribedTopics.add(topic)`; the code adds to the set **first** and then hands the call to `runTransport()`, which may park it. Both chains now put the set write before the call, and a new bullet in the disconnect/reconnect section states the rule #241 implements: a parked operation is re-checked against that set before it runs, and the alternative — what shipped until now — is a subscribe flushing after its own unsubscribe, leaving the connection holding a topic that none of the four tracked sets owns.
+- The same claim had three more copies, each corrected in both languages: the "Recovery waiter invalidation" bullet (which explained only the cancellation-generation guard, and now says plainly that the generation check alone cannot cancel a released subscribe because nothing about the recovery cycle changed), the "Transport recovery gate" paragraph's "parked operations flush behind that success" (now qualified, with a pointer), and `docs/api.md`'s `subscribe()` behavior list (which promised queuing but not cancellation). `docs/api.md`'s publication row was checked and left alone: a parked `publish()` carries no desired state to re-read, so its "sent once the transport is ready" is still exact. `docs/*.md` is in `package.json` `files`, so this is consumer-visible text and ships with the patch.
+
 ## [0.21.15] - 2026-09-24
 
 ### Tests

package/dist/centrifuge.js

@@ -7,7 +7,7 @@ import {
   publicationMetadata,
   selectWorkerBackend,
   serializeError
-} from "./chunk-VQJIMGJN.js";
+} from "./chunk-GQ6NYWQL.js";
 import {
   CENTRIFUGE_INPUT_TYPE,
   CENTRIFUGE_OUTPUT_TYPE,

package/dist/{chunk-VQJIMGJN.js → chunk-GQ6NYWQL.js}

@@ -2410,7 +2410,7 @@ var DedupManager = class {
 };
 
 // src/core/version.ts
-var SDK_VERSION = true ? "0.21.15" : "";
+var SDK_VERSION = true ? "0.21.16" : "";
 
 // src/core/data-bus.ts
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
@@ -3361,12 +3361,18 @@ var CrossTabDataBus = class {
   subscribeTransport(topic) {
     if (this.transportSubscribedTopics.has(topic)) return false;
     this.transportSubscribedTopics.add(topic);
-    this.runTransport(() => this.transport.subscribe(topic));
+    this.runTransport(
+      () => this.transport.subscribe(topic),
+      () => this.transportSubscribedTopics.has(topic)
+    );
     return true;
   }
   unsubscribeTransport(topic) {
     if (!this.transportSubscribedTopics.delete(topic)) return false;
-    this.runTransport(() => this.transport.unsubscribe(topic));
+    this.runTransport(
+      () => this.transport.unsubscribe(topic),
+      () => !this.transportSubscribedTopics.has(topic)
+    );
     return true;
   }
   /** Invoke `callback` for each item in `handlers`, isolating a throwing
@@ -3484,8 +3490,15 @@ var CrossTabDataBus = class {
    * Run a transport operation now if the transport is ready, otherwise queue
    * it behind the start promise. This ensures subscribe/unsubscribe calls made
    * during startup are not lost.
+   *
+   * `stillWanted` expresses the deferred work as the *current* desired state
+   * rather than a captured call, and is checked at each place that resumes on a
+   * later task — the recovery gate and the opening flush. The immediate branch
+   * carries no check because every path into it evaluates the desired state in
+   * the same task: a caller that just mutated `transportSubscribedTopics`, or
+   * the gate re-entry one line above.
    */
-  runTransport(operation) {
+  runTransport(operation, stillWanted) {
     if (this.suspended) return;
     if (this.recoveryGate && !this.stopping) {
       const gate = this.recoveryGate;
@@ -3495,7 +3508,8 @@ var CrossTabDataBus = class {
       void gate.then(() => {
         this.recoveryWaiters -= 1;
         if (this.stopping || this.suspended || cancellationToken !== this.recoveryCancellationToken) return;
-        this.runTransport(operation);
+        if (stillWanted && !stillWanted()) return;
+        this.runTransport(operation, stillWanted);
       });
       return;
     }
@@ -3516,6 +3530,7 @@ var CrossTabDataBus = class {
     void ready.then(
       () => {
         if (!this.started || this.stopping || this.suspended) return;
+        if (stillWanted && !stillWanted()) return;
         return operation();
       },
       // The opening promise reports its own lifecycle failure through
@@ -3626,4 +3641,4 @@ export {
   parseDataBusPublication,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-VQJIMGJN.js.map
+//# sourceMappingURL=chunk-GQ6NYWQL.js.map