@econ-v1/domain 6.7.0 → 6.10.0

package/src/services/transport-manager.js

@@ -0,0 +1,478 @@
+// @ts-check
+
+/** @typedef {import("@econ-v1/ports").DelayPort} DelayPort */
+/** @typedef {import("@econ-v1/ports").DirectHomeNodeCandidate} DirectHomeNodeCandidate */
+/** @typedef {import("@econ-v1/ports").DirectTransportPath} DirectTransportPath */
+/** @typedef {import("@econ-v1/ports").HomeNodeClient} HomeNodeClient */
+/** @typedef {import("@econ-v1/ports").TransportOfflineReason} TransportOfflineReason */
+/** @typedef {import("@econ-v1/ports").TransportState} TransportState */
+/** @typedef {import("./abort-signal.js").AbortSignalPort} AbortSignalPort */
+/** @typedef {import("./runtime-globals.js").RuntimeUrl} RuntimeUrl */
+
+import {
+  createRuntimeAbortController,
+  parseRuntimeUrl,
+} from "./runtime-globals.js";
+
+/** @type {readonly DirectTransportPath[]} */
+/** @type {readonly DirectTransportPath[]} */
+const DIRECT_TIER_ORDER = ["lan-direct", "lan-webtransport", "wan-direct"];
+
+/** @typedef {{ readonly candidates: readonly DirectHomeNodeCandidate[], readonly dial: (candidate: DirectHomeNodeCandidate, signal: AbortSignalPort) => Promise<HomeNodeClient>, readonly delay?: DelayPort, readonly priorityGraceMs?: number, readonly candidateTimeoutMs?: number, readonly now?: () => string, readonly onState?: (state: TransportState) => void }} TransportManagerOptions */
+/** @typedef {{ readonly higherPriorityThan?: DirectTransportPath, readonly path?: DirectTransportPath }} TransportConnectOptions */
+/** @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 attempt: DialAttempt, readonly client: HomeNodeClient, readonly success: true }} DialSuccess */
+/** @typedef {{ readonly attempt: DialAttempt, readonly success: false }} DialFailure */
+
+export class TransportManager {
+  /** @type {readonly DirectHomeNodeCandidate[]} */
+  #candidates;
+  /** @readonly @type {TransportManagerOptions["dial"]} */
+  #dial;
+  /** @readonly @type {DelayPort | undefined} */
+  #delay;
+  /** @readonly @type {number} */
+  #candidateTimeoutMs;
+  /** @readonly @type {() => string} */
+  #now;
+  /** @readonly @type {(state: TransportState) => void} */
+  #onState;
+  /** @type {Promise<HomeNodeClient> | undefined} */
+  #run;
+  /** @type {AbortControllerPort | undefined} */
+  #runAbort;
+  /** @type {DirectHomeNodeCandidate | undefined} */
+  #selectedCandidate;
+  /** @readonly @type {Set<AbortControllerPort>} */
+  #controllers = new Set();
+  /** @readonly @type {WeakSet<object>} */
+  #closedClients = new WeakSet();
+  /** @readonly @type {Set<(state: TransportState) => void>} */
+  #listeners = new Set();
+  /** @type {TransportState} */
+  #state = {
+    changedAt: "1970-01-01T00:00:00.000Z",
+    path: "offline",
+    status: "offline",
+  };
+
+  /** @param {TransportManagerOptions} options */
+  constructor(options) {
+    this.#candidates = normalizeDirectCandidates(options.candidates);
+    this.#dial = options.dial;
+    this.#delay = options.delay;
+    this.#candidateTimeoutMs = Math.max(
+      1,
+      options.candidateTimeoutMs ?? 15_000,
+    );
+    this.#now = options.now ?? (() => new Date().toISOString());
+    this.#onState = options.onState ?? (() => undefined);
+  }
+
+  /** @returns {TransportState} */
+  get state() {
+    return this.#state;
+  }
+
+  /** @returns {DirectHomeNodeCandidate | undefined} */
+  get selectedCandidate() {
+    return this.#selectedCandidate === undefined
+      ? undefined
+      : { ...this.#selectedCandidate };
+  }
+
+  /**
+   * @param {(state: TransportState) => void} listener
+   * @returns {() => void}
+   */
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  /**
+   * @param {readonly DirectHomeNodeCandidate[]} candidates
+   * @returns {void}
+   */
+  replaceCandidates(candidates) {
+    this.#candidates = normalizeDirectCandidates(candidates);
+  }
+
+  /**
+   * @param {TransportConnectOptions} [options]
+   * @returns {Promise<HomeNodeClient>}
+   */
+  connect(options = {}) {
+    if (
+      options.higherPriorityThan !== undefined &&
+      options.path !== undefined
+    ) {
+      throw new TypeError(
+        "Transport selection accepts either a path or a priority bound",
+      );
+    }
+    /** @type {readonly DirectHomeNodeCandidate[]} */
+    let candidates;
+    if (options.path !== undefined) {
+      candidates = this.#candidates.filter(
+        (candidate) => candidate.path === options.path,
+      );
+    } else if (options.higherPriorityThan !== undefined) {
+      const higherPriorityThan = options.higherPriorityThan;
+      candidates = this.#candidates.filter(
+        (candidate) => priority(candidate.path) < priority(higherPriorityThan),
+      );
+    } else {
+      candidates = this.#candidates;
+    }
+    return this.#shareRun(candidates, options.higherPriorityThan === undefined);
+  }
+
+  /**
+   * @param {DirectTransportPath} path
+   * @returns {void}
+   */
+  markConnected(path) {
+    this.#setState({ changedAt: this.#now(), path, status: "connected" });
+  }
+
+  /** @param {number} attempt @returns {void} */
+  markConnecting(attempt) {
+    this.#setState({
+      attempt: wholeAttempt(attempt),
+      changedAt: this.#now(),
+      path: "offline",
+      status: "connecting",
+    });
+  }
+
+  /** @param {number} attempt @param {string} nextRetryAt @returns {void} */
+  markReconnecting(attempt, nextRetryAt) {
+    this.#setState({
+      attempt: wholeAttempt(attempt),
+      changedAt: this.#now(),
+      nextRetryAt,
+      path: "offline",
+      status: "reconnecting",
+    });
+  }
+
+  /** @param {TransportOfflineReason} [reason] @returns {void} */
+  markOffline(reason) {
+    this.#setState({
+      changedAt: this.#now(),
+      path: "offline",
+      status: "offline",
+      ...(reason === undefined ? {} : { reason }),
+    });
+  }
+
+  /** @returns {void} */
+  abort() {
+    this.#runAbort?.abort();
+    for (const controller of this.#controllers) controller.abort();
+    this.markOffline();
+  }
+
+  /**
+   * @param {readonly DirectHomeNodeCandidate[]} candidates
+   * @param {boolean} publishState
+   * @returns {Promise<HomeNodeClient>}
+   */
+  #shareRun(candidates, publishState) {
+    if (this.#run !== undefined) return this.#run;
+    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;
+    });
+    this.#run = run;
+    this.#runAbort = abort;
+    return run;
+  }
+
+  /**
+   * @param {readonly DirectHomeNodeCandidate[]} candidates
+   * @param {boolean} publishState
+   * @param {AbortSignalPort} signal
+   * @returns {Promise<HomeNodeClient>}
+   */
+  async #connect(candidates, publishState, signal) {
+    /** @type {string[]} */
+    /** @type {string[]} */
+    const failures = [];
+    for (const path of DIRECT_TIER_ORDER) {
+      throwIfAborted(signal);
+      const tier = candidates.filter((candidate) => candidate.path === path);
+      if (tier.length === 0) continue;
+      const attempts = tier.map((candidate) =>
+        this.#startAttempt(candidate, signal),
+      );
+      /** @type {(DialSuccess | DialFailure)[]} */
+      const outcomes = await Promise.all(
+        attempts.map(async (attempt) => {
+          try {
+            return { attempt, client: await attempt.promise, success: true };
+          } catch (error) {
+            failures.push(`${attempt.candidate.path}:${messageFor(error)}`);
+            return { attempt, success: false };
+          } finally {
+            this.#controllers.delete(attempt.controller);
+          }
+        }),
+      );
+      throwIfAborted(signal);
+      const successes = outcomes.filter((outcome) => outcome.success);
+      const winner = successes[0];
+      if (winner === undefined) {
+        for (const attempt of attempts) attempt.controller.abort();
+        continue;
+      }
+      await Promise.all(
+        successes.slice(1).map(async (outcome) => {
+          outcome.attempt.controller.abort();
+          await this.#closeClient(outcome.client);
+        }),
+      );
+      this.#selectedCandidate = { ...winner.attempt.candidate };
+      if (publishState) this.markConnected(winner.attempt.candidate.path);
+      return winner.client;
+    }
+    if (publishState) this.markOffline();
+    throw new Error(
+      `No home-node transport available (${failures.join(", ") || "no candidates"})`,
+    );
+  }
+
+  /**
+   * @param {DirectHomeNodeCandidate} candidate
+   * @param {AbortSignalPort} runSignal
+   * @returns {DialAttempt}
+   */
+  #startAttempt(candidate, runSignal) {
+    const controller = createRuntimeAbortController();
+    this.#controllers.add(controller);
+    return {
+      candidate,
+      controller,
+      promise: this.#dialWithTimeout(candidate, controller, runSignal),
+    };
+  }
+
+  /**
+   * @param {DirectHomeNodeCandidate} candidate
+   * @param {AbortControllerPort} controller
+   * @param {AbortSignalPort} runSignal
+   * @returns {Promise<HomeNodeClient>}
+   */
+  async #dialWithTimeout(candidate, controller, runSignal) {
+    const dial = this.#dial(candidate, controller.signal);
+    void dial
+      .then(async (client) => {
+        if (controller.signal.aborted || runSignal.aborted)
+          await this.#closeClient(client);
+      })
+      .catch(() => undefined);
+    const cancellation = Promise.race([
+      rejectedOnAbort(controller.signal),
+      rejectedOnAbort(runSignal),
+    ]);
+    if (this.#delay === undefined)
+      return await Promise.race([dial, cancellation]);
+    const timeout = this.#delay.wait(this.#candidateTimeoutMs).then(() => {
+      controller.abort();
+      throw new Error("candidate dial timed out");
+    });
+    return await Promise.race([dial, timeout, cancellation]);
+  }
+
+  /**
+   * @param {ClosableHomeNodeClient} client
+   * @returns {Promise<void>}
+   */
+  async #closeClient(client) {
+    if (this.#closedClients.has(client)) return;
+    this.#closedClients.add(client);
+    await closeClient(client);
+  }
+
+  /**
+   * @param {TransportState} next
+   * @returns {void}
+   */
+  #setState(next) {
+    if (!transportStateChanged(this.#state, next)) return;
+    this.#state = next;
+    this.#onState(next);
+    for (const listener of [...this.#listeners]) listener(next);
+  }
+}
+
+/** @param {TransportState} current @param {TransportState} next @returns {boolean} */
+export function transportStateChanged(current, next) {
+  if (current.status !== next.status || current.path !== next.path) return true;
+  if (current.status === "connecting" && next.status === "connecting")
+    return current.attempt !== next.attempt;
+  if (current.status === "reconnecting" && next.status === "reconnecting")
+    return (
+      current.attempt !== next.attempt ||
+      current.nextRetryAt !== next.nextRetryAt
+    );
+  if (current.status === "offline" && next.status === "offline")
+    return current.reason !== next.reason;
+  return false;
+}
+
+/** @param {number} attempt @returns {number} */
+function wholeAttempt(attempt) {
+  return Number.isFinite(attempt) ? Math.max(1, Math.trunc(attempt)) : 1;
+}
+
+/**
+ * @param {readonly DirectHomeNodeCandidate[]} candidates
+ * @returns {readonly DirectHomeNodeCandidate[]}
+ */
+function normalizeDirectCandidates(candidates) {
+  /** @type {Record<DirectTransportPath, DirectHomeNodeCandidate[]>} */
+  /** @type {Record<DirectTransportPath, DirectHomeNodeCandidate[]>} */
+  const tiers = {
+    "lan-direct": [],
+    "lan-webtransport": [],
+    "wan-direct": [],
+  };
+  const seen = new Set();
+  const trustedNodeIds = new Set();
+  for (const candidate of candidates) {
+    if (
+      !isDirectCandidate(candidate) ||
+      candidate.address.trim() === "" ||
+      candidate.id.trim() === ""
+    ) {
+      throw new TypeError(
+        "Direct transport candidates must have a path, address, and id",
+      );
+    }
+    const address = canonicalHttpCandidateOrigin(candidate.address);
+    const identityBinding =
+      candidate.path === "lan-webtransport"
+        ? undefined
+        : candidate.identityBinding;
+    if (identityBinding !== "bootstrap") trustedNodeIds.add(candidate.id);
+    const key = JSON.stringify([candidate.path, address, candidate.id]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    tiers[candidate.path].push({ ...candidate, address });
+  }
+  if (trustedNodeIds.size > 1) {
+    throw new TypeError(
+      "Direct transport candidates must share one trusted home-node identity",
+    );
+  }
+  return DIRECT_TIER_ORDER.flatMap((path) => tiers[path]);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function canonicalHttpCandidateOrigin(value) {
+  /** @type {RuntimeUrl} */
+  let url;
+  try {
+    url = parseRuntimeUrl(value);
+  } catch {
+    throw new TypeError(DIRECT_ORIGIN_MESSAGE);
+  }
+  if (
+    !isPotentiallyTrustworthyOrigin(url) ||
+    url.username !== "" ||
+    url.password !== "" ||
+    url.hostname === "" ||
+    url.origin !== value
+  ) {
+    throw new TypeError(DIRECT_ORIGIN_MESSAGE);
+  }
+  return url.origin;
+}
+
+const DIRECT_ORIGIN_MESSAGE =
+  "Direct transport candidates must use an exact HTTPS origin (or a loopback HTTP origin)";
+
+/** @param {RuntimeUrl} url @returns {boolean} */
+export function isPotentiallyTrustworthyOrigin(url) {
+  if (url.protocol === "https:") return true;
+  if (url.protocol !== "http:") return false;
+  const host = url.hostname.toLowerCase();
+  return (
+    host === "localhost" ||
+    host.endsWith(".localhost") ||
+    host === "[::1]" ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/u.test(host)
+  );
+}
+
+/**
+ * @param {DirectHomeNodeCandidate} candidate
+ * @returns {boolean}
+ */
+function isDirectCandidate(candidate) {
+  return (
+    candidate.path === "lan-direct" ||
+    candidate.path === "lan-webtransport" ||
+    candidate.path === "wan-direct"
+  );
+}
+
+/**
+ * @param {DirectTransportPath} path
+ * @returns {number}
+ */
+function priority(path) {
+  return DIRECT_TIER_ORDER.indexOf(path);
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function messageFor(error) {
+  return error instanceof Error ? error.message : "unavailable";
+}
+
+/**
+ * @param {ClosableHomeNodeClient} client
+ * @returns {Promise<void>}
+ */
+async function closeClient(client) {
+  if (client.close === undefined) return;
+  await Promise.resolve(client.close()).catch(() => undefined);
+}
+
+/**
+ * @param {AbortSignalPort} signal
+ * @returns {Promise<never>}
+ */
+function rejectedOnAbort(signal) {
+  if (signal.aborted)
+    return Promise.reject(new Error("transport selection aborted"));
+  return new Promise((_resolve, reject) => {
+    signal.addEventListener(
+      "abort",
+      () => reject(new Error("transport selection aborted")),
+      { once: true },
+    );
+  });
+}
+
+/**
+ * @param {AbortSignalPort} signal
+ * @returns {void}
+ */
+function throwIfAborted(signal) {
+  if (signal.aborted) throw new Error("transport selection aborted");
+}