@truenas/api-client 9.0.2 → 9.0.4

package/README.md

@@ -171,6 +171,30 @@ client you get. A named `version` skips discovery and also selects the
 WebSocket endpoint, so name the version the appliance actually runs. The types
 follow it when the version is a literal.
 
+To be written against one version but run against whatever the appliance
+serves, as an appliance's own UI is, keep the `version` and move the socket:
+
+```typescript
+const client = await createTrueNasClient({
+  ...options,
+  version: 'v28.0.0',            // the surface you compile against
+  websocketPath: '/api/current', // the appliance's newest version, whichever it is
+});
+```
+
+The client then works against an older or newer release call for call; a
+method or field that release lacks fails when it is called rather than at
+compile time.
+
+Each version's models are under its namespace, and its enums are values there
+as well as types, so a request can be built from them:
+
+```typescript
+import { v28_0_0 } from '@truenas/api-client';
+
+const type: v28_0_0.KeychainCredentialEntryType = v28_0_0.KeychainCredentialEntryType.SshKeyPair;
+```
+
 For code that must run against any supported release, use `client.ops`. It
 offers the same calls on every version and maps them onto whatever that version
 provides:
@@ -234,6 +258,29 @@ version stays the same, so a different version needs a new client:
 client.connection.setEndpoint({ hostnames: ['10.0.0.5'], protocol: 'http:' });
 ```
 
+An `interceptor` sees the connection's traffic, for a debug panel or for
+mocking calls in a running app. `outgoing` gets every frame before it is
+written, including the client's own `core.set_options` and `core.ping`, and
+returning `false` keeps a frame from `send` off the socket. `injected$` frames
+are read as if the appliance had sent them, one tick later. `incoming` gets
+every frame read:
+
+```typescript
+const mocked$ = new Subject<TrueNasMessage>();
+const client = await createTrueNasClient({
+  uuid, hostnames, enabled: true,
+  interceptor: {
+    outgoing: (frame) => {
+      if (frame.method !== 'system.info') return;
+      mocked$.next({ jsonrpc: '2.0', id: frame.id, result: fakeInfo });
+      return false;
+    },
+    incoming: (frame) => console.debug('<-', frame),
+    injected$: mocked$,
+  },
+});
+```
+
 An appliance served without TLS needs `protocol: 'http:'`, which switches
 discovery to `http` and the socket to `ws`. It describes the appliance, not the
 page, and defaults to `https:`.

package/dist/{chunk-PJVDHM2S.js → chunk-PEOXWWBS.js}

@@ -1,4 +1,4 @@
-import { BehaviorSubject, filter, switchMap, catchError, EMPTY, tap, map, finalize, take, Subject, distinctUntilChanged, of, startWith, concat, throwError, retry, race, timer, skip, takeUntil, shareReplay, interval, Observable, timeout, TimeoutError, toArray, from, defer, firstValueFrom, share, ignoreElements, merge, takeWhile, skipWhile, pairwise } from 'rxjs';
+import { BehaviorSubject, filter, switchMap, catchError, EMPTY, tap, map, finalize, take, Subject, distinctUntilChanged, of, startWith, concat, throwError, retry, race, timer, skip, takeUntil, shareReplay, merge, observeOn, asapScheduler, share, interval, Subscription, Observable, timeout, TimeoutError, toArray, from, defer, firstValueFrom, ignoreElements, takeWhile, skipWhile, pairwise } from 'rxjs';
 import { webSocket } from 'rxjs/webSocket';
 import { map as map$1, catchError as catchError$1, shareReplay as shareReplay$1 } from 'rxjs/operators';
 
@@ -3203,13 +3203,14 @@ function socketScheme(protocol) {
 var tenSeconds = 10 * 1e3;
 var twentySeconds = 20 * 1e3;
 var TrueNasConnection = class {
-  constructor(initialEnabled, hostnames, systemUuid, websocketPath, systemName, retryDelay = tenSeconds, maxRetry = 3, logger = noopLogger, protocol = "https:") {
+  constructor(initialEnabled, hostnames, systemUuid, websocketPath, systemName, retryDelay = tenSeconds, maxRetry = 3, logger = noopLogger, protocol = "https:", interceptor) {
     this.systemUuid = systemUuid;
     this.websocketPath = websocketPath;
     this.systemName = systemName;
     this.retryDelay = retryDelay;
     this.maxRetry = maxRetry;
     this.logger = logger;
+    this.interceptor = interceptor;
     // compatibility properties
     this.opened = new BehaviorSubject(false);
     this.closed = new Subject();
@@ -3267,6 +3268,7 @@ var TrueNasConnection = class {
         const initMessage = createJsonRpcMessage("core.set_options", [
           { legacy_jobs: false }
         ]);
+        this.interceptor?.outgoing?.(initMessage);
         connection.ws.next(initMessage);
         return connection.ws.messages().pipe(
           filter((msg) => msg.id === initMessage.id),
@@ -3365,22 +3367,27 @@ var TrueNasConnection = class {
       map((conn) => conn.state === "error"),
       takeUntil(this.closeConnection)
     );
-    /**
-     * observable which always emits messages from the current socket.
-     */
-    this.messages$ = this.ws$.pipe(
+    /** What the appliance sends, on whichever socket is current. */
+    this.socketMessages$ = this.ws$.pipe(
       filter((ws) => ws !== null),
       switchMap((ws) => ws.messages().pipe(
         catchError(() => EMPTY)
       ))
     );
+    this.messages$ = interceptor?.injected$ ? merge(this.socketMessages$, interceptor.injected$.pipe(observeOn(asapScheduler), share())) : this.socketMessages$;
     this.endpoint$.next(resolveEndpoint(hostnames, protocol));
     this.ws$.pipe(
       switchMap((ws) => ws ? interval(twentySeconds).pipe(map(() => ws)) : EMPTY),
       takeUntil(this.closeConnection)
     ).subscribe((ws) => {
-      ws.next(createJsonRpcMessage("core.ping"));
+      const ping = createJsonRpcMessage("core.ping");
+      this.interceptor?.outgoing?.(ping);
+      ws.next(ping);
     });
+    if (interceptor?.incoming) {
+      const incoming = interceptor.incoming.bind(interceptor);
+      this.messages$.pipe(takeUntil(this.closeConnection)).subscribe((message) => incoming(message));
+    }
     this.opened$.subscribe((val) => this.opened.next(val));
     this.closed$.subscribe(() => this.closed.next());
     this.hostname$.pipe(filter(Boolean)).subscribe((name) => this.hostname.next(name));
@@ -3449,6 +3456,9 @@ var TrueNasConnection = class {
    * the next `closed$` emission.
    */
   send(message) {
+    if (this.interceptor?.outgoing?.(message) === false) {
+      return Subscription.EMPTY;
+    }
     return this.ws$.pipe(
       filter((ws) => ws !== null),
       take(1)
@@ -3646,7 +3656,8 @@ var TrueNasApiClient = class {
       this.reconnect.retryDelay,
       this.reconnect.maxRetry,
       this.logger,
-      this.protocol
+      this.protocol,
+      this.reconnect.interceptor
     );
   }
   /**
@@ -4306,6 +4317,11 @@ async function createTrueNasClient(opts) {
       `Cannot create client for system ${uuid}: hostnames array is empty`
     );
   }
+  if (opts.websocketPath !== void 0 && !opts.websocketPath.startsWith("/")) {
+    throw new Error(
+      `Cannot create client for system ${uuid}: websocketPath must be an absolute path, got '${opts.websocketPath}'.`
+    );
+  }
   logger.info("Creating versioned API client", {
     uuid: uuid.slice(0, 8),
     hostnames: hostnames.join(", "),
@@ -4335,7 +4351,7 @@ async function createTrueNasClient(opts) {
     logger.info("API version supplied by the caller, skipping discovery", {
       uuid: uuid.slice(0, 8),
       version: known.version,
-      websocketPath: known.websocketPath
+      websocketPath: opts.websocketPath ?? known.websocketPath
     });
     return instantiateClientForVersion(known, opts, logger);
   }
@@ -4354,7 +4370,7 @@ async function createTrueNasClient(opts) {
       // of them anyway.
       hostname: winner.hostname,
       version: version.version,
-      websocketPath: version.websocketPath
+      websocketPath: opts.websocketPath ?? version.websocketPath
     });
   } catch (error) {
     const errorMessage = errorMessageOrDefault(error, "Unknown error");
@@ -4480,6 +4496,7 @@ function clientClassFor(version) {
 function instantiateClientForVersion(version, opts, logger) {
   const { uuid, hostnames, enabled, systemName } = opts;
   const versionKey = clientVersionKey(version);
+  const endpoint = opts.websocketPath === void 0 ? version : { ...version, websocketPath: opts.websocketPath };
   const Client = CLIENT_BY_VERSION_KEY[versionKey];
   if (!Client) {
     logger.error("No client implementation for version", {
@@ -4494,17 +4511,18 @@ function instantiateClientForVersion(version, opts, logger) {
   logger.info(`Instantiating ${Client.name}`, {
     uuid: uuid.slice(0, 8),
     version: version.version,
-    versionKey
+    versionKey,
+    websocketPath: endpoint.websocketPath
   });
   return new Client(
     uuid,
     hostnames,
-    version,
+    endpoint,
     enabled,
     systemName,
     logger,
     opts.protocol,
-    { retryDelay: opts.retryDelay, maxRetry: opts.maxRetry }
+    { retryDelay: opts.retryDelay, maxRetry: opts.maxRetry, interceptor: opts.interceptor }
   );
 }
 function errorMessageOrDefault(error, fallback) {
@@ -4524,5 +4542,5 @@ var UserRole = /* @__PURE__ */ ((UserRole2) => {
 })(UserRole || {});
 
 export { AppState, AuthError, AuthErrorCode, AuthResponseType, InvalidVersionResponseError, JobState, NoCompatibleVersionsError, SUPPORTED_API_VERSIONS, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV27, TrueNasApiClientV28, TrueNasApiError, TrueNasAuthMechanism, TrueNasAuthenticator, TrueNasConnection, UserRole, VersionCompatibility, VersionDiscovery, VersionDiscoveryError, VersionDiscoveryNetworkError, VersionDiscoveryTimeoutError, VersionEndpointNotFoundError, VersionTooNewError, VersionTooOldError, clientClassFor, consoleLogger, createTrueNasClient, getApiErrorMessage, getCloseMessage, isJobFinished, noopLogger, parseApiVersion, policyViolationCloseCode, subscriptionName, v25_10_0_exports, v25_10_1_exports, v25_10_2_exports, v25_10_3_exports, v25_10_4_exports, v25_10_5_exports, v27_0_0_exports, v28_0_0_exports };
-//# sourceMappingURL=chunk-PJVDHM2S.js.map
-//# sourceMappingURL=chunk-PJVDHM2S.js.map
+//# sourceMappingURL=chunk-PEOXWWBS.js.map
+//# sourceMappingURL=chunk-PEOXWWBS.js.map