@truenas/api-client 9.0.0 → 9.0.1

package/dist/{chunk-TSO2EHF3.cjs → chunk-U6V2Y3AE.cjs}

@@ -30,6 +30,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";
@@ -2224,6 +2252,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 {
@@ -2233,8 +2274,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 = rxjs.defer(() => this.connection.messages()).pipe(
       rxjs.filter(
         (res) => res.method === "collection_update" && res.params?.collection === "core.get_jobs"
       ),
@@ -2243,11 +2289,20 @@ var TrueNasApi = class {
       rxjs.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();
   }
   /**
@@ -2285,11 +2340,7 @@ var TrueNasApi = class {
         withId(messageId),
         rxjs.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;
         }),
@@ -2345,18 +2396,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 rxjs.defer(() => {
       const message = createJsonRpcMessage(method, params[0]);
-      const seen = this.jobEvents.pipe(
+      const started = this.jobEvents.pipe(
         rxjs.filter((job) => job.message_ids?.includes(message.id ?? "") ?? false),
-        rxjs.map((job) => job.id),
-        rxjs.take(1)
+        rxjs.map((job) => job.id)
+      );
+      const refused = this.connection.messages().pipe(
+        withId(message.id ?? ""),
+        rxjs.map((reply) => {
+          if (reply.error) {
+            throw new TrueNasApiError(reply.error, method);
+          }
+        }),
+        rxjs.ignoreElements()
       );
       const sending = this.connection.send(message);
-      return seen.pipe(rxjs.finalize(() => sending.unsubscribe()));
+      return rxjs.merge(started, refused).pipe(
+        rxjs.take(1),
+        rxjs.finalize(() => sending.unsubscribe())
+      );
     });
   }
   /**
@@ -2375,41 +2437,118 @@ var TrueNasApi = class {
       rxjs.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 = rxjs.defer(() => {
-      const resubscribe = this.authenticated.pipe(rxjs.distinctUntilChanged(), rxjs.filter(Boolean)).subscribe(() => {
-        this.connection.send(createJsonRpcMessage("core.subscribe", [event]));
+      let subscriptionId;
+      let released = false;
+      let serverEnded = false;
+      const ended = new rxjs.Subject();
+      this.serverEnds.set(name, ended);
+      const subscribing = this.authenticated.pipe(rxjs.distinctUntilChanged()).subscribe((isAuthenticated) => {
+        subscriptionId = void 0;
+        if (!isAuthenticated) return;
+        const request = createJsonRpcMessage("core.subscribe", [name]);
+        this.connection.messages().pipe(
+          withId(request.id ?? ""),
+          rxjs.take(1),
+          rxjs.takeUntil(this.authenticated.pipe(rxjs.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(
-        rxjs.filter((res) => res.method === "collection_update"),
-        rxjs.map((res) => res.params),
+      const updates = this.connection.messages().pipe(
         rxjs.filter(
-          (params) => params?.collection === event && EVENT_KINDS.includes(params.msg)
+          (res) => res.method === "collection_update" && res.params?.collection === name
         ),
+        rxjs.map((res) => res.params),
+        rxjs.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.
+        rxjs.finalize(() => ended.complete())
+      );
+      const end = ended.pipe(
+        rxjs.map((notice) => {
+          subscriptionId = void 0;
+          serverEnded = true;
+          if (notice.error) {
+            throw new TrueNasApiError(
+              { code: -32001, message: notice.error.reason, data: notice.error },
+              name
+            );
+          }
+        })
+      );
+      return rxjs.merge(updates, end).pipe(
+        rxjs.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.
         rxjs.map(({ collection, ...change }) => change),
-        rxjs.finalize(() => resubscribe.unsubscribe())
+        // An ended stream stays ended (below), so the next `events()` call for
+        // this name needs a new one.
+        rxjs.tap({ complete: forget, error: forget }),
+        rxjs.finalize(() => {
+          released = true;
+          subscribing.unsubscribe();
+          if (this.serverEnds.get(name) === ended) this.serverEnds.delete(name);
+          if (subscriptionId) this.unsubscribe(name, subscriptionId);
+        })
       );
-    }).pipe(rxjs.share({ resetOnRefCountZero: false, resetOnComplete: false }));
-    this.eventStreams.set(event, stream);
+    }).pipe(
+      rxjs.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 ?? ""),
+      rxjs.take(1),
+      rxjs.takeUntil(this.authenticated.pipe(rxjs.filter((isUp) => !isUp))),
+      rxjs.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(rxjs.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.
    *
@@ -2442,12 +2581,10 @@ var TrueNasApi = class {
       rxjs.filter((job) => job.id === jobId),
       rxjs.map((job) => job)
     );
-    const read$ = this.dispatch("core.get_jobs", [
-      [["id", "=", jobId]]
-    ]).pipe(
-      rxjs.map((jobs) => jobs[0]),
-      rxjs.share()
+    const readJob = () => this.dispatch("core.get_jobs", [[["id", "=", jobId]]]).pipe(
+      rxjs.map((jobs) => jobs[0])
     );
+    const read$ = readJob().pipe(rxjs.share());
     const missing$ = read$.pipe(
       rxjs.filter((job) => job === void 0),
       rxjs.takeUntil(updates$)
@@ -2456,10 +2593,29 @@ var TrueNasApi = class {
       rxjs.filter((job) => job !== void 0),
       rxjs.takeUntil(updates$)
     );
-    return rxjs.merge(snapshot$, updates$).pipe(
+    const reread$ = this.authenticated.pipe(
+      rxjs.distinctUntilChanged(),
+      rxjs.skipWhile((isUp) => !isUp),
+      rxjs.pairwise(),
+      rxjs.filter(([wasUp, isUp]) => !wasUp && isUp),
+      rxjs.switchMap(
+        () => readJob().pipe(
+          // Stale once events flow again, as the opening read is; they carry the end.
+          rxjs.takeUntil(updates$),
+          // A failed read waits for the next reconnect.
+          rxjs.catchError(() => rxjs.EMPTY)
+        )
+      ),
+      rxjs.share()
+    );
+    const gone$ = reread$.pipe(rxjs.filter((job) => job === void 0));
+    const rereadJob$ = reread$.pipe(
+      rxjs.filter((job) => job !== void 0)
+    );
+    return rxjs.merge(snapshot$, updates$, rereadJob$).pipe(
       rxjs.takeWhile((job) => !isJobFinished(job), true),
       // Include the final state
-      rxjs.takeUntil(missing$)
+      rxjs.takeUntil(rxjs.merge(missing$, gone$))
     );
   }
   /**
@@ -4370,6 +4526,7 @@ exports.TrueNasApiClient = TrueNasApiClient;
 exports.TrueNasApiClientV2510 = TrueNasApiClientV2510;
 exports.TrueNasApiClientV27 = TrueNasApiClientV27;
 exports.TrueNasApiClientV28 = TrueNasApiClientV28;
+exports.TrueNasApiError = TrueNasApiError;
 exports.TrueNasAuthMechanism = TrueNasAuthMechanism;
 exports.TrueNasAuthenticator = TrueNasAuthenticator;
 exports.TrueNasConnection = TrueNasConnection;
@@ -4391,6 +4548,7 @@ exports.isJobFinished = isJobFinished;
 exports.noopLogger = noopLogger;
 exports.parseApiVersion = parseApiVersion;
 exports.policyViolationCloseCode = policyViolationCloseCode;
+exports.subscriptionName = subscriptionName;
 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;
@@ -4399,5 +4557,5 @@ exports.v25_10_4_exports = v25_10_4_exports;
 exports.v25_10_5_exports = v25_10_5_exports;
 exports.v27_0_0_exports = v27_0_0_exports;
 exports.v28_0_0_exports = v28_0_0_exports;
-//# sourceMappingURL=chunk-TSO2EHF3.cjs.map
-//# sourceMappingURL=chunk-TSO2EHF3.cjs.map
+//# sourceMappingURL=chunk-U6V2Y3AE.cjs.map
+//# sourceMappingURL=chunk-U6V2Y3AE.cjs.map