@truenas/api-client 3.0.3 → 3.0.4

package/README.md

@@ -82,6 +82,49 @@ client.api.events('app.query').subscribe(event => {
 });
 ```
 
+### Reaching an appliance over http
+
+By default the client discovers over `https://` and connects over `wss://`,
+which is what an appliance serves. An appliance reached without TLS needs
+`protocol`:
+
+```typescript
+import type { ApplianceProtocol } from '@truenas/api-client';
+
+const protocol: ApplianceProtocol =
+  location.protocol === 'http:' ? 'http:' : 'https:';
+
+const client = await createTrueNasClient({
+  uuid, hostnames: [location.host], enabled: true, protocol,
+});
+```
+
+It selects both halves of the transport — `https:` gives `https` discovery and a
+`wss` socket, `http:` gives `http` and `ws` — and defaults to `https:`, so
+existing callers are unaffected.
+
+`protocol` describes the **appliance**, not the page. Reading it from
+`location.protocol` is right when the appliance serves the page, which is the
+same-origin case this exists for. A page served from somewhere else — a dev
+server on `http://localhost:5173` talking to an https appliance — must pass what
+the *appliance* uses. Getting it wrong breaks both halves but reports only one:
+discovery's `fetch` follows the redirect and looks fine, while the socket opens
+`ws://`, meets the same redirect, and fails the handshake without naming the
+scheme.
+
+Omitting it against a plaintext appliance fails the other way, and more quietly.
+Discovery tries `https://`, `fetch` rejects, and the factory cannot tell that
+apart from the CORS block that v25.10.0 has on `/api/versions` — so it takes the
+fallback and hands back a client pinned to `v25.10.0` on `/api/v25.10.0`, with
+only a `logger.warn` to say so. Against a v26 or v27 box that is a wrong-version
+client that looks configured. If the appliance is plaintext, say so.
+
+Narrow rather than cast: `location.protocol` is a `string`, and it is genuinely
+`file:` for a locally-opened page or `chrome-extension:` in an extension. Both
+halves fall back to the encrypted scheme for anything off-contract, so a bad
+value cannot downgrade the transport — but the compiler will not stop you
+asserting one into this option, and it will not be the value you meant.
+
 ### Naming a version
 
 By default the version is discovered at runtime while the types are fixed at

package/dist/index.cjs

@@ -694,11 +694,19 @@ var TrueNasSocket = class {
   }
 };
 
+// src/types/transport.type.ts
+function httpScheme(protocol) {
+  return protocol === "http:" ? "http:" : "https:";
+}
+function socketScheme(protocol) {
+  return protocol === "http:" ? "ws:" : "wss:";
+}
+
 // src/connection/truenas-connection.ts
 var tenSeconds = 10 * 1e3;
 var twentySeconds = 20 * 1e3;
 var TrueNasConnection = class {
-  constructor(initialEnabled, hostnames, systemUuid, websocketPath, systemName, retryDelay = tenSeconds, maxRetry = 3, logger = noopLogger) {
+  constructor(initialEnabled, hostnames, systemUuid, websocketPath, systemName, retryDelay = tenSeconds, maxRetry = 3, logger = noopLogger, protocol = "https:") {
     this.hostnames = hostnames;
     this.systemUuid = systemUuid;
     this.websocketPath = websocketPath;
@@ -706,6 +714,7 @@ var TrueNasConnection = class {
     this.retryDelay = retryDelay;
     this.maxRetry = maxRetry;
     this.logger = logger;
+    this.protocol = protocol;
     // compatibility properties
     this.opened = new rxjs.BehaviorSubject(false);
     this.closed = new rxjs.Subject();
@@ -902,7 +911,7 @@ var TrueNasConnection = class {
    * error if the connection is never established and will not complete until unsubscribed from or closed.
    */
   createSocket(hostname) {
-    const url = `wss://${hostname}${this.websocketPath}`;
+    const url = `${socketScheme(this.protocol)}//${hostname}${this.websocketPath}`;
     let hasOpened = false;
     return new rxjs.Observable((subscriber) => {
       const ws = new TrueNasSocket({
@@ -3001,13 +3010,14 @@ function getWebSocketPath(version) {
 
 // src/client/truenas-api-client.ts
 var TrueNasApiClient = class {
-  constructor(uuid, hostnames, version, enabled, systemName, logger = noopLogger) {
+  constructor(uuid, hostnames, version, enabled, systemName, logger = noopLogger, protocol = "https:") {
     this.uuid = uuid;
     this.hostnames = hostnames;
     this.version = version;
     this.enabled = enabled;
     this.systemName = systemName;
     this.logger = logger;
+    this.protocol = protocol;
     this.connection = this.createConnection();
     this.authenticator = this.createAuthenticator();
     this.api = this.createApi();
@@ -3050,7 +3060,8 @@ var TrueNasApiClient = class {
       // retryDelay (use default)
       void 0,
       // maxRetry (use default)
-      this.logger
+      this.logger,
+      this.protocol
     );
   }
   /**
@@ -3444,14 +3455,18 @@ function hasErrorName(error, expected) {
   return typeof error === "object" && error !== null && "name" in error && error.name === expected;
 }
 var VersionDiscovery = class {
-  constructor(logger = noopLogger) {
+  constructor(logger = noopLogger, protocol = "https:") {
     this.logger = logger;
+    this.protocol = protocol;
     this.versionCache = /* @__PURE__ */ new Map();
   }
+  versionsUrl(hostname) {
+    return `${httpScheme(this.protocol)}//${hostname}/api/versions`;
+  }
   /**
    * Discovers the API version for a given hostname.
    *
-   * Makes a GET request to `https://{hostname}/api/versions` and returns the latest
+   * Makes a GET request to `{protocol}//{hostname}/api/versions` and returns the latest
    * compatible version. Results are cached per hostname; the cache entry is removed
    * on failure so the next call retries.
    *
@@ -3465,8 +3480,10 @@ var VersionDiscovery = class {
       this.logger.info("Version discovery cache hit", { hostname });
       return cached;
     }
-    const url = `https://${hostname}/api/versions`;
-    this.logger.info("Starting version discovery", { hostname, url });
+    this.logger.info("Starting version discovery", {
+      hostname,
+      url: this.versionsUrl(hostname)
+    });
     const discovery$ = rxjs.defer(() => rxjs.from(this.fetchVersions(hostname))).pipe(
       operators.map((versionStrings) => this.selectVersion(hostname, versionStrings)),
       operators.catchError((error) => {
@@ -3504,7 +3521,7 @@ var VersionDiscovery = class {
    * misfile as a network error. Validating here keeps it an `InvalidVersionResponseError`.
    */
   async fetchVersions(hostname) {
-    const url = `https://${hostname}/api/versions`;
+    const url = this.versionsUrl(hostname);
     const controller = new AbortController();
     const timer2 = setTimeout(() => controller.abort(), discoveryTimeoutMs);
     try {
@@ -3677,7 +3694,7 @@ async function createTrueNasClient(opts) {
     });
     return instantiateClientForVersion(known, opts, logger);
   }
-  const versionDiscovery = new VersionDiscovery(logger);
+  const versionDiscovery = new VersionDiscovery(logger, opts.protocol);
   let version;
   try {
     const winner = await discoverVersionFromAnyHostname(
@@ -3786,7 +3803,8 @@ function instantiateClientForVersion(version, opts, logger) {
     version,
     enabled,
     systemName,
-    logger
+    logger,
+    opts.protocol
   );
 }
 function errorMessageOrDefault(error, fallback) {