@truenas/api-client 7.0.0 → 7.0.1

package/dist/{chunk-SAJ5HZHK.js → chunk-NXXESRJ6.js}

@@ -1,4 +1,4 @@
-import { BehaviorSubject, filter, switchMap, catchError, EMPTY, tap, map, finalize, take, Subject, distinctUntilChanged, of, throwError, concat, retry, startWith, shareReplay, takeUntil, interval, Observable, timeout, timer, race, toArray, from, defer, firstValueFrom, share, merge, takeWhile } from 'rxjs';
+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, merge, takeWhile } from 'rxjs';
 import { webSocket } from 'rxjs/webSocket';
 import { map as map$1, catchError as catchError$1, shareReplay as shareReplay$1 } from 'rxjs/operators';
 
@@ -2902,6 +2902,9 @@ function getHttpError(reason) {
   }
   return "";
 }
+function getCloseMessage(code, reason) {
+  return isHttpStatusError(reason) ? getHttpError(reason) : getWebSocketError(code);
+}
 function getWebSocketError(code) {
   switch (code) {
     case 1e3:
@@ -2961,14 +2964,12 @@ 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:") {
-    this.hostnames = hostnames;
     this.systemUuid = systemUuid;
     this.websocketPath = websocketPath;
     this.systemName = systemName;
     this.retryDelay = retryDelay;
     this.maxRetry = maxRetry;
     this.logger = logger;
-    this.protocol = protocol;
     // compatibility properties
     this.opened = new BehaviorSubject(false);
     this.closed = new Subject();
@@ -2984,6 +2985,19 @@ var TrueNasConnection = class {
      * flip it via `setEnabled()` (the app maps `SystemState.Active -> true`).
      */
     this.enabled$ = new BehaviorSubject(false);
+    /** Replaced in the constructor, before anything subscribes. See `setEndpoint()`. */
+    this.endpoint$ = new BehaviorSubject(resolveEndpoint([], "https:"));
+    /** The endpoint the last attempt raced; a different one starts with `closed`. */
+    this.lastAttempted = null;
+    /** Protected so the testing entry's `FakeConnection` can script closes. */
+    this.closesSubject = new Subject();
+    /**
+     * Every socket close this client did not cause itself: failed attempts, lost
+     * connections and refusals, each with its code. Tearing a socket down through
+     * `setEnabled(false)`, `setEndpoint()` or `close()` does not report one, nor
+     * does an attempt that times out unanswered after 10 s, as nothing closed.
+     */
+    this.closes$ = this.closesSubject.asObservable();
     /**
      * observable which emits the current gate value and only emits again when it changes.
      */
@@ -2993,30 +3007,18 @@ var TrueNasConnection = class {
      */
     this.connection$ = this.enabledChange$.pipe(
       switchMap((enabled) => {
-        if (enabled) {
-          return this.connect().pipe(
-            map((conn) => makeActiveConnection(conn.ws, conn.hostname)),
-            // A refusal becomes a value here rather than an error, so it never
-            // reaches the `retry` below and nothing reconnects on its own.
-            //
-            // Handled at this depth on purpose: letting it out completes the
-            // pipeline and unsubscribes `enabledChange$`, and `setEnabled` is the
-            // documented way an app asks for another attempt once the network
-            // changes. Not retrying is a statement about what this client does on
-            // its own; it is not a reason to refuse the caller asking again.
-            catchError(
-              (err) => isTerminalClose(err) ? of(
-                makeConnectionError(
-                  err.message,
-                  err.hostname,
-                  err.closeCode,
-                  err.closeReason
-                )
-              ) : throwError(() => err)
-            )
-          );
+        if (!enabled) {
+          return of(closedConnection);
         }
-        return of(closedConnection);
+        return this.endpoint$.pipe(
+          distinctUntilChanged(sameEndpoint),
+          switchMap((endpoint) => {
+            const changed = this.lastAttempted !== null && !sameEndpoint(this.lastAttempted, endpoint);
+            this.lastAttempted = endpoint;
+            const attempt = this.attempt(endpoint);
+            return changed ? attempt.pipe(startWith(closedConnection)) : attempt;
+          })
+        );
       }),
       switchMap((connection) => {
         if (connection.state !== "active") {
@@ -3047,16 +3049,27 @@ var TrueNasConnection = class {
               err.closeReason
             )
           ),
-          // since this error will immediately get caught by `retry` there's no reason to build a real error.
-          throwError(() => null)
+          throwError(() => err)
         );
       }),
-      retry(),
+      // A lost live socket reconnects at once. A cycle that never opened waits
+      // `retryDelay` like any other attempt; without it the next cycle's first
+      // attempt followed the last one back to back. Nothing upstream is
+      // subscribed during the wait, so a gate or endpoint change ends it early.
+      retry({
+        delay: (err) => err?.wasOpen ? of(null) : race(
+          timer(this.retryDelay),
+          this.enabledChange$.pipe(skip(1)),
+          this.endpoint$.pipe(skip(1))
+        )
+      }),
       // start with a closed connection.
       startWith(closedConnection),
+      // Above `shareReplay`, whose `refCount: false` subscription would otherwise
+      // outlive `close()` and let a pending retry wait open another socket.
+      takeUntil(this.closeConnection),
       // prevent multiple subscriptions from re-evaluating the entire pipeline.
-      shareReplay({ bufferSize: 1, refCount: false }),
-      takeUntil(this.closeConnection)
+      shareReplay({ bufferSize: 1, refCount: false })
     );
     /**
      * observable which is either an instance of the current `TrueNasSocket` used for the connection
@@ -3121,6 +3134,7 @@ var TrueNasConnection = class {
         catchError(() => EMPTY)
       ))
     );
+    this.endpoint$.next(resolveEndpoint(hostnames, protocol));
     this.ws$.pipe(
       switchMap((ws) => ws ? interval(twentySeconds).pipe(map(() => ws)) : EMPTY),
       takeUntil(this.closeConnection)
@@ -3134,6 +3148,29 @@ var TrueNasConnection = class {
     this.lastErrorMessage$.subscribe((msg) => this.lastErrorMessage.next(msg));
     this.enabled$.next(initialEnabled);
   }
+  /** The hostnames and protocol the connection currently points at. */
+  get endpoint() {
+    return this.endpoint$.value;
+  }
+  /** The appliance's scheme; changed through `setEndpoint()`. */
+  get protocol() {
+    return this.endpoint$.value.protocol;
+  }
+  /**
+   * Re-points the connection, e.g. after the appliance's GUI address or
+   * protocol changes. Any open socket is closed and, while enabled, the new
+   * hostnames are raced at once; an unchanged endpoint does nothing. The
+   * websocket path stays, so a different API version needs a new client.
+   */
+  setEndpoint(endpoint) {
+    if (endpoint.hostnames.length === 0) {
+      throw new Error("Cannot point the connection at an empty hostnames array");
+    }
+    const next = resolveEndpoint(endpoint.hostnames, endpoint.protocol ?? this.protocol);
+    if (sameEndpoint(next, this.endpoint$.value)) return;
+    this.connectionAttempts.next(0);
+    this.endpoint$.next(next);
+  }
   /**
    * whether the connection has exhausted its retries — the **cumulative** snapshot, read
    * synchronously. (Formerly `hasConnectionError()`; renamed to disambiguate it from the
@@ -3143,7 +3180,7 @@ var TrueNasConnection = class {
    * OR when an error message is currently set. Ported from the source (tncui) behavior.
    */
   hasExhaustedRetries() {
-    const attemptsExhausted = this.connectionAttempts.value > this.hostnames.length * this.maxRetry;
+    const attemptsExhausted = this.connectionAttempts.value > this.endpoint.hostnames.length * this.maxRetry;
     const hasErrorMessage = this.lastErrorMessage.value !== null;
     return attemptsExhausted || hasErrorMessage;
   }
@@ -3183,14 +3220,15 @@ var TrueNasConnection = class {
   close() {
     this.closeConnection.next();
     this.closeConnection.complete();
+    this.closesSubject.complete();
   }
   /**
    * helper method which creates an `Observable` which emits an `ActiveConnection`
    * after it establishes a connection to the given hostname. the observable will emit an
    * error if the connection is never established and will not complete until unsubscribed from or closed.
    */
-  createSocket(hostname) {
-    const url = `${socketScheme(this.protocol)}//${hostname}${this.websocketPath}`;
+  createSocket(hostname, protocol) {
+    const url = `${socketScheme(protocol)}//${hostname}${this.websocketPath}`;
     let hasOpened = false;
     return new Observable((subscriber) => {
       const ws = new TrueNasSocket({
@@ -3205,16 +3243,22 @@ var TrueNasConnection = class {
         closeObserver: {
           next: (event) => {
             const reason = event.reason || "";
-            let errorMessage;
-            if (isHttpStatusError(reason)) {
-              errorMessage = getHttpError(reason);
-            } else {
-              errorMessage = getWebSocketError(event.code);
+            const errorMessage = getCloseMessage(event.code, reason);
+            if (!subscriber.closed) {
+              this.connectionAttempts.next(this.connectionAttempts.value + 1);
+              this.closesSubject.next({
+                code: event.code,
+                reason,
+                message: errorMessage,
+                hostname,
+                wasOpen: hasOpened,
+                refused: event.code === policyViolationCloseCode
+              });
             }
-            this.connectionAttempts.next(this.connectionAttempts.value + 1);
-            subscriber.error(
-              makeConnectionError(errorMessage, hostname, event.code, reason)
-            );
+            subscriber.error({
+              ...makeConnectionError(errorMessage, hostname, event.code, reason),
+              wasOpen: hasOpened
+            });
           }
         }
       });
@@ -3228,8 +3272,17 @@ var TrueNasConnection = class {
       };
     }).pipe(
       // retry logic:
-      //   * if a connection is not established in 10 seconds, consider that an error
-      timeout({ first: tenSeconds }),
+      //   * if a connection is not established in 10 seconds, consider that an error.
+      //     Counted here: rxjs never closes a socket still connecting, so no
+      //     close event reliably follows, and one that does finds `subscriber`
+      //     closed. Nothing on `closes$` either: nothing closed.
+      timeout({
+        first: tenSeconds,
+        with: (info) => {
+          this.connectionAttempts.next(this.connectionAttempts.value + 1);
+          return throwError(() => new TimeoutError(info));
+        }
+      }),
       retry({
         //   * while still *establishing*: wait `retryDelay` before trying again, giving up
         //     after `maxRetry` retries.
@@ -3247,12 +3300,36 @@ var TrueNasConnection = class {
       })
     );
   }
+  /** One attempt at `endpoint`: the race, with a refusal turned into a value. */
+  attempt(endpoint) {
+    return this.connect(endpoint).pipe(
+      map((conn) => makeActiveConnection(conn.ws, conn.hostname)),
+      // A refusal becomes a value here rather than an error, so it never
+      // reaches the `retry` in `connection$` and nothing reconnects on its own.
+      //
+      // Handled at this depth on purpose: letting it out completes the
+      // pipeline and unsubscribes `enabledChange$`, and `setEnabled` (or
+      // `setEndpoint`) is how an app asks for another attempt once the network
+      // changes. Not retrying is a statement about what this client does on
+      // its own; it is not a reason to refuse the caller asking again.
+      catchError(
+        (err) => isTerminalClose(err) ? of(
+          makeConnectionError(
+            err.message,
+            err.hostname,
+            err.closeCode,
+            err.closeReason
+          )
+        ) : throwError(() => err)
+      )
+    );
+  }
   /**
    * helper function which actually performs the parallel connection `race`.
    */
-  connect() {
+  connect(endpoint) {
     return race(
-      this.hostnames.map(this.createSocket.bind(this))
+      endpoint.hostnames.map((hostname) => this.createSocket(hostname, endpoint.protocol))
     ).pipe(
       tap((conn) => this.logger.debug(`TrueNas socket opened to ${conn.hostname}.`)),
       takeUntil(this.closeConnection)
@@ -3273,11 +3350,13 @@ var makeConnectionError = (message, hostname, closeCode, closeReason) => ({
   state: "error"
 });
 var isTerminalClose = (err) => err?.closeCode === policyViolationCloseCode;
+var resolveEndpoint = (hostnames, protocol) => Object.freeze({ hostnames: Object.freeze([...hostnames]), protocol });
+var sameEndpoint = (a, b) => a.protocol === b.protocol && a.hostnames.length === b.hostnames.length && a.hostnames.every((hostname, i) => hostname === b.hostnames[i]);
 var closedConnection = { state: "closed" };
 
 // src/client/truenas-api-client.ts
 var TrueNasApiClient = class {
-  constructor(uuid, hostnames, version, enabled, systemName, logger = noopLogger, protocol = "https:") {
+  constructor(uuid, hostnames, version, enabled, systemName, logger = noopLogger, protocol = "https:", reconnect = {}) {
     this.uuid = uuid;
     this.hostnames = hostnames;
     this.version = version;
@@ -3285,6 +3364,7 @@ var TrueNasApiClient = class {
     this.systemName = systemName;
     this.logger = logger;
     this.protocol = protocol;
+    this.reconnect = reconnect;
     this.connection = this.createConnection();
     this.authenticator = this.createAuthenticator();
     this.api = this.createApi();
@@ -3323,10 +3403,8 @@ var TrueNasApiClient = class {
       this.uuid,
       websocketPath,
       this.systemName,
-      void 0,
-      // retryDelay (use default)
-      void 0,
-      // maxRetry (use default)
+      this.reconnect.retryDelay,
+      this.reconnect.maxRetry,
       this.logger,
       this.protocol
     );
@@ -4182,7 +4260,8 @@ function instantiateClientForVersion(version, opts, logger) {
     enabled,
     systemName,
     logger,
-    opts.protocol
+    opts.protocol,
+    { retryDelay: opts.retryDelay, maxRetry: opts.maxRetry }
   );
 }
 function errorMessageOrDefault(error, fallback) {
@@ -4201,6 +4280,6 @@ var UserRole = /* @__PURE__ */ ((UserRole2) => {
   return UserRole2;
 })(UserRole || {});
 
-export { AppState, AuthError, AuthErrorCode, AuthResponseType, InvalidVersionResponseError, JobState, NoCompatibleVersionsError, SUPPORTED_API_VERSIONS, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV26, TrueNasApiClientV27, TrueNasAuthMechanism, TrueNasAuthenticator, TrueNasConnection, UserRole, VersionCompatibility, VersionDiscovery, VersionDiscoveryError, VersionDiscoveryNetworkError, VersionDiscoveryTimeoutError, VersionEndpointNotFoundError, VersionTooNewError, VersionTooOldError, clientClassFor, consoleLogger, createTrueNasClient, getApiErrorMessage, isJobFinished, noopLogger, parseApiVersion, v25_10_0_exports, v25_10_1_exports, v25_10_2_exports, v25_10_3_exports, v25_10_4_exports, v25_10_5_exports, v26_0_0_exports, v27_0_0_exports };
-//# sourceMappingURL=chunk-SAJ5HZHK.js.map
-//# sourceMappingURL=chunk-SAJ5HZHK.js.map
+export { AppState, AuthError, AuthErrorCode, AuthResponseType, InvalidVersionResponseError, JobState, NoCompatibleVersionsError, SUPPORTED_API_VERSIONS, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV26, TrueNasApiClientV27, TrueNasAuthMechanism, TrueNasAuthenticator, TrueNasConnection, UserRole, VersionCompatibility, VersionDiscovery, VersionDiscoveryError, VersionDiscoveryNetworkError, VersionDiscoveryTimeoutError, VersionEndpointNotFoundError, VersionTooNewError, VersionTooOldError, clientClassFor, consoleLogger, createTrueNasClient, getApiErrorMessage, getCloseMessage, isJobFinished, noopLogger, parseApiVersion, policyViolationCloseCode, v25_10_0_exports, v25_10_1_exports, v25_10_2_exports, v25_10_3_exports, v25_10_4_exports, v25_10_5_exports, v26_0_0_exports, v27_0_0_exports };
+//# sourceMappingURL=chunk-NXXESRJ6.js.map
+//# sourceMappingURL=chunk-NXXESRJ6.js.map