sailfork / t3code-github / .repos/ effect/ packages/ platform/ node-shared/ test/ NodeChildProcessSpawner.test.ts

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<string | number | undefined> }
  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<void>((resume) => {
    const timer = setTimeout(() => resume(Effect.void), millis)
    return Effect.sync(() => clearTimeout(timer))
  })

const liveTimeout = (millis: number) => <A, E, R>(effect: Effect.Effect<A, E, R>) =>
  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<number>()
  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*<A, E, R>(effect: Effect.Effect<A, E, R>) {
  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)))