@git.zone/tsrust 1.9.1 → 1.10.1

package/ts/mod_matrix/classes.matrixcommandrunner.ts

@@ -0,0 +1,294 @@
+import * as childProcess from 'node:child_process';
+import * as fs from 'node:fs';
+
+export interface IMatrixCommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface IMatrixCommandOptions {
+  cwd?: string;
+  capture?: boolean;
+  timeoutMs?: number;
+  heartbeatStdin?: boolean;
+  input?: string | Buffer;
+  inputFile?: string;
+  outputFile?: string;
+  maximumOutputBytes?: number;
+  allowedExitCodes?: number[];
+  environment?: NodeJS.ProcessEnv;
+}
+
+export interface IMatrixCommandRunner {
+  execute(
+    commandArg: string,
+    argsArg: string[],
+    optionsArg?: IMatrixCommandOptions,
+  ): Promise<IMatrixCommandResult>;
+}
+
+const defaultCommandTimeoutMs = 60 * 60 * 1000;
+const forceKillDelayMs = 10 * 1000;
+const maximumCapturedOutputBytes = 16 * 1024 * 1024;
+type TForwardedSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';
+
+export class MatrixCommandRunner implements IMatrixCommandRunner {
+  constructor(private environment: NodeJS.ProcessEnv = process.env) {}
+
+  public async execute(
+    commandArg: string,
+    argsArg: string[],
+    optionsArg: IMatrixCommandOptions = {},
+  ): Promise<IMatrixCommandResult> {
+    if (
+      [optionsArg.heartbeatStdin === true, optionsArg.input !== undefined, !!optionsArg.inputFile]
+        .filter(Boolean)
+        .length > 1
+    ) {
+      throw new Error('A matrix command can use only one stdin source');
+    }
+    if (optionsArg.capture && optionsArg.outputFile) {
+      throw new Error('A matrix command cannot capture stdout and write it to a file');
+    }
+    if (
+      optionsArg.outputFile &&
+      (!Number.isSafeInteger(optionsArg.maximumOutputBytes) ||
+        (optionsArg.maximumOutputBytes || 0) <= 0)
+    ) {
+      throw new Error('A matrix output file requires a positive byte limit');
+    }
+    const capture = optionsArg.capture === true;
+    let inputFileDescriptor: number | undefined;
+    let outputFileDescriptor: number | undefined;
+    let child: childProcess.ChildProcess;
+    try {
+      if (optionsArg.inputFile) {
+        inputFileDescriptor = fs.openSync(
+          optionsArg.inputFile,
+          fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+        );
+      }
+      if (optionsArg.outputFile) {
+        outputFileDescriptor = fs.openSync(
+          optionsArg.outputFile,
+          fs.constants.O_WRONLY |
+            fs.constants.O_CREAT |
+            fs.constants.O_EXCL |
+            fs.constants.O_NOFOLLOW,
+          0o600,
+        );
+      }
+      const stdinMode =
+        inputFileDescriptor ??
+        (optionsArg.heartbeatStdin || optionsArg.input !== undefined ? 'pipe' : 'ignore');
+      const stdoutMode = optionsArg.outputFile ? 'pipe' : capture ? 'pipe' : 'inherit';
+      child = childProcess.spawn(commandArg, argsArg, {
+        cwd: optionsArg.cwd || process.cwd(),
+        env: optionsArg.environment || this.environment,
+        stdio: [stdinMode, stdoutMode, capture ? 'pipe' : 'inherit'],
+        detached: true,
+      });
+    } catch (error) {
+      if (inputFileDescriptor !== undefined) fs.closeSync(inputFileDescriptor);
+      if (outputFileDescriptor !== undefined) fs.closeSync(outputFileDescriptor);
+      throw error;
+    }
+    if (inputFileDescriptor !== undefined) fs.closeSync(inputFileDescriptor);
+
+    let stdout = '';
+    let stderr = '';
+    let capturedOutputBytes = 0;
+    let timedOut = false;
+    let outputLimitExceeded = false;
+    let outputFileBytes = 0;
+    let outputFileError: Error | undefined;
+    let forwardedSignal: TForwardedSignal | undefined;
+    let forwardedSignalCount = 0;
+    let spawnError: Error | undefined;
+    let stdinError: Error | undefined;
+    let forceKillTimer: NodeJS.Timeout | undefined;
+    let heartbeatTimer: NodeJS.Timeout | undefined;
+
+    const killProcessGroup = (signalArg: NodeJS.Signals): void => {
+      if (!child.pid) return;
+      try {
+        process.kill(-child.pid, signalArg);
+      } catch {
+        try {
+          child.kill(signalArg);
+        } catch {
+          // The process may already have exited.
+        }
+      }
+    };
+    const terminateProcessGroup = (signalArg: NodeJS.Signals): void => {
+      killProcessGroup(signalArg);
+      if (!forceKillTimer) {
+        forceKillTimer = setTimeout(() => killProcessGroup('SIGKILL'), forceKillDelayMs);
+      }
+    };
+    const processGroupExists = (): boolean => {
+      if (!child.pid) return false;
+      try {
+        process.kill(-child.pid, 0);
+        return true;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false;
+        throw error;
+      }
+    };
+    const waitForProcessGroupExit = async (timeoutMsArg: number): Promise<boolean> => {
+      const deadline = Date.now() + timeoutMsArg;
+      while (processGroupExists() && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+      return !processGroupExists();
+    };
+    const ensureProcessGroupStopped = async (): Promise<void> => {
+      if (!processGroupExists()) return;
+      terminateProcessGroup('SIGTERM');
+      if (!(await waitForProcessGroupExit(forceKillDelayMs + 1000))) {
+        killProcessGroup('SIGKILL');
+        if (!(await waitForProcessGroupExit(2000))) {
+          throw new Error(`${commandArg} left a live descendant process group`);
+        }
+      }
+    };
+
+    const signalHandlers = new Map<TForwardedSignal, () => void>();
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'] as TForwardedSignal[]) {
+      const handler = (): void => {
+        forwardedSignal = signal;
+        forwardedSignalCount += 1;
+        if (forwardedSignalCount === 1) terminateProcessGroup(signal);
+        else killProcessGroup('SIGKILL');
+      };
+      signalHandlers.set(signal, handler);
+      process.on(signal, handler);
+    }
+
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      terminateProcessGroup('SIGTERM');
+    }, optionsArg.timeoutMs || defaultCommandTimeoutMs);
+
+    if (optionsArg.heartbeatStdin) {
+      child.stdin?.on('error', () => {
+        // Process close handles a lost heartbeat channel.
+      });
+      const sendHeartbeat = (): void => {
+        if (!child.stdin?.destroyed) child.stdin?.write('heartbeat\n');
+      };
+      sendHeartbeat();
+      heartbeatTimer = setInterval(sendHeartbeat, 1000);
+    } else if (optionsArg.input !== undefined) {
+      child.stdin?.on('error', (errorArg) => {
+        stdinError = errorArg;
+        terminateProcessGroup('SIGTERM');
+      });
+      child.stdin?.end(optionsArg.input);
+    }
+
+    const captureChunk = (targetArg: 'stdout' | 'stderr', chunkArg: Buffer): void => {
+      capturedOutputBytes += chunkArg.length;
+      if (capturedOutputBytes > maximumCapturedOutputBytes) {
+        outputLimitExceeded = true;
+        terminateProcessGroup('SIGTERM');
+        return;
+      }
+      if (targetArg === 'stdout') stdout += chunkArg.toString('utf8');
+      else stderr += chunkArg.toString('utf8');
+    };
+    if (optionsArg.outputFile) {
+      child.stdout?.on('data', (chunkArg: Buffer) => {
+        if (outputLimitExceeded || outputFileError || outputFileDescriptor === undefined) return;
+        if (outputFileBytes + chunkArg.length > (optionsArg.maximumOutputBytes || 0)) {
+          outputLimitExceeded = true;
+          terminateProcessGroup('SIGTERM');
+          return;
+        }
+        try {
+          let offset = 0;
+          while (offset < chunkArg.length) {
+            offset += fs.writeSync(
+              outputFileDescriptor,
+              chunkArg,
+              offset,
+              chunkArg.length - offset,
+            );
+          }
+          outputFileBytes += chunkArg.length;
+        } catch (error) {
+          outputFileError = error as Error;
+          terminateProcessGroup('SIGTERM');
+        }
+      });
+    } else {
+      child.stdout?.on('data', (chunkArg: Buffer) => captureChunk('stdout', chunkArg));
+    }
+    child.stderr?.on('data', (chunkArg: Buffer) => captureChunk('stderr', chunkArg));
+    child.once('error', (errorArg) => {
+      spawnError = errorArg;
+    });
+
+    return new Promise<IMatrixCommandResult>((resolve, reject) => {
+      child.once('close', (codeArg, signalArg) => {
+        void (async () => {
+          try {
+            if (outputFileDescriptor !== undefined) {
+              try {
+                fs.fsyncSync(outputFileDescriptor);
+                fs.closeSync(outputFileDescriptor);
+                outputFileDescriptor = undefined;
+              } catch (error) {
+                outputFileError = error as Error;
+              }
+            }
+            await ensureProcessGroupStopped();
+            const exitCode = codeArg ?? -1;
+            if (timedOut) {
+              throw new Error(`${commandArg} exceeded its command timeout`);
+            }
+            if (outputLimitExceeded) {
+              throw new Error(`${commandArg} exceeded the captured output limit`);
+            }
+            if (forwardedSignal) {
+              throw new Error(`${commandArg} was interrupted by ${forwardedSignal}`);
+            }
+            if (spawnError) throw spawnError;
+            if (stdinError) throw stdinError;
+            if (outputFileError) throw outputFileError;
+            if (!(optionsArg.allowedExitCodes || [0]).includes(exitCode)) {
+              if (capture && stdout) process.stdout.write(stdout);
+              if (capture && stderr) process.stderr.write(stderr);
+              throw new Error(
+                `${commandArg} exited with ${
+                  signalArg ? `signal ${signalArg}` : `status ${exitCode}`
+                }`,
+              );
+            }
+            resolve({ stdout, stderr, exitCode });
+          } catch (error) {
+            reject(error);
+          } finally {
+            clearTimeout(timeout);
+            if (forceKillTimer) clearTimeout(forceKillTimer);
+            if (heartbeatTimer) clearInterval(heartbeatTimer);
+            child.stdin?.end();
+            if (outputFileDescriptor !== undefined) {
+              try {
+                fs.closeSync(outputFileDescriptor);
+              } catch {
+                // Preserve the command's primary error.
+              }
+            }
+            for (const [signal, handler] of signalHandlers) {
+              process.off(signal, handler);
+            }
+          }
+        })();
+      });
+    });
+  }
+}