@econ-v1/domain 7.0.53 → 7.0.55

package/dist/services/transport-manager.d.ts

@@ -12,6 +12,7 @@ export function isPotentiallyTrustworthyOrigin(url: RuntimeUrl): boolean;
 /** @typedef {HomeNodeClient & { close?: () => void | Promise<void> }} ClosableHomeNodeClient */
 /** @typedef {{ abort(): void, readonly signal: AbortSignalPort }} AbortControllerPort */
 /** @typedef {{ readonly candidate: DirectHomeNodeCandidate, readonly controller: AbortControllerPort, readonly promise: Promise<HomeNodeClient> }} DialAttempt */
+/** @typedef {{ readonly abort: AbortControllerPort, readonly promise: Promise<HomeNodeClient> }} SharedRun */
 /** @typedef {{ readonly attempt: DialAttempt, readonly client: HomeNodeClient, readonly success: true }} DialSuccess */
 /** @typedef {{ readonly attempt: DialAttempt, readonly success: false }} DialFailure */
 export class TransportManager {
@@ -55,7 +56,17 @@ export class TransportManager {
     markReconnecting(attempt: number, nextRetryAt: string): void;
     /** @param {TransportOfflineReason} [reason] @returns {void} */
     markOffline(reason?: TransportOfflineReason): void;
-    /** @returns {void} */
+    /**
+     * Stops everything in flight. This is a global teardown primitive — `close()` and
+     * `disconnect()` on the seam above call it — never a per-caller cancel, so it stays
+     * "abort all runs" rather than becoming per-run. What did have to change is the
+     * bookkeeping: with concurrent runs possible, a single `#runAbort` slot held only the
+     * most recently started one, and an older run would have kept walking
+     * `DIRECT_TIER_ORDER` — `#connect` re-checks its own run signal between tiers, and that
+     * signal was never aborted — dialling fresh candidates after the caller asked for
+     * silence. Aborting every registered run closes that gap.
+     * @returns {void}
+     */
     abort(): void;
     #private;
 }
@@ -92,6 +103,10 @@ export type DialAttempt = {
     readonly controller: AbortControllerPort;
     readonly promise: Promise<HomeNodeClient>;
 };
+export type SharedRun = {
+    readonly abort: AbortControllerPort;
+    readonly promise: Promise<HomeNodeClient>;
+};
 export type DialSuccess = {
     readonly attempt: DialAttempt;
     readonly client: HomeNodeClient;

package/dist/services/transport-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-manager.d.ts","sourceRoot":"","sources":["../../src/services/transport-manager.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"transport-manager.d.ts","sourceRoot":"","sources":["../../src/services/transport-manager.js"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@econ-v1/domain",
-  "version": "7.0.53",
+  "version": "7.0.55",
   "description": "Platform-neutral domain contracts and errors for Node clients",
   "license": "MIT OR Apache-2.0",
   "author": "Node contributors",
@@ -57,6 +57,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@econ-v1/ports": "7.0.53"
+    "@econ-v1/ports": "7.0.55"
   }
 }

package/src/services/transport-manager.js

@@ -24,6 +24,7 @@ const DIRECT_TIER_ORDER = ["lan-direct", "lan-webtransport", "wan-direct"];
 /** @typedef {HomeNodeClient & { close?: () => void | Promise<void> }} ClosableHomeNodeClient */
 /** @typedef {{ abort(): void, readonly signal: AbortSignalPort }} AbortControllerPort */
 /** @typedef {{ readonly candidate: DirectHomeNodeCandidate, readonly controller: AbortControllerPort, readonly promise: Promise<HomeNodeClient> }} DialAttempt */
+/** @typedef {{ readonly abort: AbortControllerPort, readonly promise: Promise<HomeNodeClient> }} SharedRun */
 /** @typedef {{ readonly attempt: DialAttempt, readonly client: HomeNodeClient, readonly success: true }} DialSuccess */
 /** @typedef {{ readonly attempt: DialAttempt, readonly success: false }} DialFailure */
 
@@ -40,10 +41,15 @@ export class TransportManager {
   #now;
   /** @readonly @type {(state: TransportState) => void} */
   #onState;
-  /** @type {Promise<HomeNodeClient> | undefined} */
-  #run;
-  /** @type {AbortControllerPort | undefined} */
-  #runAbort;
+  /**
+   * In-flight dials, keyed by the exact candidate set each was created for (see
+   * `#shareRun`). A map rather than a single slot because two callers may legitimately
+   * be dialling DIFFERENT ladders at the same moment — the supervisor's LAN promotion
+   * probe and a kernel read that wants the full ladder — and neither may inherit the
+   * other's result.
+   * @readonly @type {Map<string, SharedRun>}
+   */
+  #runs = new Map();
   /** @type {DirectHomeNodeCandidate | undefined} */
   #selectedCandidate;
   /** @readonly @type {Set<AbortControllerPort>} */
@@ -181,30 +187,64 @@ export class TransportManager {
     });
   }
 
