@push.rocks/smartrust 1.5.0 → 1.6.1

package/ts/classes.stdiotransport.ts

@@ -1,7 +1,13 @@
 import * as plugins from './plugins.js';
 import { LineScanner } from './classes.linescanner.js';
 import type { IRustBridgeLogger } from './interfaces/index.js';
-import type { IRustTransport } from './interfaces/transport.js';
+import type {
+  IRustTransport,
+  IRustTransportDisconnectOptions,
+} from './interfaces/transport.js';
+
+const DEFAULT_DISCONNECT_GRACE_PERIOD_MS = 5000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 
 export interface IStdioTransportOptions {
   binaryPath: string;
@@ -11,6 +17,21 @@ export interface IStdioTransportOptions {
   logger: IRustBridgeLogger;
 }
 
+interface IStdioTransportGeneration {
+  childProcess: plugins.childProcess.ChildProcess;
+  stderrRemainder: string;
+  exited: boolean;
+  closed: boolean;
+  closePromise: Promise<void>;
+  resolveClose: () => void;
+  disconnectPromise: Promise<void> | null;
+  rejectDisconnect: ((error: Error) => void) | null;
+  forceKillTimer: ReturnType<typeof setTimeout> | null;
+  sigtermAttempted: boolean;
+  sigkillAttempted: boolean;
+  sigtermError: Error | null;
+}
+
 /**
  * Transport that spawns a child process and communicates via stdin/stdout.
  * Extracted from the original RustBridge process management logic.
@@ -18,8 +39,8 @@ export interface IStdioTransportOptions {
 export class StdioTransport extends plugins.events.EventEmitter implements IRustTransport {
   private options: IStdioTransportOptions;
   private childProcess: plugins.childProcess.ChildProcess | null = null;
+  private generation: IStdioTransportGeneration | null = null;
   private lineScanner: LineScanner;
-  private stderrRemainder: string = '';
   private _connected: boolean = false;
 
   constructor(options: IStdioTransportOptions) {
@@ -35,22 +56,59 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
   /**
    * Spawn the child process. Resolves when the process is running (not necessarily ready).
    */
-  public async connect(): Promise<void> {
+  public connect(): Promise<void> {
+    if (this.generation && !this.generation.closed) {
+      return Promise.reject(
+        new Error('Stdio transport cannot connect until the previous child has closed'),
+      );
+    }
+
     const env = this.options.env
       ? { ...process.env, ...this.options.env }
       : { ...process.env };
 
-    this.childProcess = plugins.childProcess.spawn(
-      this.options.binaryPath,
-      this.options.cliArgs,
-      { stdio: ['pipe', 'pipe', 'pipe'], env },
-    );
+    let childProcess: plugins.childProcess.ChildProcess;
+    try {
+      childProcess = plugins.childProcess.spawn(
+        this.options.binaryPath,
+        this.options.cliArgs,
+        { stdio: ['pipe', 'pipe', 'pipe'], env },
+      );
+    } catch (error: unknown) {
+      return Promise.reject(this.toError(error, 'Failed to spawn child process'));
+    }
 
-    // Handle stderr with cross-chunk buffering
-    this.childProcess.stderr?.on('data', (data: Buffer) => {
-      this.stderrRemainder += data.toString();
-      const lines = this.stderrRemainder.split('\n');
-      this.stderrRemainder = lines.pop()!;
+    let resolveClose!: () => void;
+    const closePromise = new Promise<void>((resolve) => {
+      resolveClose = resolve;
+    });
+    const generation: IStdioTransportGeneration = {
+      childProcess,
+      stderrRemainder: '',
+      exited: false,
+      closed: false,
+      closePromise,
+      resolveClose,
+      disconnectPromise: null,
+      rejectDisconnect: null,
+      forceKillTimer: null,
+      sigtermAttempted: false,
+      sigkillAttempted: false,
+      sigtermError: null,
+    };
+
+    this.generation = generation;
+    this.childProcess = childProcess;
+
+    // Handle stderr with cross-chunk buffering.
+    childProcess.stderr?.on('data', (data: Buffer) => {
+      if (this.generation !== generation || generation.closed) {
+        return;
+      }
+
+      generation.stderrRemainder += data.toString();
+      const lines = generation.stderrRemainder.split('\n');
+      generation.stderrRemainder = lines.pop()!;
       for (const line of lines) {
         const trimmed = line.trim();
         if (trimmed) {
@@ -59,53 +117,125 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
       }
     });
 
-    // Handle stdout via LineScanner
-    this.childProcess.stdout!.on('data', (chunk: Buffer) => {
+    // Handle stdout via LineScanner.
+    childProcess.stdout!.on('data', (chunk: Buffer) => {
+      if (this.generation !== generation || generation.closed) {
+        return;
+      }
+
       this.lineScanner.push(chunk, (line) => {
-        this.emit('line', line);
+        if (this.generation === generation && !generation.closed) {
+          this.emit('line', line);
+        }
+      });
+    });
+
+    childProcess.on('exit', () => {
+      generation.exited = true;
+      if (this.generation === generation) {
+        this._connected = false;
+      }
+
+      // A descendant may inherit the child's stdio descriptors and otherwise
+      // keep ChildProcess 'close' from ever firing after the owned child exits.
+      // Allow already-queued data events through this poll turn, then close our
+      // endpoints so confirmation cannot retain that pipe graph indefinitely.
+      setImmediate(() => {
+        if (generation.closed) {
+          return;
+        }
+        this.destroyOwnedStdioEndpoint(generation, 'stdin');
+        this.destroyOwnedStdioEndpoint(generation, 'stdout');
+        this.destroyOwnedStdioEndpoint(generation, 'stderr');
       });
     });
 
-    // Handle process exit
-    this.childProcess.on('exit', (code: number | null, signal: string | null) => {
-      // Flush remaining stderr
-      if (this.stderrRemainder.trim()) {
-        this.emit('stderr', this.stderrRemainder.trim());
+    // ChildProcess 'close' is the termination confirmation: the process has exited
+    // and its stdio streams have closed.
+    childProcess.on('close', (code: number | null, signal: NodeJS.Signals | null) => {
+      if (generation.closed) {
+        return;
+      }
+
+      // Flush stderr while this generation is still considered active so a
+      // synchronous listener cannot start a replacement child mid-cleanup.
+      if (
+        this.generation === generation
+        && generation.stderrRemainder.trim()
+      ) {
+        this.emit('stderr', generation.stderrRemainder.trim());
       }
+      generation.stderrRemainder = '';
+      generation.exited = true;
+      generation.closed = true;
+      if (generation.forceKillTimer) {
+        clearTimeout(generation.forceKillTimer);
+        generation.forceKillTimer = null;
+      }
+      generation.resolveClose();
+
+      if (this.generation !== generation) {
+        return;
+      }
+
       this._connected = false;
+      this.childProcess = null;
       this.lineScanner.clear();
-      this.stderrRemainder = '';
       this.emit('close', code, signal);
     });
 
-    this.childProcess.on('error', (err: Error) => {
+    childProcess.on('error', (error: Error) => {
+      if (this.generation !== generation || generation.closed) {
+        return;
+      }
+
       this._connected = false;
-      this.emit('error', err);
+      if (generation.sigkillAttempted && generation.rejectDisconnect) {
+        generation.rejectDisconnect(
+          this.toError(error, 'Unable to confirm child termination after SIGKILL'),
+        );
+      }
+
+      if (this.listenerCount('error') > 0) {
+        this.emit('error', error);
+      } else if (generation.disconnectPromise) {
+        this.options.logger.log('error', 'Stdio transport error during disconnect: ' + error.message);
+      } else {
+        this.emit('error', error);
+      }
     });
 
     this._connected = true;
+    return Promise.resolve();
   }
 
   /**
    * Write data to stdin with backpressure support.
    */
-  public async write(data: string): Promise<void> {
+  public write(data: string): Promise<void> {
     return new Promise<void>((resolve, reject) => {
-      if (!this.childProcess?.stdin) {
+      const generation = this.generation;
+      if (
+        !generation
+        || generation.closed
+        || generation.childProcess !== this.childProcess
+        || !this._connected
+        || !generation.childProcess.stdin
+      ) {
         reject(new Error('stdin not available'));
         return;
       }
 
-      const canContinue = this.childProcess.stdin.write(data, 'utf8', (err) => {
-        if (err) {
-          reject(err);
+      const canContinue = generation.childProcess.stdin.write(data, 'utf8', (error) => {
+        if (error) {
+          reject(error);
         }
       });
 
       if (canContinue) {
         resolve();
       } else {
-        this.childProcess.stdin.once('drain', () => {
+        generation.childProcess.stdin.once('drain', () => {
           resolve();
         });
       }
@@ -113,37 +243,211 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
   }
 
   /**
-   * Kill the child process. Sends SIGTERM, then SIGKILL after 5s.
+   * Kill the child process without waiting for confirmation.
    */
   public disconnect(): void {
-    if (!this.childProcess) return;
+    try {
+      void this.disconnectAndWait().catch((error: unknown) => {
+        this.options.logger.log(
+          'error',
+          'Failed to disconnect stdio transport: ' + this.getErrorMessage(error),
+        );
+      });
+    } catch (error: unknown) {
+      this.options.logger.log(
+        'error',
+        'Failed to disconnect stdio transport: ' + this.getErrorMessage(error),
+      );
+    }
+  }
 
-    const proc = this.childProcess;
-    this.childProcess = null;
+  /**
+   * Send SIGTERM, escalate to SIGKILL after the grace period, and wait for
+   * ChildProcess 'close' to confirm termination.
+   */
+  public disconnectAndWait(
+    options: IRustTransportDisconnectOptions = {},
+  ): Promise<void> {
+    const gracePeriodMs = options.gracePeriodMs ?? DEFAULT_DISCONNECT_GRACE_PERIOD_MS;
+    if (!Number.isSafeInteger(gracePeriodMs) || gracePeriodMs < 0) {
+      throw new RangeError(
+        'StdioTransport gracePeriodMs must be a non-negative safe integer',
+      );
+    }
+
+    const generation = this.generation;
+    if (!generation) {
+      return Promise.resolve();
+    }
+    if (generation.disconnectPromise) {
+      return generation.disconnectPromise;
+    }
+    if (generation.closed) {
+      generation.disconnectPromise = generation.closePromise;
+      return generation.disconnectPromise;
+    }
+
+    let rejectDisconnect!: (error: Error) => void;
+    const disconnectPromise = new Promise<void>((resolve, reject) => {
+      rejectDisconnect = reject;
+      void generation.closePromise.then(resolve);
+    });
+    generation.disconnectPromise = disconnectPromise;
+    generation.rejectDisconnect = rejectDisconnect;
     this._connected = false;
-    this.lineScanner.clear();
-    this.stderrRemainder = '';
-
-    // Remove all listeners
-    proc.removeAllListeners();
-    proc.stdout?.removeAllListeners();
-    proc.stderr?.removeAllListeners();
-    proc.stdin?.removeAllListeners();
-
-    // Kill the process
-    try { proc.kill('SIGTERM'); } catch { /* already dead */ }
-
-    // Destroy stdio pipes
-    try { proc.stdin?.destroy(); } catch { /* ignore */ }
-    try { proc.stdout?.destroy(); } catch { /* ignore */ }
-    try { proc.stderr?.destroy(); } catch { /* ignore */ }
-
-    // Unref so Node doesn't wait
-    try { proc.unref(); } catch { /* ignore */ }
-
-    // Force kill after 5 seconds
-    setTimeout(() => {
-      try { proc.kill('SIGKILL'); } catch { /* already dead */ }
-    }, 5000).unref();
+    void disconnectPromise.then(
+      () => {
+        if (generation.disconnectPromise === disconnectPromise) {
+          generation.rejectDisconnect = null;
+        }
+      },
+      () => {
+        if (generation.disconnectPromise !== disconnectPromise) {
+          return;
+        }
+        if (generation.forceKillTimer) {
+          clearTimeout(generation.forceKillTimer);
+          generation.forceKillTimer = null;
+        }
+        generation.disconnectPromise = null;
+        generation.rejectDisconnect = null;
+        generation.sigtermAttempted = false;
+        generation.sigkillAttempted = false;
+        generation.sigtermError = null;
+      },
+    );
+
+    if (this.hasExited(generation)) {
+      this.destroyOwnedStdioEndpoint(generation, 'stdin');
+      this.destroyOwnedStdioEndpoint(generation, 'stdout');
+      this.destroyOwnedStdioEndpoint(generation, 'stderr');
+      return disconnectPromise;
+    }
+
+    generation.sigtermAttempted = true;
+    generation.sigtermError = this.sendSignal(generation, 'SIGTERM');
+
+    if (generation.closed || this.hasExited(generation)) {
+      return disconnectPromise;
+    }
+
+    if (gracePeriodMs === 0) {
+      this.forceKill(generation);
+    } else {
+      this.scheduleForceKill(generation, gracePeriodMs);
+    }
+
+    return disconnectPromise;
+  }
+
+  private scheduleForceKill(
+    generation: IStdioTransportGeneration,
+    remainingMs: number,
+  ): void {
+    if (generation.closed || this.hasExited(generation)) {
+      return;
+    }
+
+    const delayMs = Math.min(remainingMs, MAX_TIMER_DELAY_MS);
+    const scheduledAt = Date.now();
+    try {
+      generation.forceKillTimer = setTimeout(() => {
+        generation.forceKillTimer = null;
+        if (generation.closed || this.hasExited(generation)) {
+          return;
+        }
+
+        const elapsedMs = Math.max(1, Date.now() - scheduledAt);
+        const nextRemainingMs = remainingMs - elapsedMs;
+        if (nextRemainingMs > 0) {
+          this.scheduleForceKill(generation, nextRemainingMs);
+        } else {
+          this.forceKill(generation);
+        }
+      }, delayMs);
+    } catch (error: unknown) {
+      generation.rejectDisconnect?.(
+        this.toError(error, 'Unable to schedule SIGKILL escalation'),
+      );
+    }
+  }
+
+  private forceKill(generation: IStdioTransportGeneration): void {
+    if (
+      generation.closed
+      || generation.sigkillAttempted
+      || this.hasExited(generation)
+    ) {
+      return;
+    }
+
+    generation.sigkillAttempted = true;
+    const sigkillError = this.sendSignal(generation, 'SIGKILL');
+    if (sigkillError && !generation.closed && !this.hasExited(generation)) {
+      const sigtermDetail = generation.sigtermError
+        ? ' SIGTERM also failed: ' + generation.sigtermError.message + '.'
+        : '';
+      generation.rejectDisconnect?.(
+        new Error(sigkillError.message + '.' + sigtermDetail),
+      );
+    }
+  }
+
+  private sendSignal(
+    generation: IStdioTransportGeneration,
+    signal: NodeJS.Signals,
+  ): Error | null {
+    try {
+      const delivered = generation.childProcess.kill(signal);
+      if (delivered || generation.closed || this.hasExited(generation)) {
+        return null;
+      }
+      return new Error('Failed to send ' + signal + ' to child process');
+    } catch (error: unknown) {
+      if (generation.closed || this.hasExited(generation)) {
+        return null;
+      }
+      return this.toError(error, 'Failed to send ' + signal + ' to child process');
+    }
+  }
+
+  private hasExited(generation: IStdioTransportGeneration): boolean {
+    return (
+      generation.exited
+      || generation.childProcess.exitCode !== null
+      || generation.childProcess.signalCode !== null
+    );
+  }
+
+  private destroyOwnedStdioEndpoint(
+    generation: IStdioTransportGeneration,
+    endpointName: 'stdin' | 'stdout' | 'stderr',
+  ): void {
+    const endpoint = generation.childProcess[endpointName];
+    if (!endpoint || endpoint.destroyed) {
+      return;
+    }
+
+    try {
+      endpoint.destroy();
+    } catch (error: unknown) {
+      const endpointError = this.toError(
+        error,
+        'Failed to close inherited child ' + endpointName,
+      );
+      generation.rejectDisconnect?.(endpointError);
+      this.options.logger.log('error', endpointError.message);
+      if (this.listenerCount('error') > 0) {
+        this.emit('error', endpointError);
+      }
+    }
+  }
+
+  private toError(error: unknown, prefix: string): Error {
+    return new Error(prefix + ': ' + this.getErrorMessage(error));
+  }
+
+  private getErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
   }
 }

package/ts/interfaces/config.ts

@@ -15,6 +15,15 @@ export interface IRustBridgeRequestOptions {
   timeoutMs?: number;
 }
 
+/** Options for confirmed bridge termination. */
+export interface IRustBridgeTerminateOptions {
+  /**
+   * Time to allow an owned stdio child to exit after SIGTERM before SIGKILL.
+   * Zero requests immediate SIGKILL. Defaults to 5000 milliseconds.
+   */
+  gracePeriodMs?: number;
+}
+
 /**
  * Options for locating a Rust binary.
  */

package/ts/interfaces/transport.ts

@@ -1,5 +1,11 @@
 import type * as plugins from '../plugins.js';
 
+/** Options for confirmed transport disconnection. */
+export interface IRustTransportDisconnectOptions {
+  /** Grace period before escalating process termination, in milliseconds. */
+  gracePeriodMs?: number;
+}
+
 /**
  * Abstract transport for communicating with a Rust process.
  * Both stdio and socket transports implement this interface.
@@ -21,6 +27,12 @@ export interface IRustTransport extends plugins.events.EventEmitter {
   /** Disconnect the transport. For stdio: kills the process. For socket: closes the connection. */
   disconnect(): void;
 
+  /** Disconnect and resolve only after the local transport has confirmed closure. */
+  disconnectAndWait?(options?: IRustTransportDisconnectOptions): Promise<void>;
+
   /** Whether the transport is currently connected and writable. */
   readonly connected: boolean;
+
+  /** Whether the transport is preserving its lifecycle for an automatic reconnect. */
+  readonly reconnecting?: boolean;
 }