@effectionx/process 0.6.1 → 0.7.0

package/src/exec/win32.ts

@@ -0,0 +1,217 @@
+import { platform } from "node:os";
+import { once } from "@effectionx/node/events";
+import { fromReadable } from "@effectionx/node/stream";
+// @ts-types="npm:@types/cross-spawn@6.0.6"
+import { spawn as spawnProcess } from "cross-spawn";
+import { ctrlc } from "ctrlc-windows";
+import {
+  Err,
+  Ok,
+  type Result,
+  all,
+  createSignal,
+  resource,
+  spawn,
+  withResolvers,
+} from "effection";
+import type { CreateOSProcess, ExitStatus, Writable } from "./api.ts";
+import { ExecError } from "./error.ts";
+
+type ProcessResultValue = [number?, string?];
+
+function* killTree(pid: number) {
+  try {
+    const killer = spawnProcess(
+      "cmd.exe",
+      ["/c", "taskkill", "/PID", String(pid), "/T", "/F"],
+      { windowsHide: true, stdio: "ignore" },
+    );
+    yield* once(killer, "close");
+  } catch (_) {
+    // best-effort; ignore errors
+  }
+}
+
+export const createWin32Process: CreateOSProcess = (command, options) => {
+  return resource(function* (provide) {
+    let processResult = withResolvers<Result<ProcessResultValue>>();
+
+    // Windows-specific process spawning with different options than POSIX
+    let childProcess = spawnProcess(command, options.arguments || [], {
+      // We lose exit information and events if this is detached in windows
+      // and it opens a window in windows+powershell.
+      detached: false,
+      // The `shell` option is passed to `cross-spawn` to control whether a shell is used.
+      // On Windows, `shell: true` is necessary to run command strings, as it uses
+      // `cmd.exe` to parse the command and find executables in the PATH.
+      // Using a boolean `true` was previously disabled, causing ENOENT errors for
+      // commands that were not a direct path to an executable.
+      shell: options.shell || false,
+      // With stdio as pipe, windows gets stuck where neither the child nor the
+      // parent wants to close the stream, so we call it ourselves in the exit event.
+      stdio: "pipe",
+      // Hide the child window so that killing it will not block the parent
+      // with a Terminate Batch Process (Y/n)
+      windowsHide: true,
+      env: options.env,
+      cwd: options.cwd,
+    });
+
+    let { pid } = childProcess;
+
+    if (!childProcess.stdout || !childProcess.stderr) {
+      throw new Error("stdout and stderr must be available with stdio: pipe");
+    }
+
+    let io = {
+      stdout: yield* fromReadable(childProcess.stdout),
+      stderr: yield* fromReadable(childProcess.stderr),
+      stdoutDone: withResolvers<void>(),
+      stderrDone: withResolvers<void>(),
+    };
+
+    const stdout = createSignal<Uint8Array, void>();
+    const stderr = createSignal<Uint8Array, void>();
+
+    yield* spawn(function* () {
+      let next = yield* io.stdout.next();
+      while (!next.done) {
+        stdout.send(next.value);
+        next = yield* io.stdout.next();
+      }
+      stdout.close();
+      io.stdoutDone.resolve();
+    });
+
+    yield* spawn(function* () {
+      let next = yield* io.stderr.next();
+      while (!next.done) {
+        stderr.send(next.value);
+        next = yield* io.stderr.next();
+      }
+      stderr.close();
+      io.stderrDone.resolve();
+    });
+
+    let stdin: Writable<string> = {
+      send(data: string) {
+        childProcess.stdin.write(data);
+      },
+    };
+
+    yield* spawn(function* trapError() {
+      const [error] = yield* once<Error[]>(childProcess, "error");
+      processResult.resolve(Err(error));
+    });
+
+    yield* spawn(function* () {
+      let value = yield* once<ProcessResultValue>(childProcess, "close");
+      yield* all([io.stdoutDone.operation, io.stderrDone.operation]);
+      processResult.resolve(Ok(value));
+    });
+
+    function* join() {
+      let result = yield* processResult.operation;
+      if (result.ok) {
+        let [code, signal] = result.value;
+        return { command, options, code, signal } as ExitStatus;
+      }
+      throw result.error;
+    }
+
+    function* expect() {
+      let status = yield* join();
+      if (status.code !== 0) {
+        throw new ExecError(status, command, options);
+      }
+      return status;
+    }
+
+    // Suppress EPIPE errors on stdin - these occur on Windows when the child
+    // process exits before we finish writing to it. This is expected during
+    // cleanup when we're killing the process.
+    childProcess.stdin.on("error", (err: Error & { code?: string }) => {
+      if (err.code !== "EPIPE") {
+        throw err;
+      }
+    });
+
+    try {
+      yield* provide({
+        pid: pid as number,
+        stdin,
+        stdout,
+        stderr,
+        join,
+        expect,
+      });
+    } finally {
+      try {
+        // Only try to kill the process if it hasn't exited yet
+        if (
+          childProcess.exitCode === null &&
+          childProcess.signalCode === null
+        ) {
+          if (typeof childProcess.pid === "undefined") {
+            // biome-ignore lint/correctness/noUnsafeFinally: Intentional error for missing PID
+            throw new Error("no pid for childProcess");
+          }
+
+          let stdinStream = childProcess.stdin;
+
+          // Try graceful shutdown with ctrlc
+          try {
+            ctrlc(childProcess.pid);
+            if (stdinStream.writable) {
+              try {
+                // Terminate batch process (Y/N)
+                stdinStream.write("Y\n");
+              } catch (_err) {
+                // not much we can do here
+              }
+            }
+          } catch (_err) {
+            // ctrlc might fail
+          }
+
+          // Close stdin to allow process to exit cleanly
+          try {
+            stdinStream.end();
+          } catch (_err) {
+            // stdin might already be closed
+          }
+
+          // If process still hasn't exited, escalate
+          if (
+            childProcess.exitCode === null &&
+            childProcess.signalCode === null
+          ) {
+            // Try regular kill first
+            try {
+              childProcess.kill();
+            } catch (_err) {
+              // process might already be dead
+            }
+
+            // If still alive after kill, force-kill entire process tree
+            // This is necessary for bash on Windows where ctrlc doesn't work
+            // and child.kill() only kills the shell, leaving grandchildren alive
+            if (
+              childProcess.exitCode === null &&
+              childProcess.signalCode === null
+            ) {
+              yield* killTree(childProcess.pid);
+            }
+          }
+
+          // Wait for streams to finish
+          yield* all([io.stdoutDone.operation, io.stderrDone.operation]);
+        }
+      } catch (_e) {
+        // do nothing, process is probably already dead
+      }
+    }
+  });
+};
+
+export const isWin32 = (): boolean => platform() === "win32";