-  /** @returns {void} */
+  /**
+   * Stops everything in flight. This is a global teardown primitive — `close()` and
+   * `disconnect()` on the seam above call it — never a per-caller cancel, so it stays
+   * "abort all runs" rather than becoming per-run. What did have to change is the
+   * bookkeeping: with concurrent runs possible, a single `#runAbort` slot held only the
+   * most recently started one, and an older run would have kept walking
+   * `DIRECT_TIER_ORDER` — `#connect` re-checks its own run signal between tiers, and that
+   * signal was never aborted — dialling fresh candidates after the caller asked for
+   * silence. Aborting every registered run closes that gap.
+   * @returns {void}
+   */
   abort() {
-    this.#runAbort?.abort();
+    for (const run of this.#runs.values()) run.abort.abort();
     for (const controller of this.#controllers) controller.abort();
     this.markOffline();
   }
 
   /**
+   * Collapses concurrent callers asking for THE SAME dial onto one run, and only those.
+   *
+   * This used to share `this.#run` with whoever asked next, ignoring the `candidates`
+   * argument entirely on the early return. That is a correctness bug, not an
+   * optimization: the supervisor's LAN promotion probe calls
+   * `connect({ higherPriorityThan: "wan-direct" })` every ~10s, which filters the ladder
+   * down to the LAN tiers. On a normal deployment those tiers are empty, so `#connect`
+   * finds no tier with members and rejects IMMEDIATELY, with no I/O at all — and that
+   * rejected run was then handed to every later caller, including
+   * `ManagedHomeNodeClient`'s bare `connect()` that wanted the full ladder and would have
+   * reached the node. Measured in a browser against a live node: reads succeeded during
+   * page load, the first promotion tick poisoned the slot, and for the remaining 92s of
+   * the window the client issued ZERO fetches while every read failed and was recorded
+   * against the node as unreachable — the chip flipped to Offline at ~89s with the node
+   * up and answering the whole time.
+   *
+   * So the shared run is keyed by the candidate set it was created for. A caller that
+   * asked for a different set gets its own dial; a caller that asked for the same set
+   * still gets the in-flight one, which is the single-activation contract
+   * `ManagedHomeNodeClient#ensureClient` depends on to avoid duplicate connections. Do
+   * not widen this back to unconditional sharing.
+   *
    * @param {readonly DirectHomeNodeCandidate[]} candidates
    * @param {boolean} publishState
    * @returns {Promise<HomeNodeClient>}
    */
   #shareRun(candidates, publishState) {
-    if (this.#run !== undefined) return this.#run;
+    const key = candidateSetKey(candidates);
+    const shared = this.#runs.get(key);
+    if (shared !== undefined) return shared.promise;
     const abort = createRuntimeAbortController();
     const connection = this.#connect(candidates, publishState, abort.signal);
     /** @type {Promise<HomeNodeClient>} */
-    /** @type {Promise<HomeNodeClient>} */
     const run = connection.finally(() => {
-      if (this.#run === run) this.#run = undefined;
-      if (this.#runAbort === abort) this.#runAbort = undefined;
+      // Keyed on the same entry, so a settled run can never be matched by a later
+      // caller, and a run started after this one for the same key is never evicted
+      // by its predecessor settling.
+      if (this.#runs.get(key)?.promise === run) this.#runs.delete(key);
     });
-    this.#run = run;
-    this.#runAbort = abort;
+    this.#runs.set(key, { abort, promise: run });
     return run;
   }
 
@@ -357,6 +397,30 @@ function wholeAttempt(attempt) {
   return Number.isFinite(attempt) ? Math.max(1, Math.trunc(attempt)) : 1;
 }
 
+/**
+ * Identity of a requested dial, for `#shareRun`'s in-flight registry.
+ *
+ * Deliberately the same `[path, address, id]` triple `normalizeDirectCandidates` already
+ * keys its dedup on, so "the same candidate" means one thing in this file rather than
+ * two. Every set reaching here is a filtered view of the normalized ladder, so the
+ * addresses are already canonical and the order is the ladder's — two callers asking for
+ * the same thing produce byte-identical keys. `JSON.stringify` of the whole list (not a
+ * join) keeps an empty set at `"[]"`, which no non-empty set can collide with: the
+ * empty-set run is exactly the one that rejects without dialling, and it must never be
+ * mistaken for a request to dial the ladder.
+ * @param {readonly DirectHomeNodeCandidate[]} candidates
+ * @returns {string}
+ */
+function candidateSetKey(candidates) {
+  return JSON.stringify(
+    candidates.map((candidate) => [
+      candidate.path,
+      candidate.address,
+      candidate.id,
+    ]),
+  );
+}
+
 /**
  * @param {readonly DirectHomeNodeCandidate[]} candidates
  * @returns {readonly DirectHomeNodeCandidate[]}