@push.rocks/smartrust 2.3.0 → 2.5.0

package/ts/classes.rustbridge.ts

@@ -1,18 +1,23 @@
 import * as plugins from './plugins.js';
 import { RustBinaryLocator } from './classes.rustbinarylocator.js';
 import { RustBinaryLocatorError } from './classes.rustbinarylocatorerror.js';
-import { RustBridgeRequestError } from './classes.rustbridgerequesterror.js';
+import {
+  RustBridgeRequestError,
+  type IRustBridgeRemoteSettlement,
+} 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,
+  IRustBridgeStreamingRequestOptions,
   IRustBridgeTerminateOptions,
   IRustBridgeLogger,
   ISocketConnectOptions,
   TCommandMap,
   IManagementRequest,
+  IManagementCancelRequest,
   IManagementResponse,
   IManagementEvent,
   TStreamingCommandKeys,
@@ -35,6 +40,12 @@ interface IPendingRequest {
   abortHandler?: () => void;
   streaming?: StreamingResponse<any, any>;
   admissionReservation?: IRequestAdmissionReservation;
+  /**
+   * Transport the request line was handed to, recorded only when that
+   * connection advertised the `cancel` capability and the request is not
+   * sensitive. A later timeout or abort sends its cancel frame here.
+   */
+  cancelTransport?: TConfirmableRustTransport;
   sensitive?: {
     byteLength: number;
     writeComplete: boolean;
@@ -42,6 +53,12 @@ interface IPendingRequest {
   };
 }
 
+/** A request abandoned locally whose cancel frame awaits Rust's answer. */
+interface IRemoteCancellation {
+  method: string;
+  settle: (settlementArg: IRustBridgeRemoteSettlement) => void;
+}
+
 interface IRequestAdmissionReservation {
   method: string;
   released: boolean;
@@ -81,6 +98,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   private sensitiveRequestId: string | null = null;
   private sensitiveUsedGeneration: number | null = null;
   private regularRequestPreparations = 0;
+  /** Whether the current transport generation's ready event advertised `cancel`. */
+  private remoteCancelSupported = false;
+  private remoteCancellations = new Map<string, IRemoteCancellation>();
 
   constructor(options: IRustBridgeOptions) {
     super();
@@ -211,6 +231,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     const generation = ++this.lifecycleGeneration;
     this.sensitiveRequestId = null;
     this.sensitiveUsedGeneration = null;
+    this.remoteCancelSupported = false;
     this.lifecycleState = 'starting';
 
     const activationPromise = (async (): Promise<boolean> => {
@@ -262,6 +283,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         throw new Error(`RustBridge cannot activate while lifecycle state is '${this.lifecycleState}'`);
       }
       this.lifecycleState = 'starting';
+      this.remoteCancelSupported = false;
       this.transport = transportArg;
     }
 
@@ -309,7 +331,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         if (!isCurrent()) {
           return;
         }
-        this.handleLine(line, () => {
+        this.handleLine(line, (readyEvent: IManagementEvent) => {
           if (!isCurrent() || this.lifecycleState !== 'starting') {
             return;
           }
@@ -317,6 +339,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
             clearTimeout(reconnectReadyTimeout);
             reconnectReadyTimeout = null;
           }
+          this.remoteCancelSupported = this.readCancelCapability(readyEvent);
           this.lifecycleState = 'ready';
           this.isRunning = true;
           this.logger.log('info', `Bridge connected to ${this.options.binaryName}`);
@@ -346,7 +369,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         };
         this.logger.log('info', 'Transport closed');
         this.isRunning = false;
+        this.remoteCancelSupported = false;
         this.rejectAllPendingRequests(`${this.options.binaryName} process exited`);
+        this.settleAllRemoteCancellations();
         if (!intentional && transportArg.reconnecting === true) {
           if (reconnectReadyTimeout) {
             clearTimeout(reconnectReadyTimeout);
@@ -385,6 +410,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         }
         this.logger.log('info', 'Transport reconnected, waiting for ready event');
         this.lifecycleState = 'starting';
+        this.remoteCancelSupported = false;
         if (reconnectReadyTimeout) {
           clearTimeout(reconnectReadyTimeout);
         }
@@ -527,39 +553,28 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
 
         try {
           if (options?.signal) {
+            const signal = 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,
-                  },
-                ),
-              });
+              this.abandonPendingRequest(
+                id,
+                'ERR_RUST_BRIDGE_REQUEST_ABORTED',
+                `Command '${method}' was aborted`,
+                signal.reason,
+              );
             };
-            options.signal.addEventListener('abort', pending.abortHandler, { once: true });
-            if (options.signal.aborted) {
+            signal.addEventListener('abort', pending.abortHandler, { once: true });
+            if (signal.aborted) {
               pending.abortHandler();
               return;
             }
           }
 
           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,
-                },
-              ),
-            });
+            this.abandonPendingRequest(
+              id,
+              'ERR_RUST_BRIDGE_REQUEST_TIMEOUT',
+              `Command '${method}' timed out after ${timeoutMs}ms`,
+            );
           }, timeoutMs);
 
           const currentAvailabilityError = this.getRequestAvailabilityError(
@@ -577,6 +592,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
             return;
           }
 
