import { buildSpawnOptions } from "@effect/platform-node-shared/internal/nodeChildProcessSpawner" import * as NodeChildProcessSpawner from "@effect/platform-node-shared/NodeChildProcessSpawner" import * as NodeFileSystem from "@effect/platform-node-shared/NodeFileSystem" import * as NodePath from "@effect/platform-node-shared/NodePath" import { assert, describe, it } from "@effect/vitest" import * as ChildProcessSpawnerTest from "effect-test/process/ChildProcessSpawnerTest" import * as ByteSize from "effect/ByteSize" import * as Deferred from "effect/Deferred" import * as Effect from "effect/Effect" import * as Exit from "effect/Exit" import * as FileSystem from "effect/FileSystem" import * as Layer from "effect/Layer" import * as ChildProcess from "effect/process/ChildProcess" import * as Scope from "effect/Scope" import * as Stream from "effect/Stream" import NodeChildProcess, { spawnSync } from "node:child_process" import { syncBuiltinESMExports } from "node:module" import { join } from "node:path" import { vi } from "vitest" const NodeServices = NodeChildProcessSpawner.layer.pipe( Layer.provideMerge(Layer.mergeAll( NodeFileSystem.layer, NodePath.layer )) ) ChildProcessSpawnerTest.suite("NodeChildProcessSpawner", NodeServices, { processGroups: true }) describe.skipIf(process.platform === "win32")("error descriptions", () => { it.effect("quote arguments and escape control characters", () => Effect.gen(function*() { const error = yield* Effect.flip(ChildProcess.make("nonexistent-command-12345", ["a b", "it's", "\u001b[2J"])) assert.strictEqual(error.reason._tag, "NotFound") assert.strictEqual( error.reason._tag === "NotFound" ? error.reason.pathOrDescriptor : undefined, "nonexistent-command-12345 'a b' 'it'\\''s' '\\u001b[2J'" ) }).pipe(Effect.provide(NodeServices))) }) describe("Windows cleanup", { concurrent: false }, () => { for (const signal of [false, true]) { it.skipIf(signal && process.platform === "win32")( `does not taskkill a ${signal ? "signal-terminated" : "failed"} child during exit, kill or scope release`, async () => { const platform = Object.getOwnPropertyDescriptor(process, "platform")! const taskkill = vi.spyOn(NodeChildProcess, "execFile").mockImplementation((...args) => { const callback = args.at(-1) if (typeof callback === "function") callback(null, "", "") return new NodeChildProcess.ChildProcess() }) syncBuiltinESMExports() try { await Effect.runPromise( Effect.scoped(Effect.gen(function*() { const handle = yield* ChildProcess.make(process.execPath, [ "-e", signal ? "process.kill(process.pid, 'SIGTERM')" : "process.exit(1)" ]) // Spawn natively, then exercise the Windows exit and cleanup paths. Object.defineProperty(process, "platform", { value: "win32" }) if (signal) { assert.isTrue(Exit.isFailure(yield* Effect.exit(handle.exitCode))) } else { assert.strictEqual(yield* handle.exitCode, 1) } yield* handle.kill() })).pipe(Effect.provide(NodeServices)) ) assert.strictEqual(taskkill.mock.calls.length, 0) } finally { Object.defineProperty(process, "platform", platform) taskkill.mockRestore() syncBuiltinESMExports() } } ) } }) describe.skipIf(process.platform === "win32")("non-detached exit cleanup", { concurrent: false }, () => { for (const signal of [false, true]) { it.live( `does not signal the process group of a ${ signal ? "signal-terminated" : "failed" } child during exit, kill or scope release`, () => Effect.gen(function*() { const kill = vi.spyOn(process, "kill") yield* Effect.addFinalizer(() => Effect.sync(() => kill.mockRestore())) let pid = 0 yield* Effect.scoped(Effect.gen(function*() { const handle = yield* ChildProcess.make(process.execPath, [ "-e", signal ? "process.kill(process.pid, 'SIGTERM')" : "process.exit(1)" ], { detached: false, forceKillAfter: "100 millis" }) pid = handle.pid if (signal) { assert.isTrue(Exit.isFailure(yield* Effect.exit(handle.exitCode))) } else { assert.strictEqual(yield* handle.exitCode, 1) } // The exited child's PID may now lead an unrelated process group. yield* Effect.ignore(handle.kill()) })) assert.deepStrictEqual(kill.mock.calls.filter(([target]) => target === -pid), []) }).pipe(Effect.scoped, Effect.provide(NodeServices)) ) } it.live("does not poll or force kill the process group of a child that exits during scope release", () => Effect.gen(function*() { const kill = vi.spyOn(process, "kill") yield* Effect.addFinalizer(() => Effect.sync(() => kill.mockRestore())) let pid = 0 yield* Effect.scoped(Effect.gen(function*() { const handle = yield* ChildProcess.make(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { detached: false, forceKillAfter: "1 second" }) pid = handle.pid })) // Signalling the live child is fine; polling or escalating after it exits is not. assert.deepStrictEqual(kill.mock.calls.filter(([target, signal]) => target === -pid && signal !== "SIGTERM"), []) }).pipe(Effect.scoped, Effect.provide(NodeServices))) }) const zombieProbes = 3 // macOS answers EPERM rather than ESRCH while the group's remaining members are zombies. const stubZombieProcessGroup = Effect.fnUntraced(function*() { const nativeKill = process.kill.bind(process) const group = { pid: 0, probes: 0, signals: [] as Array } const kill = vi.spyOn(process, "kill").mockImplementation((target, signal) => { if (group.pid === 0 || target !== -group.pid) { return nativeKill(target, signal) } if (signal === 0) { group.probes++ } else { group.signals.push(signal) } throw Object.assign(new Error("kill"), { code: group.probes <= zombieProbes ? "EPERM" : "ESRCH" }) }) yield* Effect.addFinalizer(() => Effect.sync(() => kill.mockRestore())) return group }) describe.skipIf(process.platform === "win32")("detached exit cleanup", { concurrent: false }, () => { it.live("kill waits for a process group that exists but cannot be signalled", () => Effect.gen(function*() { const group = yield* stubZombieProcessGroup() const handle = yield* ChildProcess.make(process.execPath, ["-e", "setInterval(() => {}, 1000)"]) group.pid = handle.pid yield* handle.kill() assert.strictEqual(group.probes, zombieProbes + 1) }).pipe(Effect.scoped, Effect.provide(NodeServices))) it.live("kill escalates and waits for a process group whose exited leader left only zombies", () => Effect.gen(function*() { const group = yield* stubZombieProcessGroup() const handle = yield* ChildProcess.make(process.execPath, ["-e", ""]) group.pid = handle.pid assert.strictEqual(yield* handle.exitCode, 0) yield* handle.kill({ forceKillAfter: "0 millis" }) assert.deepStrictEqual(group.signals, ["SIGTERM", "SIGKILL"]) assert.strictEqual(group.probes, zombieProbes + 1) }).pipe(Effect.scoped, Effect.provide(NodeServices))) }) // Synchronous fixture runs must not block other tests with active timeout budgets. describe("interrupted buffered input", { concurrent: false, timeout: 15_000 }, () => { for (const input of ["stdin", "fd3"] as const) { it(`does not crash the host when ${input} is interrupted`, () => { // Isolate the host so an unhandled writable error becomes an assertion // failure rather than an uncaught exception in the test runner. const result = spawnSync(process.execPath, [join(__dirname, "fixtures", "buffered-input.ts"), input], { encoding: "utf8", timeout: 10_000 }) assert.strictEqual(result.error, undefined) assert.strictEqual(result.status, 0, result.stderr) assert.strictEqual(result.stdout, "program finished: Failure\nstill alive after 500ms\n") }) } }) describe("buildSpawnOptions", () => { const base = { stdio: "pipe" } as const it("defaults to hiding non-detached Windows children", () => { assert.deepStrictEqual(buildSpawnOptions({}, base, "win32"), { stdio: "pipe", detached: false, shell: undefined, windowsHide: true }) assert.deepStrictEqual(buildSpawnOptions({ detached: true }, base, "win32"), { stdio: "pipe", detached: true, shell: undefined, windowsHide: false }) assert.deepStrictEqual(buildSpawnOptions({ detached: false }, base, "win32"), { stdio: "pipe", detached: false, shell: undefined, windowsHide: true }) }) it("allows windowsHide to be configured independently of detached", () => { assert.deepStrictEqual( buildSpawnOptions({ detached: false, windowsHide: false }, base, "win32"), { stdio: "pipe", detached: false, shell: undefined, windowsHide: false } ) assert.deepStrictEqual( buildSpawnOptions({ detached: true, windowsHide: true }, base, "win32"), { stdio: "pipe", detached: true, shell: undefined, windowsHide: true } ) }) }) it.live("kills every process in a pipeline", () => Effect.gen(function*() { const fs = yield* FileSystem.FileSystem const directory = yield* fs.makeTempDirectoryScoped() const rootHeartbeat = `${directory}/root-heartbeat` const childHeartbeat = `${directory}/child-heartbeat` const handle = yield* ChildProcess.make( "sh", [ "-c", "printf x >> \"$1\"; printf 'ROOT_READY\\n'; while :; do printf x >> \"$1\"; sleep 0.01; done", "pipeline-root", rootHeartbeat ] ).pipe(ChildProcess.pipeTo(ChildProcess.make( "sh", [ "-c", "printf x >> \"$1\"; printf 'CHILD_READY\\n'; read -r ready; printf '%s\\n' \"$ready\"; while :; do printf x >> \"$1\"; sleep 0.01; done", "pipeline-child", childHeartbeat ] ))) const readyLines = yield* handle.stdout.pipe( Stream.decodeText, Stream.splitLines, Stream.take(2), Stream.runCollect ) assert.deepStrictEqual(readyLines, ["CHILD_READY", "ROOT_READY"]) yield* handle.kill({ killSignal: "SIGKILL" }) const rootSizeAfterKill = (yield* fs.stat(rootHeartbeat)).size const childSizeAfterKill = (yield* fs.stat(childHeartbeat)).size yield* Effect.sleep("100 millis") const rootFinalSize = (yield* fs.stat(rootHeartbeat)).size const childFinalSize = (yield* fs.stat(childHeartbeat)).size assert.strictEqual(ByteSize.toBigInt(rootFinalSize), ByteSize.toBigInt(rootSizeAfterKill)) assert.strictEqual(ByteSize.toBigInt(childFinalSize), ByteSize.toBigInt(childSizeAfterKill)) }).pipe(Effect.scoped, Effect.provide(NodeServices))) const processGroupFixture = join(__dirname, "fixtures", "process-group.ts") // Use native timers under TestClock. const liveSleep = (millis: number) => Effect.callback((resume) => { const timer = setTimeout(() => resume(Effect.void), millis) return Effect.sync(() => clearTimeout(timer)) }) const liveTimeout = (millis: number) => (effect: Effect.Effect) => Effect.raceFirst(effect, liveSleep(millis).pipe(Effect.andThen(Effect.die(new Error("timed out"))))) const startProcessGroup = Effect.fnUntraced(function*( mode: "exit-on-signal" | "ignore-signal", options?: ChildProcess.CommandOptions, delays: { readonly leader: number; readonly descendant: number } = { leader: 0, descendant: 200 } ) { const fs = yield* FileSystem.FileSystem const directory = yield* fs.makeTempDirectoryScoped() const marker = `${directory}/marker` const scope = yield* Scope.fork(yield* Effect.scope) const handle = yield* Scope.provide(scope)(ChildProcess.make( process.execPath, [processGroupFixture, "leader", mode, marker, String(delays.leader), String(delays.descendant)], { stdin: "ignore", ...options } )) const ready = yield* Deferred.make() yield* handle.stdout.pipe( Stream.decodeText, Stream.splitLines, Stream.runForEach((line) => line.startsWith("READY ") ? Deferred.succeed(ready, Number(line.slice("READY ".length))) : Effect.void ), Effect.forkScoped ) const descendantPid = yield* Deferred.await(ready).pipe(liveTimeout(5_000)) return { handle, descendantPid, marker, scope } }) const killDescendant = (pid: number) => Effect.sync(() => { try { process.kill(pid, "SIGKILL") } catch {} }) const assertHeartbeatStopped = Effect.fnUntraced(function*(marker: string) { const fs = yield* FileSystem.FileSystem const sizeAfterKill = (yield* fs.stat(marker)).size yield* liveSleep(100) const finalSize = (yield* fs.stat(marker)).size assert.strictEqual(finalSize, sizeAfterKill) }) const timed = Effect.fnUntraced(function*(effect: Effect.Effect) { const start = Date.now() yield* effect return Date.now() - start }) describe.skipIf(process.platform === "win32")("process group cleanup", () => { it.live("scope release cleans descendants after the leader exits successfully", () => Effect.gen(function*() { const fs = yield* FileSystem.FileSystem const { descendantPid, handle, marker, scope } = yield* startProcessGroup("exit-on-signal", { stdin: "pipe" }) yield* Effect.addFinalizer(() => killDescendant(descendantPid)) yield* Stream.run(Stream.make(new TextEncoder().encode("exit\n")), handle.stdin) assert.strictEqual(yield* handle.exitCode, 0) assert.doesNotThrow(() => process.kill(descendantPid, 0), "descendant must still be alive after the leader exits") assert.isFalse(yield* fs.exists(marker)) yield* Scope.close(scope, Exit.void) assert.strictEqual(yield* fs.readFileString(marker), "exited") }).pipe(Effect.scoped, Effect.provide(NodeServices))) it.live("scope release force kills descendants after the leader exits with a non-zero code", () => Effect.gen(function*() { const { descendantPid, handle, marker, scope } = yield* startProcessGroup("ignore-signal", { stdin: "pipe", forceKillAfter: "200 millis" }) yield* Effect.addFinalizer(() => killDescendant(descendantPid)) yield* Stream.run(Stream.make(new TextEncoder().encode("exit 1\n")), handle.stdin) assert.strictEqual(yield* handle.exitCode, 1) yield* Scope.close(scope, Exit.void).pipe(liveTimeout(2_000)) yield* assertHeartbeatStopped(marker) }).pipe(Effect.scoped, Effect.provide(NodeServices))) it.live("scope release cleans descendants after the leader is killed externally", () => Effect.gen(function*() { const fs = yield* FileSystem.FileSystem const { descendantPid, handle, marker, scope } = yield* startProcessGroup("exit-on-signal") yield* Effect.addFinalizer(() => killDescendant(descendantPid)) process.kill(handle.pid, "SIGKILL") assert.isTrue(Exit.isFailure(yield* Effect.exit(handle.exitCode))) assert.doesNotThrow(() => process.kill(descendantPid, 0), "descendant must survive the leader's SIGKILL") assert.isFalse(yield* fs.exists(marker)) yield* Scope.close(scope, Exit.void) assert.isTrue(yield* fs.exists(marker), "scope release must wait for the descendant's exit marker") assert.strictEqual(yield* fs.readFileString(marker), "exited") }).pipe(Effect.scoped, Effect.provide(NodeServices))) it.live("scope release waits for descendants that outlive the leader", () => Effect.gen(function*() { const fs = yield* FileSystem.FileSystem const { handle, marker, scope } = yield* startProcessGroup("exit-on-signal") yield* Scope.close(scope, Exit.void) assert.isFalse(yield* handle.isRunning) assert.isTrue(yield* fs.exists(marker)) }).pipe(Effect.scoped, Effect.provide(NodeServices))) it.live("scope release drains descendants after a slow leader exits", () => Effect.gen(function*() { const fs = yield* FileSystem.FileSystem const { descendantPid, handle, marker, scope } = yield* startProcessGroup("exit-on-signal", undefined, { leader: 1_500, descendant: 2_000 }) yield* Effect.addFinalizer(() => killDescendant(descendantPid)) const releaseMillis = yield* timed(Scope.close(scope, Exit.void)) assert.isAtLeast(releaseMillis, 1_500) assert.isFalse(yield* handle.isRunning) assert.isTrue(yield* fs.exists(marker), "scope release must wait for the descendant's exit marker") assert.strictEqual(yield* fs.readFileString(marker), "exited") }).pipe(Effect.provide(NodeServices))) it.live("scope release force kills descendants that ignore the kill signal", () => Effect.gen(function*() { const { marker, scope } = yield* startProcessGroup("ignore-signal", { forceKillAfter: "200 millis" }) yield* Scope.close(scope, Exit.void) yield* assertHeartbeatStopped(marker) }).pipe(Effect.scoped, Effect.provide(NodeServices))) it.live("kill force kills descendants that ignore the kill signal", () => Effect.gen(function*() { const { handle, marker, scope } = yield* startProcessGroup("ignore-signal") yield* handle.kill({ forceKillAfter: "200 millis" }) assert.isFalse(yield* handle.isRunning) yield* assertHeartbeatStopped(marker) yield* Scope.close(scope, Exit.void) }).pipe(Effect.scoped, Effect.provide(NodeServices))) it.effect("forceKillAfter escalation does not depend on the Effect clock", () => Effect.gen(function*() { const { marker, scope } = yield* startProcessGroup("ignore-signal", { forceKillAfter: "200 millis" }) const releaseMillis = yield* timed(Scope.close(scope, Exit.void)) assert.isBelow(releaseMillis, 2_000) yield* assertHeartbeatStopped(marker) }).pipe(Effect.scoped, Effect.provide(NodeServices))) it.live("scope release returns when a descendant holds the inherited pipe without forceKillAfter", () => Effect.gen(function*() { const { descendantPid, handle, scope } = yield* startProcessGroup("ignore-signal") yield* Effect.gen(function*() { const releaseMillis = yield* timed(Scope.close(scope, Exit.void)) assert.isFalse(yield* handle.isRunning) assert.isAtLeast(releaseMillis, 1_000) assert.isBelow(releaseMillis, 3_000) }).pipe(Effect.ensuring(killDescendant(descendantPid))) }).pipe(Effect.scoped, Effect.provide(NodeServices))) }) it.live("scope release returns when stdout is unread and backpressured", () => Effect.gen(function*() { const releaseMillis = yield* timed(Effect.scoped(Effect.gen(function*() { yield* ChildProcess.make(process.execPath, [ "-e", "process.stdout.write(\"x\".repeat(1024 * 1024)); setInterval(() => {}, 1000)" ], { stdin: "ignore" }) yield* Effect.sleep("100 millis") }))) assert.isBelow(releaseMillis, 2_000) }).pipe(Effect.provide(NodeServices))) it.live("scope release closes stdin for a child that drains it on the kill signal", () => Effect.gen(function*() { const releaseMillis = yield* timed(Effect.scoped(Effect.gen(function*() { const handle = yield* ChildProcess.make(process.execPath, [ "-e", // Exits with EOF on SIGTERM, or after 3 seconds if stdin stays open. "process.on(\"SIGTERM\", () => process.stdin.on(\"end\", () => process.exit(0)).resume()); console.log(\"READY\"); setTimeout(() => process.exit(1), 3_000)" ], { stdin: Stream.never }) yield* Stream.runHead(handle.stdout) }))) assert.isBelow(releaseMillis, 2_000) }).pipe(Effect.provide(NodeServices)))