@truenas/api-client 6.0.3 → 7.0.1

package/README.md

@@ -172,6 +172,37 @@ client.connection.setEnabled(false);   // disconnect; true connects again
 client.close();                        // disconnect for good
 ```
 
+The connection reconnects on its own and never gives up, so an appliance
+rebooting or failing over just comes back. `retryDelay` (default 10 s) sets the
+pause between failed attempts. `maxRetry` (default 3) sets how many retries run
+before `hasConnectionError$` reports an error; retrying carries on after that.
+Pass `maxRetry: Infinity` so failed attempts never report one. Losing a live
+socket still does, until a socket opens again:
+
+```typescript
+const client = await createTrueNasClient({
+  uuid, hostnames, enabled: true, retryDelay: 5_000, maxRetry: Infinity,
+});
+```
+
+The one close that stops retrying is 1008: the appliance refusing this client,
+for example because its address is not in Allowed IP Addresses. `closes$`
+reports every socket close with its code, so the two cases can be told apart:
+
+```typescript
+client.connection.closes$.subscribe(({ code, reason, refused }) => {
+  if (refused) showAccessDeniedDialog(reason);
+});
+```
+
+`setEndpoint` re-points a live client at new hostnames or a new protocol, for
+example after the GUI address changes. The socket reconnects there; the API
+version stays the same, so a different version needs a new client:
+
+```typescript
+client.connection.setEndpoint({ hostnames: ['10.0.0.5'], protocol: 'http:' });
+```
+
 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-6PF34AWT.cjs → chunk-JVFS4GW2.cjs}

@@ -2904,6 +2904,9 @@ function getHttpError(reason) {
   }
   return "";
 }
+function getCloseMessage(code, reason) {
+  return isHttpStatusError(reason) ? getHttpError(reason) : getWebSocketError(code);
+}
 function getWebSocketError(code) {
   switch (code) {
     case 1e3:
@@ -2963,14 +2966,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 rxjs.BehaviorSubject(false);
     this.closed = new rxjs.Subject();
@@ -2986,6 +2987,19 @@ var TrueNasConnection = class {
      * flip it via `setEnabled()` (the app maps `SystemState.Active -> true`).
      */
     this.enabled$ = new rxjs.BehaviorSubject(false);
+    /** Replaced in the constructor, before anything subscribes. See `setEndpoint()`. */
+    this.endpoint$ = new rxjs.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 rxjs.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.
      */
@@ -2995,30 +3009,18 @@ var TrueNasConnection = class {
      */
     this.connection$ = this.enabledChange$.pipe(
       rxjs.switchMap((enabled) => {
-        if (enabled) {
-          return this.connect().pipe(
-            rxjs.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.
-            rxjs.catchError(
-              (err) => isTerminalClose(err) ? rxjs.of(
-                makeConnectionError(
-                  err.message,
-                  err.hostname,
-                  err.closeCode,
-                  err.closeReason
-                )
-              ) : rxjs.throwError(() => err)
-            )
-          );
+        if (!enabled) {
+          return rxjs.of(closedConnection);
         }
-        return rxjs.of(closedConnection);
+        return this.endpoint$.pipe(
+          rxjs.distinctUntilChanged(sameEndpoint),
+          rxjs.switchMap((endpoint) => {
+            const changed = this.lastAttempted !== null && !sameEndpoint(this.lastAttempted, endpoint);
+            this.lastAttempted = endpoint;
+            const attempt = this.attempt(endpoint);
+            return changed ? attempt.pipe(rxjs.startWith(closedConnection)) : attempt;
+          })
+        );
       }),
       rxjs.switchMap((connection) => {
         if (connection.state !== "active") {
@@ -3049,16 +3051,27 @@ var TrueNasConnection = class {
               err.closeReason
             )
           ),
-          // since this error will immediately get caught by `retry` there's no reason to build a real error.
-          rxjs.throwError(() => null)
+          rxjs.throwError(() => err)
         );
       }),
-      rxjs.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.
+      rxjs.retry({
+        delay: (err) => err?.wasOpen ? rxjs.of(null) : rxjs.race(
+          rxjs.timer(this.retryDelay),
+          this.enabledChange$.pipe(rxjs.skip(1)),
+          this.endpoint$.pipe(rxjs.skip(1))
+        )
+      }),
       // start with a closed connection.
       rxjs.startWith(closedConnection),
+      // Above `shareReplay`, whose `refCount: false` subscription would otherwise
+      // outlive `close()` and let a pending retry wait open another socket.
+      rxjs.takeUntil(this.closeConnection),
       // prevent multiple subscriptions from re-evaluating the entire pipeline.
-      rxjs.shareReplay({ bufferSize: 1, refCount: false }),
-      rxjs.takeUntil(this.closeConnection)
+      rxjs.shareReplay({ bufferSize: 1, refCount: false })
     );
     /**
      * observable which is either an instance of the current `TrueNasSocket` used for the connection
@@ -3123,6 +3136,7 @@ var TrueNasConnection = class {
         rxjs.catchError(() => rxjs.EMPTY)
       ))
     );
+    this.endpoint$.next(resolveEndpoint(hostnames, protocol));
     this.ws$.pipe(
       rxjs.switchMap((ws) => ws ? rxjs.interval(twentySeconds).pipe(rxjs.map(() => ws)) : rxjs.EMPTY),
       rxjs.takeUntil(this.closeConnection)
@@ -3136,6 +3150,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
@@ -3145,7 +3182,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;
   }
@@ -3185,14 +3222,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 rxjs.Observable((subscriber) => {
       const ws = new TrueNasSocket({
@@ -3207,16 +3245,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
+            });
           }
         }
       });
@@ -3230,8 +3274,17 @@ var TrueNasConnection = class {
       };
     }).pipe(
       // retry logic:
-      //   * if a connection is not established in 10 seconds, consider that an error
-      rxjs.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.
+      rxjs.timeout({
+        first: tenSeconds,
+        with: (info) => {
+          this.connectionAttempts.next(this.connectionAttempts.value + 1);
+          return rxjs.throwError(() => new rxjs.TimeoutError(info));
+        }
+      }),
       rxjs.retry({
         //   * while still *establishing*: wait `retryDelay` before trying again, giving up
         //     after `maxRetry` retries.
@@ -3249,12 +3302,36 @@ var TrueNasConnection = class {
       })
     );
   }
+  /** One attempt at `endpoint`: the race, with a refusal turned into a value. */
+  attempt(endpoint) {
+    return this.connect(endpoint).pipe(
+      rxjs.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.
+      rxjs.catchError(
+        (err) => isTerminalClose(err) ? rxjs.of(
+          makeConnectionError(
+            err.message,
+            err.hostname,
+            err.closeCode,
+            err.closeReason
+          )
+        ) : rxjs.throwError(() => err)
+      )
+    );
+  }
   /**
    * helper function which actually performs the parallel connection `race`.
    */
-  connect() {
+  connect(endpoint) {
     return rxjs.race(
-      this.hostnames.map(this.createSocket.bind(this))
+      endpoint.hostnames.map((hostname) => this.createSocket(hostname, endpoint.protocol))
     ).pipe(
       rxjs.tap((conn) => this.logger.debug(`TrueNas socket opened to ${conn.hostname}.`)),
       rxjs.takeUntil(this.closeConnection)
@@ -3275,11 +3352,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;
@@ -3287,6 +3366,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();
@@ -3325,10 +3405,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
     );
@@ -4184,7 +4262,8 @@ function instantiateClientForVersion(version, opts, logger) {
     enabled,
     systemName,
     logger,
-    opts.protocol
+    opts.protocol,
+    { retryDelay: opts.retryDelay, maxRetry: opts.maxRetry }
   );
 }
 function errorMessageOrDefault(error, fallback) {
@@ -4231,9 +4310,11 @@ exports.clientClassFor = clientClassFor;
 exports.consoleLogger = consoleLogger;
 exports.createTrueNasClient = createTrueNasClient;
 exports.getApiErrorMessage = getApiErrorMessage;
+exports.getCloseMessage = getCloseMessage;
 exports.isJobFinished = isJobFinished;
 exports.noopLogger = noopLogger;
 exports.parseApiVersion = parseApiVersion;
+exports.policyViolationCloseCode = policyViolationCloseCode;
 exports.v25_10_0_exports = v25_10_0_exports;
 exports.v25_10_1_exports = v25_10_1_exports;
 exports.v25_10_2_exports = v25_10_2_exports;
@@ -4242,5 +4323,5 @@ exports.v25_10_4_exports = v25_10_4_exports;
 exports.v25_10_5_exports = v25_10_5_exports;
 exports.v26_0_0_exports = v26_0_0_exports;
 exports.v27_0_0_exports = v27_0_0_exports;
-//# sourceMappingURL=chunk-6PF34AWT.cjs.map
-//# sourceMappingURL=chunk-6PF34AWT.cjs.map
+//# sourceMappingURL=chunk-JVFS4GW2.cjs.map
+//# sourceMappingURL=chunk-JVFS4GW2.cjs.map