package/src/exec.ts

@@ -0,0 +1,100 @@
+import shellwords from "shellwords-ts";
+
+import { type Operation, spawn } from "effection";
+import type {
+  CreateOSProcess,
+  ExecOptions,
+  ExitStatus,
+  Process,
+  ProcessResult,
+} from "./exec/api.ts";
+import { createPosixProcess } from "./exec/posix.ts";
+import { createWin32Process, isWin32 } from "./exec/win32.ts";
+
+export * from "./exec/api.ts";
+export * from "./exec/error.ts";
+
+export interface Exec extends Operation<Process> {
+  join(): Operation<ProcessResult>;
+  expect(): Operation<ProcessResult>;
+}
+
+const createProcess: CreateOSProcess = (cmd, opts) => {
+  if (isWin32()) {
+    return createWin32Process(cmd, opts);
+  }
+  return createPosixProcess(cmd, opts);
+};
+
+/**
+ * Execute `command` with `options`. You should use this operation for processes
+ * that have a finite lifetime and on which you may wish to synchronize on the
+ * exit status. If you want to start a process like a server that spins up and runs
+ * forever, consider using `daemon()`
+ */
+export function exec(command: string, options: ExecOptions = {}): Exec {
+  let [cmd, ...args] = options.shell ? [command] : shellwords.split(command);
+  let opts = { ...options, arguments: args.concat(options.arguments || []) };
+
+  return {
+    *[Symbol.iterator]() {
+      return yield* createProcess(cmd, opts);
+    },
+    *join() {
+      const process = yield* createProcess(cmd, opts);
+
+      let stdout = "";
+      let stderr = "";
+
+      yield* spawn(function* () {
+        let subscription = yield* process.stdout;
+        let next = yield* subscription.next();
+        while (!next.done) {
+          stdout += next.value;
+          next = yield* subscription.next();
+        }
+      });
+
+      yield* spawn(function* () {
+        let subscription = yield* process.stderr;
+        let next = yield* subscription.next();
+        while (!next.done) {
+          stderr += next.value;
+          next = yield* subscription.next();
+        }
+      });
+
+      let status: ExitStatus = yield* process.join();
+
+      return { ...status, stdout, stderr };
+    },
+    *expect() {
+      const process = yield* createProcess(cmd, opts);
+
+      let stdout = "";
+      let stderr = "";
+
+      yield* spawn(function* () {
+        let subscription = yield* process.stdout;
+        let next = yield* subscription.next();
+        while (!next.done) {
+          stdout += next.value;
+          next = yield* subscription.next();
+        }
+      });
+
+      yield* spawn(function* () {
+        let subscription = yield* process.stderr;
+        let next = yield* subscription.next();
+        while (!next.done) {
+          stderr += next.value;
+          next = yield* subscription.next();
+        }
+      });
+
+      let status: ExitStatus = yield* process.expect();
+
+      return { ...status, stdout, stderr };
+    },
+  };
+}

