@truenas/api-client 9.0.5 → 10.0.0

package/README.md

@@ -258,6 +258,21 @@ version stays the same, so a different version needs a new client:
 client.connection.setEndpoint({ hostnames: ['10.0.0.5'], protocol: 'http:' });
 ```
 
+Middleware holds 20 calls per connection on current releases and refuses the
+next one, so a client that can put more than that in flight at once (an app
+loading a dashboard, say) should cap itself with `maxConcurrentCalls`. Calls
+beyond the cap wait, in order, for an answer to make room. Every frame counts,
+the client's own `core.ping` included:
+
+```typescript
+const client = await createTrueNasClient({ uuid, hostnames, enabled: true, maxConcurrentCalls: 20 });
+```
+
+Calls still waiting when a socket is lost are held until the session is
+authenticated again, since a new socket starts signed out. If the next person to
+sign in may not be the one who made those calls, end them first:
+`client.connection.refuseHeldCalls()` answers each with `ENOTAUTHENTICATED`.
+
 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

package/dist/{chunk-KME2PLIQ.cjs → chunk-PWRUBUVD.cjs}

@@ -1733,6 +1733,7 @@ __export(v27_0_0_exports, {
   IscsiTargetCreateModeInput: () => IscsiTargetCreateModeInput,
   KeychainCredentialEntryType: () => KeychainCredentialEntryType,
   KeychainCredentialEntryTypeInput: () => KeychainCredentialEntryTypeInput,
+  Layout: () => Layout,
   Level: () => Level,
   NFS4ACEType: () => NFS4ACEType,
   NFS4ACETypeInput: () => NFS4ACETypeInput,
@@ -1847,6 +1848,10 @@ var Interval = {
   "30": 30,
   "60": 60
 };
+var Layout = {
+  Bucket: "BUCKET",
+  Dataset: "DATASET"
+};
 var Name2 = {
   Cpu: "cpu",
   Cputemp: "cputemp",
@@ -1990,6 +1995,7 @@ __export(v28_0_0_exports, {
   IscsiTargetCreateModeInput: () => IscsiTargetCreateModeInput,
   KeychainCredentialEntryType: () => KeychainCredentialEntryType,
   KeychainCredentialEntryTypeInput: () => KeychainCredentialEntryTypeInput,
+  Layout: () => Layout,
   Level: () => Level,
   NFS4ACEType: () => NFS4ACEType,
   NFS4ACETypeInput: () => NFS4ACETypeInput,
@@ -2065,6 +2071,8 @@ __export(v28_0_0_exports, {
   Versioning: () => Versioning,
   Volblocksize: () => Volblocksize,
   When: () => When,
+  ZFSResourceUserspaceEntryType: () => ZFSResourceUserspaceEntryType,
+  ZFSResourceUserspaceEntryTypeInput: () => ZFSResourceUserspaceEntryTypeInput,
   ZfsTierRewriteJobEntryStatus: () => ZfsTierRewriteJobEntryStatus,
   ZfsTierRewriteJobEntryStatusInput: () => ZfsTierRewriteJobEntryStatusInput,
   ZpoolScrubRunAction: () => ZpoolScrubRunAction
@@ -2150,6 +2158,14 @@ var VMWareMatchDatastoresWithDatasetsResultFilesystemTypeInput = {
   Filesystem: "FILESYSTEM",
   Volume: "VOLUME"
 };
+var ZFSResourceUserspaceEntryType = {
+  User: "user",
+  Group: "group"
+};
+var ZFSResourceUserspaceEntryTypeInput = {
+  User: "user",
+  Group: "group"
+};
 
 // src/generated/index.ts
 var SUPPORTED_API_VERSIONS = [
@@ -3177,6 +3193,157 @@ function getWebSocketError(code) {
       return "Network connection failed - Check IP address and connectivity";
   }
 }
+var CallLimiter = class {
+  constructor(limit, write) {
+    this.limit = limit;
+    this.write = write;
+    /**
+     * Each request awaiting an answer, with the handle `write` gave for it. That
+     * handle closes once the frame is on a socket: until then the connection is
+     * still holding it for one, and giving up on it takes it back.
+     */
+    this.inFlight = /* @__PURE__ */ new Map();
+    this.waiting = [];
+    /**
+     * Calls that were waiting when a socket was lost, kept apart from `waiting`
+     * until `release()`. A call sent after the loss, the sign-in among them, then
+     * never waits behind one: nothing would write it, and `release()` waits on it.
+     */
+    this.heldCalls = [];
+  }
+  /** Requests written or being written, and not answered yet. */
+  get inFlightCount() {
+    return this.inFlight.size;
+  }
+  /** Requests waiting for a place, held ones included. */
+  get waitingCount() {
+    return this.waiting.length + this.heldCalls.length;
+  }
+  /** Whether calls are being kept from a lost socket until `release()`. */
+  get held() {
+    return this.heldCalls.length > 0;
+  }
+  /**
+   * Sends `message` now if there is room, or queues it. Frames that are not
+   * requests pass straight through. Unsubscribing the returned handle takes
+   * the call back if it has not been written yet.
+   *
+   * New calls are not held back by a lost socket, only by the limit: the frames
+   * that sign a new socket in come through here, and the held calls are
+   * waiting on exactly those.
+   */
+  send(message) {
+    if (!isRequest(message)) {
+      return this.write(message);
+    }
+    const call = { id: message.id, message, handle: new rxjs.Subscription() };
+    if (this.inFlight.size < this.limit) {
+      this.start(call);
+      return call.handle;
+    }
+    this.waiting.push(call);
+    call.handle.add(() => {
+      remove(this.waiting, call);
+      remove(this.heldCalls, call);
+    });
+    return call.handle;
+  }
+  /**
+   * Counts a request the connection wrote to a socket itself, such as its
+   * keepalive `core.ping`, or returns `false` without counting it when there is
+   * no room. A request written that way is not the limiter's to queue: the
+   * caller decides what not sending it means.
+   */
+  tryTrack(id) {
+    if (this.inFlight.size >= this.limit) {
+      return false;
+    }
+    this.inFlight.set(id, rxjs.Subscription.EMPTY);
+    return true;
+  }
+  /** Frees the place of the request this frame answers, if it is one. */
+  received(message) {
+    if (message.id === void 0 || message.id === null || message.method) {
+      return;
+    }
+    this.finish(String(message.id));
+  }
+  /**
+   * What was written on the lost socket is lost with it, answers included, so
+   * those places are freed. A frame the connection has not written yet is still
+   * its to send on the next socket, so it stays counted. Calls still waiting are
+   * held until `release()`: the new socket starts signed out, and a call sent on
+   * it before the session is back is refused.
+   */
+  socketLost() {
+    this.inFlight.forEach((sending, id) => {
+      if (sending.closed) {
+        this.inFlight.delete(id);
+      }
+    });
+    this.heldCalls.push(...this.waiting.splice(0));
+  }
+  /**
+   * Lets held calls go out again, once the session they were made in is back.
+   * They were sent before anything still waiting, so they go first.
+   */
+  release() {
+    this.waiting.unshift(...this.heldCalls.splice(0));
+    this.startWaiting();
+  }
+  /**
+   * Takes back every call held from a lost socket, unsent, and returns their
+   * ids so the caller can answer them. Does nothing while nothing is held.
+   */
+  takeHeld() {
+    return this.heldCalls.splice(0).map(({ id }) => id);
+  }
+  // The three below call each other in a ring.
+  start({ id, message, handle }) {
+    this.inFlight.set(id, rxjs.Subscription.EMPTY);
+    let sending;
+    try {
+      sending = this.write(message);
+    } catch (error) {
+      this.finish(id);
+      throw error;
+    }
+    if (!this.inFlight.has(id)) {
+      return;
+    }
+    this.inFlight.set(id, sending);
+    handle.add(() => {
+      const isWritten = sending.closed;
+      sending.unsubscribe();
+      if (!isWritten && this.inFlight.get(id) === sending) {
+        this.finish(id);
+      }
+    });
+  }
+  startWaiting() {
+    while (this.inFlight.size < this.limit) {
+      const next = this.waiting.shift();
+      if (!next) {
+        return;
+      }
+      this.start(next);
+    }
+  }
+  finish(id) {
+    if (this.inFlight.delete(id)) {
+      this.startWaiting();
+    }
+  }
+};
+function remove(calls, call) {
+  const index = calls.indexOf(call);
+  if (index >= 0) {
+    calls.splice(index, 1);
+  }
+}
+function isRequest(message) {
+  return message.id !== void 0 && message.id !== null && Boolean(message.method);
+}
 var TrueNasSocket = class {
   constructor(config) {
     this.config = config;
@@ -3205,7 +3372,7 @@ 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:", interceptor) {
+  constructor(initialEnabled, hostnames, systemUuid, websocketPath, systemName, retryDelay = tenSeconds, maxRetry = 3, logger = noopLogger, protocol = "https:", interceptor, maxConcurrentCalls) {
     this.systemUuid = systemUuid;
     this.websocketPath = websocketPath;
     this.systemName = systemName;
@@ -3213,6 +3380,7 @@ var TrueNasConnection = class {
     this.maxRetry = maxRetry;
     this.logger = logger;
     this.interceptor = interceptor;
+    this.maxConcurrentCalls = maxConcurrentCalls;
     // compatibility properties
     this.opened = new rxjs.BehaviorSubject(false);
     this.closed = new rxjs.Subject();
@@ -3376,16 +3544,39 @@ var TrueNasConnection = class {
         rxjs.catchError(() => rxjs.EMPTY)
       ))
     );
-    this.messages$ = interceptor?.injected$ ? rxjs.merge(this.socketMessages$, interceptor.injected$.pipe(rxjs.observeOn(rxjs.asapScheduler), rxjs.share())) : this.socketMessages$;
+    /** Answers given here, to calls ended without being sent. See `refuseHeldCalls()`. */
+    this.refusals$ = new rxjs.Subject();
+    if (maxConcurrentCalls !== void 0 && !(Number.isInteger(maxConcurrentCalls) && maxConcurrentCalls > 0)) {
+      throw new Error(`maxConcurrentCalls must be a positive integer, got ${String(maxConcurrentCalls)}`);
+    }
+    this.limiter = maxConcurrentCalls === void 0 ? null : new CallLimiter(maxConcurrentCalls, (message) => this.writeToNextSocket(message));
+    this.messages$ = interceptor?.injected$ ? rxjs.merge(this.socketMessages$, this.refusals$, interceptor.injected$.pipe(rxjs.observeOn(rxjs.asapScheduler), rxjs.share())) : rxjs.merge(this.socketMessages$, this.refusals$);
     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)
     ).subscribe((ws) => {
       const ping = createJsonRpcMessage("core.ping");
+      if (this.limiter && !this.limiter.tryTrack(ping.id ?? "")) {
+        this.logger.debug("Skipping core.ping: every concurrent call place is taken");
+        return;
+      }
       this.interceptor?.outgoing?.(ping);
       ws.next(ping);
     });
+    if (this.limiter) {
+      const limiter = this.limiter;
+      this.socketMessages$.pipe(rxjs.takeUntil(this.closeConnection)).subscribe((message) => {
+        limiter.received(message);
+      });
+      let wasOpen = false;
+      this.opened$.pipe(rxjs.takeUntil(this.closeConnection)).subscribe((isOpen) => {
+        if (wasOpen && !isOpen) {
+          limiter.socketLost();
+        }
+        wasOpen = isOpen;
+      });
+    }
     if (interceptor?.incoming) {
       const incoming = interceptor.incoming.bind(interceptor);
       this.messages$.pipe(rxjs.takeUntil(this.closeConnection)).subscribe((message) => incoming(message));
@@ -3456,11 +3647,46 @@ var TrueNasConnection = class {
    * sends a message over the current websocket OR queues it to send once
    * the next websocket is opened. messages sent via `send` will not be lost until after
    * the next `closed$` emission.
+   *
+   * With `maxConcurrentCalls` set, a request beyond the limit waits for an
+   * answer to make room. Unsubscribing the returned handle takes back a frame
+   * not written yet, waiting or queued.
    */
   send(message) {
     if (this.interceptor?.outgoing?.(message) === false) {
       return rxjs.Subscription.EMPTY;
     }
+    return this.limiter ? this.limiter.send(message) : this.writeToNextSocket(message);
+  }
+  /**
+   * Lets calls held from a lost socket go out again. The client calls this
+   * whenever the session is authenticated, so a consumer does not need to;
+   * a no-op without `maxConcurrentCalls`, or with nothing held.
+   *
+   * Calls waiting for a place when a socket is lost are held, not sent on the
+   * next one: a new socket starts signed out, so middleware would refuse them
+   * with `ENOTAUTHENTICATED`.
+   */
+  releaseHeldCalls() {
+    this.limiter?.release();
+  }
+  /**
+   * Ends every call held from a lost socket without sending it, answering each
+   * on `messages()` with the refusal middleware would have given it on a socket
+   * that is not signed in: `ENOTAUTHENTICATED`. Returns how many it ended.
+   *
+   * For an app whose next sign-in may be a different user than the one who made
+   * those calls, e.g. a password prompt after the session was lost. Call it
+   * before that sign-in; otherwise the calls go out once it succeeds. A no-op
+   * while nothing is held, so a healthy session's waiting calls are not touched.
+   */
+  refuseHeldCalls() {
+    const ids = this.limiter?.takeHeld() ?? [];
+    ids.forEach((id) => this.refusals$.next(notAuthenticatedRefusal(id)));
+    return ids.length;
+  }
+  /** Writes to the current socket, or to the next one once it opens. */
+  writeToNextSocket(message) {
     return this.ws$.pipe(
       rxjs.filter((ws) => ws !== null),
       rxjs.take(1)
@@ -3604,6 +3830,22 @@ var makeConnectionError = (message, hostname, closeCode, closeReason) => ({
 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 notAuthenticatedRefusal = (id) => ({
+  jsonrpc: "2.0",
+  id,
+  error: {
+    code: -32001,
+    message: "Method call error",
+    data: {
+      // `ErrnoMixin.ENOTAUTHENTICATED` in truenas_api_client.
+      error: 207,
+      errname: "ENOTAUTHENTICATED",
+      reason: "The session this call was made in ended before it could be sent.",
+      extra: null,
+      trace: null
+    }
+  }
+});
 var closedConnection = { state: "closed" };
 
 // src/client/truenas-api-client.ts
@@ -3621,6 +3863,11 @@ var TrueNasApiClient = class {
     this.authenticator = this.createAuthenticator();
     this.api = this.createApi();
     this.ops = this.createOperations();
+    this.authenticator.authenticated$.pipe(
+      rxjs.distinctUntilChanged(),
+      rxjs.filter(Boolean),
+      rxjs.takeUntil(this.connection.closeConnection)
+    ).subscribe(() => this.connection.releaseHeldCalls());
   }
   /**
    * Get current connection status.
@@ -3659,7 +3906,8 @@ var TrueNasApiClient = class {
       this.reconnect.maxRetry,
       this.logger,
       this.protocol,
-      this.reconnect.interceptor
+      this.reconnect.interceptor,
+      this.reconnect.maxConcurrentCalls
     );
   }
   /**
@@ -3975,7 +4223,12 @@ function toContainer3(container) {
   return {
     id: container.id.toString(),
     name: container.name,
-    status: toAppState(container.status.state),
+    // `status` is nullable from v28. Middleware's own word on when: "`null` if
+    // `query-options.extra.retrieve_status` is `false`" — so a null is status
+    // that was not fetched, not a container in an unreportable state. That is
+    // what `Unknown` is for ("no usable state"), and it keeps `Container.status`
+    // non-optional for every caller.
+    status: container.status ? toAppState(container.status.state) : "UNKNOWN" /* Unknown */,
     // Optional in the generated entry, required by `Container`.
     autostart: container.autostart ?? false,
     description
@@ -4524,7 +4777,12 @@ function instantiateClientForVersion(version, opts, logger) {
     systemName,
     logger,
     opts.protocol,
-    { retryDelay: opts.retryDelay, maxRetry: opts.maxRetry, interceptor: opts.interceptor }
+    {
+      retryDelay: opts.retryDelay,
+      maxRetry: opts.maxRetry,
+      interceptor: opts.interceptor,
+      maxConcurrentCalls: opts.maxConcurrentCalls
+    }
   );
 }
 function errorMessageOrDefault(error, fallback) {
@@ -4586,5 +4844,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-KME2PLIQ.cjs.map
-//# sourceMappingURL=chunk-KME2PLIQ.cjs.map
+//# sourceMappingURL=chunk-PWRUBUVD.cjs.map
+//# sourceMappingURL=chunk-PWRUBUVD.cjs.map