@push.rocks/smartrust 1.3.2 → 1.4.1

package/readme.md

@@ -9,9 +9,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 ## Install 📦
 
 ```bash
-npm install @push.rocks/smartrust
-# or
-pnpm install @push.rocks/smartrust
+pnpm add @push.rocks/smartrust
 ```
 
 ## Overview 🔭
@@ -105,6 +103,57 @@ bridge.on('management:configChanged', (data) => {
 bridge.kill();
 ```
 
+### Per-Command Deadlines and Cancellation
+
+Non-streaming commands accept an optional `IRustBridgeRequestOptions` argument:
+
+```typescript
+import { RustBridgeRequestError } from '@push.rocks/smartrust';
+
+const controller = new AbortController();
+
+try {
+  const metrics = await bridge.sendCommand(
+    'getMetrics',
+    {},
+    {
+      timeoutMs: 2000,
+      signal: controller.signal,
+    },
+  );
+} catch (error) {
+  if (error instanceof RustBridgeRequestError) {
+    console.error(error.code, error.message);
+  }
+}
+```
+
+`timeoutMs` must be a positive safe integer. When it is omitted, the bridge's
+constructor-level `requestTimeoutMs` remains the default. An already-aborted
+signal rejects before a request ID is allocated or anything is written.
+
+Timeout and abort only abandon the local TypeScript wait. They do not kill or
+disconnect the shared bridge, late responses are ignored, and later commands
+can continue using the same bridge.
+
+> The JSON-lines protocol has no cancellation message. After a command has
+> been written, Rust may still execute it even if the local wait times out or
+> is aborted. Do not blindly retry mutating commands; first establish whether
+> the original command executed or design the command to be idempotent.
+
+Timeout, cancellation, transport-write/exit, and Rust response failures use
+`RustBridgeRequestError`.
+Existing message text remains available, while `code` is stable for
+programmatic handling:
+
+| Code | Meaning |
+|---|---|
+| `ERR_RUST_BRIDGE_REQUEST_TIMEOUT` | The local request deadline elapsed |
+| `ERR_RUST_BRIDGE_REQUEST_ABORTED` | The caller's signal aborted the local wait |
+| `ERR_RUST_BRIDGE_REQUEST_WRITE` | The transport rejected the request write |
+| `ERR_RUST_BRIDGE_REQUEST_TRANSPORT` | The transport exited, disconnected, or was killed |
+| `ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE` | Rust returned `success: false` |
+
 ### Socket Mode — Connect to a Running Daemon 🔗
 
 When the Rust binary runs as a system service (e.g., via `systemd`, `launchd`, or a Windows Service), use `connect()` to talk to it over a Unix socket or named pipe:
@@ -284,7 +333,7 @@ const bridge = new RustBridge<TMyCommands>({
 
   // --- Bridge Options ---
   cliArgs: ['--management'],                  // optional: args passed to binary (default: ['--management'])
-  requestTimeoutMs: 30000,                    // optional: per-request timeout (default: 30000)
+  requestTimeoutMs: 30000,                    // optional: default request timeout (default: 30000)
   streamTimeoutMs: 30000,                     // optional: streaming inactivity timeout (default: requestTimeoutMs)
   readyTimeoutMs: 10000,                      // optional: ready event timeout (default: 10000)
   maxPayloadSize: 50 * 1024 * 1024,           // optional: max message size in bytes (default: 50MB)
@@ -488,7 +537,7 @@ fn main() {
 | `constructor` | `new RustBridge<T>(options: IRustBridgeOptions)` | Create a new bridge instance |
 | `spawn()` | `Promise<boolean>` | **Stdio mode**: Spawn the binary and wait for ready; returns `false` on failure |
 | `connect(socketPath, options?)` | `Promise<boolean>` | **Socket mode**: Connect to a running daemon; returns `false` on failure |
-| `sendCommand(method, params)` | `Promise<TCommands[K]['result']>` | Send a typed command and await the response |
+| `sendCommand(method, params, options?)` | `Promise<TCommands[K]['result']>` | Send a typed command with an optional per-call timeout or abort signal |
 | `sendCommandStreaming(method, params)` | `StreamingResponse<TChunk, TResult>` | Send a streaming command; returns immediately |
 | `kill()` | `void` | Stdio: SIGTERM the process, SIGKILL after 5s. Socket: close the connection (daemon stays alive) |
 | `running` | `boolean` | Whether the bridge is currently connected and ready |
@@ -541,6 +590,7 @@ fn main() {
 | Interface / Type | Description |
 |---|---|
 | `IRustBridgeOptions` | Full configuration for `RustBridge` |
+| `IRustBridgeRequestOptions` | Per-command options: `{ signal?, timeoutMs? }` |
 | `IBinaryLocatorOptions` | Configuration for `RustBinaryLocator` |
 | `ISocketConnectOptions` | Socket connection options (reconnect settings) |
 | `IRustBridgeLogger` | Logger interface: `{ log(level, message, data?) }` |
@@ -553,10 +603,12 @@ fn main() {
 | `TCommandMap` | `Record<string, ICommandDefinition>` |
 | `TStreamingCommandKeys<T>` | Extracts keys from a command map that have a `chunk` field |
 | `TExtractChunk<T>` | Extracts the chunk type from a streaming command definition |
+| `RustBridgeRequestError` | Request error class with stable `code`, `requestId`, and `method` fields |
+| `TRustBridgeRequestErrorCode` | Union of stable request error code strings |
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartrust',
-  version: '1.3.2',
-  description: 'a bridge between JS engines and rust'
+  version: '1.4.1',
+  description: 'A type-safe bridge between JavaScript engines and Rust binaries.'
 }

package/ts/classes.rustbridge.ts

@@ -1,10 +1,12 @@
 import * as plugins from './plugins.js';
 import { RustBinaryLocator } from './classes.rustbinarylocator.js';
+import { RustBridgeRequestError } from './classes.rustbridgerequesterror.js';
 import { StreamingResponse } from './classes.streamingresponse.js';
 import { StdioTransport } from './classes.stdiotransport.js';
 import { SocketTransport } from './classes.sockettransport.js';
 import type {
   IRustBridgeOptions,
+  IRustBridgeRequestOptions,
   IRustBridgeLogger,
   ISocketConnectOptions,
   TCommandMap,
@@ -20,6 +22,20 @@ const defaultLogger: IRustBridgeLogger = {
   log() {},
 };
 
+interface IPendingRequest {
+  resolve: (value: any) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout> | null;
+  method: string;
+  abortSignal?: AbortSignal;
+  abortHandler?: () => void;
+  streaming?: StreamingResponse<any, any>;
+}
+
+type TPendingRequestSettlement =
+  | { outcome: 'resolve'; value: any }
+  | { outcome: 'reject'; error: Error };
+
 /**
  * Generic bridge between TypeScript and a Rust binary.
  * Communicates via JSON-over-stdin/stdout IPC protocol (stdio mode)
@@ -32,12 +48,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   private options: Required<Pick<IRustBridgeOptions, 'cliArgs' | 'requestTimeoutMs' | 'readyTimeoutMs' | 'readyEventName' | 'maxPayloadSize'>> & IRustBridgeOptions;
   private logger: IRustBridgeLogger;
   private transport: IRustTransport | null = null;
-  private pendingRequests = new Map<string, {
-    resolve: (value: any) => void;
-    reject: (error: Error) => void;
-    timer: ReturnType<typeof setTimeout>;
-    streaming?: StreamingResponse<any, any>;
-  }>();
+  private pendingRequests = new Map<string, IPendingRequest>();
   private requestCounter = 0;
   private isRunning = false;
   private binaryPath: string | null = null;
@@ -116,13 +127,13 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
 
         transport.on('close', (...args: any[]) => {
           this.logger.log('info', `Transport closed`);
-          this.cleanup();
+          this.cleanup(`${this.options.binaryName} process exited`);
           this.emit('exit', ...args);
         });
 
         transport.on('error', (err: Error) => {
           this.logger.log('error', `Transport error: ${err.message}`);
-          this.cleanup();
+          this.cleanup(`${this.options.binaryName} process exited`, err);
           resolve(false);
         });
 
@@ -164,11 +175,32 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   public async sendCommand<K extends string & keyof TCommands>(
     method: K,
     params: TCommands[K]['params'],
+    options?: IRustBridgeRequestOptions,
   ): Promise<TCommands[K]['result']> {
+    const timeoutMs = options?.timeoutMs ?? this.options.requestTimeoutMs;
+    if (
+      options?.timeoutMs !== undefined
+      && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)
+    ) {
+      throw new RangeError('RustBridge request timeoutMs must be a positive safe integer');
+    }
+
+    if (options?.signal?.aborted) {
+      throw new RustBridgeRequestError(
+        `Command '${method}' was aborted before it was sent`,
+        {
+          code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
+          method,
+          cause: options.signal.reason,
+        },
+      );
+    }
+
     if (!this.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);
@@ -182,18 +214,76 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     }
 
     return new Promise<TCommands[K]['result']>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(id);
-        reject(new Error(`Command '${method}' timed out after ${this.options.requestTimeoutMs}ms`));
-      }, this.options.requestTimeoutMs);
+      const pending: IPendingRequest = {
+        resolve,
+        reject,
+        timer: null,
+        method,
+        abortSignal: options?.signal,
+      };
+      this.pendingRequests.set(id, pending);
+
+      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 });
+      }
 
-      this.pendingRequests.set(id, { resolve, reject, timer });
+      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);
 
-      this.transport!.write(json + '\n').catch((err) => {
-        clearTimeout(timer);
-        this.pendingRequests.delete(id);
-        reject(new Error(`Failed to write to transport: ${err.message}`));
-      });
+      try {
+        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,
+            },
+          ),
+        });
+      }
     });
   }
 
@@ -227,22 +317,33 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
 
     const timeoutMs = this.options.streamTimeoutMs ?? this.options.requestTimeoutMs;
     const timer = setTimeout(() => {
-      this.pendingRequests.delete(id);
-      streaming.fail(new Error(`Streaming command '${method}' timed out after ${timeoutMs}ms`));
+      this.settlePendingRequest(id, {
+        outcome: 'reject',
+        error: new Error(`Streaming command '${method}' timed out after ${timeoutMs}ms`),
+      });
     }, timeoutMs);
 
     this.pendingRequests.set(id, {
       resolve: (result: any) => streaming.finish(result),
       reject: (error: Error) => streaming.fail(error),
       timer,
+      method,
       streaming,
     });
 
-    this.transport!.write(json + '\n').catch((err) => {
-      clearTimeout(timer);
-      this.pendingRequests.delete(id);
-      streaming.fail(new Error(`Failed to write to transport: ${err.message}`));
-    });
+    try {
+      void this.transport!.write(json + '\n').catch((err: unknown) => {
+        this.settlePendingRequest(id, {
+          outcome: 'reject',
+          error: new Error(`Failed to write to transport: ${this.getErrorMessage(err)}`),
+        });
+      });
+    } catch (err: unknown) {
+      this.settlePendingRequest(id, {
+        outcome: 'reject',
+        error: new Error(`Failed to write to transport: ${this.getErrorMessage(err)}`),
+      });
+    }
 
     return streaming;
   }
@@ -259,11 +360,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       this.isRunning = false;
 
       // Reject pending requests
-      for (const [, pending] of this.pendingRequests) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error(`${this.options.binaryName} process killed`));
-      }
-      this.pendingRequests.clear();
+      this.rejectAllPendingRequests(`${this.options.binaryName} process killed`);
 
       transport.removeAllListeners();
       transport.disconnect();
@@ -300,11 +397,15 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       const pending = this.pendingRequests.get(parsed.id);
       if (pending?.streaming) {
         // Reset inactivity timeout
-        clearTimeout(pending.timer);
+        if (pending.timer) {
+          clearTimeout(pending.timer);
+        }
         const timeoutMs = this.options.streamTimeoutMs ?? this.options.requestTimeoutMs;
         pending.timer = setTimeout(() => {
-          this.pendingRequests.delete(parsed.id);
-          pending.reject(new Error(`Streaming command timed out after ${timeoutMs}ms of inactivity`));
+          this.settlePendingRequest(parsed.id, {
+            outcome: 'reject',
+            error: new Error(`Streaming command timed out after ${timeoutMs}ms of inactivity`),
+          });
         }, timeoutMs);
         pending.streaming.pushChunk(parsed.data);
       }
@@ -316,26 +417,85 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       const response = parsed as IManagementResponse;
       const pending = this.pendingRequests.get(response.id);
       if (pending) {
-        clearTimeout(pending.timer);
-        this.pendingRequests.delete(response.id);
         if (response.success) {
-          pending.resolve(response.result);
+          this.settlePendingRequest(response.id, {
+            outcome: 'resolve',
+            value: response.result,
+          });
         } else {
-          pending.reject(new Error(response.error || 'Unknown error from Rust process'));
+          const message = response.error || 'Unknown error from Rust process';
+          this.settlePendingRequest(response.id, {
+            outcome: 'reject',
+            error: pending.streaming
+              ? new Error(message)
+              : new RustBridgeRequestError(
+                message,
+                {
+                  code: 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE',
+                  requestId: response.id,
+                  method: pending.method,
+                },
+              ),
+          });
         }
       }
     }
   }
 
-  private cleanup(): void {
-    this.isRunning = false;
-    this.transport = null;
+  private settlePendingRequest(
+    id: string,
+    settlement: TPendingRequestSettlement,
+  ): boolean {
+    const pending = this.pendingRequests.get(id);
+    if (!pending) {
+      return false;
+    }
 
-    // Reject all pending requests
-    for (const [, pending] of this.pendingRequests) {
+    this.pendingRequests.delete(id);
+    if (pending.timer) {
       clearTimeout(pending.timer);
-      pending.reject(new Error(`${this.options.binaryName} process exited`));
+      pending.timer = null;
+    }
+    if (pending.abortSignal && pending.abortHandler) {
+      pending.abortSignal.removeEventListener('abort', pending.abortHandler);
+      pending.abortHandler = undefined;
+    }
+
+    if (settlement.outcome === 'resolve') {
+      pending.resolve(settlement.value);
+    } else {
+      pending.reject(settlement.error);
     }
-    this.pendingRequests.clear();
+    return true;
+  }
+
+  private rejectAllPendingRequests(message: string, cause?: unknown): void {
+    for (const [id, pending] of [...this.pendingRequests]) {
+      this.settlePendingRequest(id, {
+        outcome: 'reject',
+        error: pending.streaming
+          ? new Error(message)
+          : new RustBridgeRequestError(
+            message,
+            {
+              code: 'ERR_RUST_BRIDGE_REQUEST_TRANSPORT',
+              requestId: id,
+              method: pending.method,
+              cause,
+            },
+          ),
+      });
+    }
+  }
+
+  private cleanup(message: string, cause?: unknown): void {
+    this.isRunning = false;
+    this.transport = null;
+
+    this.rejectAllPendingRequests(message, cause);
+  }
+
+  private getErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
   }
 }

package/ts/classes.rustbridgerequesterror.ts

@@ -0,0 +1,37 @@
+/**
+ * Stable error codes for failures while waiting for a Rust bridge request.
+ */
+export type TRustBridgeRequestErrorCode =
+  | 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT'
+  | 'ERR_RUST_BRIDGE_REQUEST_ABORTED'
+  | 'ERR_RUST_BRIDGE_REQUEST_WRITE'
+  | 'ERR_RUST_BRIDGE_REQUEST_TRANSPORT'
+  | 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE';
+
+export interface IRustBridgeRequestErrorOptions {
+  code: TRustBridgeRequestErrorCode;
+  requestId?: string;
+  method?: string;
+  cause?: unknown;
+}
+
+/**
+ * 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.
+ */
+export class RustBridgeRequestError extends Error {
+  public readonly code: TRustBridgeRequestErrorCode;
+  public readonly requestId?: string;
+  public readonly method?: string;
+
+  constructor(message: string, options: IRustBridgeRequestErrorOptions) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = 'RustBridgeRequestError';
+    this.code = options.code;
+    this.requestId = options.requestId;
+    this.method = options.method;
+  }
+}

package/ts/index.ts

@@ -1,4 +1,9 @@
 export { RustBridge } from './classes.rustbridge.js';
+export {
+  RustBridgeRequestError,
+  type IRustBridgeRequestErrorOptions,
+  type TRustBridgeRequestErrorCode,
+} from './classes.rustbridgerequesterror.js';
 export { RustBinaryLocator } from './classes.rustbinarylocator.js';
 export { StreamingResponse } from './classes.streamingresponse.js';
 export { StdioTransport } from './classes.stdiotransport.js';

package/ts/interfaces/config.ts

@@ -5,6 +5,16 @@ export interface IRustBridgeLogger {
   log(level: string, message: string, data?: Record<string, any>): void;
 }
 
+/**
+ * Options for one non-streaming Rust bridge request.
+ */
+export interface IRustBridgeRequestOptions {
+  /** Abort only the local wait for this request. */
+  signal?: AbortSignal;
+  /** Override the bridge request timeout for this call, in milliseconds. */
+  timeoutMs?: number;
+}
+
 /**
  * Options for locating a Rust binary.
  */

package/.gitea/workflows/default_nottags.yaml

@@ -1,66 +0,0 @@
-name: Default (not tags)
-
-on:
-  push:
-    tags-ignore:
-      - '**'
-
-env:
-  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
-  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@code.foss.global/${{gitea.repository}}.git
-  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
-  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
-  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
-  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
-
-jobs:
-  security:
-    runs-on: ubuntu-latest
-    continue-on-error: true
-    container:
-      image: ${{ env.IMAGE }}
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Install pnpm and npmci
-        run: |
-          pnpm install -g pnpm
-          pnpm install -g @ship.zone/npmci
-
-      - name: Run npm prepare
-        run: npmci npm prepare
-
-      - name: Audit production dependencies
-        run: |
-          npmci command npm config set registry https://registry.npmjs.org
-          npmci command pnpm audit --audit-level=high --prod
-        continue-on-error: true
-
-      - name: Audit development dependencies
-        run: |
-          npmci command npm config set registry https://registry.npmjs.org
-          npmci command pnpm audit --audit-level=high --dev
-        continue-on-error: true
-
-  test:
-    if: ${{ always() }}
-    needs: security
-    runs-on: ubuntu-latest
-    container:
-      image: ${{ env.IMAGE }}
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Test stable
-        run: |
-          npmci node install stable
-          npmci npm install
-          npmci npm test
-
-      - name: Test build
-        run: |
-          npmci node install stable
-          npmci npm install
-          npmci npm build