@truenas/api-client 3.0.2 → 3.0.4

package/README.md

@@ -82,21 +82,106 @@ 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
 
-The version is discovered at runtime; the types are fixed at compile time.
-`createTrueNasClient` defaults to the oldest supported version, which
-understates a newer server rather than promising methods it lacks. Name a
-version to reach the rest:
+By default the version is discovered at runtime while the types are fixed at
+compile time, and `createTrueNasClient` assumes the oldest supported version —
+which understates a newer server rather than promising methods it lacks. There
+are two ways to reach the rest, and they differ in more than syntax.
+
+**Assert the surface** when you do not know the version but intend to write
+against a particular one:
 
 ```typescript
 const client = await createTrueNasClient<ApiDirectoryV26_0_0>(opts);
 client.api.query('container.query');                   // v26-only, reachable
 ```
 
-That is a claim about the server, not a guarantee — the client you get is
-whichever version discovery found. Operations that must work across versions
-belong on `client.ops`, which resolves them at runtime.
+Discovery still runs and still decides which client is built. The type argument
+is a claim about the server, not a guarantee — the client you get is whichever
+version discovery found, so a wrong claim fails at runtime.
+
+**State the version** when you already know it — a UI served by the appliance,
+a harness against a pinned image:
+
+```typescript
+const client = await createTrueNasClient({
+  uuid, hostnames, enabled: true, version: 'v27.0.0',
+});
+client.api.query('container.query');   // typed v27, derived from the string
+```
+
+This skips discovery entirely: no `GET /api/versions`, no CORS fallback. The
+surface is *derived* rather than asserted, so there is no type argument to get
+wrong, and a version the package ships no types for does not compile.
+
+It is the stronger claim of the two, because the version also selects the
+websocket path. Naming `v27.0.0` at a v26 appliance connects on `/api/v27.0.0`
+with v27 types over a v26 server, and discovery cannot correct it — declining
+discovery is the point.
+
+The derivation needs the version to be literal at the call site. Passing a type
+argument as well, forwarding `version` through a wrapper, or annotating the
+options object as `CreateClientOptions` all compile, all connect to the version
+you named, and all type as the default surface instead. That
+errs safely — understated types fail at the method call, not at runtime — but
+silently, so keep the literal where the call is.
+
+Compatibility is still checked, and two kinds of refusal reach a caller. A string that
+is not a supported version — reachable only from JavaScript — throws a plain
+`Error` naming the ones that are. A supported version this build has no client
+for throws `VersionTooNewError`, the same type discovery raises; that happens
+when types have been generated for a release before its client was written.
+There is no `VersionTooOldError` here, because the oldest version you can name
+is the oldest one supported.
+
+Operations that must work across versions belong on `client.ops`. On the
+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.
 
 ## Documentation
 

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 {
@@ -3644,12 +3661,40 @@ async function createTrueNasClient(opts) {
       `Cannot create client for system ${uuid}: hostnames array is empty`
     );
   }
-  const versionDiscovery = new VersionDiscovery(logger);
   logger.info("Creating versioned API client", {
     uuid: uuid.slice(0, 8),
     hostnames: hostnames.join(", "),
     systemName
   });
+  if (opts.version !== void 0) {
+    if (!SUPPORTED_API_VERSIONS.includes(opts.version)) {
+      throw new Error(
+        `Cannot create client for system ${uuid}: '${opts.version}' is not a version this package ships types for. Supported: ${SUPPORTED_API_VERSIONS.join(", ")}.`
+      );
+    }
+    const known = parseApiVersion(opts.version);
+    if (!known) {
+      throw new Error(
+        `Cannot create client for system ${uuid}: supported version '${opts.version}' failed to parse.`
+      );
+    }
+    const compatibility = checkVersionCompatibility(known);
+    if (compatibility === "too-new" /* TooNew */) {
+      throw new VersionTooNewError(hostnames[0], [known.version]);
+    }
+    if (compatibility !== "compatible" /* Compatible */) {
+      throw new Error(
+        `Cannot create client for system ${uuid}: the supported version range is not usable (${apiVersionConfig.MIN_SUPPORTED_VERSION}..${apiVersionConfig.MAX_SUPPORTED_VERSION}).`
+      );
+    }
+    logger.info("API version supplied by the caller, skipping discovery", {
+      uuid: uuid.slice(0, 8),
+      version: known.version,
+      websocketPath: known.websocketPath
+    });
+    return instantiateClientForVersion(known, opts, logger);
+  }
+  const versionDiscovery = new VersionDiscovery(logger, opts.protocol);
   let version;
   try {
     const winner = await discoverVersionFromAnyHostname(
@@ -3758,7 +3803,8 @@ function instantiateClientForVersion(version, opts, logger) {
     version,
     enabled,
     systemName,
-    logger
+    logger,
+    opts.protocol
   );
 }
 function errorMessageOrDefault(error, fallback) {