@truenas/api-client 4.0.0 → 4.0.2

package/README.md

@@ -183,6 +183,65 @@ discovery route that resolves against whatever the appliance turned out to be.
 On the named route it cannot: the client class is picked from the version you
 stated, so `ops` is that version's mappings whether or not the server agrees.
 
+`ops` is deliberately flat — `OperationMappings`, not parameterized by the
+directory — so every operation is callable whether or not you pinned a version.
+That is what lets an operation paper over a difference the type system would
+otherwise force the caller to handle.
+
+```ts
+// The same call on every supported version.
+const sessions = await firstValueFrom(
+  client.ops.smbStatus({ infoLevel: 'SESSIONS' })
+);
+
+// A client count is this composed, not a second operation.
+const count = await firstValueFrom(
+  client.ops.smbStatus({
+    infoLevel: 'SESSIONS',
+    options: { count: true },
+    statusOptions: { fast: true },
+  })
+);
+```
+
+`smbStatus` is worth singling out, because it is the first operation whose
+v25.10 leg is invisible to `middlewared --dump-api`. `smb.status` is public on
+v26+ and generated like any other method; on v25.10 it is the same method taking
+the same four positional arguments and returning the same `list | dict | int`,
+but middleware declares it `private=True`, so the dump omits it and no generated
+v25.10 type mentions it. The v25.10 client therefore *asserts* the method exists
+rather than reading it from the directory — a single narrow declaration admitting
+one method name, one argument tuple and one return type, checked against
+middleware source instead of against the dump.
+
+Three consequences worth knowing before you reach for it.
+
+**It needs a full-admin session on v25.10.** Being private there decides
+authorization, not just documentation. `smb.status` declares no roles on
+v25.10, and middleware role-registers a method only `if roles:` — so it is in no
+role's allowlist, and only a **non-STIG full-admin** session, whose allowlist is
+the wildcard `{ method: '*', resource: '*' }`, reaches it. A session holding
+exactly `SHARING_SMB_READ` is refused with `EACCES` on v25.10 and succeeds on
+v26+, where the method carries that role. Under STIG, full admin is expanded to
+the union of its roles' allowlists rather than the wildcard, so it is refused on
+v25.10 as well. The client does not pre-empt any of this: you get middleware's
+own error, on the version where it applies.
+
+**It logs server-side on every dispatch**, which matters if you poll it. v25.10
+is in maintenance and that cost is accepted there, but it is not a pattern to
+extend.
+
+**The result is the union middleware sends** — which arm arrives is decided by
+the options, not the info level — so callers narrow it themselves.
+
+These types are deliberately not the generated ones. `SmbStatusOptions` is not
+v26's `SMBStatusOptions`, and `SmbStatusResponse` is not that method's generated
+response: the generated types describe one version's dump, while these describe
+the contract both versions honour. They are named `Smb…` rather than `SMB…` so
+the two cannot be confused at a call site — and `SmbStatusOptions` is the one
+pair where the names sit closest, since it is the fourth positional argument on
+both versions.
+
 ## Documentation
 
 The API reference is generated from the TSDoc comments in the source with

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"
 };
@@ -3446,6 +3449,16 @@ function toAppState(state) {
   }
 }
 
+// src/utils/smb-status.utils.ts
+function toSmbStatusParams(request = {}) {
+  return [
+    request.infoLevel ?? "ALL",
+    request.filters ?? [],
+    request.options ?? {},
+    request.statusOptions ?? {}
+  ];
+}
+
 // src/client/truenas-api-client-v25-10.ts
 var TrueNasApiClientV2510 = class extends TrueNasApiClient {
   /**
@@ -3485,6 +3498,42 @@ var TrueNasApiClientV2510 = class extends TrueNasApiClient {
           );
         }
         return this.api.job("virt.instance.delete", [id]);
+      },
+      // The private leg. See `PrivateSmbStatusCall` for why this is a cast and
+      // not a directory lookup.
+      //
+      // v25.10 answers rather than refusing, for a caller with the authority.
+      // Being private does not stop the method running: `ws_handler/rpc.py`
+      // logs a warning for a private call over websocket and dispatches it
+      // anyway — the `# FIXME: Eventually, prohibit this` above that branch is
+      // still unresolved on master.
+      //
+      // It does decide who may run it. `smb.status` carries no `roles=` here,
+      // and middleware role-registers a method only `if roles:`, so it is in no
+      // role's allowlist and only the non-STIG full-admin wildcard reaches it.
+      // That is documented on `OperationMappings.smbStatus`; this leg does not
+      // pre-empt it. A caller without the authority gets middleware's `EACCES`,
+      // which is the honest answer and the server's to give.
+      //
+      // The server-side warning is per dispatch, and a client count is exactly
+      // the sort of thing a caller polls. Reported at debug rather than warn,
+      // because nothing here is degraded or unhonoured — the request is served
+      // in full — and left to the caller to weigh.
+      //
+      // Future tense, and for the same reason as `containerDelete` above: this
+      // runs when the operation is built, and `api.call` is cold, so no request
+      // has gone out yet and may never. One built observable subscribed twice
+      // dispatches twice; this line is what will happen, not a record that it
+      // did.
+      smbStatus: (request) => {
+        this.logger.debug(
+          "smbStatus: smb.status is private on v25.10; each dispatch will log a warning server-side and needs a non-STIG full-admin session",
+          { method: "smb.status", infoLevel: request?.infoLevel ?? "ALL" }
+        );
+        return this.api.call(
+          "smb.status",
+          toSmbStatusParams(request)
+        );
       }
     };
   }
@@ -3572,7 +3621,16 @@ var TrueNasApiClientV26 = class extends TrueNasApiClient {
       containerDelete: (id, options) => this.api.job(
         "container.delete",
         options ? [parseInt(id, 10), options] : [parseInt(id, 10)]
-      )
+      ),
+      // `smb.status` is public here and gated on `SHARING_SMB_READ`, so it is
+      // an ordinary `call` read straight out of the generated directory — the
+      // one leg of this operation that needs no assertion about the server.
+      //
+      // Not a query verb: middleware returns the same `list | dict | int`
+      // polymorphism a `.query` does, but the generator did not mark the entry
+      // with an `entity`, so `api.query` does not accept it and the union is
+      // handed to the caller to narrow.
+      smbStatus: (request) => this.api.call("smb.status", toSmbStatusParams(request))
     };
   }
 };
@@ -3653,7 +3711,16 @@ var TrueNasApiClientV27 = class extends TrueNasApiClient {
       containerDelete: (id, options) => this.api.job(
         "container.delete",
         options ? [parseInt(id, 10), options] : [parseInt(id, 10)]
-      )
+      ),
+      // `smb.status` is public here and gated on `SHARING_SMB_READ`, so it is
+      // an ordinary `call` read straight out of the generated directory — the
+      // one leg of this operation that needs no assertion about the server.
+      //
+      // Not a query verb: middleware returns the same `list | dict | int`
+      // polymorphism a `.query` does, but the generator did not mark the entry
+      // with an `entity`, so `api.query` does not accept it and the union is
+      // handed to the caller to narrow.
+      smbStatus: (request) => this.api.call("smb.status", toSmbStatusParams(request))
     };
   }
 };
@@ -3753,6 +3820,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 +3838,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 +4133,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(