@push.rocks/smartrust 1.7.1 → 1.9.0

package/ts/classes.rustbridge.ts

@@ -32,6 +32,12 @@ interface IPendingRequest {
   abortSignal?: AbortSignal;
   abortHandler?: () => void;
   streaming?: StreamingResponse<any, any>;
+  admissionReservation?: IRequestAdmissionReservation;
+}
+
+interface IRequestAdmissionReservation {
+  method: string;
+  released: boolean;
 }
 
 type TPendingRequestSettlement =
@@ -57,6 +63,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   private logger: IRustBridgeLogger;
   private transport: TConfirmableRustTransport | null = null;
   private pendingRequests = new Map<string, IPendingRequest>();
+  private pendingRequestReservationsByMethod = new Map<string, number>();
   private requestCounter = 0;
   private isRunning = false;
   private binaryPath: string | null = null;
@@ -67,6 +74,24 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
 
   constructor(options: IRustBridgeOptions) {
     super();
+    if (options.inheritedFileDescriptors) {
+      for (const descriptor of options.inheritedFileDescriptors) {
+        if (!Number.isSafeInteger(descriptor) || descriptor < 0) {
+          throw new RangeError(
+            'RustBridge inheritedFileDescriptors values must be non-negative safe integers',
+          );
+        }
+      }
+    }
+    if (options.maxPendingRequestsByMethod) {
+      for (const [method, limit] of Object.entries(options.maxPendingRequestsByMethod)) {
+        if (!method || !Number.isSafeInteger(limit) || limit <= 0) {
+          throw new RangeError(
+            'RustBridge maxPendingRequestsByMethod values must be positive safe integers',
+          );
+        }
+      }
+    }
     this.logger = options.logger || defaultLogger;
     this.options = {
       cliArgs: ['--management'],
@@ -75,6 +100,12 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       readyEventName: 'ready',
       maxPayloadSize: 50 * 1024 * 1024,
       ...options,
+      inheritedFileDescriptors: options.inheritedFileDescriptors
+        ? [...options.inheritedFileDescriptors]
+        : undefined,
+      maxPendingRequestsByMethod: options.maxPendingRequestsByMethod
+        ? { ...options.maxPendingRequestsByMethod }
+        : undefined,
     };
     this.locator = new RustBinaryLocator(options, this.logger);
   }
@@ -98,6 +129,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         binaryPath,
         cliArgs: this.options.cliArgs,
         env: this.options.env,
+        inheritedFileDescriptors: this.options.inheritedFileDescriptors,
         maxPayloadSize: this.options.maxPayloadSize,
         logger: this.logger,
       });
