@truenas/api-client 4.0.0 → 4.0.1

package/dist/index.d.cts

@@ -30429,9 +30429,10 @@ interface CreateClientOptions {
      *
      * Omitting it against a plaintext appliance is the quieter failure and the
      * likelier one, since it is the case this option exists for. Discovery tries
-     * `https`, `fetch` rejects, and that is indistinguishable from the CORS block
-     * v25.10.0 has on `/api/versions` — so the fallback fires and the caller gets
-     * a client pinned to v25.10.0, warned about only in the log.
+     * `https` and `fetch` rejects, which reads exactly like the CORS block
+     * v25.10.0 has on `/api/versions`. The reachability probe now runs on the same
+     * scheme and fails the same way, so the mismatch is reported as unreachable
+     * rather than quietly answered with a v25.10.0 client.
      */
     protocol?: ApplianceProtocol;
 }
@@ -30545,11 +30546,18 @@ interface CreateClientOptions {
  * @returns a Promise that resolves with the created client, or rejects with a
  *   {@link VersionDiscoveryError} subclass (or a client-selection error).
  *   Rejects if version discovery on all hostnames *fails* and is not recoverable.
- *   Note that when the selected failure is a `VersionDiscoveryNetworkError`,
- *   this function attempts to use a fallback API version (see `FALLBACK_VERSION`)
- *   because network errors are actually expected on 25.10.0 systems due to a CORS
- *   bug. A network error alongside a version-compatibility error or a 404 does
- *   *not* reach the fallback — see `selectRepresentativeFailure`.
+ *
+ *   A `VersionDiscoveryNetworkError` is not by itself a verdict: `fetch` reports
+ *   a CORS refusal, an absent appliance, a bad name and the wrong scheme
+ *   identically. So that failure opens a reachability probe and a second
+ *   discovery attempt. A retry that succeeds is used; one that fails with a
+ *   specific error raises that instead; an appliance that answers nothing
+ *   rejects with the network error. Only one that answers the probe and still
+ *   will not serve `/api/versions` — which is what 25.10.0 looks like from a
+ *   browser — falls back to `FALLBACK_VERSION`.
+ *
+ *   A network error alongside a version-compatibility error or a 404 does
+ *   *not* reach any of that — see `selectRepresentativeFailure`.
  */
 declare function createTrueNasClient<V extends SupportedApiVersion>(opts: CreateClientOptions & {
     version: V;
@@ -30694,6 +30702,13 @@ declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
     protected createOperations(): OperationMappings;
 }
 
+/**
+ * What a reachability probe found. Three states rather than two: "we asked and
+ * got silence" and "there was no way to ask" refuse the CORS fallback for
+ * different reasons, and collapsing them into one `false` is the conflation
+ * this whole change exists to undo.
+ */
+type Reachability = 'reachable' | 'silent' | 'cannot-ask';
 /**
  * Discovers available API versions from TrueNAS systems.
  *
@@ -30708,8 +30723,10 @@ declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
  * service. Because `fetch` resolves (rather than rejects) on non-2xx responses and
  * throws a `TypeError` on network/CORS/unreachable failures, the error contract
  * differs from the original: a network/CORS/unreachable failure surfaces as a
- * {@link VersionDiscoveryNetworkError} — the sentinel the client factory keys on for
- * its CORS fallback (replacing the old `HttpErrorResponse.status === 0` check).
+ * {@link VersionDiscoveryNetworkError} (replacing the old
+ * `HttpErrorResponse.status === 0` check). That error names a symptom with
+ * several causes, so it opens the client factory's disambiguation rather than
+ * deciding it — see {@link VersionDiscovery.probeReachable}.
  */
 declare class VersionDiscovery {
     private readonly logger;
@@ -30717,6 +30734,19 @@ declare class VersionDiscovery {
     private versionCache;
     constructor(logger?: Logger, protocol?: ApplianceProtocol);
     private versionsUrl;
+    /**
+     * 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".
+     */
+    probeReachable(hostname: string): Promise<Reachability>;
     /**
      * Discovers the API version for a given hostname.
      *

package/dist/index.d.ts

@@ -30429,9 +30429,10 @@ interface CreateClientOptions {
      *
      * Omitting it against a plaintext appliance is the quieter failure and the
      * likelier one, since it is the case this option exists for. Discovery tries
-     * `https`, `fetch` rejects, and that is indistinguishable from the CORS block
-     * v25.10.0 has on `/api/versions` — so the fallback fires and the caller gets
-     * a client pinned to v25.10.0, warned about only in the log.
+     * `https` and `fetch` rejects, which reads exactly like the CORS block
+     * v25.10.0 has on `/api/versions`. The reachability probe now runs on the same
+     * scheme and fails the same way, so the mismatch is reported as unreachable
+     * rather than quietly answered with a v25.10.0 client.
      */
     protocol?: ApplianceProtocol;
 }
@@ -30545,11 +30546,18 @@ interface CreateClientOptions {
  * @returns a Promise that resolves with the created client, or rejects with a
  *   {@link VersionDiscoveryError} subclass (or a client-selection error).
  *   Rejects if version discovery on all hostnames *fails* and is not recoverable.
- *   Note that when the selected failure is a `VersionDiscoveryNetworkError`,
- *   this function attempts to use a fallback API version (see `FALLBACK_VERSION`)
- *   because network errors are actually expected on 25.10.0 systems due to a CORS
- *   bug. A network error alongside a version-compatibility error or a 404 does
- *   *not* reach the fallback — see `selectRepresentativeFailure`.
+ *
+ *   A `VersionDiscoveryNetworkError` is not by itself a verdict: `fetch` reports
+ *   a CORS refusal, an absent appliance, a bad name and the wrong scheme
+ *   identically. So that failure opens a reachability probe and a second
+ *   discovery attempt. A retry that succeeds is used; one that fails with a
+ *   specific error raises that instead; an appliance that answers nothing
+ *   rejects with the network error. Only one that answers the probe and still
+ *   will not serve `/api/versions` — which is what 25.10.0 looks like from a
+ *   browser — falls back to `FALLBACK_VERSION`.
+ *
+ *   A network error alongside a version-compatibility error or a 404 does
+ *   *not* reach any of that — see `selectRepresentativeFailure`.
  */
 declare function createTrueNasClient<V extends SupportedApiVersion>(opts: CreateClientOptions & {
     version: V;
@@ -30694,6 +30702,13 @@ declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
     protected createOperations(): OperationMappings;
 }
 
+/**
+ * What a reachability probe found. Three states rather than two: "we asked and
+ * got silence" and "there was no way to ask" refuse the CORS fallback for
+ * different reasons, and collapsing them into one `false` is the conflation
+ * this whole change exists to undo.
+ */
+type Reachability = 'reachable' | 'silent' | 'cannot-ask';
 /**
  * Discovers available API versions from TrueNAS systems.
  *
@@ -30708,8 +30723,10 @@ declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
  * service. Because `fetch` resolves (rather than rejects) on non-2xx responses and
  * throws a `TypeError` on network/CORS/unreachable failures, the error contract
  * differs from the original: a network/CORS/unreachable failure surfaces as a
- * {@link VersionDiscoveryNetworkError} — the sentinel the client factory keys on for
- * its CORS fallback (replacing the old `HttpErrorResponse.status === 0` check).
+ * {@link VersionDiscoveryNetworkError} (replacing the old
+ * `HttpErrorResponse.status === 0` check). That error names a symptom with
+ * several causes, so it opens the client factory's disambiguation rather than
+ * deciding it — see {@link VersionDiscovery.probeReachable}.
  */
 declare class VersionDiscovery {
     private readonly logger;
@@ -30717,6 +30734,19 @@ declare class VersionDiscovery {
     private versionCache;
     constructor(logger?: Logger, protocol?: ApplianceProtocol);
     private versionsUrl;
+    /**
+     * 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".
+     */
+    probeReachable(hostname: string): Promise<Reachability>;
     /**
      * Discovers the API version for a given hostname.
      *

package/dist/index.js

@@ -2387,8 +2387,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"
 };
@@ -3751,6 +3754,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;
 }
@@ -3763,6 +3772,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.
    *
@@ -4022,30 +4067,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) => firstValueFrom(versionDiscovery.discoverVersion(hostname)).then(