@truenas/api-client 4.0.0 → 4.0.1

package/dist/index.cjs

@@ -2389,8 +2389,11 @@ var apiVersionConfig = {
    * - DNS lookup failure
    * - Server unreachable
    *
-   * Using this fallback means systems with genuine network issues will still
-   * attempt connection (and fail during WebSocket handshake instead of immediately).
+   * Which is why it is no longer reached on all of them. A discovery failure is
+   * now put to a reachability probe and a second attempt first, and only an
+   * appliance that answers the probe and still will not serve `/api/versions`
+   * is assumed to be this version. One that answers nothing is reported as
+   * unreachable rather than pinned to a version nobody confirmed.
    */
   FALLBACK_VERSION: "v25.10.0"
 };
@@ -3753,6 +3756,12 @@ var InvalidVersionResponseError = class extends VersionDiscoveryError {
   }
 };
 var discoveryTimeoutMs = 5e3;
+var probeTimeoutMs = 5e3;
+function corsIsEnforced() {
+  const hasDocument = typeof window !== "undefined" && typeof window.document !== "undefined";
+  const inWorker = typeof globalThis.WorkerGlobalScope !== "undefined";
+  return hasDocument || inWorker;
+}
 function hasErrorName(error, expected) {
   return typeof error === "object" && error !== null && "name" in error && error.name === expected;
 }
@@ -3765,6 +3774,42 @@ var VersionDiscovery = class {
   versionsUrl(hostname) {
     return `${httpScheme(this.protocol)}//${hostname}/api/versions`;
   }
+  /**
+   * Whether the appliance answers at all, asked in a way CORS cannot block.
+   *
+   * A `no-cors` request yields a response the page may not read, but its
+   * *arrival* is the whole answer here: something served it. That separates the
+   * two failures `fetch` reports identically — a box that refused to share its
+   * versions with this origin, and a box that is not there.
+   *
+   * `cannot-ask` where CORS is not enforced: nothing is blocking anything, so a
+   * failed fetch already means unreachable and a probe would only repeat what
+   * discovery just found. It is not a quieter way of saying "no".
+   */
+  async probeReachable(hostname) {
+    if (!corsIsEnforced()) return "cannot-ask";
+    const url = this.versionsUrl(hostname);
+    const controller = new AbortController();
+    const timer2 = setTimeout(() => controller.abort(), probeTimeoutMs);
+    try {
+      await fetch(url, {
+        mode: "no-cors",
+        cache: "no-store",
+        signal: controller.signal
+      });
+      this.logger.info("Reachability probe answered", { hostname, url });
+      return "reachable";
+    } catch (error) {
+      this.logger.warn("Reachability probe got no answer", {
+        hostname,
+        url,
+        error
+      });
+      return "silent";
+    } finally {
+      clearTimeout(timer2);
+    }
+  }
   /**
    * Discovers the API version for a given hostname.
    *
@@ -4024,30 +4069,81 @@ async function createTrueNasClient(opts) {
       });
       throw error;
     }
-    const fallbackVersionString = apiVersionConfig.FALLBACK_VERSION;
-    const fallbackVersion = parseApiVersion(fallbackVersionString);
-    if (!fallbackVersion) {
-      logger.error("Invalid fallback version configuration", {
-        uuid: uuid.slice(0, 8),
-        hostnames: hostnames.join(", "),
-        fallbackVersion: fallbackVersionString
-      });
-      throw error;
+    const reachable = await probeAnyHostname(hostnames, versionDiscovery);
+    if (reachable === "silent") {
+      await sleep(unreachableRetryDelayMs);
     }
-    logger.warn(
-      "Version discovery failed with a network error (possible CORS or network issue), falling back to assumed version",
-      {
+    try {
+      const retryWinner = await discoverVersionFromAnyHostname(
+        hostnames,
+        versionDiscovery
+      );
+      logger.info("Version discovery succeeded on retry", {
         uuid: uuid.slice(0, 8),
-        hostnames: hostnames.join(", "),
-        fallbackVersion: fallbackVersionString,
-        originalError: errorMessage,
-        warning: "A network error has multiple causes (CORS, network down, DNS failure). The connection may still fail during the WebSocket handshake."
+        hostname: retryWinner.hostname,
+        version: retryWinner.version.version,
+        firstError: errorMessage
+      });
+      version = retryWinner.version;
+    } catch (retryError) {
+      if (!(retryError instanceof VersionDiscoveryNetworkError)) {
+        throw retryError;
       }
-    );
-    version = fallbackVersion;
+      if (reachable !== "reachable") {
+        logger.error(
+          "Version discovery failed and the appliance did not answer a reachability probe; not assuming a version",
+          {
+            uuid: uuid.slice(0, 8),
+            hostnames: hostnames.join(", "),
+            probe: reachable === "silent" ? "no answer" : "not applicable",
+            error: errorMessageOrDefault(retryError, "Unknown error")
+          }
+        );
+        throw retryError;
+      }
+      const fallbackVersionString = apiVersionConfig.FALLBACK_VERSION;
+      const fallbackVersion = parseApiVersion(fallbackVersionString);
+      if (!fallbackVersion) {
+        logger.error("Invalid fallback version configuration", {
+          uuid: uuid.slice(0, 8),
+          hostnames: hostnames.join(", "),
+          fallbackVersion: fallbackVersionString
+        });
+        throw retryError;
+      }
+      logger.warn(
+        "Appliance is reachable but version discovery is still blocked; falling back to assumed version",
+        {
+          uuid: uuid.slice(0, 8),
+          hostnames: hostnames.join(", "),
+          fallbackVersion: fallbackVersionString,
+          originalError: errorMessage,
+          warning: "The appliance answered a probe but not /api/versions, which is what v25.10.0 looks like from a browser. If it is newer than that, this client is now pinned to the wrong surface."
+        }
+      );
+      version = fallbackVersion;
+    }
   }
   return instantiateClientForVersion(version, opts, logger);
 }
+var unreachableRetryDelayMs = 2500;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function probeAnyHostname(hostnames, versionDiscovery) {
+  const probes = hostnames.map(
+    (hostname) => versionDiscovery.probeReachable(hostname)
+  );
+  const remaining = new Set(probes);
+  let sawSilence = false;
+  while (remaining.size > 0) {
+    const settled = await Promise.race(
+      [...remaining].map((probe) => probe.then((result) => ({ probe, result })))
+    );
+    if (settled.result === "reachable") return "reachable";
+    if (settled.result === "silent") sawSilence = true;
+    remaining.delete(settled.probe);
+  }
+  return sawSilence ? "silent" : "cannot-ask";
+}
 async function discoverVersionFromAnyHostname(hostnames, versionDiscovery) {
   const attempts = hostnames.map(
     (hostname) => rxjs.firstValueFrom(versionDiscovery.discoverVersion(hostname)).then(