@@ -112,6 +144,11 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
    * @param socketOptions - Optional socket connection options (reconnect, etc.)
    */
   public connect(socketPath: string, socketOptions?: ISocketConnectOptions): Promise<boolean> {
+    if (this.options.inheritedFileDescriptors?.length) {
+      return Promise.reject(
+        new Error('RustBridge inheritedFileDescriptors are available only with spawn()'),
+      );
+    }
     return this.activate(async () => new SocketTransport({
       socketPath,
       maxPayloadSize: this.options.maxPayloadSize,
@@ -396,95 +433,137 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       );
     }
 
-    if (!this.transport?.connected || !this.isRunning) {
+    const transport = this.transport;
+    if (!transport?.connected || !this.isRunning) {
       throw new Error(`${this.options.binaryName} bridge is not running`);
     }
 
-    const transport = this.transport;
-    const id = `req_${++this.requestCounter}`;
-    const request: IManagementRequest = { id, method, params };
-    const json = JSON.stringify(request);
-
-    // Check outbound payload size
-    const byteLength = Buffer.byteLength(json, 'utf8');
-    if (byteLength > this.options.maxPayloadSize) {
-      throw new Error(
-        `Outbound message exceeds maxPayloadSize (${byteLength} > ${this.options.maxPayloadSize})`
-      );
-    }
+    const lifecycleGeneration = this.lifecycleGeneration;
+    const admissionReservation = this.reservePendingRequest(method);
+    let reservationTransferred = false;
 
-    return new Promise<TCommands[K]['result']>((resolve, reject) => {
-      const pending: IPendingRequest = {
-        resolve,
-        reject,
-        timer: null,
+    try {
+      const id = `req_${++this.requestCounter}`;
+      const request: IManagementRequest = { id, method, params };
+      const json = JSON.stringify(request);
+
+      const byteLength = Buffer.byteLength(json, 'utf8');
+      if (byteLength > this.options.maxPayloadSize) {
+        throw new Error(
+          `Outbound message exceeds maxPayloadSize (${byteLength} > ${this.options.maxPayloadSize})`
+        );
+      }
+
+      const availabilityError = this.getRequestAvailabilityError(
         method,
-        abortSignal: options?.signal,
-      };
-      this.pendingRequests.set(id, pending);
+        options?.signal,
+        transport,
+        lifecycleGeneration,
+      );
+      if (availabilityError) {
+        throw availabilityError;
+      }
 
-      if (options?.signal) {
-        pending.abortHandler = () => {
-          this.settlePendingRequest(id, {
-            outcome: 'reject',
-            error: new RustBridgeRequestError(
-              `Command '${method}' was aborted`,
-              {
-                code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
-                requestId: id,
-                method,
-                cause: options.signal?.reason,
-              },
-            ),
-          });
+      return new Promise<TCommands[K]['result']>((resolve, reject) => {
+        const pending: IPendingRequest = {
+          resolve,
+          reject,
+          timer: null,
+          method,
+          abortSignal: options?.signal,
+          admissionReservation,
         };
-        options.signal.addEventListener('abort', pending.abortHandler, { once: true });
-      }
+        this.pendingRequests.set(id, pending);
+        reservationTransferred = true;
 
-      pending.timer = setTimeout(() => {
-        this.settlePendingRequest(id, {
-          outcome: 'reject',
-          error: new RustBridgeRequestError(
-            `Command '${method}' timed out after ${timeoutMs}ms`,
-            {
-              code: 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT',
-              requestId: id,
-              method,
-            },
-          ),
-        });
-      }, timeoutMs);
+        try {
+          if (options?.signal) {
+            pending.abortHandler = () => {
+              this.settlePendingRequest(id, {
+                outcome: 'reject',
+                error: new RustBridgeRequestError(
+                  `Command '${method}' was aborted`,
+                  {
+                    code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
+                    requestId: id,
+                    method,
+                    cause: options.signal?.reason,
+                  },
+                ),
+              });
+            };
+            options.signal.addEventListener('abort', pending.abortHandler, { once: true });
+            if (options.signal.aborted) {
+              pending.abortHandler();
+              return;
+            }
+          }
 
-      try {
-        void transport.write(json + '\n').catch((err: unknown) => {
+          pending.timer = setTimeout(() => {
+            this.settlePendingRequest(id, {
+              outcome: 'reject',
+              error: new RustBridgeRequestError(
+                `Command '${method}' timed out after ${timeoutMs}ms`,
+                {
+                  code: 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT',
+                  requestId: id,
+                  method,
+                },
+              ),
+            });
+          }, timeoutMs);
+
+          const currentAvailabilityError = this.getRequestAvailabilityError(
+            method,
+            options?.signal,
+            transport,
+            lifecycleGeneration,
+            id,
+          );
+          if (currentAvailabilityError) {
+            this.settlePendingRequest(id, {
+              outcome: 'reject',
+              error: currentAvailabilityError,
+            });
+            return;
+          }
+
+          void transport.write(json + '\n').catch((err: unknown) => {
+            this.settlePendingRequest(id, {
+              outcome: 'reject',
+              error: new RustBridgeRequestError(
+                `Failed to write to transport: ${this.getErrorMessage(err)}`,
+                {
+                  code: 'ERR_RUST_BRIDGE_REQUEST_WRITE',
+                  requestId: id,
+                  method,
+                  cause: err,
+                },
+              ),
+            });
+          });
+        } catch (err: unknown) {
           this.settlePendingRequest(id, {
             outcome: 'reject',
-            error: new RustBridgeRequestError(
-              `Failed to write to transport: ${this.getErrorMessage(err)}`,
-              {
-                code: 'ERR_RUST_BRIDGE_REQUEST_WRITE',
-                requestId: id,
-                method,
-                cause: err,
-              },
-            ),
+            error: err instanceof RustBridgeRequestError
+              ? err
+              : new RustBridgeRequestError(
+                `Failed to write to transport: ${this.getErrorMessage(err)}`,
+                {
+                  code: 'ERR_RUST_BRIDGE_REQUEST_WRITE',
+                  requestId: id,
+                  method,
+                  cause: err,
+                },
+              ),
           });
-        });
-      } catch (err: unknown) {
-        this.settlePendingRequest(id, {
-          outcome: 'reject',
-          error: new RustBridgeRequestError(
-            `Failed to write to transport: ${this.getErrorMessage(err)}`,
-            {
-              code: 'ERR_RUST_BRIDGE_REQUEST_WRITE',
-              requestId: id,
-              method,
-              cause: err,
-            },
-          ),
-        });
+        }
+      });
+    } finally {
+      if (!reservationTransferred) {
+        this.releasePendingRequestReservation(admissionReservation);
       }
-    });
+    }
   }
 
   /**
@@ -498,51 +577,120 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   ): StreamingResponse<TExtractChunk<TCommands[K]>, TCommands[K]['result']> {
     const streaming = new StreamingResponse<TExtractChunk<TCommands[K]>, TCommands[K]['result']>();
 
-    if (!this.transport?.connected || !this.isRunning) {
+    const transport = this.transport;
+    if (!transport?.connected || !this.isRunning) {
       streaming.fail(new Error(`${this.options.binaryName} bridge is not running`));
       return streaming;
     }
 
-    const id = `req_${++this.requestCounter}`;
-    const request: IManagementRequest = { id, method, params };
-    const json = JSON.stringify(request);
+    const lifecycleGeneration = this.lifecycleGeneration;
+    let admissionReservation: IRequestAdmissionReservation | undefined;
+    let reservationTransferred = false;
+    let requestId: string | undefined;
 
-    const byteLength = Buffer.byteLength(json, 'utf8');
-    if (byteLength > this.options.maxPayloadSize) {
-      streaming.fail(
-        new Error(`Outbound message exceeds maxPayloadSize (${byteLength} > ${this.options.maxPayloadSize})`)
+    try {
+      admissionReservation = this.reservePendingRequest(method);
+      const id = `req_${++this.requestCounter}`;
+      requestId = id;
+      const request: IManagementRequest = { id, method, params };
+      const json = JSON.stringify(request);
+
+      const byteLength = Buffer.byteLength(json, 'utf8');
+      if (byteLength > this.options.maxPayloadSize) {
+        throw new Error(
+          `Outbound message exceeds maxPayloadSize (${byteLength} > ${this.options.maxPayloadSize})`,
+        );
+      }
+
+      const availabilityError = this.getRequestAvailabilityError(
+        method,
+        undefined,
+        transport,
+        lifecycleGeneration,
       );
-      return streaming;
-    }
+      if (availabilityError) {
+        throw availabilityError;
+      }
 
-    const timeoutMs = this.options.streamTimeoutMs ?? this.options.requestTimeoutMs;
-    const timer = setTimeout(() => {
-      this.settlePendingRequest(id, {
-        outcome: 'reject',
-        error: new Error(`Streaming command '${method}' timed out after ${timeoutMs}ms`),
+      this.pendingRequests.set(id, {
+        resolve: (result: any) => streaming.finish(result),
+        reject: (error: Error) => streaming.fail(error),
+        timer: null,
+        method,
+        streaming,
+        admissionReservation,
       });
-    }, timeoutMs);
-
-    this.pendingRequests.set(id, {
-      resolve: (result: any) => streaming.finish(result),
-      reject: (error: Error) => streaming.fail(error),
-      timer,
-      method,
-      streaming,
-    });
+      reservationTransferred = true;
 
-    try {
-      void this.transport!.write(json + '\n').catch((err: unknown) => {
+      try {
+        const timeoutMs = this.options.streamTimeoutMs ?? this.options.requestTimeoutMs;
+        const pending = this.pendingRequests.get(id)!;
+        pending.timer = setTimeout(() => {
+          this.settlePendingRequest(id, {
+            outcome: 'reject',
+            error: new Error(`Streaming command '${method}' timed out after ${timeoutMs}ms`),
+          });
+        }, timeoutMs);
+
+        const currentAvailabilityError = this.getRequestAvailabilityError(
+          method,
+          undefined,
+          transport,
+          lifecycleGeneration,
+          id,
+        );
+        if (currentAvailabilityError) {
+          this.settlePendingRequest(id, {
+            outcome: 'reject',
+            error: currentAvailabilityError,
+          });
+          return streaming;
+        }
+
+        void transport.write(json + '\n').catch((err: unknown) => {
+          this.settlePendingRequest(id, {
+            outcome: 'reject',
+            error: new RustBridgeRequestError(
+              `Failed to write to transport: ${this.getErrorMessage(err)}`,
+              {
+                code: 'ERR_RUST_BRIDGE_REQUEST_WRITE',
+                requestId: id,
+                method,
+                cause: err,
+              },
+            ),
+          });
+        });
+      } catch (err: unknown) {
         this.settlePendingRequest(id, {
           outcome: 'reject',
-          error: new Error(`Failed to write to transport: ${this.getErrorMessage(err)}`),
+          error: err instanceof RustBridgeRequestError
+            ? err
+            : new RustBridgeRequestError(
+              `Failed to write to transport: ${this.getErrorMessage(err)}`,
+              {
+                code: 'ERR_RUST_BRIDGE_REQUEST_WRITE',
+                requestId: id,
+                method,
+                cause: err,
+              },
+            ),
         });
-      });
+      }
     } catch (err: unknown) {
-      this.settlePendingRequest(id, {
-        outcome: 'reject',
-        error: new Error(`Failed to write to transport: ${this.getErrorMessage(err)}`),
-      });
+      const error = err instanceof Error ? err : new Error(this.getErrorMessage(err));
+      if (reservationTransferred && requestId) {
+        this.settlePendingRequest(requestId, {
+          outcome: 'reject',
+          error,
+        });
+      } else {
+        streaming.fail(error);
+      }
+    } finally {
+      if (!reservationTransferred) {
+        this.releasePendingRequestReservation(admissionReservation);
+      }
     }
 
     return streaming;
@@ -746,6 +894,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     }
 
     this.pendingRequests.delete(id);
+    this.releasePendingRequestReservation(pending.admissionReservation);
     if (pending.timer) {
       clearTimeout(pending.timer);
       pending.timer = null;
@@ -782,6 +931,86 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     }
   }
 
+  private reservePendingRequest(method: string): IRequestAdmissionReservation | undefined {
+    const configuredLimits = this.options.maxPendingRequestsByMethod;
+    const limit = configuredLimits
+      && Object.prototype.hasOwnProperty.call(configuredLimits, method)
+      ? configuredLimits[method]
+      : undefined;
+    if (limit === undefined) {
+      return undefined;
+    }
+
+    const currentCount = this.pendingRequestReservationsByMethod.get(method) || 0;
+    if (currentCount >= limit) {
+      throw new RustBridgeRequestError(
+        `Command '${method}' reached its pending request limit of ${limit}`,
+        {
+          code: 'ERR_RUST_BRIDGE_REQUEST_LIMIT',
+          method,
+        },
+      );
+    }
+
+    this.pendingRequestReservationsByMethod.set(method, currentCount + 1);
+    return { method, released: false };
+  }
+
+  private releasePendingRequestReservation(
+    reservation: IRequestAdmissionReservation | undefined,
+  ): void {
+    if (!reservation || reservation.released) {
+      return;
+    }
+    reservation.released = true;
+
+    const currentCount = this.pendingRequestReservationsByMethod.get(reservation.method) || 0;
+    if (currentCount <= 1) {
+      this.pendingRequestReservationsByMethod.delete(reservation.method);
+    } else {
+      this.pendingRequestReservationsByMethod.set(reservation.method, currentCount - 1);
+    }
+  }
+
+  private getRequestAvailabilityError(
+    method: string,
+    signal: AbortSignal | undefined,
+    transport: TConfirmableRustTransport,
+    lifecycleGeneration: number,
+    requestId?: string,
+  ): RustBridgeRequestError | null {
+    if (signal?.aborted) {
+      return new RustBridgeRequestError(
+        `Command '${method}' was aborted before it was sent`,
+        {
+          code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
+          requestId,
+          method,
+          cause: signal.reason,
+        },
+      );
+    }
+
+    if (
+      this.lifecycleState !== 'ready'
+      || !this.isRunning
+      || this.lifecycleGeneration !== lifecycleGeneration
+      || this.transport !== transport
+      || !transport.connected
+    ) {
+      return new RustBridgeRequestError(
+        `Command '${method}' could not be sent because the bridge lifecycle changed`,
+        {
+          code: 'ERR_RUST_BRIDGE_REQUEST_TRANSPORT',
+          requestId,
+          method,
+        },
+      );
+    }
+
+    return null;
+  }
+
   private getErrorMessage(error: unknown): string {
     return error instanceof Error ? error.message : String(error);
   }

package/ts/classes.rustbridgerequesterror.ts

@@ -4,6 +4,7 @@
 export type TRustBridgeRequestErrorCode =
   | 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT'
   | 'ERR_RUST_BRIDGE_REQUEST_ABORTED'
+  | 'ERR_RUST_BRIDGE_REQUEST_LIMIT'
   | 'ERR_RUST_BRIDGE_REQUEST_WRITE'
   | 'ERR_RUST_BRIDGE_REQUEST_TRANSPORT'
   | 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE';
@@ -20,8 +21,8 @@ export interface IRustBridgeRequestErrorOptions {
  * Error raised while preparing or waiting for a Rust bridge request.
  *
  * Existing error messages are preserved while `code` provides a stable way to
- * distinguish timeout, cancellation, transport, write, and Rust response
- * failures.
+ * distinguish admission, timeout, cancellation, transport, write, and Rust
+ * response failures.
  */
 export class RustBridgeRequestError extends Error {
   public readonly code: TRustBridgeRequestErrorCode;

package/ts/classes.stdiotransport.ts

@@ -13,6 +13,7 @@ export interface IStdioTransportOptions {
   binaryPath: string;
   cliArgs: string[];
   env?: Record<string, string>;
+  inheritedFileDescriptors?: readonly number[];
   maxPayloadSize: number;
   logger: IRustBridgeLogger;
 }
@@ -70,10 +71,16 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
 
     let childProcess: plugins.childProcess.ChildProcess;
     try {
+      const stdio: plugins.childProcess.StdioOptions = [
+        'pipe',
+        'pipe',
+        'pipe',
+        ...(this.options.inheritedFileDescriptors ?? []),
+      ];
       childProcess = plugins.childProcess.spawn(
         this.options.binaryPath,
         this.options.cliArgs,
-        { stdio: ['pipe', 'pipe', 'pipe'], env },
+        { stdio, env },
       );
     } catch (error: unknown) {
       return Promise.reject(this.toError(error, 'Failed to spawn child process'));

package/ts/interfaces/config.ts

@@ -48,6 +48,13 @@ export interface IBinaryLocatorOptions {
 export interface IRustBridgeOptions extends IBinaryLocatorOptions {
   /** CLI arguments passed to the binary (default: ['--management']) */
   cliArgs?: string[];
+  /**
+   * Caller-owned descriptors inherited only by stdio children. The first
+   * source descriptor is duplicated to child fd 3, the next to fd 4, and so
+   * on. Sources must remain valid through each spawn call. Smartrust never
+   * closes the caller's source descriptors.
+   */
+  inheritedFileDescriptors?: readonly number[];
   /** Timeout for individual requests in ms (default: 30000) */
   requestTimeoutMs?: number;
   /** Timeout for the ready event during spawn in ms (default: 10000) */
@@ -63,6 +70,12 @@ export interface IRustBridgeOptions extends IBinaryLocatorOptions {
   /** Inactivity timeout for streaming commands in ms (default: same as requestTimeoutMs).
    *  Resets on each chunk received. */
   streamTimeoutMs?: number;
+  /**
+   * Optional per-method limits for locally pending requests. A saturated
+   * method fails before serialization or transport writes, while other
+   * methods remain available for control and callback traffic.
+   */
+  maxPendingRequestsByMethod?: Record<string, number>;
 }
 
 /**