package/src/helpers.ts

@@ -0,0 +1,12 @@
+import { Err, Ok, type Operation, type Result, type Stream } from "effection";
+
+export type OutputStream = Stream<Uint8Array, void>;
+
+export function* box<T>(op: () => Operation<T>): Operation<Result<T>> {
+  try {
+    const value = yield* op();
+    return Ok(value);
+  } catch (e) {
+    return Err(e as Error);
+  }
+}

package/test/daemon.test.ts

@@ -0,0 +1,106 @@
+import process from "node:process";
+import { beforeEach, describe, it } from "@effectionx/bdd";
+import { type Task, spawn, until, withResolvers } from "effection";
+import { expect } from "expect";
+
+import { lines } from "@effectionx/stream-helpers";
+import { type Daemon, daemon } from "../mod.ts";
+import { captureError, expectMatch, fetchText } from "./helpers.ts";
+
+const SystemRoot = process.env.SystemRoot;
+
+describe("daemon", () => {
+  let task: Task<void>;
+  let proc: Daemon;
+
+  describe("controlling from outside", () => {
+    beforeEach(function* () {
+      const result = withResolvers<Daemon>();
+      task = yield* spawn<void>(function* () {
+        let proc = yield* daemon("node", {
+          arguments: [
+            "--experimental-strip-types",
+            "./fixtures/echo-server.ts",
+          ],
+          env: {
+            PORT: "29002",
+            PATH: process.env.PATH as string,
+            ...(SystemRoot ? { SystemRoot } : {}),
+          },
+          cwd: import.meta.dirname,
+        });
+        result.resolve(proc);
+        yield* proc;
+      });
+
+      proc = yield* result.operation;
+
+      yield* expectMatch(/listening/, lines()(proc.stdout));
+    });
+
+    it("starts the given child", function* () {
+      const response = yield* fetchText("http://localhost:29002", {
+        method: "POST",
+        body: "hello",
+      });
+
+      expect(response.status).toEqual(200);
+      expect(response.text).toEqual("hello");
+    });
+
+    describe("halting the daemon task", () => {
+      beforeEach(function* () {
+        yield* until(task.halt());
+      });
+      it("kills the process", function* () {
+        expect(
+          yield* captureError(
+            fetchText("http://localhost:29002", {
+              method: "POST",
+              body: "hello",
+            }),
+          ),
+        ).toMatchObject({
+          message: expect.stringContaining("FetchError"),
+        });
+      });
+    });
+  });
+
+  describe("shutting down the daemon process prematurely", () => {
+    let task: Task<Error>;
+    beforeEach(function* () {
+      let proc = yield* daemon("node", {
+        arguments: ["--experimental-strip-types", "fixtures/echo-server.ts"],
+        env: {
+          PORT: "29001",
+          PATH: process.env.PATH as string,
+          ...(SystemRoot ? { SystemRoot } : {}),
+        },
+        cwd: import.meta.dirname,
+      });
+
+      task = yield* spawn(function* () {
+        try {
+          yield* proc;
+        } catch (e) {
+          return e as Error;
+        }
+        return new Error(`this shouldn't happen`);
+      });
+
+      yield* expectMatch(/listening/, lines()(proc.stdout));
+
+      yield* fetchText("http://localhost:29001", {
+        method: "POST",
+        body: "exit",
+      });
+    });
+
+    it("throw an error because it was not expected to close", function* () {
+      yield* until(
+        expect(task).resolves.toHaveProperty("name", "DaemonExitError"),
+      );
+    });
+  });
+});

