@push.rocks/smartrust 1.5.0 → 1.6.1

package/ts/classes.rustbridge.ts

@@ -7,6 +7,7 @@ import { SocketTransport } from './classes.sockettransport.js';
 import type {
   IRustBridgeOptions,
   IRustBridgeRequestOptions,
+  IRustBridgeTerminateOptions,
   IRustBridgeLogger,
   ISocketConnectOptions,
   TCommandMap,
@@ -16,6 +17,7 @@ import type {
   TStreamingCommandKeys,
   TExtractChunk,
   IRustTransport,
+  IRustTransportDisconnectOptions,
 } from './interfaces/index.js';
 
 const defaultLogger: IRustBridgeLogger = {
@@ -36,6 +38,12 @@ type TPendingRequestSettlement =
   | { outcome: 'resolve'; value: any }
   | { outcome: 'reject'; error: Error };
 
+type TRustBridgeLifecycleState = 'idle' | 'starting' | 'ready' | 'stopping';
+
+type TConfirmableRustTransport = IRustTransport & {
+  disconnectAndWait(optionsArg?: IRustTransportDisconnectOptions): Promise<void>;
+};
+
 /**
  * Generic bridge between TypeScript and a Rust binary.
  * Communicates via JSON-over-stdin/stdout IPC protocol (stdio mode)
@@ -47,11 +55,15 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   private locator: RustBinaryLocator;
   private options: Required<Pick<IRustBridgeOptions, 'cliArgs' | 'requestTimeoutMs' | 'readyTimeoutMs' | 'readyEventName' | 'maxPayloadSize'>> & IRustBridgeOptions;
   private logger: IRustBridgeLogger;
-  private transport: IRustTransport | null = null;
+  private transport: TConfirmableRustTransport | null = null;
   private pendingRequests = new Map<string, IPendingRequest>();
   private requestCounter = 0;
   private isRunning = false;
   private binaryPath: string | null = null;
+  private lifecycleState: TRustBridgeLifecycleState = 'idle';
+  private lifecycleGeneration = 0;
+  private activationPromise: Promise<boolean> | null = null;
+  private terminationPromise: Promise<void> | null = null;
 
   constructor(options: IRustBridgeOptions) {
     super();
@@ -71,21 +83,25 @@ 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.
    */
-  public async spawn(): Promise<boolean> {
-    this.binaryPath = await this.locator.findBinary();
-    if (!this.binaryPath) {
-      return false;
-    }
+  public spawn(): Promise<boolean> {
+    return this.activate(async (generationArg) => {
+      const binaryPath = await this.locator.findBinary();
+      if (!this.isStartingGeneration(generationArg)) {
+        return null;
+      }
+      this.binaryPath = binaryPath;
+      if (!binaryPath) {
+        return null;
+      }
 
-    const transport = new StdioTransport({
-      binaryPath: this.binaryPath,
-      cliArgs: this.options.cliArgs,
-      env: this.options.env,
-      maxPayloadSize: this.options.maxPayloadSize,
-      logger: this.logger,
+      return new StdioTransport({
+        binaryPath,
+        cliArgs: this.options.cliArgs,
+        env: this.options.env,
+        maxPayloadSize: this.options.maxPayloadSize,
+        logger: this.logger,
+      });
     });
-
-    return this.connectWithTransport(transport);
   }
 
   /**
@@ -95,8 +111,8 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
    * @param socketPath - Path to Unix socket or Windows named pipe
    * @param socketOptions - Optional socket connection options (reconnect, etc.)
    */
-  public async connect(socketPath: string, socketOptions?: ISocketConnectOptions): Promise<boolean> {
-    const transport = new SocketTransport({
+  public connect(socketPath: string, socketOptions?: ISocketConnectOptions): Promise<boolean> {
+    return this.activate(async () => new SocketTransport({
       socketPath,
       maxPayloadSize: this.options.maxPayloadSize,
       logger: this.logger,
@@ -104,68 +120,252 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       reconnectBaseDelayMs: socketOptions?.reconnectBaseDelayMs,
       reconnectMaxDelayMs: socketOptions?.reconnectMaxDelayMs,
       maxReconnectAttempts: socketOptions?.maxReconnectAttempts,
-    });
+    }));
+  }
 
-    return this.connectWithTransport(transport);
+  /** Reserve activation synchronously, or sequence it after confirmed termination. */
+  private activate(
+    createTransportArg: (generationArg: number) => Promise<TConfirmableRustTransport | null>,
+  ): Promise<boolean> {
+    if (this.lifecycleState === 'stopping' && this.terminationPromise) {
+      return this.terminationPromise.then(() => this.beginActivation(createTransportArg));
+    }
+    if (this.lifecycleState !== 'idle') {
+      return Promise.reject(
+        new Error(`RustBridge cannot activate while lifecycle state is '${this.lifecycleState}'`),
+      );
+    }
+    return this.beginActivation(createTransportArg);
   }
 
-  /**
-   * Internal: wire up any transport and wait for the ready handshake.
-   */
-  private connectWithTransport(transport: IRustTransport): Promise<boolean> {
-    return new Promise<boolean>((resolve) => {
+  /** Start one transport generation. A second concurrent activation is rejected. */
+  private beginActivation(
+    createTransportArg: (generationArg: number) => Promise<TConfirmableRustTransport | null>,
+  ): Promise<boolean> {
+    if (this.lifecycleState !== 'idle') {
+      throw new Error(`RustBridge cannot activate while lifecycle state is '${this.lifecycleState}'`);
+    }
+
+    const generation = ++this.lifecycleGeneration;
+    this.lifecycleState = 'starting';
+
+    const activationPromise = (async (): Promise<boolean> => {
       try {
+        const transport = await createTransportArg(generation);
+        if (!transport || !this.isStartingGeneration(generation)) {
+          if (this.isStartingGeneration(generation)) {
+            this.lifecycleState = 'idle';
+          }
+          return false;
+        }
+
         this.transport = transport;
+        return await this.connectWithTransport(transport, generation);
+      } catch (error: unknown) {
+        this.logger.log('error', `Failed to connect: ${this.getErrorMessage(error)}`);
+        if (this.isStartingGeneration(generation)) {
+          this.lifecycleState = 'idle';
+        }
+        return false;
+      }
+    })();
 
-        // Wire transport events
-        transport.on('line', (line: string) => this.handleLine(line));
+    this.activationPromise = activationPromise;
+    void activationPromise.then(
+      () => {
+        if (this.activationPromise === activationPromise) {
+          this.activationPromise = null;
+        }
+      },
+      () => {
+        if (this.activationPromise === activationPromise) {
+          this.activationPromise = null;
+        }
+      },
+    );
+    return activationPromise;
+  }
+
+  /** Wire one transport generation and wait for its ready handshake. */
+  private connectWithTransport(
+    transportArg: TConfirmableRustTransport,
+    generationArg?: number,
+  ): Promise<boolean> {
+    const generation = generationArg ?? ++this.lifecycleGeneration;
+    if (generationArg === undefined) {
+      if (this.lifecycleState !== 'idle') {
+        throw new Error(`RustBridge cannot activate while lifecycle state is '${this.lifecycleState}'`);
+      }
+      this.lifecycleState = 'starting';
+      this.transport = transportArg;
+    }
+
+    return new Promise<boolean>((resolve) => {
+      let settled = false;
+      let readyTimeout: ReturnType<typeof setTimeout> | null = null;
+      let reconnectReadyTimeout: ReturnType<typeof setTimeout> | null = null;
+
+      const isCurrent = (): boolean => this.isCurrentTransport(transportArg, generation);
+      const settle = (valueArg: boolean): void => {
+        if (readyTimeout) {
+          clearTimeout(readyTimeout);
+          readyTimeout = null;
+        }
+        if (reconnectReadyTimeout) {
+          clearTimeout(reconnectReadyTimeout);
+          reconnectReadyTimeout = null;
+        }
+        if (settled) {
+          return;
+        }
+        settled = true;
+        resolve(valueArg);
+      };
 
-        transport.on('stderr', (line: string) => {
-          this.logger.log('debug', `[${this.options.binaryName}] ${line}`);
-          this.emit('stderr', line);
+      const requestConfirmedCleanup = (): void => {
+        let termination: Promise<void>;
+        try {
+          termination = this.terminate();
+        } catch (error: unknown) {
+          this.logger.log('error', `Transport cleanup failed: ${this.getErrorMessage(error)}`);
+          settle(false);
+          return;
+        }
+        void termination.then(
+          () => settle(false),
+          (error: unknown) => {
+            this.logger.log('error', `Transport cleanup failed: ${this.getErrorMessage(error)}`);
+            settle(false);
+          },
+        );
+      };
+
+      transportArg.on('line', (line: string) => {
+        if (!isCurrent()) {
+          return;
+        }
+        this.handleLine(line, () => {
+          if (!isCurrent() || this.lifecycleState !== 'starting') {
+            return;
+          }
+          if (reconnectReadyTimeout) {
+            clearTimeout(reconnectReadyTimeout);
+            reconnectReadyTimeout = null;
+          }
+          this.lifecycleState = 'ready';
+          this.isRunning = true;
+          this.logger.log('info', `Bridge connected to ${this.options.binaryName}`);
+          this.emit('ready');
+          settle(true);
         });
+      });
+
+      transportArg.on('stderr', (line: string) => {
+        if (!isCurrent()) {
+          return;
+        }
+        this.logger.log('debug', `[${this.options.binaryName}] ${line}`);
+        this.emit('stderr', line);
+      });
+
+      transportArg.on('close', (...args: any[]) => {
+        if (!isCurrent()) {
+          return;
+        }
+        const intentional = this.lifecycleState === 'stopping';
+        this.logger.log('info', 'Transport closed');
+        this.isRunning = false;
+        this.rejectAllPendingRequests(`${this.options.binaryName} process exited`);
+        if (!intentional && transportArg.reconnecting === true) {
+          if (reconnectReadyTimeout) {
+            clearTimeout(reconnectReadyTimeout);
+            reconnectReadyTimeout = null;
+          }
+          this.lifecycleState = 'starting';
+          return;
+        }
 
-        transport.on('close', (...args: any[]) => {
-          this.logger.log('info', `Transport closed`);
-          this.cleanup(`${this.options.binaryName} process exited`);
+        this.transport = null;
+        if (!intentional) {
+          this.lifecycleState = 'idle';
           this.emit('exit', ...args);
-        });
+        }
+        settle(false);
+      });
 
-        transport.on('error', (err: Error) => {
-          this.logger.log('error', `Transport error: ${err.message}`);
-          this.cleanup(`${this.options.binaryName} process exited`, err);
-          resolve(false);
-        });
+      transportArg.on('error', (errorArg: Error) => {
+        if (!isCurrent()) {
+          return;
+        }
+        this.logger.log('error', `Transport error: ${errorArg.message}`);
+        this.isRunning = false;
+        this.rejectAllPendingRequests(`${this.options.binaryName} process exited`, errorArg);
+      });
 
-        transport.on('reconnected', () => {
-          this.logger.log('info', 'Transport reconnected, waiting for ready event');
-          this.emit('reconnected');
-        });
+      transportArg.on('reconnected', () => {
+        if (!isCurrent()) {
+          return;
+        }
+        this.logger.log('info', 'Transport reconnected, waiting for ready event');
+        this.lifecycleState = 'starting';
+        if (reconnectReadyTimeout) {
+          clearTimeout(reconnectReadyTimeout);
+        }
+        reconnectReadyTimeout = setTimeout(() => {
+          if (!isCurrent() || this.lifecycleState !== 'starting') {
+            return;
+          }
+          this.logger.log(
+            'error',
+            `Reconnected process did not send ready event within ${this.options.readyTimeoutMs}ms`,
+          );
+          requestConfirmedCleanup();
+        }, this.options.readyTimeoutMs);
+        this.emit('reconnected');
+      });
 
-        // Connect the transport
-        transport.connect().then(() => {
-          // Wait for the ready event from the protocol layer
-          const readyTimeout = setTimeout(() => {
-            this.logger.log('error', `Process did not send ready event within ${this.options.readyTimeoutMs}ms`);
-            this.kill();
-            resolve(false);
-          }, this.options.readyTimeoutMs);
-
-          this.once(`management:${this.options.readyEventName}`, () => {
-            clearTimeout(readyTimeout);
-            this.isRunning = true;
-            this.logger.log('info', `Bridge connected to ${this.options.binaryName}`);
-            this.emit('ready');
-            resolve(true);
-          });
-        }).catch((err: Error) => {
-          this.logger.log('error', `Transport connect failed: ${err.message}`);
-          resolve(false);
-        });
-      } catch (err: any) {
-        this.logger.log('error', `Failed to connect: ${err.message}`);
-        resolve(false);
+      transportArg.on('reconnect_failed', () => {
+        if (!isCurrent()) {
+          return;
+        }
+        if (reconnectReadyTimeout) {
+          clearTimeout(reconnectReadyTimeout);
+          reconnectReadyTimeout = null;
+        }
+        this.isRunning = false;
+        this.transport = null;
+        this.lifecycleState = 'idle';
+        this.rejectAllPendingRequests(`${this.options.binaryName} reconnect failed`);
+        this.emit('exit');
+        settle(false);
+      });
+
+      readyTimeout = setTimeout(() => {
+        if (!isCurrent() || this.lifecycleState !== 'starting') {
+          return;
+        }
+        this.logger.log(
+          'error',
+          `Process did not send ready event within ${this.options.readyTimeoutMs}ms`,
+        );
+        requestConfirmedCleanup();
+      }, this.options.readyTimeoutMs);
+
+      let connectionPromise: Promise<void>;
+      try {
+        connectionPromise = transportArg.connect();
+      } catch (error: unknown) {
+        this.logger.log('error', `Transport connect failed: ${this.getErrorMessage(error)}`);
+        requestConfirmedCleanup();
+        return;
       }
+      void connectionPromise.catch((error: unknown) => {
+        if (!isCurrent()) {
+          return;
+        }
+        this.logger.log('error', `Transport connect failed: ${this.getErrorMessage(error)}`);
+        requestConfirmedCleanup();
+      });
     });
   }
 
@@ -349,22 +549,94 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   }
 
   /**
-   * Kill the connection and clean up all resources.
-   * For stdio: kills the child process (SIGTERM, then SIGKILL).
-   * For socket: closes the socket connection (does NOT kill the daemon).
+   * Terminate the active transport and wait for confirmed closure.
+   * For stdio this confirms child exit after SIGTERM/SIGKILL escalation.
+   * For socket mode this confirms local socket closure and never kills the daemon.
    */
-  public kill(): void {
-    if (this.transport) {
-      const transport = this.transport;
+  public terminate(optionsArg: IRustBridgeTerminateOptions = {}): Promise<void> {
+    if (
+      optionsArg.gracePeriodMs !== undefined
+      && (!Number.isSafeInteger(optionsArg.gracePeriodMs) || optionsArg.gracePeriodMs < 0)
+    ) {
+      throw new RangeError('RustBridge terminate gracePeriodMs must be a non-negative safe integer');
+    }
+
+    if (this.terminationPromise) {
+      return this.terminationPromise;
+    }
+
+    if (
+      this.lifecycleState === 'idle'
+      && !this.transport
+      && !this.activationPromise
+    ) {
+      return Promise.resolve();
+    }
+
+    const generation = this.lifecycleGeneration;
+    const transport = this.transport;
+    const activationPromise = this.activationPromise;
+
+    this.lifecycleState = 'stopping';
+    this.isRunning = false;
+    this.rejectAllPendingRequests(`${this.options.binaryName} process killed`);
+
+    const terminationPromise = (async (): Promise<void> => {
+      if (transport) {
+        await transport.disconnectAndWait({ gracePeriodMs: optionsArg.gracePeriodMs });
+      } else if (activationPromise) {
+        // No transport exists yet (for example, binary lookup is pending). The
+        // stopping state prevents that activation from publishing a transport.
+        await activationPromise;
+      }
+
+      if (this.lifecycleGeneration !== generation) {
+        throw new Error('RustBridge lifecycle generation changed during termination');
+      }
+
+      const lateTransport = this.transport;
+      if (lateTransport && lateTransport !== transport) {
+        await lateTransport.disconnectAndWait({ gracePeriodMs: optionsArg.gracePeriodMs });
+      }
+
       this.transport = null;
       this.isRunning = false;
+      this.lifecycleState = 'idle';
+    })();
+
+    this.terminationPromise = terminationPromise;
+    void terminationPromise.then(
+      () => {
+        if (this.terminationPromise === terminationPromise) {
+          this.terminationPromise = null;
+        }
+      },
+      () => {
+        if (this.terminationPromise === terminationPromise) {
+          // Retain transport ownership and the stopping state, but allow a
+          // later termination attempt after the caller has addressed the
+          // transient cleanup failure.
+          this.terminationPromise = null;
+        }
+      },
+    );
+    return terminationPromise;
+  }
 
-      // Reject pending requests
-      this.rejectAllPendingRequests(`${this.options.binaryName} process killed`);
-
-      transport.removeAllListeners();
-      transport.disconnect();
+  /**
+   * Fire-and-forget compatibility wrapper around confirmed termination.
+   */
+  public kill(): void {
+    let termination: Promise<void>;
+    try {
+      termination = this.terminate();
+    } catch (error: unknown) {
+      this.logger.log('error', `Bridge termination failed: ${this.getErrorMessage(error)}`);
+      return;
     }
+    void termination.catch((error: unknown) => {
+      this.logger.log('error', `Bridge termination failed: ${this.getErrorMessage(error)}`);
+    });
   }
 
   /**
@@ -374,7 +646,24 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     return this.isRunning;
   }
 
-  private handleLine(line: string): void {
+  private isStartingGeneration(generationArg: number): boolean {
+    return (
+      this.lifecycleGeneration === generationArg
+      && this.lifecycleState === 'starting'
+    );
+  }
+
+  private isCurrentTransport(
+    transportArg: TConfirmableRustTransport,
+    generationArg: number,
+  ): boolean {
+    return (
+      this.lifecycleGeneration === generationArg
+      && this.transport === transportArg
+    );
+  }
+
+  private handleLine(line: string, onReadyArg: () => void): void {
     if (!line) return;
 
     let parsed: any;
@@ -388,6 +677,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     // Check if it's an event (has 'event' field, no 'id')
     if ('event' in parsed && !('id' in parsed)) {
       const event = parsed as IManagementEvent;
+      if (event.event === this.options.readyEventName) {
+        onReadyArg();
+      }
       this.emit(`management:${event.event}`, event.data);
       return;
     }
@@ -488,13 +780,6 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     }
   }
 
-  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);
   }