diff --git a/src/drivers/android/emulator.ts b/src/drivers/android/emulator.ts index 86b0351e7..7f0f9c00a 100644 --- a/src/drivers/android/emulator.ts +++ b/src/drivers/android/emulator.ts @@ -269,7 +269,9 @@ export class Emulator { ...this.#flags, ...launchArgs, ], - { env: this.#env(data), stdio: { file: logPath } }, + // why: on Windows a kill otherwise ends `emulator.exe` alone, and its qemu child keeps + // running with the guest's RAM. Not a tree kill: qemu's `netsimd.exe` serves every emulator. + { env: this.#env(data), killChildren: true, stdio: { file: logPath } }, ); handle.unref(); // why: No announcement here, deliberately. adb answers `host:emulator:` by connecting diff --git a/src/drivers/android/index-boot.test.ts b/src/drivers/android/index-boot.test.ts index 53e7411e9..9473e6673 100644 --- a/src/drivers/android/index-boot.test.ts +++ b/src/drivers/android/index-boot.test.ts @@ -238,6 +238,24 @@ describe("AndroidDriver", () => { }, ); + // why: On Windows a kill ends the child alone, and `emulator.exe`'s qemu child would keep its + // RAM; but an `adb` client can start the adb server as its child, and for a phone that is the + // shared 5037 server. + it("asks for its children to be killed with the emulator, and for no adb command", async () => { + const harness = await provisionedHarness(); + + await harness.driver.makeReady(harness.device); + + const emulatorCalls = harness.runner.calls.filter( + (call) => call.command === binaries.emulator && call.args.includes("-avd"), + ); + const adbCalls = harness.runner.calls.filter((call) => call.command === binaries.adb); + expect(emulatorCalls.length).toBeGreaterThan(0); + expect(emulatorCalls.filter((call) => call.options.killChildren !== true)).toEqual([]); + expect(adbCalls.length).toBeGreaterThan(0); + expect(adbCalls.filter((call) => call.options.killChildren !== undefined)).toEqual([]); + }); + // why: The gRPC port follows the reserved console port, so two parallel leases never share one. it("puts the gRPC endpoint at the reserved console port plus 3000", async () => { const filesystem = await androidFilesystem(); diff --git a/src/drivers/android/index-lifecycle.test.ts b/src/drivers/android/index-lifecycle.test.ts index 88e8ae3e3..bd217a5ab 100644 --- a/src/drivers/android/index-lifecycle.test.ts +++ b/src/drivers/android/index-lifecycle.test.ts @@ -29,6 +29,7 @@ import { home } from "./test-index.js"; // why: The emulator outlives the daemon, so it is spawned detached; its output goes to the log file in its AVD folder. const emulatorOptions = { env: { ...scopedEnv, ANDROID_EMU_CRASH_REPORTING_DATABASE: `${avdDirectory}/emu-crash.db` }, + killChildren: true, stdio: { file: `${avdDirectory}/simlock_one/simlock.avd/emulator.log` }, } as const; diff --git a/src/ports/node-process-runner.ts b/src/ports/node-process-runner.ts index 058317aba..17039369d 100644 --- a/src/ports/node-process-runner.ts +++ b/src/ports/node-process-runner.ts @@ -3,7 +3,7 @@ import { closeSync, openSync } from "node:fs"; import type { Writable } from "node:stream"; import { LineBuffer, captureLines } from "./process-line-buffer.js"; -import { isRunning, killProcessTree, runLimits } from "./process-tree-kill.js"; +import { isRunning, killProcessTree, runLimits, type WindowsKill } from "./process-tree-kill.js"; import { childLaunch } from "./windows-command.js"; import { InputStreamFailedError, @@ -142,7 +142,7 @@ export class NodeProcessRunner implements ProcessRunner { options.lineEnd ?? "newline", this.exitDeferralCapMs, this.exitGraceMs, - launch.windowsVerbatimArguments, + windowsKillOf(launch.windowsVerbatimArguments, options.killChildren === true), runLimits(options), ); } @@ -176,7 +176,7 @@ export class NodeProcessRunner implements ProcessRunner { options.onChunk, this.exitDeferralCapMs, this.exitGraceMs, - launch.windowsVerbatimArguments, + windowsKillOf(launch.windowsVerbatimArguments, false), ); if (options.input !== undefined) { // why: One shot, then closed (ADR 0005 ยง19c): a command reading stdin sees exactly this and @@ -317,7 +317,7 @@ class NodeStreamingProcessHandle implements StreamingProcessHandle { onChunk: (stream: "stdout" | "stderr", chunk: string) => void | Promise, private readonly exitDeferralCapMs: number, private readonly exitGraceMs: number, - private readonly wrapped: boolean, + private readonly windowsKill: WindowsKill, ) { this.pid = pid; this.#forward(child.stdout, "stdout", onChunk); @@ -331,7 +331,7 @@ class NodeStreamingProcessHandle implements StreamingProcessHandle { settled = true; const killedWith = this.#killedWith; resolve( - wrapped && killedWith !== undefined + windowsKill !== "child" && killedWith !== undefined ? { code: null, signal: killedWith } : { code, signal }, ); @@ -404,7 +404,7 @@ class NodeStreamingProcessHandle implements StreamingProcessHandle { kill(signal: NodeJS.Signals = "SIGTERM"): void { if (isRunning(this.child)) this.#killedWith ??= signal; - killProcessTree(this.child, this.pid, signal, this.wrapped); + killProcessTree(this.child, this.pid, signal, this.windowsKill); } wait(): Promise { @@ -480,7 +480,7 @@ class NodeProcessHandle implements ProcessHandle { lineEnd: LineEnd, private readonly exitDeferralCapMs: number, private readonly exitGraceMs: number, - private readonly wrapped: boolean, + private readonly windowsKill: WindowsKill, limits: Pick = {}, ) { this.pid = pid; @@ -497,7 +497,7 @@ class NodeProcessHandle implements ProcessHandle { } settled = true; resolve({ - code: wrapped && this.#killedWith !== undefined ? null : code, + code: windowsKill !== "child" && this.#killedWith !== undefined ? null : code, stderr: this.#stderrChunks.join(""), stdout: this.#stdoutChunks.join(""), ...(this.#endedBy === undefined ? {} : { endedBy: this.#endedBy }), @@ -560,7 +560,7 @@ class NodeProcessHandle implements ProcessHandle { this.#killedWith ??= signal; this.#endedBy ??= endedBy; } - killProcessTree(this.child, this.pid, signal, this.wrapped); + killProcessTree(this.child, this.pid, signal, this.windowsKill); } unref(): void { @@ -579,3 +579,11 @@ function childStdio( if (logFd !== undefined) return ["ignore", logFd, logFd]; return stdio === undefined || typeof stdio === "object" ? "pipe" : stdio; } + +// why: a batch file's `cmd.exe` wrapper dies with its whole tree; a `killChildren` child with its +// own children only; any other child alone. Off Windows every child is `"child"`: its exit code +// stands, as the kill there is the process group's own signal. +function windowsKillOf(wrapped: boolean, killChildren: boolean): WindowsKill { + if (wrapped) return "tree"; + return killChildren && process.platform === "win32" ? "children" : "child"; +} diff --git a/src/ports/process-runner-types.ts b/src/ports/process-runner-types.ts index 4d8440d1b..4a6dbe6fb 100644 --- a/src/ports/process-runner-types.ts +++ b/src/ports/process-runner-types.ts @@ -30,6 +30,15 @@ export interface ProcessRunOptions { * newline. The captured `ProcessResult` text is the same either way. */ readonly lineEnd?: LineEnd; + /** + * why: on Windows `kill` ends the child alone, and a program that runs its real work as a child + * (`emulator.exe` runs qemu) leaves that child running. With this, `kill` also ends the child's + * own children, never theirs: a grandchild can be a process others use (the first emulator's + * qemu starts the host's one `netsimd.exe`, and every emulator's network goes through it), and + * an `adb` client can start the shared adb server, so no adb command sets this. Elsewhere `kill` + * already ends the child's process group, and this changes nothing. + */ + readonly killChildren?: boolean; } export type LineEnd = "newline" | "carriage-return-too"; diff --git a/src/ports/process-runner.test.ts b/src/ports/process-runner.test.ts index 49f9b615a..59869f115 100644 --- a/src/ports/process-runner.test.ts +++ b/src/ports/process-runner.test.ts @@ -513,6 +513,27 @@ describe("NodeProcessRunner: spawnStreaming", () => { } }); + // why: `killChildren` is a Windows kill; elsewhere a child that answers SIGTERM with its own + // exit code keeps reporting it. + it.skipIf(process.platform === "win32")( + "reports the exit code of a killChildren child that exits on SIGTERM", + async () => { + const handle = new NodeProcessRunner().spawn( + process.execPath, + [ + "-e", + "process.on('SIGTERM', () => process.exit(7)); console.log('ready'); setInterval(() => {}, 1_000)", + ], + { killChildren: true }, + ); + for await (const line of handle.stdout) if (line === "ready") break; + + handle.kill("SIGTERM"); + + await expect(handle.wait()).resolves.toMatchObject({ code: 7 }); + }, + ); + it("kills the grandchildren too, because the signal goes to the process group", async () => { // The reason `kill` signals `-pid` rather than the child: a tool that forks (an // `adb`/`emulator` wrapper script, `simctl spawn`) leaves the work in a *grandchild*, and a diff --git a/src/ports/process-tree-kill.ts b/src/ports/process-tree-kill.ts index df656417b..d41d16ee9 100644 --- a/src/ports/process-tree-kill.ts +++ b/src/ports/process-tree-kill.ts @@ -14,6 +14,8 @@ export function runLimits({ }; } +export type WindowsKill = "child" | "children" | "tree"; + /** * why: Windows has no process groups, and a batch file runs under a `cmd.exe` wrapper * (`windows-command.ts`): signalling the wrapper alone would leave the script's own processes, @@ -25,24 +27,60 @@ export function runLimits({ * wrapper alone is killed as before. */ function killWindowsProcessTree(child: ChildProcess, pid: number, signal: NodeJS.Signals): void { + runWindowsKill(child, signal, "taskkill", ["/pid", String(pid), "/T", "/F"]); +} + +/** + * why: `killChildren` (`ProcessRunOptions`): the child and the processes it started, never + * theirs, so `taskkill /T` does not fit. Windows keeps a dead parent's pid in its children's + * `ParentProcessId`, and pids are reused, so a listed process counts as a child only when it + * started after the child did. Should PowerShell fail, the child alone is killed. + */ +function killWindowsProcessAndChildren( + child: ChildProcess, + pid: number, + signal: NodeJS.Signals, +): void { + const script = [ + "$ErrorActionPreference = 'Stop'", + `$parent = Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}'`, + "if ($null -eq $parent) { exit 1 }", + `$children = @(Get-CimInstance Win32_Process -Filter 'ParentProcessId = ${pid}' | Where-Object { $_.CreationDate -ge $parent.CreationDate })`, + `Stop-Process -Id ${pid} -Force`, + "foreach ($c in $children) { Stop-Process -Id $c.ProcessId -Force -ErrorAction SilentlyContinue }", + ].join("\n"); + runWindowsKill(child, signal, "powershell.exe", [ + "-NoProfile", + "-NonInteractive", + "-EncodedCommand", + Buffer.from(script, "utf16le").toString("base64"), + ]); +} + +function runWindowsKill( + child: ChildProcess, + signal: NodeJS.Signals, + command: string, + args: readonly string[], +): void { const fallback = () => { if (isRunning(child)) child.kill(signal); }; - const taskkill = spawnChildProcess("taskkill", ["/pid", String(pid), "/T", "/F"], { + const killer = spawnChildProcess(command, args, { stdio: "ignore", timeout: TASKKILL_TIMEOUT_MS, windowsHide: true, }); - taskkill.once("error", fallback); - taskkill.once("exit", (code) => { + killer.once("error", fallback); + killer.once("exit", (code) => { if (code !== 0) fallback(); }); } /** * why: Signals the child's whole process group (children are spawned `detached`, so the group is - * the unit that actually dies), or on Windows a batch file's whole tree and any other child - * alone, treating an already-exited process as success. Extracted so `ProcessHandle` and `StreamingProcessHandle` + * the unit that actually dies), or on Windows a batch file's whole tree, a `killChildren` child + * with its own children, and any other child alone, treating an already-exited process as success. Extracted so `ProcessHandle` and `StreamingProcessHandle` * kill identically -- a timeout that only reached the direct child would leave a tool's own * subprocesses running. * @@ -59,12 +97,13 @@ export function killProcessTree( child: ChildProcess, pid: number, signal: NodeJS.Signals, - wrapped: boolean, + windowsKill: WindowsKill, ): void { if (!isRunning(child)) return; if (process.platform === "win32") { - if (wrapped) killWindowsProcessTree(child, pid, signal); + if (windowsKill === "tree") killWindowsProcessTree(child, pid, signal); + else if (windowsKill === "children") killWindowsProcessAndChildren(child, pid, signal); else child.kill(signal); return; } diff --git a/src/ports/windows-command.test.ts b/src/ports/windows-command.test.ts index fa1a90b4e..ed77e2ffe 100644 --- a/src/ports/windows-command.test.ts +++ b/src/ports/windows-command.test.ts @@ -4,7 +4,7 @@ import { join } from "node:path"; import { describe, expect, it } from "vitest"; -import { NodeProcessRunner } from "./index.js"; +import { NodeProcessRunner, type ProcessHandle, type ProcessRunOptions } from "./index.js"; import { childLaunch } from "./windows-command.js"; const sdkmanager = String.raw`C:\Android\Sdk/cmdline-tools/latest/bin/sdkmanager.bat`; @@ -136,6 +136,36 @@ describe.runIf(process.platform === "win32")("NodeProcessRunner on Windows", () } }); + /** + * why: `emulator.exe` runs qemu as its child, and a kill that reached only the parent left qemu + * running with the guest's RAM. The first emulator's qemu also starts the host's one + * `netsimd.exe`, which every emulator's network goes through, so the grandchild here must + * outlive the kill. Each process is `detached` because libuv otherwise puts it in a job + * object that ends it with its parent, which neither `emulator.exe` nor qemu does. + */ + it("ends an .exe spawned with killChildren and its child, leaves its grandchild running, and reports no exit code", async () => { + await withProcessChain({ killChildren: true }, async (handle, { child, grandchild }) => { + handle.kill("SIGKILL"); + + await expect(handle.wait()).resolves.toMatchObject({ code: null }); + await expect.poll(() => isAlive(child), { timeout: 10_000 }).toBe(false); + expect(isAlive(grandchild)).toBe(true); + }); + }); + + /** + * why: an `adb` client can start the adb server as its child, and for a phone that is the + * shared 5037 server, which a timed-out command must not take down with it. + */ + it("kills an .exe spawned without killChildren alone, leaving its children running", async () => { + await withProcessChain({}, async (handle, { child }) => { + handle.kill("SIGKILL"); + + await handle.wait(); + expect(isAlive(child)).toBe(true); + }); + }); + it("reports a batch file's own exit code when kill comes after cmd.exe exited but a grandchild still holds its output", async () => { const directory = await mkdtemp(join(tmpdir(), "simlock bat ")); const pidFile = join(directory, "grandchild.pid"); @@ -170,6 +200,38 @@ exit /b 0 }); }); +async function withProcessChain( + options: ProcessRunOptions, + use: (handle: ProcessHandle, pids: { child: number; grandchild: number }) => Promise, +): Promise { + const directory = await mkdtemp(join(tmpdir(), "simlock exe ")); + const childPidFile = join(directory, "child.pid"); + const grandchildPidFile = join(directory, "grandchild.pid"); + const grandchild = `require('fs').writeFileSync(process.argv[1], String(process.pid)); setInterval(() => {}, 1000)`; + const child = `require('child_process').spawn(process.execPath, ['-e', ${JSON.stringify(grandchild)}, process.argv[2]], { detached: true, stdio: 'ignore' }); require('fs').writeFileSync(process.argv[1], String(process.pid)); setInterval(() => {}, 1000)`; + const parent = `require('child_process').spawn(process.execPath, ['-e', ${JSON.stringify(child)}, process.argv[1], process.argv[2]], { detached: true, stdio: 'ignore' }); setInterval(() => {}, 1000)`; + let handle: ProcessHandle | undefined; + const pids: number[] = []; + try { + handle = new NodeProcessRunner().spawn( + process.execPath, + ["-e", parent, childPidFile, grandchildPidFile], + options, + ); + for (const file of [childPidFile, grandchildPidFile]) { + await expect + .poll(() => readFile(file, "utf8").catch(() => ""), { timeout: 10_000 }) + .not.toBe(""); + pids.push(Number(await readFile(file, "utf8"))); + } + await use(handle, { child: pids[0] ?? 0, grandchild: pids[1] ?? 0 }); + } finally { + handle?.kill("SIGKILL"); + for (const pid of pids) if (isAlive(pid)) process.kill(pid); + await rm(directory, { force: true, recursive: true }); + } +} + function isAlive(pid: number): boolean { try { process.kill(pid, 0);