+          if (this.remoteCancelSupported) {
+            pending.cancelTransport = transport;
+          }
           void transport.write(json + '\n').catch((err: unknown) => {
             this.settlePendingRequest(id, {
               outcome: 'reject',
@@ -809,8 +827,18 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   public sendCommandStreaming<K extends string & TStreamingCommandKeys<TCommands>>(
     method: K,
     params: TCommands[K]['params'],
+    options?: IRustBridgeStreamingRequestOptions,
   ): StreamingResponse<TExtractChunk<TCommands[K]>, TCommands[K]['result']> {
     const streaming = new StreamingResponse<TExtractChunk<TCommands[K]>, TCommands[K]['result']>();
+    const signal = options?.signal;
+
+    if (signal?.aborted) {
+      streaming.fail(new RustBridgeRequestError(
+        `Command '${method}' was aborted before it was sent`,
+        { code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED', method, cause: signal.reason },
+      ));
+      return streaming;
+    }
 
     if (this.sensitiveRequestId !== null) {
       streaming.fail(new RustBridgeRequestError(
@@ -848,7 +876,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
 
       const availabilityError = this.getRequestAvailabilityError(
         method,
-        undefined,
+        signal,
         transport,
         lifecycleGeneration,
       );
@@ -856,29 +884,36 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         throw availabilityError;
       }
 
-      this.pendingRequests.set(id, {
+      const pending: IPendingRequest = {
         resolve: (result: any) => streaming.finish(result),
         reject: (error: Error) => streaming.fail(error),
         timer: null,
         method,
+        abortSignal: signal,
         streaming,
         admissionReservation,
-      });
+      };
+      this.pendingRequests.set(id, pending);
       reservationTransferred = true;
 
       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);
+        if (signal) {
+          pending.abortHandler = () => {
+            this.abandonPendingRequest(
+              id,
+              'ERR_RUST_BRIDGE_REQUEST_ABORTED',
+              `Streaming command '${method}' was aborted`,
+              signal.reason,
+            );
+          };
+          signal.addEventListener('abort', pending.abortHandler, { once: true });
+        }
+
+        this.armStreamingTimeout(id, pending, false);
 
         const currentAvailabilityError = this.getRequestAvailabilityError(
           method,
-          undefined,
+          signal,
           transport,
           lifecycleGeneration,
           id,
@@ -891,6 +926,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
           return streaming;
         }
 
+        if (this.remoteCancelSupported) {
+          pending.cancelTransport = transport;
+        }
         void transport.write(json + '\n').catch((err: unknown) => {
           this.settlePendingRequest(id, {
             outcome: 'reject',
@@ -997,6 +1035,8 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       this.transport = null;
       this.isRunning = false;
       this.lifecycleState = 'idle';
+      // The transport is confirmed closed, so no answer can still arrive.
+      this.settleAllRemoteCancellations();
     })();
 
     this.terminationPromise = terminationPromise;
@@ -1058,7 +1098,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     );
   }
 
-  private handleLine(line: string, onReadyArg: () => void): void {
+  private handleLine(line: string, onReadyArg: (readyEventArg: IManagementEvent) => void): void {
     if (!line) return;
 
     let parsed: any;
@@ -1073,27 +1113,26 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     if ('event' in parsed && !('id' in parsed)) {
       const event = parsed as IManagementEvent;
       if (event.event === this.options.readyEventName) {
-        onReadyArg();
+        onReadyArg(event);
       }
       this.emit(`management:${event.event}`, event.data);
       return;
     }
 
+    // Late lines of a request abandoned after a cancel frame. Chunks are
+    // dropped; the one final answer settles the remote cancellation.
+    if ('id' in parsed && this.remoteCancellations.has(parsed.id)) {
+      if (parsed.stream !== true) {
+        this.settleRemoteCancellation(parsed as IManagementResponse);
+      }
+      return;
+    }
+
     // Stream chunk (has 'id' + stream === true + 'data')
     if ('id' in parsed && parsed.stream === true && 'data' in parsed) {
       const pending = this.pendingRequests.get(parsed.id);
       if (pending?.streaming) {
-        // Reset inactivity timeout
-        if (pending.timer) {
-          clearTimeout(pending.timer);
-        }
-        const timeoutMs = this.options.streamTimeoutMs ?? this.options.requestTimeoutMs;
-        pending.timer = setTimeout(() => {
-          this.settlePendingRequest(parsed.id, {
-            outcome: 'reject',
-            error: new Error(`Streaming command timed out after ${timeoutMs}ms of inactivity`),
-          });
-        }, timeoutMs);
+        this.armStreamingTimeout(parsed.id, pending, true);
         pending.streaming.pushChunk(parsed.data);
       }
       return;
@@ -1110,6 +1149,132 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     }
   }
 
+  /** Start or restart the inactivity deadline of one streaming request. */
+  private armStreamingTimeout(id: string, pending: IPendingRequest, afterChunkArg: boolean): void {
+    if (pending.timer) {
+      clearTimeout(pending.timer);
+    }
+    const timeoutMs = this.options.streamTimeoutMs ?? this.options.requestTimeoutMs;
+    const message = afterChunkArg
+      ? `Streaming command '${pending.method}' timed out after ${timeoutMs}ms of inactivity`
+      : `Streaming command '${pending.method}' timed out after ${timeoutMs}ms`;
+    pending.timer = setTimeout(() => {
+      this.abandonPendingRequest(id, 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT', message);
+    }, timeoutMs);
+  }
+
+  /**
+   * Reject a pending request on timeout or abort. When the request was
+   * already written to a transport that accepts cancel frames, send one and
+   * attach the remote settlement to the rejection.
+   */
+  private abandonPendingRequest(
+    id: string,
+    code: 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT' | 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
+    message: string,
+    cause?: unknown,
+  ): void {
+    const pending = this.pendingRequests.get(id);
+    if (!pending) {
+      return;
+    }
+    const remoteSettlement = this.sendRemoteCancel(id, pending);
+    this.settlePendingRequest(id, {
+      outcome: 'reject',
+      error: new RustBridgeRequestError(message, {
+        code,
+        requestId: id,
+        method: pending.method,
+        cause,
+        remoteSettlement,
+      }),
+    });
+  }
+
+  /** Write one cancel frame and track the original id until Rust answers it. */
+  private sendRemoteCancel(
+    id: string,
+    pending: IPendingRequest,
+  ): Promise<IRustBridgeRemoteSettlement> | undefined {
+    const transport = pending.cancelTransport;
+    if (!transport || pending.sensitive || this.transport !== transport || !transport.connected) {
+      return undefined;
+    }
+
+    let settle!: (settlementArg: IRustBridgeRemoteSettlement) => void;
+    const remoteSettlement = new Promise<IRustBridgeRemoteSettlement>((resolve) => {
+      settle = resolve;
+    });
+    this.remoteCancellations.set(id, { method: pending.method, settle });
+
+    const frame: IManagementCancelRequest = { id, cancel: true };
+    const logWriteFailure = (error: unknown): void => {
+      // A failed write means the transport is closing; its close settles
+      // the cancellation as disconnected.
+      this.logger.log(
+        'warn',
+        `Failed to write cancel for '${pending.method}' (${id}): ${this.getErrorMessage(error)}`,
+      );
+    };
+    try {
+      void transport.write(JSON.stringify(frame) + '\n').catch(logWriteFailure);
+    } catch (error: unknown) {
+      logWriteFailure(error);
+    }
+    return remoteSettlement;
+  }
+
+  private settleRemoteCancellation(response: IManagementResponse): void {
+    const cancellation = this.remoteCancellations.get(response.id);
+    if (!cancellation) {
+      return;
+    }
+    this.remoteCancellations.delete(response.id);
+
+    if (response.success) {
+      cancellation.settle({ outcome: 'completed', result: response.result });
+      return;
+    }
+    const settlement: IRustBridgeRemoteSettlement = {
+      outcome: response.cancelled === true ? 'cancelled' : 'failed',
+    };
+    if (typeof response.error === 'string') {
+      settlement.error = response.error;
+    }
+    if (typeof response.errorCode === 'string') {
+      settlement.errorCode = response.errorCode;
+    }
+    if (response.errorData !== undefined) {
+      settlement.errorData = response.errorData;
+    }
+    cancellation.settle(settlement);
+  }
+
+  /** Settle every tracked cancellation as disconnected after transport closure. */
+  private settleAllRemoteCancellations(): void {
+    const cancellations = [...this.remoteCancellations.values()];
+    this.remoteCancellations.clear();
+    for (const cancellation of cancellations) {
+      cancellation.settle({ outcome: 'disconnected' });
+    }
+  }
+
+  /** Read the `cancel` opt-in from a ready event's `capabilities`. */
+  private readCancelCapability(readyEvent: IManagementEvent): boolean {
+    const capabilities: unknown = readyEvent.capabilities;
+    if (capabilities === undefined) {
+      return false;
+    }
+    if (!Array.isArray(capabilities) || !capabilities.every((entry) => typeof entry === 'string')) {
+      this.logger.log(
+        'warn',
+        `Ignoring malformed ready capabilities from ${this.options.binaryName}`,
+      );
+      return false;
+    }
+    return capabilities.includes('cancel');
+  }
+
   private acceptSensitiveResponse(response: IManagementResponse, pending: IPendingRequest): void {
     const state = pending.sensitive!;
     const ack = response.sensitiveAck;
@@ -1155,6 +1320,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       error: new RustBridgeRequestError(message, {
         code: 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE',
         responseErrorCode: typeof response.errorCode === 'string' ? response.errorCode : undefined,
+        responseErrorData: response.errorData,
         requestId: response.id,
         method: pending.method,
       }),
@@ -1193,17 +1359,12 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     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,
-            },
-          ),
+        error: new RustBridgeRequestError(message, {
+          code: 'ERR_RUST_BRIDGE_REQUEST_TRANSPORT',
+          requestId: id,
+          method: pending.method,
+          cause,
+        }),
       });
     }
   }

package/ts/classes.rustbridgerequesterror.ts

@@ -11,12 +11,41 @@ export type TRustBridgeRequestErrorCode =
   | 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_PROTOCOL'
   | 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE';
 
+/**
+ * How the Rust side settled a request after the bridge sent it a cancel frame.
+ *
+ * - `cancelled`: Rust stopped the command and answered `cancelled: true`.
+ * - `completed`: Rust finished the command anyway and answered `success: true`.
+ * - `failed`: Rust answered `success: false` without `cancelled: true`.
+ * - `disconnected`: the transport closed before Rust answered; the outcome is unknown.
+ */
+export type TRustBridgeRemoteSettlementOutcome =
+  | 'cancelled'
+  | 'completed'
+  | 'failed'
+  | 'disconnected';
+
+/** Remote outcome of a locally abandoned request, as reported by Rust. */
+export interface IRustBridgeRemoteSettlement {
+  outcome: TRustBridgeRemoteSettlementOutcome;
+  /** The command's result, present only for `completed`. */
+  result?: unknown;
+  /** Rust's error text, for `cancelled` and `failed` when Rust sent one. */
+  error?: string;
+  /** Rust's string `errorCode`, for `cancelled` and `failed` when Rust sent one. */
+  errorCode?: string;
+  /** Rust's `errorData` as sent, for `cancelled` and `failed` when Rust sent it. */
+  errorData?: unknown;
+}
+
 export interface IRustBridgeRequestErrorOptions {
   code: TRustBridgeRequestErrorCode;
   responseErrorCode?: string;
+  responseErrorData?: unknown;
   requestId?: string;
   method?: string;
   cause?: unknown;
+  remoteSettlement?: Promise<IRustBridgeRemoteSettlement>;
 }
 
 /**
@@ -29,15 +58,25 @@ export interface IRustBridgeRequestErrorOptions {
 export class RustBridgeRequestError extends Error {
   public readonly code: TRustBridgeRequestErrorCode;
   public readonly responseErrorCode?: string;
+  /** Structured details from the Rust error response's `errorData`, as sent. */
+  public readonly responseErrorData?: unknown;
   public readonly requestId?: string;
   public readonly method?: string;
+  /**
+   * Present when a timeout or abort made the bridge send a cancel frame for a
+   * request already written to Rust. Settles once Rust answers the original
+   * request or the transport closes. It never rejects.
+   */
+  public readonly remoteSettlement?: Promise<IRustBridgeRemoteSettlement>;
 
   constructor(message: string, options: IRustBridgeRequestErrorOptions) {
     super(message, options.cause === undefined ? undefined : { cause: options.cause });
     this.name = 'RustBridgeRequestError';
     this.code = options.code;
     this.responseErrorCode = options.responseErrorCode;
+    this.responseErrorData = options.responseErrorData;
     this.requestId = options.requestId;
     this.method = options.method;
+    this.remoteSettlement = options.remoteSettlement;
   }
 }

package/ts/index.ts

@@ -2,6 +2,8 @@ export { RustBridge } from './classes.rustbridge.js';
 export {
   RustBridgeRequestError,
   type IRustBridgeRequestErrorOptions,
+  type IRustBridgeRemoteSettlement,
+  type TRustBridgeRemoteSettlementOutcome,
   type TRustBridgeRequestErrorCode,
 } from './classes.rustbridgerequesterror.js';
 export { RustBinaryLocator } from './classes.rustbinarylocator.js';

package/ts/interfaces/config.ts

@@ -9,12 +9,28 @@ export interface IRustBridgeLogger {
  * Options for one non-streaming Rust bridge request.
  */
 export interface IRustBridgeRequestOptions {
-  /** Abort only the local wait for this request. */
+  /**
+   * Abort the local wait for this request. When the binary advertised the
+   * `cancel` capability and the request was already written, the bridge also
+   * sends a cancel frame.
+   */
   signal?: AbortSignal;
   /** Override the bridge request timeout for this call, in milliseconds. */
   timeoutMs?: number;
 }
 
+/**
+ * Options for one streaming Rust bridge request.
+ */
+export interface IRustBridgeStreamingRequestOptions {
+  /**
+   * Abort the local stream. When the binary advertised the `cancel`
+   * capability and the request was already written, the bridge also sends a
+   * cancel frame.
+   */
+  signal?: AbortSignal;
+}
+
 /** Options for confirmed bridge termination. */
 export interface IRustBridgeTerminateOptions {
   /**

package/ts/interfaces/ipc.ts

@@ -9,6 +9,17 @@ export interface IManagementRequest {
   sensitive?: IManagementSensitivePayload;
 }
 
+/**
+ * Cancel frame sent to a binary that advertised the `cancel` capability, after
+ * a timeout or abort abandoned a request that was already written. The binary
+ * ignores it for ids it no longer runs and otherwise still answers the
+ * original id exactly once.
+ */
+export interface IManagementCancelRequest {
+  id: string;
+  cancel: true;
+}
+
 export interface IManagementSensitivePayload {
   protocol: 'smartrust-sensitive-v1';
   fileDescriptor: number;
@@ -30,6 +41,10 @@ export interface IManagementResponse {
   result?: any;
   error?: string;
   errorCode?: string;
+  /** Optional structured details of a failure, for example per-field validation errors. */
+  errorData?: unknown;
+  /** Set with `success: false` when the command stopped because of a cancel frame. */
+  cancelled?: boolean;
   /** Required after the receiver consumed the exact associated binary frame. */
   sensitiveAck?: IManagementSensitiveAck;
 }
@@ -40,6 +55,11 @@ export interface IManagementResponse {
 export interface IManagementEvent {
   event: string;
   data: any;
+  /**
+   * Protocol capabilities, read only from the ready event. `cancel` opts the
+   * current transport generation in to cancel frames.
+   */
+  capabilities?: string[];
 }
 
 /**