package/test/eventemitter.test.ts

@@ -0,0 +1,82 @@
+import { EventEmitter } from "node:events";
+import { describe, it } from "@effectionx/bdd";
+import { spawn, withResolvers } from "effection";
+import { expect } from "expect";
+
+import { once } from "@effectionx/node/events";
+
+describe("once", () => {
+  it("resolves with single argument as array", function* () {
+    expect.assertions(1);
+    const emitter = new EventEmitter();
+    const { resolve, operation } = withResolvers<[string]>();
+
+    yield* spawn(function* () {
+      resolve(yield* once<[string]>(emitter, "test"));
+    });
+
+    yield* spawn(function* () {
+      emitter.emit("test", "hello");
+    });
+
+    expect(yield* operation).toEqual(["hello"]);
+  });
+
+  it("resolves with multiple arguments as array", function* () {
+    expect.assertions(1);
+    const emitter = new EventEmitter();
+
+    let { resolve, operation } = withResolvers<[number, string]>();
+
+    yield* spawn(function* () {
+      resolve(yield* once<[number, string]>(emitter, "exit"));
+    });
+
+    yield* spawn(function* () {
+      emitter.emit("exit", 42, "SIGTERM");
+    });
+
+    expect(yield* operation).toEqual([42, "SIGTERM"]);
+  });
+
+  it("only resolves once even with multiple emissions", function* () {
+    const emitter = new EventEmitter();
+
+    const { resolve, operation } = withResolvers<void>();
+    let results: string[][] = [];
+
+    yield* spawn(function* () {
+      results.push(yield* once<[string]>(emitter, "data"));
+      resolve();
+    });
+
+    yield* spawn(function* () {
+      emitter.emit("data", "first");
+      emitter.emit("data", "second");
+    });
+
+    yield* operation;
+
+    expect(results).toEqual([["first"]]);
+  });
+
+  it("removes listener after resolving", function* () {
+    expect.assertions(2);
+    const emitter = new EventEmitter();
+
+    const { resolve, operation } = withResolvers<void>();
+
+    yield* spawn(function* () {
+      yield* once<[string]>(emitter, "test");
+      resolve();
+    });
+
+    yield* spawn(function* () {
+      expect(emitter.listenerCount("test")).toBe(1);
+      emitter.emit("test", "hello");
+    });
+
+    yield* operation;
+    expect(emitter.listenerCount("test")).toBe(0);
+  });
+});