@truenas/api-client 2.0.0 → 2.0.1

package/dist/index.d.cts

@@ -27443,7 +27443,11 @@ type DefaultApiDirectory = ApiDirectory$7;
 interface CreateClientOptions {
     /** System UUID. */
     uuid: string;
-    /** Hostnames to connect to — primary first, then fallbacks. */
+    /**
+     * Hostnames to connect to. Order carries no precedence for version discovery
+     * (every hostname is asked at once); it only breaks ties when deciding which
+     * failure to report if none of them answer.
+     */
     hostnames: string[];
     /**
      * Initial connection gate. The client only opens a socket while this is `true`;
@@ -27462,7 +27466,8 @@ interface CreateClientOptions {
 /**
  * Creates a version-specific TrueNAS API client.
  *
- * 1. Discovers the API version from the primary hostname (`GET /api/versions`).
+ * 1. Discovers the API version (`GET /api/versions`), asking every hostname in
+ *    parallel. The first usable answer wins.
  * 2. Selects the matching client implementation (`v25.10.x` -> `TrueNasApiClientV2510`,
  *    `v26.x.y` -> `TrueNasApiClientV26`).
  * 3. Instantiates and returns it.
@@ -27498,7 +27503,12 @@ interface CreateClientOptions {
  *   it, so naming a method this surface does not have is a build error.
  * @returns a Promise that resolves with the created client, or rejects with a
  *   {@link VersionDiscoveryError} subclass (or a client-selection error).
- *   Rejects if `hostnames` is empty.
+ *   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`.
  */
 declare function createTrueNasClient<D extends ApiDirectoryShape = DefaultApiDirectory>(opts: CreateClientOptions): Promise<TrueNasApiClient<D>>;
 

package/dist/index.d.ts

@@ -27443,7 +27443,11 @@ type DefaultApiDirectory = ApiDirectory$7;
 interface CreateClientOptions {
     /** System UUID. */
     uuid: string;
-    /** Hostnames to connect to — primary first, then fallbacks. */
+    /**
+     * Hostnames to connect to. Order carries no precedence for version discovery
+     * (every hostname is asked at once); it only breaks ties when deciding which
+     * failure to report if none of them answer.
+     */
     hostnames: string[];
     /**
      * Initial connection gate. The client only opens a socket while this is `true`;
@@ -27462,7 +27466,8 @@ interface CreateClientOptions {
 /**
  * Creates a version-specific TrueNAS API client.
  *
- * 1. Discovers the API version from the primary hostname (`GET /api/versions`).
+ * 1. Discovers the API version (`GET /api/versions`), asking every hostname in
+ *    parallel. The first usable answer wins.
  * 2. Selects the matching client implementation (`v25.10.x` -> `TrueNasApiClientV2510`,
  *    `v26.x.y` -> `TrueNasApiClientV26`).
  * 3. Instantiates and returns it.
@@ -27498,7 +27503,12 @@ interface CreateClientOptions {
  *   it, so naming a method this surface does not have is a build error.
  * @returns a Promise that resolves with the created client, or rejects with a
  *   {@link VersionDiscoveryError} subclass (or a client-selection error).
- *   Rejects if `hostnames` is empty.
+ *   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`.
  */
 declare function createTrueNasClient<D extends ApiDirectoryShape = DefaultApiDirectory>(opts: CreateClientOptions): Promise<TrueNasApiClient<D>>;
 

package/dist/index.js

@@ -3304,7 +3304,7 @@ var VersionDiscovery = class {
       map$1((versionStrings) => this.selectVersion(hostname, versionStrings)),
       catchError((error) => {
         this.versionCache.delete(hostname);
-        this.logger.error("Version discovery failed", { hostname, error });
+        this.logger.warn("Version discovery failed", { hostname, error });
         return throwError(() => this.classify(error, hostname));
       }),
       shareReplay(1)
@@ -3375,7 +3375,7 @@ var VersionDiscovery = class {
     });
     const parsedVersions = versionStrings.map(parseApiVersion).filter((v) => v !== null);
     if (parsedVersions.length === 0) {
-      this.logger.error("No valid versions in response", {
+      this.logger.warn("No valid versions in response", {
         hostname,
         versionStrings
       });
@@ -3477,29 +3477,34 @@ async function createTrueNasClient(opts) {
       `Cannot create client for system ${uuid}: hostnames array is empty`
     );
   }
-  const primaryHostname = hostnames[0];
   const versionDiscovery = new VersionDiscovery(logger);
   logger.info("Creating versioned API client", {
     uuid: uuid.slice(0, 8),
-    hostname: primaryHostname,
+    hostnames: hostnames.join(", "),
     systemName
   });
   let version;
   try {
-    version = await firstValueFrom(
-      versionDiscovery.discoverVersion(primaryHostname)
+    const winner = await discoverVersionFromAnyHostname(
+      hostnames,
+      versionDiscovery
     );
+    version = winner.version;
     logger.info("API version discovered, instantiating client", {
       uuid: uuid.slice(0, 8),
+      // Which hostname answered is log context only. The client is built with
+      // the full hostname list regardless — the websocket connection races all
+      // of them anyway.
+      hostname: winner.hostname,
       version: version.version,
       websocketPath: version.websocketPath
     });
   } catch (error) {
     const errorMessage = errorMessageOrDefault(error, "Unknown error");
     if (!(error instanceof VersionDiscoveryNetworkError)) {
-      logger.error("Version discovery failed", {
+      logger.error("Version discovery failed on every hostname", {
         uuid: uuid.slice(0, 8),
-        hostname: primaryHostname,
+        hostnames: hostnames.join(", "),
         error: errorMessage,
         errorType: error instanceof Error ? error.constructor.name : typeof error
       });
@@ -3510,7 +3515,7 @@ async function createTrueNasClient(opts) {
     if (!fallbackVersion) {
       logger.error("Invalid fallback version configuration", {
         uuid: uuid.slice(0, 8),
-        hostname: primaryHostname,
+        hostnames: hostnames.join(", "),
         fallbackVersion: fallbackVersionString
       });
       throw error;
@@ -3519,7 +3524,7 @@ async function createTrueNasClient(opts) {
       "Version discovery failed with a network error (possible CORS or network issue), falling back to assumed version",
       {
         uuid: uuid.slice(0, 8),
-        hostname: primaryHostname,
+        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."
@@ -3529,6 +3534,27 @@ async function createTrueNasClient(opts) {
   }
   return instantiateClientForVersion(version, opts, logger);
 }
+async function discoverVersionFromAnyHostname(hostnames, versionDiscovery) {
+  const attempts = hostnames.map(
+    (hostname) => firstValueFrom(versionDiscovery.discoverVersion(hostname)).then(
+      (version) => ({ hostname, version })
+    )
+  );
+  try {
+    return await Promise.any(attempts);
+  } catch (error) {
+    const failures = error instanceof AggregateError ? error.errors : [error];
+    throw selectRepresentativeFailure(failures);
+  }
+}
+function selectRepresentativeFailure(failures) {
+  const isVersionError = (error) => (
+    // cases: valid response, but the given versions won't work for us
+    error instanceof VersionTooOldError || error instanceof VersionTooNewError || error instanceof NoCompatibleVersionsError || error instanceof VersionEndpointNotFoundError
+  );
+  const isNetworkError = (error) => error instanceof VersionDiscoveryNetworkError;
+  return failures.find(isVersionError) ?? failures.find(isNetworkError) ?? failures[0];
+}
 var CLIENT_BY_VERSION_KEY = {
   "25.10": TrueNasApiClientV2510,
   "26": TrueNasApiClientV26