@push.rocks/smartrust 2.5.1 → 2.6.1

package/ts/classes.rustbridge.ts

@@ -31,10 +31,44 @@ const defaultLogger: IRustBridgeLogger = {
   log() {},
 };
 
+/** A bridge deadline armed by `armDeadline`. */
+interface IBridgeDeadline {
+  /** Cancel the deadline, including an expiry that already fired and still waits for its turn. */
+  clear(): void;
+}
+
+/**
+ * Arm a deadline that never beats an answer already waiting to be read.
+ *
+ * When the process resumes from a stall (a frozen cgroup, a stopped or descheduled VM, a long
+ * synchronous task), Node runs every expired timer before it polls for I/O again, so a deadline
+ * can expire while the answer it bounds sits unread in the pipe: a frozen Pallet guest timed out a
+ * command whose answer its Rust side had written 13.5 ms before the freeze. The expiry therefore
+ * acts one event-loop turn later: `setImmediate` runs after the next poll phase, which reads
+ * whatever had arrived. Whatever that read settles clears the deadline, and `clear()` cancels the
+ * waiting expiry too, so an answer that won is never abandoned afterwards. Every bridge deadline
+ * is armed here, never with a bare `setTimeout`.
+ */
+const armDeadline = (timeoutMs: number, onExpired: () => void): IBridgeDeadline => {
+  let expiry: ReturnType<typeof setImmediate> | null = null;
+  const timer = setTimeout(() => {
+    expiry = setImmediate(onExpired);
+  }, timeoutMs);
+  return {
+    clear: () => {
+      clearTimeout(timer);
+      if (expiry) {
+        clearImmediate(expiry);
+        expiry = null;
+      }
+    },
+  };
+};
+
 interface IPendingRequest {
   resolve: (value: any) => void;
   reject: (error: Error) => void;
-  timer: ReturnType<typeof setTimeout> | null;
+  deadline: IBridgeDeadline | null;
   method: string;
   abortSignal?: AbortSignal;
   abortHandler?: () => void;
@@ -155,7 +189,8 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   /**
    * Spawn the Rust binary and wait for it to signal readiness.
    * Returns true if the binary was found and spawned successfully.
-   * Rejects with RustBinaryLocatorError for an invalid explicit binaryPath.
+   * Rejects with RustBinaryLocatorError for an invalid explicit binaryPath and,
+   * inside a single executable application, for an embedded sidecar it cannot provide.
    */
   public spawn(): Promise<boolean> {
     return this.activate(async (generationArg) => {
@@ -289,18 +324,18 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
 
     return new Promise<boolean>((resolve) => {
       let settled = false;
-      let readyTimeout: ReturnType<typeof setTimeout> | null = null;
-      let reconnectReadyTimeout: ReturnType<typeof setTimeout> | null = null;
+      let readyDeadline: IBridgeDeadline | null = null;
+      let reconnectReadyDeadline: IBridgeDeadline | null = null;
 
       const isCurrent = (): boolean => this.isCurrentTransport(transportArg, generation);
       const settle = (valueArg: boolean): void => {
-        if (readyTimeout) {
-          clearTimeout(readyTimeout);
-          readyTimeout = null;
+        if (readyDeadline) {
+          readyDeadline.clear();
+          readyDeadline = null;
         }
-        if (reconnectReadyTimeout) {
-          clearTimeout(reconnectReadyTimeout);
-          reconnectReadyTimeout = null;
+        if (reconnectReadyDeadline) {
+          reconnectReadyDeadline.clear();
+          reconnectReadyDeadline = null;
         }
         if (settled) {
           return;
@@ -335,9 +370,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
           if (!isCurrent() || this.lifecycleState !== 'starting') {
             return;
           }
-          if (reconnectReadyTimeout) {
-            clearTimeout(reconnectReadyTimeout);
-            reconnectReadyTimeout = null;
+          if (reconnectReadyDeadline) {
+            reconnectReadyDeadline.clear();
+            reconnectReadyDeadline = null;
           }
           this.remoteCancelSupported = this.readCancelCapability(readyEvent);
           this.lifecycleState = 'ready';
@@ -373,9 +408,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         this.rejectAllPendingRequests(`${this.options.binaryName} process exited`);
         this.settleAllRemoteCancellations();
         if (!intentional && transportArg.reconnecting === true) {
-          if (reconnectReadyTimeout) {
-            clearTimeout(reconnectReadyTimeout);
-            reconnectReadyTimeout = null;
+          if (reconnectReadyDeadline) {
+            reconnectReadyDeadline.clear();
+            reconnectReadyDeadline = null;
           }
           this.lifecycleState = 'starting';
           // Idle capability owners must observe loss before any reconnect timer
@@ -411,10 +446,10 @@ 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);
+        if (reconnectReadyDeadline) {
+          reconnectReadyDeadline.clear();
         }
-        reconnectReadyTimeout = setTimeout(() => {
+        reconnectReadyDeadline = armDeadline(this.options.readyTimeoutMs, () => {
           if (!isCurrent() || this.lifecycleState !== 'starting') {
             return;
           }
@@ -423,7 +458,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
             `Reconnected process did not send ready event within ${this.options.readyTimeoutMs}ms`,
           );
           requestConfirmedCleanup();
-        }, this.options.readyTimeoutMs);
+        });
         this.emit('reconnected');
       });
 
@@ -431,9 +466,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         if (!isCurrent()) {
           return;
         }
-        if (reconnectReadyTimeout) {
-          clearTimeout(reconnectReadyTimeout);
-          reconnectReadyTimeout = null;
+        if (reconnectReadyDeadline) {
+          reconnectReadyDeadline.clear();
+          reconnectReadyDeadline = null;
         }
         this.isRunning = false;
         this.transport = null;
@@ -443,7 +478,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         settle(false);
       });
 
-      readyTimeout = setTimeout(() => {
+      readyDeadline = armDeadline(this.options.readyTimeoutMs, () => {
         if (!isCurrent() || this.lifecycleState !== 'starting') {
           return;
         }
@@ -452,7 +487,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
           `Process did not send ready event within ${this.options.readyTimeoutMs}ms`,
         );
         requestConfirmedCleanup();
-      }, this.options.readyTimeoutMs);
+      });
 
       let connectionPromise: Promise<void>;
       try {
@@ -543,7 +578,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         const pending: IPendingRequest = {
           resolve,
           reject,
-          timer: null,
+          deadline: null,
           method,
           abortSignal: options?.signal,
           admissionReservation,
@@ -569,13 +604,13 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
             }
           }
 
-          pending.timer = setTimeout(() => {
+          pending.deadline = armDeadline(timeoutMs, () => {
             this.abandonPendingRequest(
               id,
               'ERR_RUST_BRIDGE_REQUEST_TIMEOUT',
               `Command '${method}' timed out after ${timeoutMs}ms`,
             );
-          }, timeoutMs);
+          });
 
           const currentAvailabilityError = this.getRequestAvailabilityError(
             method,
@@ -743,7 +778,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         const pending: IPendingRequest = {
           resolve,
           reject,
-          timer: null,
+          deadline: null,
           method,
           abortSignal: options?.signal,
           admissionReservation,
@@ -764,14 +799,14 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
           };
           options.signal.addEventListener('abort', pending.abortHandler, { once: true });
         }
-        pending.timer = setTimeout(() => {
+        pending.deadline = armDeadline(timeoutMs, () => {
           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);
+        });
 
         void (async (): Promise<void> => {
           try {
@@ -887,7 +922,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       const pending: IPendingRequest = {
         resolve: (result: any) => streaming.finish(result),
         reject: (error: Error) => streaming.fail(error),
-        timer: null,
+        deadline: null,
         method,
         abortSignal: signal,
         streaming,
@@ -1151,16 +1186,16 @@ 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);
-    }
+    // Clearing also cancels an expiry that fired and waits for its turn: a chunk read in that turn
+    // keeps the stream alive.
+    pending.deadline?.clear();
     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(() => {
+    pending.deadline = armDeadline(timeoutMs, () => {
       this.abandonPendingRequest(id, 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT', message);
-    }, timeoutMs);
+    });
   }
 
   /**
@@ -1338,9 +1373,10 @@ 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;
+    // A settled request's deadline does nothing more, even when it fired and waits for its turn.
+    if (pending.deadline) {
+      pending.deadline.clear();
+      pending.deadline = null;
     }
     if (pending.abortSignal && pending.abortHandler) {
       pending.abortSignal.removeEventListener('abort', pending.abortHandler);

package/ts/index.ts

@@ -7,7 +7,7 @@ export {
   type TRustBridgeRequestErrorCode,
 } from './classes.rustbridgerequesterror.js';
 export { RustBinaryLocator } from './classes.rustbinarylocator.js';
-export { RustBinaryLocatorError } from './classes.rustbinarylocatorerror.js';
+export { RustBinaryLocatorError, type TRustBinaryLocatorErrorCode } from './classes.rustbinarylocatorerror.js';
 export { StreamingResponse } from './classes.streamingresponse.js';
 export { StdioTransport } from './classes.stdiotransport.js';
 export { SocketTransport } from './classes.sockettransport.js';

package/ts/plugins.ts

@@ -11,5 +11,6 @@ export { path, fs, childProcess, events, url, net, stream };
 
 // @push.rocks scope
 import * as smartpath from '@push.rocks/smartpath';
+import * as smartsea from '@push.rocks/smartsea';
 
-export { smartpath };
+export { smartpath, smartsea };