@truenas/api-client 9.0.0 → 9.0.1

package/README.md

@@ -89,7 +89,9 @@ client.api.call('alert.dismiss', ['uuid-1']);   // params checked against the me
 client.api.call('nope.nope');                   // ✗ compile error
 ```
 
-A failed call errors with middleware's own message.
+A failed call errors with a `TrueNasApiError`. Its `message` is middleware's own
+reason, and the rest of the error is there too: `errname` (such as `EINVAL`),
+and `data.extra`, where a validation error names the fields it rejected.
 
 ## Queries
 
@@ -116,7 +118,9 @@ client.api.job('pool.dataset.export_key', ['tank/encrypted']).subscribe(job => {
 ```
 
 The stream emits each state and completes when the job finishes. A failed job
-completes too, with `state` and `error` set.
+completes too, with `state` and `error` set. A job method refused before it
+starts a job, such as for a validation error, errors with a `TrueNasApiError`
+instead, because there is no job to report.
 
 ## Events
 
@@ -129,7 +133,20 @@ client.api.events('app.query').subscribe(change => {
 
 Changes are typed per collection and discriminated on `msg`. One server
 subscription is shared by every subscriber and re-registered after each
-reconnect.
+reconnect. When the last subscriber leaves, it is released with
+`core.unsubscribe`.
+
+Event sources take their arguments after the name, typed from the method's
+`subscriptionParams`:
+
+```typescript
+client.api.events('filesystem.file_tail_follow', { path: '/var/log/messages' })
+  .subscribe(line => append(line.fields.data));
+```
+
+A source with different arguments is a separate subscription. If middleware
+ends a source, the stream completes. If it rejects the arguments, the stream
+errors with a `TrueNasApiError`.
 
 ## Working across versions
 
@@ -164,6 +181,17 @@ client.ops.smbStatus({ infoLevel: 'SESSIONS' });
 Per-version details, such as permissions that differ between releases, are in
 the `OperationMappings` reference.
 
+Some behaviour differs between versions in ways no type can express, because a
+default is not part of a TypeScript signature. One worth knowing: at v28.0.0,
+`config.save()` with no arguments includes the secret seed in the backup, where
+at v25.10 and v27.0 the same call left it out. That seed decrypts every
+password, private key and API key the backup contains, so treat such a backup
+as a secret; pass `{ secretseed: false }` for the old behaviour, bearing in mind
+a backup saved without it cannot be uploaded. These are recorded as they are
+found in
+[`src/generated/MANIFEST.md`](https://github.com/truenas/api-client-ts/blob/main/src/generated/MANIFEST.md),
+which is in the repository rather than the published package.
+
 ## Connection
 
 ```typescript
@@ -212,7 +240,8 @@ the client is doing.
 
 ## Errors
 
-- **Calls** error with middleware's message.
+- **Calls, queries and job starts** error with `TrueNasApiError`. Its `message`
+  is middleware's reason, and `errname`, `code` and `data` carry the rest.
 - **Logins** error with `AuthError`. Check `code` against `AuthErrorCode`.
 - **`createTrueNasClient`** rejects with a `VersionDiscoveryError` subclass, such
   as `VersionTooOldError`, `VersionTooNewError` or

package/dist/{chunk-LFNAVARU.js → chunk-K7BL6J3Z.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, 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, ignoreElements, merge, 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';
 
@@ -28,6 +28,34 @@ function getApiErrorMessage(error, fallback = "API call failed") {
   return fallback;
 }
 
+// src/errors/api.errors.ts
+var TrueNasApiError = class _TrueNasApiError extends Error {
+  constructor(frame, method) {
+    super(getApiErrorMessage(frame, "API call failed"));
+    this.frame = frame;
+    this.method = method;
+    this.name = "TrueNasApiError";
+    Object.setPrototypeOf(this, _TrueNasApiError.prototype);
+  }
+  /** The JSON-RPC code: `-32001` for a refused call, others for a malformed one. */
+  get code() {
+    return this.frame.code;
+  }
+  /**
+   * The TrueNAS payload — `errname`, `reason`, `extra`, `trace`.
+   *
+   * `undefined` for the codes middleware sends without one, such as
+   * `-32601 "Method does not exist"`.
+   */
+  get data() {
+    return this.frame.data;
+  }
+  /** `data.errname`, e.g. `EINVAL`, or `undefined` when there is no payload. */
+  get errname() {
+    return this.frame.data?.errname;
+  }
+};
+
 // src/types/job.type.ts
 var JobState = /* @__PURE__ */ ((JobState2) => {
   JobState2["Pending"] = "PENDING";
@@ -2222,6 +2250,19 @@ function createJsonRpcMessage(method, params) {
   };
 }
 
+// src/utils/subscription.utils.ts
+function subscriptionName(event, params) {
+  return params === void 0 ? event : `${event}:${JSON.stringify(params, sortKeys)}`;
+}
+function sortKeys(_key, value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+  );
+}
+
 // src/api/truenas-api.ts
 var EVENT_KINDS = ["added", "changed", "removed"];
 var TrueNasApi = class {
@@ -2231,8 +2272,13 @@ var TrueNasApi = class {
     /**
      * Stream of job events from websocket.
      * JSON-RPC 2.0 events have structure: { method: 'collection_update', params: { collection, fields, ... } }
+     *
+     * Reads `messages()` when first subscribed, not when this is built, as every
+     * other verb does. A consumer that wraps the connection's `messages()` after
+     * the client is created — a debug panel mixing in mocked answers — is
+     * otherwise heard by `call` and `events` but not by job tracking.
      */
-    this.jobEvents = this.connection.messages().pipe(
+    this.jobEvents = defer(() => this.connection.messages()).pipe(
       filter(
         (res) => res.method === "collection_update" && res.params?.collection === "core.get_jobs"
       ),
@@ -2241,11 +2287,20 @@ var TrueNasApi = class {
       share()
     );
     /**
-     * One shared stream per subscribed event name — see {@link events}.
-     * Keyed by name rather than by caller, because the subscription it stands
-     * for lives on the server and is per socket, not per caller.
+     * One shared stream per subscription — see {@link events}. Keyed by the
+     * name *with* its arguments: a tail of one file is not a tail of another.
      */
     this.eventStreams = /* @__PURE__ */ new Map();
+    /**
+     * Releases awaiting their `core.unsubscribe` reply, per name. Middleware
+     * sends a source's release notice (`terminate`) before that reply, and a
+     * notice names only the collection; so an error-free one arriving inside
+     * that window belongs to the release, not to a later subscription. One per
+     * window, which closes on the reply whether or not a notice came.
+     */
+    this.releasing = /* @__PURE__ */ new Map();
+    /** The live subscription per name, told when the server ends it. */
+    this.serverEnds = /* @__PURE__ */ new Map();
     this.initializeJobEventsSubscription();
   }
   /**
@@ -2283,11 +2338,7 @@ var TrueNasApi = class {
         withId(messageId),
         map((msg) => {
           if (msg.error) {
-            const errorMessage = getApiErrorMessage(
-              msg.error,
-              "API call failed"
-            );
-            throw new Error(errorMessage);
+            throw new TrueNasApiError(msg.error, method);
           }
           return msg.result;
         }),
@@ -2343,18 +2394,29 @@ var TrueNasApi = class {
    * differs by version (v25.10 answers with the id, v27 with `null`), while
    * the event correlation holds for both.
    *
-   * @returns Observable that emits the job ID when received from websocket events
+   * @returns the job's id; errors with a {@link TrueNasApiError} if the method is refused before a job starts
    */
   callAndGetJobId(method, ...params) {
     return defer(() => {
       const message = createJsonRpcMessage(method, params[0]);
-      const seen = this.jobEvents.pipe(
+      const started = this.jobEvents.pipe(
         filter((job) => job.message_ids?.includes(message.id ?? "") ?? false),
-        map((job) => job.id),
-        take(1)
+        map((job) => job.id)
+      );
+      const refused = this.connection.messages().pipe(
+        withId(message.id ?? ""),
+        map((reply) => {
+          if (reply.error) {
+            throw new TrueNasApiError(reply.error, method);
+          }
+        }),
+        ignoreElements()
       );
       const sending = this.connection.send(message);
-      return seen.pipe(finalize(() => sending.unsubscribe()));
+      return merge(started, refused).pipe(
+        take(1),
+        finalize(() => sending.unsubscribe())
+      );
     });
   }
   /**
@@ -2373,41 +2435,118 @@ var TrueNasApi = class {
       switchMap((jobId) => this.trackJob(jobId))
     );
   }
-  /**
-   * Subscribe to a collection and emit its changes, discriminated on `msg`.
-   *
-   * ```typescript
-   * api.events('app.query').subscribe(event => {
-   *   if (event.msg === 'removed') return drop(event.id);
-   *   render(event.fields);          // only reachable once narrowed
-   * });
-   * ```
-   *
-   * Narrow before reading `fields`: `removed` events almost never carry it.
-   * Sources taking subscribe-time arguments are excluded; see {@link EventName}.
-   */
-  events(event) {
-    const existing = this.eventStreams.get(event);
+  events(event, params) {
+    const name = subscriptionName(event, params);
+    this.listenForEndNotices();
+    const existing = this.eventStreams.get(name);
     if (existing) return existing;
+    const forget = () => {
+      if (this.eventStreams.get(name) === stream) this.eventStreams.delete(name);
+    };
     const stream = defer(() => {
-      const resubscribe = this.authenticated.pipe(distinctUntilChanged(), filter(Boolean)).subscribe(() => {
-        this.connection.send(createJsonRpcMessage("core.subscribe", [event]));
+      let subscriptionId;
+      let released = false;
+      let serverEnded = false;
+      const ended = new Subject();
+      this.serverEnds.set(name, ended);
+      const subscribing = this.authenticated.pipe(distinctUntilChanged()).subscribe((isAuthenticated) => {
+        subscriptionId = void 0;
+        if (!isAuthenticated) return;
+        const request = createJsonRpcMessage("core.subscribe", [name]);
+        this.connection.messages().pipe(
+          withId(request.id ?? ""),
+          take(1),
+          takeUntil(this.authenticated.pipe(filter((isUp) => !isUp)))
+        ).subscribe((reply) => {
+          if (typeof reply.result !== "string") return;
+          if (!released) subscriptionId = reply.result;
+          else if (!serverEnded) this.unsubscribe(name, reply.result);
+        });
+        this.connection.send(request);
       });
-      return this.connection.messages().pipe(
-        filter((res) => res.method === "collection_update"),
-        map((res) => res.params),
+      const updates = this.connection.messages().pipe(
         filter(
-          (params) => params?.collection === event && EVENT_KINDS.includes(params.msg)
+          (res) => res.method === "collection_update" && res.params?.collection === name
         ),
+        map((res) => res.params),
+        filter((params2) => EVENT_KINDS.includes(params2.msg)),
+        // `merge` below ends only when both inputs do. The connection closing
+        // for good ends this one; `ended` has to follow, or the stream never
+        // completes and nothing tears down the resubscription.
+        finalize(() => ended.complete())
+      );
+      const end = ended.pipe(
+        map((notice) => {
+          subscriptionId = void 0;
+          serverEnded = true;
+          if (notice.error) {
+            throw new TrueNasApiError(
+              { code: -32001, message: notice.error.reason, data: notice.error },
+              name
+            );
+          }
+        })
+      );
+      return merge(updates, end).pipe(
+        takeWhile((change) => change !== void 0),
         // `collection` is the subscription the caller already named; what is
         // left is exactly the payload the directory declares, plus its tag.
         map(({ collection, ...change }) => change),
-        finalize(() => resubscribe.unsubscribe())
+        // An ended stream stays ended (below), so the next `events()` call for
+        // this name needs a new one.
+        tap({ complete: forget, error: forget }),
+        finalize(() => {
+          released = true;
+          subscribing.unsubscribe();
+          if (this.serverEnds.get(name) === ended) this.serverEnds.delete(name);
+          if (subscriptionId) this.unsubscribe(name, subscriptionId);
+        })
       );
-    }).pipe(share({ resetOnRefCountZero: false, resetOnComplete: false }));
-    this.eventStreams.set(event, stream);
+    }).pipe(
+      share({
+        resetOnRefCountZero: true,
+        resetOnComplete: false,
+        resetOnError: false
+      })
+    );
+    this.eventStreams.set(name, stream);
     return stream;
   }
+  /**
+   * Release a subscription by the id `core.subscribe` answered with, holding
+   * its notice window (see {@link releasing}) open until the reply.
+   */
+  unsubscribe(name, subscriptionId) {
+    const release = { noticed: false };
+    this.releasing.set(name, [...this.releasing.get(name) ?? [], release]);
+    const request = createJsonRpcMessage("core.unsubscribe", [subscriptionId]);
+    this.connection.messages().pipe(
+      withId(request.id ?? ""),
+      take(1),
+      takeUntil(this.authenticated.pipe(filter((isUp) => !isUp))),
+      finalize(() => {
+        const open = (this.releasing.get(name) ?? []).filter((r) => r !== release);
+        if (open.length) this.releasing.set(name, open);
+        else this.releasing.delete(name);
+      })
+    ).subscribe();
+    this.connection.send(request);
+  }
+  /**
+   * Route each `notify_unsubscribed` once: an error-free one inside an open
+   * release window is that release's, anything else ends the name's live
+   * subscription. Installed on the first `events()` call, before any stream
+   * listens.
+   */
+  listenForEndNotices() {
+    if (this.endNotices) return;
+    this.endNotices = this.connection.messages().pipe(filter((res) => res.method === "notify_unsubscribed")).subscribe((res) => {
+      const notice = res.params;
+      const release = notice.error ? void 0 : this.releasing.get(notice.collection)?.find((r) => !r.noticed);
+      if (release) release.noticed = true;
+      else this.serverEnds.get(notice.collection)?.next(notice);
+    });
+  }
   /**
    * Convenience wrapper for auth.generate_token API call.
    *
@@ -2440,12 +2579,10 @@ var TrueNasApi = class {
       filter((job) => job.id === jobId),
       map((job) => job)
     );
-    const read$ = this.dispatch("core.get_jobs", [
-      [["id", "=", jobId]]
-    ]).pipe(
-      map((jobs) => jobs[0]),
-      share()
+    const readJob = () => this.dispatch("core.get_jobs", [[["id", "=", jobId]]]).pipe(
+      map((jobs) => jobs[0])
     );
+    const read$ = readJob().pipe(share());
     const missing$ = read$.pipe(
       filter((job) => job === void 0),
       takeUntil(updates$)
@@ -2454,10 +2591,29 @@ var TrueNasApi = class {
       filter((job) => job !== void 0),
       takeUntil(updates$)
     );
-    return merge(snapshot$, updates$).pipe(
+    const reread$ = this.authenticated.pipe(
+      distinctUntilChanged(),
+      skipWhile((isUp) => !isUp),
+      pairwise(),
+      filter(([wasUp, isUp]) => !wasUp && isUp),
+      switchMap(
+        () => readJob().pipe(
+          // Stale once events flow again, as the opening read is; they carry the end.
+          takeUntil(updates$),
+          // A failed read waits for the next reconnect.
+          catchError(() => EMPTY)
+        )
+      ),
+      share()
+    );
+    const gone$ = reread$.pipe(filter((job) => job === void 0));
+    const rereadJob$ = reread$.pipe(
+      filter((job) => job !== void 0)
+    );
+    return merge(snapshot$, updates$, rereadJob$).pipe(
       takeWhile((job) => !isJobFinished(job), true),
       // Include the final state
-      takeUntil(missing$)
+      takeUntil(merge(missing$, gone$))
     );
   }
   /**
@@ -4356,6 +4512,6 @@ var UserRole = /* @__PURE__ */ ((UserRole2) => {
   return UserRole2;
 })(UserRole || {});
 
-export { AppState, AuthError, AuthErrorCode, AuthResponseType, InvalidVersionResponseError, JobState, NoCompatibleVersionsError, SUPPORTED_API_VERSIONS, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV27, TrueNasApiClientV28, 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, v27_0_0_exports, v28_0_0_exports };
-//# sourceMappingURL=chunk-LFNAVARU.js.map
-//# sourceMappingURL=chunk-LFNAVARU.js.map
+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-K7BL6J3Z.js.map
+//# sourceMappingURL=chunk-K7BL6J3Z.js.map