diff --git a/.github/workflows/ffi-experiment.yml b/.github/workflows/ffi-experiment.yml new file mode 100644 index 000000000..bd7b6d322 --- /dev/null +++ b/.github/workflows/ffi-experiment.yml @@ -0,0 +1,61 @@ +name: FFI PTY experiment + +on: + push: + branches: [experiment/ffi-pty] + paths: + - "experiments/ffi-pty/**" + - "test/experiments/ffi-pty/**" + - ".github/workflows/ffi-experiment.yml" + pull_request: + paths: + - "experiments/ffi-pty/**" + - "test/experiments/ffi-pty/**" + - ".github/workflows/ffi-experiment.yml" + workflow_dispatch: + +permissions: + contents: read + +jobs: + test: + strategy: + fail-fast: false + matrix: + include: + - runner: macos-15 + name: macOS 15 ARM64 + - runner: macos-15-intel + name: macOS 15 x64 + - runner: ubuntu-22.04 + name: Ubuntu 22.04 x64 + - runner: ubuntu-22.04-arm + name: Ubuntu 22.04 ARM64 + - runner: windows-2022 + name: Windows Server 2022 x64 + - runner: windows-2025 + name: Windows Server 2025 x64 + - runner: windows-11-arm + name: Windows 11 ARM64 + name: ${{ matrix.name }} + runs-on: ${{ matrix.runner }} + timeout-minutes: 10 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 26.12.0 + - name: Test Windows without a helper executable + if: runner.os == 'Windows' + run: node --experimental-ffi --test --test-timeout=60000 test/experiments/ffi-pty/windows.test.mts + - name: Build native Windows helper + if: runner.os == 'Windows' + run: node experiments/ffi-pty/build-windows-helper.mts + - run: node --experimental-ffi --test --test-timeout=60000 test/experiments/ffi-pty/*.test.mts + - name: Upload native Windows helper + if: runner.os == 'Windows' + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: ffi-helper-${{ matrix.runner }}-${{ runner.arch }} + path: build/ffi-pty/*/helper.exe + if-no-files-found: error diff --git a/experiments/ffi-pty/README.md b/experiments/ffi-pty/README.md new file mode 100644 index 000000000..91b6b8796 --- /dev/null +++ b/experiments/ffi-pty/README.md @@ -0,0 +1,69 @@ +# Cross-platform Node FFI PTY experiment + +This opt-in experiment creates a PTY without a node-pty native addon. It requires Node.js 26.12.0 with `--experimental-ffi`. It is not imported by node-pty's public entry point and does not change the public `IPty` API. + +## Try it + +```sh +node --experimental-ffi experiments/ffi-pty/probe.mts +node --experimental-ffi --test test/experiments/ffi-pty/*.test.mts +``` + +The facade exports `spawnPty(file, args, options)`, which resolves to a PTY with `pid`, `cols`, `rows`, `onData`, `onExit`, `write`, `resize`, `kill`, `pause`, `resume`, `close`, and `exited`. + +Supported spawn options are `cols` (80), `rows` (24), `cwd` (current directory), `env` (current environment), and UTF-8 `encoding`. A supplied `env` replaces the inherited environment; `TERM=xterm-256color` is added if absent. Dimensions must be 1–32767. Unknown options and non-UTF-8 encodings are rejected before a PTY is allocated. + +This is a small experimental API, not full `IPty` parity. It does not support credentials such as `uid`/`gid`, pixel dimensions, ConPTY DLL or cursor-inheritance options, or encodings other than UTF-8. + +## Platform paths + +| Platform | Native path and current limit | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| macOS | `openpty` and `posix_spawn` from `libSystem`; a Node bootstrap calls public `login_tty` then `execve` to set the controlling terminal; resize delegates to `/bin/stty`. | +| Linux | glibc `openpty` and `posix_spawn`; requires glibc 2.34 or newer; resize delegates to `stty`. | +| Windows | System ConPTY APIs; requires Windows 10 version 1809 or Windows Server 2019 or newer. | + +On Unix, `uv_poll_init` sets the PTY master nonblocking through a temporary libuv loop. The shared backend serializes writes, retries `EAGAIN` and `EINTR`, caps queued input at 8 MiB, and yields between 64 KiB writes. After child exit, it waits for output EOF for up to 1.5 seconds of unpaused time so inherited descriptors cannot hold exit open indefinitely. Explicitly pausing output suspends that budget; an unread stream still has the bounded timeout. Unix resize runs the system `stty` command; Windows uses ConPTY resize. ([libuv poll API](https://docs.libuv.org/en/v1.x/poll.html)) + +The implementation relies on Node's experimental and unsafe FFI interface ([Node.js FFI](https://nodejs.org/api/ffi.html)), Unix PTY and process APIs ([Apple `posix_spawn`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html), [Apple `login_tty`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/login_tty.3.html), [Linux `openpty`](https://www.man7.org/linux/man-pages/man3/openpty.3.html), [Linux `posix_spawn`](https://man7.org/linux/man-pages/man3/posix_spawn.3.html)), and Windows' [CreatePseudoConsole API](https://learn.microsoft.com/en-us/windows/console/createpseudoconsole). Windows pseudoconsoles are a system facility; this experiment does not bundle a ConPTY DLL. The macOS bootstrap adds a Node startup before the target process. No performance or binary-size advantage has been measured. + +Windows selects its implementation using the actual OS version from `RtlGetVersion`: + +| System | Implementation | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| Windows 10 1809+, Windows 11 before 24H2, Server 2019/2022 (builds 17763–26099) | Node subprocess by default; verified native helper when available. | +| Windows 11 24H2+ and Server 2025 (build 26100+) | FFI in an in-process worker; no helper executable needed. | +| Before build 17763 | Unsupported: ConPTY is unavailable. | + +The helper process contains a [known handle leak in older system ConPTY implementations](https://github.com/microsoft/terminal/issues/17903#issuecomment-2343499050), because exiting it releases its handles. Build 26100 fixes that leak and makes [`ClosePseudoConsole` nonblocking](https://learn.microsoft.com/en-us/windows/console/closepseudoconsole). All Windows paths use a kill-on-close job to clean up the target and its descendants. Modern Windows isolates synchronous ConPTY calls in a worker so blocked resize calls do not stall the main thread. + +On affected Windows, the default helper runs with the installed Node executable. An optional C++ helper uses Win32 directly, without Node or its addon ABI. Automatic selection requires a valid Windows Authenticode signature matching the publisher specified by trusted release metadata. Missing files, absent publisher metadata, signature failures, and verification timeouts select Node instead. Development builds require no signing certificate. + +Verification is cached for the host process lifetime. A verified helper remains locked against modification or replacement while that process runs; restart the host after installing or updating it. Verification uses Windows PowerShell. Windows may retrieve certificate trust information during verification; a bounded timeout falls back to Node. + +A fast PE-header check rejects unsigned files before starting signature verification. It reads only the header fields locating the certificate table and its record header, never the executable payload. A certificate table only indicates that a signature may be present; Windows still validates the signed file and publisher before native execution. An empty publisher policy skips file inspection entirely. + +To build the optional native helper or run its lifecycle tests, use Visual Studio C++ tools: + +```sh +node experiments/ffi-pty/build-windows-helper.mts +``` + +The build writes `build/ffi-pty/win32-/helper.exe`; `--arch=x64` and `--arch=arm64` select a target explicitly. Spawning a terminal never compiles or downloads the helper. Normal terminal use does not require this file. Build it before running the full Windows test suite, which exercises the unsigned helper directly as an internal test fixture. + +The signed-helper trust integration test runs only on disposable GitHub-hosted Windows runners; it adds a unique temporary certificate to the machine root store and removes it during cleanup. + +CI artifacts are unsigned experimental builds. Public helper releases need a maintainer-owned Windows signing process; checksums and build provenance do not replace Authenticode or override application-control policy. See [Microsoft's signing guidance](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/code-signing-options). + +
+Signing the optional helper for release + +Use the maintainer's existing signing service or [Azure Artifact Signing](https://learn.microsoft.com/en-us/azure/artifact-signing/overview). Azure manages the publisher identity and keys; SignTool or the Azure GitHub Action applies the signature. The helper is a standalone EXE, so MSIX packaging is unnecessary. + +Build and test each architecture, sign with SHA-256 and a timestamp, verify with `signtool verify /pa /all /v /tw helper.exe`, then include those exact bytes in the npm package. Reject missing timestamps and failed verification. Azure's short-lived certificates make timestamping essential. Keep signing credentials in the release infrastructure; GitHub OIDC avoids a long-lived client secret. See [signing integration](https://learn.microsoft.com/en-us/azure/artifact-signing/how-to-signing-integrations) and [OIDC setup](https://github.com/Azure/artifact-signing-action/blob/main/docs/OIDC.md). + +The expected publisher is release metadata, not a user environment override. Do not pin a rotating leaf certificate thumbprint. Signing establishes publisher identity but does not bypass machine policy or guarantee immediate SmartScreen reputation. + +
+ +The CI workflow tests macOS and Ubuntu on x64/ARM64, Windows Server 2022 and 2025 on x64, and Windows 11 on ARM64. Windows jobs also build the native helper and publish it as a downloadable artifact. Check workflow results for validation status. diff --git a/experiments/ffi-pty/build-windows-helper.mts b/experiments/ffi-pty/build-windows-helper.mts new file mode 100644 index 000000000..9f1fc1649 --- /dev/null +++ b/experiments/ffi-pty/build-windows-helper.mts @@ -0,0 +1,115 @@ +import { gzipSync } from "node:zlib"; +import { execFileSync, spawnSync } from "node:child_process"; +import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +const ROOT = resolve(fileURLToPath(new URL("../..", import.meta.url))); +const SOURCE = join(ROOT, "experiments", "ffi-pty", "native"); + +export function targetArchitecture( + argv = process.argv.slice(2), + env = process.env, +): "x64" | "arm64" { + const requested = + argv.find((arg) => arg.startsWith("--arch="))?.slice("--arch=".length) ?? + env.npm_config_arch ?? + env.ARCH ?? + process.arch; + if (requested !== "x64" && requested !== "arm64") { + throw new Error(`Windows helper supports x64 and arm64 targets; got ${requested}`); + } + return requested; +} + +export function findVsDevCmd(env: NodeJS.ProcessEnv): string { + const root = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)"; + const vswhere = join(root, "Microsoft Visual Studio", "Installer", "vswhere.exe"); + try { + const result = execFileSync( + vswhere, + [ + "-latest", + "-products", + "*", + "-requires", + "Microsoft.VisualStudio.Component.VC.Tools.x86.x64", + "-find", + "Common7\\Tools\\VsDevCmd.bat", + ], + { encoding: "utf8", windowsHide: true }, + ) + .trim() + .split(/\r?\n/); + const path = result.find((entry) => entry.toLowerCase().endsWith("vsdevcmd.bat")); + if (path) return path; + } catch (error) { + throw new Error(`Unable to locate Visual Studio C++ tools with vswhere: ${String(error)}`); + } + throw new Error("Visual Studio C++ tools are missing (VsDevCmd.bat was not found)"); +} + +export function quoteResponsePath(value: string): string { + if (value.includes('"')) throw new Error("build paths may not contain quotes"); + return `"${value}"`; +} + +export function buildHelper(arch = targetArchitecture(), env = process.env): string { + if (process.platform !== "win32") + throw new Error("The Win32 helper can only be built on Windows"); + const hostArch = process.arch === "arm64" ? "arm64" : "x64"; + const outputDir = join(ROOT, "build", "ffi-pty", `win32-${arch}`); + mkdirSync(outputDir, { recursive: true }); + const executable = join(outputDir, "helper.exe"); + const response = join(tmpdir(), `pty-helper-${process.pid}-${arch}.rsp`); + const arguments_ = [ + "/nologo", + "/std:c++17", + "/EHsc", + "/W4", + "/WX", + "/O2", + "/MT", + "/DUNICODE", + "/D_UNICODE", + "/D_WIN32_WINNT=0x0A00", + "/DWINVER=0x0A00", + `/Fe${quoteResponsePath(executable)}`, + `/Fo${quoteResponsePath(`${outputDir}/`)}`, + quoteResponsePath(join(SOURCE, "windows_helper.cpp")), + quoteResponsePath(join(SOURCE, "windows_helper_protocol.cpp")), + ]; + writeFileSync(response, `${arguments_.join("\r\n")}\r\n`, "utf8"); + const vsDevCmd = findVsDevCmd(env); + const command = `call "${vsDevCmd}" -no_logo -arch=${arch} -host_arch=${hostArch} && cl.exe @"${response}"`; + const result = spawnSync("cmd.exe", ["/d", "/s", "/c", command], { + cwd: ROOT, + env, + encoding: "utf8", + windowsHide: true, + windowsVerbatimArguments: true, + }); + if (result.stdout) process.stdout.write(result.stdout); + if (result.stderr) process.stderr.write(result.stderr); + if (result.error) throw result.error; + if (result.status !== 0) + throw new Error(`MSVC helper build failed with exit code ${result.status}`); + + const bytes = statSync(executable).size; + const compressedBytes = gzipSync(readFileSync(executable), { level: 9 }).length; + const summary = `Windows helper (${arch}): ${bytes} bytes (${(bytes / 1024).toFixed(1)} KiB), gzip ${compressedBytes} bytes (${(compressedBytes / 1024).toFixed(1)} KiB) at ${executable}`; + console.log(summary); + if (env.GITHUB_STEP_SUMMARY) + writeFileSync(env.GITHUB_STEP_SUMMARY, `${summary}\n`, { flag: "a" }); + return executable; +} + +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + try { + buildHelper(); + } catch (error) { + console.error(error instanceof Error ? error.message : String(error)); + process.exitCode = 1; + } +} diff --git a/experiments/ffi-pty/contract.mts b/experiments/ffi-pty/contract.mts new file mode 100644 index 000000000..5c9fb240e --- /dev/null +++ b/experiments/ffi-pty/contract.mts @@ -0,0 +1,55 @@ +import type { Readable } from "node:stream"; + +export interface ExitStatus { + exitCode: number | null; + signal: number; +} + +export interface SpawnOptions { + file: string; + args: string[]; + cols: number; + rows: number; + cwd: string; + env: Record; +} + +export interface SpawnOptionsInput { + cols?: number; + rows?: number; + cwd?: string; + env?: Record; + encoding?: "utf8"; + uid?: never; + gid?: never; + pixelWidth?: never; + pixelHeight?: never; + useConptyDll?: never; + conptyInheritCursor?: never; + [key: string]: unknown; +} + +export interface Backend { + pid: number; + readable: Readable; + write(data: Buffer): Promise; + resize(cols: number, rows: number): Promise; + kill(signal?: string): Promise; + close(): Promise; + exited: Promise; +} + +export interface FfiPty { + readonly pid: number; + readonly cols: number; + readonly rows: number; + readonly exited: Promise; + onData(listener: (data: string) => void): { dispose(): void }; + onExit(listener: (status: ExitStatus) => void): { dispose(): void }; + write(data: string | Buffer): Promise; + resize(cols: number, rows: number): Promise; + kill(signal?: string): Promise; + pause(): void; + resume(): void; + close(): Promise; +} diff --git a/experiments/ffi-pty/darwin-bootstrap.mts b/experiments/ffi-pty/darwin-bootstrap.mts new file mode 100644 index 000000000..d7b7d56a4 --- /dev/null +++ b/experiments/ffi-pty/darwin-bootstrap.mts @@ -0,0 +1,61 @@ +import { dlopen, getInt32 } from "node:ffi"; +import { fileURLToPath } from "node:url"; + +export function loginControllingTerminal(): void { + const { functions } = dlopen("/usr/lib/libSystem.B.dylib", { + login_tty: { arguments: ["int32"], return: "int32" }, + __error: { arguments: [], return: "pointer" }, + }); + if (functions.login_tty(0) !== 0) { + throw new Error(`login_tty failed with errno ${getInt32(functions.__error())}`); + } +} + +export function resetIgnoredSignals(): void { + const { functions } = dlopen("/usr/lib/libSystem.B.dylib", { + signal: { arguments: ["int32", "pointer"], return: "pointer" }, + }); + // Node ignores SIGPIPE and SIGXFSZ. Exec preserves ignored dispositions. + functions.signal(13, 0n); + functions.signal(25, 0n); +} + +export function recoverTargetEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv { + const privateKey = "PTY_FFI_TARGET_NODE_ENV"; + const payload = env[privateKey]; + const base = { ...env }; + delete base[privateKey]; + return { ...base, ...(payload ? JSON.parse(payload) : {}) }; +} + +export function splitTargetEnvironment(env: Record): Record { + const bootstrapEnv = Object.create(null) as Record; + const nodeEnv = Object.create(null) as Record; + for (const [key, value] of Object.entries(env)) { + if (key.startsWith("NODE_") || key === "PTY_FFI_TARGET_NODE_ENV") nodeEnv[key] = value; + else bootstrapEnv[key] = value; + } + bootstrapEnv.PTY_FFI_TARGET_NODE_ENV = JSON.stringify(nodeEnv); + return bootstrapEnv; +} + +export function execTarget(argv: string[], env: NodeJS.ProcessEnv): never { + const [executable, argv0, ...args] = argv; + if (!executable || !argv0) throw new Error("Invalid Darwin PTY bootstrap arguments"); + resetIgnoredSignals(); + const targetEnv = recoverTargetEnvironment(env); + process.execve(executable, [argv0, ...args], targetEnv); + throw new Error("process.execve unexpectedly returned"); +} + +if (process.argv[1] === fileURLToPath(import.meta.url)) { + try { + loginControllingTerminal(); + execTarget(process.argv.slice(2), process.env); + } catch (error) { + process.stderr.write( + `PTY child bootstrap failed: ${error instanceof Error ? error.message : String(error)}\n`, + ); + process.exitCode = 127; + } +} diff --git a/experiments/ffi-pty/darwin.mts b/experiments/ffi-pty/darwin.mts new file mode 100644 index 000000000..1a5a44215 --- /dev/null +++ b/experiments/ffi-pty/darwin.mts @@ -0,0 +1,188 @@ +import { dlopen, getInt32 } from "node:ffi"; +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { fileURLToPath } from "node:url"; +import { constants as osConstants } from "node:os"; +import { createUnixBackend } from "./unix-common.mts"; +import type { SpawnOptions } from "./contract.mts"; +import type { UnixBindings } from "./unix-common.mts"; +import { makePointerVector, resolveExecutable } from "./unix-native.mts"; +import { splitTargetEnvironment } from "./darwin-bootstrap.mts"; + +const execFileAsync = promisify(execFile); +const { functions: c } = dlopen("/usr/lib/libSystem.B.dylib", { + openpty: { arguments: ["pointer", "pointer", "pointer", "pointer", "pointer"], return: "int32" }, + close: { arguments: ["int32"], return: "int32" }, + posix_spawnattr_init: { arguments: ["pointer"], return: "int32" }, + posix_spawnattr_setflags: { arguments: ["pointer", "int16"], return: "int32" }, + posix_spawnattr_setsigmask: { arguments: ["pointer", "pointer"], return: "int32" }, + posix_spawnattr_setsigdefault: { arguments: ["pointer", "pointer"], return: "int32" }, + posix_spawnattr_destroy: { arguments: ["pointer"], return: "int32" }, + posix_spawn_file_actions_init: { arguments: ["pointer"], return: "int32" }, + posix_spawn_file_actions_addopen: { + arguments: ["pointer", "int32", "string", "int32", "uint16"], + return: "int32", + }, + posix_spawn_file_actions_adddup2: { arguments: ["pointer", "int32", "int32"], return: "int32" }, + posix_spawn_file_actions_addclose: { arguments: ["pointer", "int32"], return: "int32" }, + posix_spawn_file_actions_addchdir_np: { arguments: ["pointer", "string"], return: "int32" }, + posix_spawn_file_actions_destroy: { arguments: ["pointer"], return: "int32" }, + posix_spawn: { + arguments: ["pointer", "string", "pointer", "pointer", "pointer", "pointer"], + return: "int32", + }, + waitpid: { arguments: ["int32", "pointer", "int32"], return: "int32" }, + kill: { arguments: ["int32", "int32"], return: "int32" }, + __error: { arguments: [], return: "pointer" }, +}); + +const SIGNALS = osConstants.signals; + +export function nativeErrno(): number { + return getInt32(c.__error()); +} + +export function checked(result: number, operation: string): void { + if (result !== 0) throw new Error(`${operation} failed with errno ${result}`); +} + +export function spawn(options: SpawnOptions) { + const executable = resolveExecutable(options.file, options.cwd, options.env); + const bootstrapPath = fileURLToPath(new URL("./darwin-bootstrap.mts", import.meta.url)); + const childEnv = splitTargetEnvironment(options.env); + const masterOut = Buffer.alloc(4); + const slaveOut = Buffer.alloc(4); + const nameOut = Buffer.alloc(1024); + const size = Buffer.alloc(8); + size.writeUInt16LE(options.rows, 0); + size.writeUInt16LE(options.cols, 2); + if (c.openpty(masterOut, slaveOut, nameOut, null, size) !== 0) { + throw new Error(`openpty failed with errno ${nativeErrno()}`); + } + const masterFd = masterOut.readInt32LE(); + const slaveFd = slaveOut.readInt32LE(); + if (masterFd < 3 || slaveFd < 3) { + c.close(masterFd); + c.close(slaveFd); + throw new Error("openpty returned a descriptor that conflicts with standard I/O"); + } + const terminator = nameOut.indexOf(0); + if (terminator < 0) { + c.close(masterFd); + c.close(slaveFd); + throw new Error("openpty returned an unterminated slave name"); + } + const slaveName = nameOut.toString("utf8", 0, terminator); + const attr = Buffer.alloc(8); + const actions = Buffer.alloc(8); + const emptySignalSet = Buffer.alloc(4); + const defaultSignalSet = Buffer.alloc(4); + // Reset every catchable signal to its default disposition in the child. In + // particular, Node may ignore SIGPIPE in the parent process. + const defaultMask = 0xffffffff & ~(1 << (9 - 1)) & ~(1 << (17 - 1)); + defaultSignalSet.writeUInt32LE(defaultMask >>> 0); + const pidOut = Buffer.alloc(4); + let attrReady = false; + let actionsReady = false; + let spawned = false; + try { + checked(c.posix_spawnattr_init(attr), "posix_spawnattr_init"); + attrReady = true; + checked(c.posix_spawnattr_setsigmask(attr, emptySignalSet), "posix_spawnattr_setsigmask"); + checked( + c.posix_spawnattr_setsigdefault(attr, defaultSignalSet), + "posix_spawnattr_setsigdefault", + ); + // The bootstrap calls login_tty(), which creates a session and controlling TTY. + // Darwin SDK: SETSIGDEF=0x04, SETSIGMASK=0x08, CLOEXEC_DEFAULT=0x4000. + checked(c.posix_spawnattr_setflags(attr, 0x0004 | 0x0008 | 0x4000), "posix_spawnattr_setflags"); + checked(c.posix_spawn_file_actions_init(actions), "posix_spawn_file_actions_init"); + actionsReady = true; + checked( + c.posix_spawn_file_actions_addchdir_np(actions, options.cwd), + "posix_spawn_file_actions_addchdir_np", + ); + checked( + c.posix_spawn_file_actions_addopen(actions, 0, slaveName, 2, 0), + "attach controlling terminal", + ); + checked(c.posix_spawn_file_actions_adddup2(actions, 0, 1), "dup stdin to stdout"); + checked(c.posix_spawn_file_actions_adddup2(actions, 0, 2), "dup stdin to stderr"); + checked(c.posix_spawn_file_actions_addclose(actions, masterFd), "close child master"); + checked(c.posix_spawn_file_actions_addclose(actions, slaveFd), "close child parent slave"); + const argv = makePointerVector([ + process.execPath, + "--experimental-ffi", + bootstrapPath, + executable, + options.file, + ...options.args, + ]); + const env = makePointerVector( + Object.entries(childEnv).map(([key, value]) => `${key}=${value}`), + ); + const result = c.posix_spawn( + pidOut, + process.execPath, + actions, + attr, + argv.pointers, + env.pointers, + ); + // Keep native C strings and pointer arrays live until the native call returns. + void argv.buffers; + void env.buffers; + if (result !== 0) throw new Error(`posix_spawn failed with errno ${result}`); + spawned = true; + } finally { + if (actionsReady) c.posix_spawn_file_actions_destroy(actions); + if (attrReady) c.posix_spawnattr_destroy(attr); + c.close(slaveFd); + if (!spawned) c.close(masterFd); + } + return { pid: pidOut.readInt32LE(), masterFd, slaveName }; +} + +export function wait(pid: number) { + const status = Buffer.alloc(4); + const found = c.waitpid(pid, status, 1); + if (found < 0) { + const errno = nativeErrno(); + if (errno === 4) return null; // EINTR; the shared poll loop will retry. + throw new Error(`waitpid failed with errno ${errno}`); + } + if (!found) return null; + const raw = status.readInt32LE(); + return { exitCode: (raw & 0x7f) === 0 ? (raw >>> 8) & 0xff : null, signal: raw & 0x7f }; +} + +export function kill(pid: number, signal: string) { + const number = SIGNALS[signal] ?? Number(signal); + if (!Number.isInteger(number) || number < 0 || number > 31) + throw new TypeError(`Unsupported signal: ${signal}`); + if (c.kill(pid, number) !== 0) { + const errno = nativeErrno(); + if (errno !== 3) throw new Error(`kill failed with errno ${errno}`); + } +} + +export async function resize(slaveName: string, cols: number, rows: number): Promise { + await execFileAsync("/bin/stty", ["-f", slaveName, "rows", String(rows), "cols", String(cols)], { + timeout: 2000, + maxBuffer: 1024, + }); +} + +const bindings: UnixBindings = { + spawn, + wait, + kill, + resize, + closeFd: (fd) => { + c.close(fd); + }, +}; + +export async function createBackend(options: SpawnOptions) { + return createUnixBackend(options, bindings); +} diff --git a/experiments/ffi-pty/events.mts b/experiments/ffi-pty/events.mts new file mode 100644 index 000000000..f40ebbbf8 --- /dev/null +++ b/experiments/ffi-pty/events.mts @@ -0,0 +1,170 @@ +import { setImmediate as defer } from "node:timers"; +import { StringDecoder } from "node:string_decoder"; +import type { Backend, ExitStatus, FfiPty } from "./contract.mts"; +import { validateDimension } from "./validation.mts"; + +export function createPtyFromBackend( + backend: Backend, + initialCols: number, + initialRows: number, +): FfiPty { + const decoder = new StringDecoder("utf8"); + const dataListeners = new Set<(data: string) => void>(); + const exitListeners = new Set<(status: ExitStatus) => void>(); + let cols = initialCols; + let rows = initialRows; + let paused = false; + let closing = false; + let outputEnded = false; + let status: ExitStatus | undefined; + let streamError: Error | undefined; + let settled = false; + let closePromise: Promise | undefined; + let resolveExit!: (status: ExitStatus) => void; + let rejectExit!: (error: Error) => void; + const exited = new Promise((resolve, reject) => { + resolveExit = resolve; + rejectExit = reject; + }); + void exited.catch(() => {}); + + const cleanupBackend = () => { + if (closePromise) return; + closing = true; + paused = false; + backend.readable.resume(); + closePromise = backend.close(); + void closePromise.catch(() => {}); + }; + + const settle = () => { + if (settled) return; + if (streamError) { + settled = true; + rejectExit(streamError); + return; + } + if (!outputEnded || !status) return; + settled = true; + for (const listener of [...exitListeners]) { + try { + listener(status); + } catch (error) { + queueMicrotask(() => { + throw error; + }); + } + } + resolveExit(status); + }; + const emit = (value: string) => { + if (!value) return; + for (const listener of [...dataListeners]) { + try { + listener(value); + } catch (error) { + queueMicrotask(() => { + throw error; + }); + } + } + }; + const onData = (chunk: Buffer | string) => { + emit(typeof chunk === "string" ? decoder.write(Buffer.from(chunk)) : decoder.write(chunk)); + }; + const onEnd = () => { + emit(decoder.end()); + outputEnded = true; + settle(); + }; + const onError = (error: Error) => { + streamError = error; + outputEnded = true; + settle(); + cleanupBackend(); + }; + backend.readable.pause(); + backend.readable.on("data", onData); + backend.readable.once("end", onEnd); + backend.readable.once("error", onError); + defer(() => { + if (!paused && !closing) backend.readable.resume(); + }); + backend.exited.then( + (value) => { + status = value; + settle(); + }, + (error: unknown) => { + streamError = error instanceof Error ? error : new Error(String(error)); + settle(); + cleanupBackend(); + }, + ); + + return { + pid: backend.pid, + get cols() { + return cols; + }, + get rows() { + return rows; + }, + exited, + onData(listener) { + dataListeners.add(listener); + return { dispose: () => dataListeners.delete(listener) }; + }, + onExit(listener) { + exitListeners.add(listener); + let active = true; + if (settled && status && !streamError) + queueMicrotask(() => { + if (active) listener(status!); + }); + return { + dispose: () => { + active = false; + exitListeners.delete(listener); + }, + }; + }, + async write(data) { + if (closing) throw new Error("PTY is closed"); + if (status || outputEnded || settled) throw new Error("PTY has exited"); + const bytes = Buffer.isBuffer(data) ? Buffer.from(data) : Buffer.from(data, "utf8"); + await backend.write(bytes); + }, + async resize(nextCols, nextRows) { + if (closing) throw new Error("PTY is closed"); + if (status || outputEnded || settled) throw new Error("PTY has exited"); + validateDimension(nextCols, "cols"); + validateDimension(nextRows, "rows"); + await backend.resize(nextCols, nextRows); + cols = nextCols; + rows = nextRows; + }, + async kill(signal) { + if (!closing && !status && !settled) await backend.kill(signal); + }, + pause() { + if (paused || closing) return; + paused = true; + backend.readable.pause(); + }, + resume() { + if (!paused || closing) return; + paused = false; + backend.readable.resume(); + }, + close() { + if (!closePromise) { + closing = true; + paused = false; + backend.readable.resume(); + closePromise = backend.close(); + } + return closePromise; + }, + }; +} diff --git a/experiments/ffi-pty/linux.mts b/experiments/ffi-pty/linux.mts new file mode 100644 index 000000000..4c5c052a6 --- /dev/null +++ b/experiments/ffi-pty/linux.mts @@ -0,0 +1,194 @@ +import { dlopen, getInt32 } from "node:ffi"; +import { execFile as execFileCallback } from "node:child_process"; +import { constants as osConstants } from "node:os"; +import { promisify } from "node:util"; +import { createUnixBackend, type UnixBindings } from "./unix-common.mts"; +import { makePointerVector, resolveExecutable } from "./unix-native.mts"; +import type { SpawnOptions } from "./contract.mts"; + +if (process.platform !== "linux" || (process.arch !== "x64" && process.arch !== "arm64")) { + throw new Error("The Linux FFI PTY backend requires Linux x64 or ARM64"); +} +export function assertSupportedGlibc( + version = process.report?.getReport().header.glibcVersionRuntime, +): void { + const match = version?.match(/^(\d+)\.(\d+)/); + if (!match || Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 34)) { + throw new Error( + `The Linux FFI PTY backend requires glibc 2.34 or newer (found ${version ?? "unknown"})`, + ); + } +} +let c: any; +export function isLinuxNativeLoaded(): boolean { + return c !== undefined; +} + +export function getLibcFunctions() { + if (c) return c; + assertSupportedGlibc(); + c = dlopen("libc.so.6", { + openpty: { + arguments: ["pointer", "pointer", "pointer", "pointer", "pointer"], + return: "int32", + }, + posix_spawnattr_init: { arguments: ["pointer"], return: "int32" }, + posix_spawnattr_setflags: { arguments: ["pointer", "int16"], return: "int32" }, + posix_spawnattr_setsigdefault: { arguments: ["pointer", "pointer"], return: "int32" }, + posix_spawnattr_setsigmask: { arguments: ["pointer", "pointer"], return: "int32" }, + posix_spawnattr_destroy: { arguments: ["pointer"], return: "int32" }, + posix_spawn_file_actions_init: { arguments: ["pointer"], return: "int32" }, + posix_spawn_file_actions_addopen: { + arguments: ["pointer", "int32", "string", "int32", "uint32"], + return: "int32", + }, + posix_spawn_file_actions_adddup2: { arguments: ["pointer", "int32", "int32"], return: "int32" }, + posix_spawn_file_actions_addclosefrom_np: { arguments: ["pointer", "int32"], return: "int32" }, + posix_spawn_file_actions_addchdir_np: { arguments: ["pointer", "string"], return: "int32" }, + posix_spawn_file_actions_destroy: { arguments: ["pointer"], return: "int32" }, + posix_spawn: { + arguments: ["pointer", "string", "pointer", "pointer", "pointer", "pointer"], + return: "int32", + }, + sigemptyset: { arguments: ["pointer"], return: "int32" }, + sigaddset: { arguments: ["pointer", "int32"], return: "int32" }, + close: { arguments: ["int32"], return: "int32" }, + __errno_location: { arguments: [], return: "pointer" }, + waitpid: { arguments: ["int32", "pointer", "int32"], return: "int32" }, + kill: { arguments: ["int32", "int32"], return: "int32" }, + }).functions; + return c; +} +export const GLIBC_LP64_ABI = Object.freeze({ + spawnAttrBytes: 336, + fileActionsBytes: 80, + sigsetBytes: 128, + modeBytes: 4, +}); + +export function readErrno(): number { + const c = getLibcFunctions(); + return getInt32(c.__errno_location()); +} + +export function spawnLinux({ file, args, cols, rows, cwd, env }: SpawnOptions) { + const c = getLibcFunctions(); + const masterOut = Buffer.alloc(4), + slaveOut = Buffer.alloc(4), + name = Buffer.alloc(256); + const size = Buffer.alloc(8); + size.writeUInt16LE(rows, 0); + size.writeUInt16LE(cols, 2); + const rc = c.openpty(masterOut, slaveOut, name, null, size); + if (rc !== 0) throw new Error(`openpty failed (errno ${readErrno()})`); + const masterFd = masterOut.readInt32LE(), + slaveFd = slaveOut.readInt32LE(); + const slaveName = name.toString("utf8", 0, name.indexOf(0)); + if (masterFd < 3 || slaveFd < 3) { + c.close(masterFd); + c.close(slaveFd); + throw new Error("openpty returned a standard descriptor; cannot safely spawn"); + } + const attr = Buffer.alloc(GLIBC_LP64_ABI.spawnAttrBytes), + actions = Buffer.alloc(GLIBC_LP64_ABI.fileActionsBytes), + pidOut = Buffer.alloc(4); + let attrReady = false, + actionsReady = false, + spawned = false; + const ck = (result: number, op: string) => { + if (result !== 0) throw new Error(`${op} failed with ${result}`); + }; + try { + ck(c.posix_spawnattr_init(attr), "posix_spawnattr_init"); + attrReady = true; + const sigdefault = Buffer.alloc(GLIBC_LP64_ABI.sigsetBytes), + sigmask = Buffer.alloc(GLIBC_LP64_ABI.sigsetBytes); + ck(c.sigemptyset(sigdefault), "sigemptyset"); + // Reset caught signals to default in the child; clear inherited blocked mask. + for (let sig = 1; sig <= 64; sig++) { + // Linux reserves 32 and 33 for the threading runtime; glibc rejects them. + if (sig !== 9 && sig !== 19 && sig !== 32 && sig !== 33) + ck(c.sigaddset(sigdefault, sig), "sigaddset"); + } + ck(c.sigemptyset(sigmask), "sigemptyset"); + ck(c.posix_spawnattr_setsigdefault(attr, sigdefault), "setsigdefault"); + ck(c.posix_spawnattr_setsigmask(attr, sigmask), "setsigmask"); + ck(c.posix_spawnattr_setflags(attr, 0x80 | 0x04 | 0x08), "set spawn flags"); + ck(c.posix_spawn_file_actions_init(actions), "actions init"); + actionsReady = true; + ck(c.posix_spawn_file_actions_addopen(actions, 0, slaveName, 2, 0), "open slave in child"); + ck(c.posix_spawn_file_actions_adddup2(actions, 0, 1), "dup stdout"); + ck(c.posix_spawn_file_actions_adddup2(actions, 0, 2), "dup stderr"); + ck(c.posix_spawn_file_actions_addchdir_np(actions, cwd), "set child cwd"); + ck(c.posix_spawn_file_actions_addclosefrom_np(actions, 3), "close child descriptors"); + const executable = resolveExecutable(file, cwd, env); + const argv = makePointerVector([file, ...args]); + const envp = makePointerVector(Object.entries(env).map(([k, v]) => `${k}=${v}`)); + // Resolve against the requested child cwd and PATH before spawning, since + // posix_spawnp searches the parent's PATH before the chdir action runs. + ck( + c.posix_spawn(pidOut, executable, actions, attr, argv.pointers, envp.pointers), + "posix_spawn", + ); + void argv.buffers; + void envp.buffers; + spawned = true; + } finally { + if (actionsReady) c.posix_spawn_file_actions_destroy(actions); + if (attrReady) c.posix_spawnattr_destroy(attr); + c.close(slaveFd); + if (!spawned) c.close(masterFd); + } + return { pid: pidOut.readInt32LE(), masterFd, slaveName }; +} + +export function waitLinux(pid: number) { + const c = getLibcFunctions(); + const status = Buffer.alloc(4); + const found = c.waitpid(pid, status, 1); + if (found === 0) return null; + if (found < 0) { + const error = readErrno(); + if (error === 4) return null; // EINTR + throw new Error(`waitpid failed (errno ${error})`); + } + const raw = status.readInt32LE(), + sig = raw & 0x7f; + return { exitCode: sig === 0 ? (raw >>> 8) & 0xff : null, signal: sig }; +} + +export function killLinux(pid: number, signal = "SIGTERM"): void { + const c = getLibcFunctions(); + const number = + typeof signal === "number" + ? signal + : osConstants.signals[signal as keyof typeof osConstants.signals]; + if (!number) throw new Error(`Unknown signal: ${signal}`); + if (c.kill(pid, number) !== 0) throw new Error(`kill failed (errno ${readErrno()})`); +} + +const runFile = promisify(execFileCallback); +export async function resizeLinux(slaveName: string, cols: number, rows: number): Promise { + await runFile("/bin/stty", ["-F", slaveName, "rows", String(rows), "cols", String(cols)], { + timeout: 2000, + }); +} + +export function closeLinuxFd(fd: number): void { + const c = getLibcFunctions(); + if (c.close(fd) !== 0) throw new Error(`close failed (errno ${readErrno()})`); +} + +export function createLinuxBindings(): UnixBindings { + return { + spawn: spawnLinux, + wait: waitLinux, + kill: killLinux, + resize: resizeLinux, + closeFd: closeLinuxFd, + }; +} + +export async function createBackend(options: SpawnOptions) { + return createUnixBackend(options, createLinuxBindings()); +} diff --git a/experiments/ffi-pty/native/windows_helper.cpp b/experiments/ffi-pty/native/windows_helper.cpp new file mode 100644 index 000000000..0408028a3 --- /dev/null +++ b/experiments/ffi-pty/native/windows_helper.cpp @@ -0,0 +1,344 @@ +#include +#include +#include +#include +#include +#include +#include +#include + +#include "windows_helper_protocol.h" + +namespace pty_helper { +namespace { +constexpr DWORD kPipeFlags = PIPE_TYPE_BYTE | PIPE_READMODE_BYTE | PIPE_WAIT | PIPE_REJECT_REMOTE_CLIENTS; +constexpr DWORD kFirstInstance = FILE_FLAG_FIRST_PIPE_INSTANCE; +constexpr DWORD kCreateUnicodeEnvironment = 0x00000400; +constexpr DWORD kExtendedStartupInfo = 0x00080000; +constexpr DWORD kStartfUseStdHandles = 0x00000100; +constexpr DWORD kJobObjectExtendedLimitInformation = 9; +constexpr DWORD kJobObjectLimitKillOnJobClose = 0x00002000; +constexpr DWORD kProcThreadAttributePseudoConsole = 0x00020016; +constexpr DWORD kProcThreadAttributeJobList = 0x0002000d; +constexpr size_t kMaxQueuedCommands = 1024; + +HANDLE g_input = INVALID_HANDLE_VALUE; +HANDLE g_output = INVALID_HANDLE_VALUE; +HANDLE g_job = nullptr; +HANDLE g_process = nullptr; +HANDLE g_thread = nullptr; +HANDLE g_commandEvent = nullptr; +HANDLE g_reader = nullptr; +HPCON g_conpty = nullptr; +CRITICAL_SECTION g_queueLock; +std::vector g_commands; +std::atomic g_parentGone{false}; +std::atomic g_readerFailed{false}; +std::atomic g_stopReader{false}; +bool g_closeRequested = false; +bool g_queueInitialized = false; +std::atomic g_terminationSignal{0}; +} + +std::string WinError(const char* operation) { + return std::string(operation) + " failed with Win32 error " + std::to_string(GetLastError()); +} + +void Close(HANDLE* handle) { + if (*handle && *handle != INVALID_HANDLE_VALUE) CloseHandle(*handle); + *handle = nullptr; +} + +void StopReader() { + if (!g_reader) return; + g_stopReader = true; + CancelSynchronousIo(g_reader); + if (WaitForSingleObject(g_reader, 0) == WAIT_OBJECT_0) Close(&g_reader); +} + +[[noreturn]] void AbortHelper() { + TerminateJob(1); + ExitProcess(1); +} + +void CloseJob() { + HANDLE job = nullptr; + if (g_queueInitialized) EnterCriticalSection(&g_queueLock); + job = g_job; + g_job = nullptr; + if (g_queueInitialized) LeaveCriticalSection(&g_queueLock); + if (job) CloseHandle(job); +} + +bool TerminateJob(DWORD code) { + if (g_queueInitialized) EnterCriticalSection(&g_queueLock); + const HANDLE job = g_job; + const BOOL terminated = job && TerminateJobObject(job, code); + const DWORD error = terminated ? ERROR_SUCCESS : GetLastError(); + if (g_queueInitialized) LeaveCriticalSection(&g_queueLock); + if (!terminated) SetLastError(error); + return terminated != FALSE; +} + +void Cleanup() { + CloseJob(); + StopReader(); + const bool readerStopped = !g_reader; + if (g_process) { + WaitForSingleObject(g_process, 5000); + CloseHandle(g_process); + g_process = nullptr; + } + if (g_thread) Close(&g_thread); + if (g_conpty) { + ClosePseudoConsole(g_conpty); + g_conpty = nullptr; + } + if (g_input != INVALID_HANDLE_VALUE) CloseHandle(g_input); + if (g_output != INVALID_HANDLE_VALUE) CloseHandle(g_output); + g_input = g_output = INVALID_HANDLE_VALUE; + if (readerStopped) { + Close(&g_commandEvent); + if (g_queueInitialized) { + DeleteCriticalSection(&g_queueLock); + g_queueInitialized = false; + } + } +} + +bool Fail(const std::string& message) { + WriteUtf8(GetStdHandle(STD_OUTPUT_HANDLE), Opcode::Error, 0, message); + return false; +} + +HANDLE CreatePipe(const std::wstring& name) { + HANDLE handle = CreateNamedPipeW(name.c_str(), PIPE_ACCESS_DUPLEX | kFirstInstance, + kPipeFlags, 1, 65536, 65536, 0, nullptr); + if (handle == INVALID_HANDLE_VALUE) throw std::runtime_error(WinError("CreateNamedPipeW")); + return handle; +} + +bool Connect(HANDLE pipe) { + if (ConnectNamedPipe(pipe, nullptr)) return true; + return GetLastError() == ERROR_PIPE_CONNECTED; +} + +bool CreateTarget(const StartOptions& options, uint32_t* pid) { + g_input = CreatePipe(options.inputName); + g_output = CreatePipe(options.outputName); + if (!WriteFrame(GetStdHandle(STD_OUTPUT_HANDLE), Opcode::Pipes, 0, nullptr, 0)) return false; + Frame connected{}; + if (!ReadFrame(GetStdHandle(STD_INPUT_HANDLE), &connected) || connected.opcode != Opcode::Connected || + connected.id != 0 || !connected.payload.empty()) return false; + if (!Connect(g_input) || !Connect(g_output)) throw std::runtime_error(WinError("ConnectNamedPipe")); + + COORD size{static_cast(options.cols), static_cast(options.rows)}; + HRESULT result = CreatePseudoConsole(size, g_input, g_output, 0, &g_conpty); + if (FAILED(result)) throw std::runtime_error("CreatePseudoConsole failed with HRESULT " + std::to_string(static_cast(result))); + + g_job = CreateJobObjectW(nullptr, nullptr); + if (!g_job) throw std::runtime_error(WinError("CreateJobObjectW")); + JOBOBJECT_EXTENDED_LIMIT_INFORMATION jobInfo{}; + jobInfo.BasicLimitInformation.LimitFlags = kJobObjectLimitKillOnJobClose; + if (!SetInformationJobObject(g_job, static_cast(kJobObjectExtendedLimitInformation), + &jobInfo, static_cast(sizeof(jobInfo)))) throw std::runtime_error(WinError("SetInformationJobObject")); + + SIZE_T attributeBytes = 0; + InitializeProcThreadAttributeList(nullptr, 2, 0, &attributeBytes); + if (!attributeBytes || attributeBytes > 65536) throw std::runtime_error("Invalid process attribute list size"); + std::vector attributes(attributeBytes); + auto* attributeList = reinterpret_cast(attributes.data()); + if (!InitializeProcThreadAttributeList(attributeList, 2, 0, &attributeBytes)) throw std::runtime_error(WinError("InitializeProcThreadAttributeList")); + HANDLE jobList[] = {g_job}; + bool attributesReady = true; + auto deleteAttributes = [&]() { + if (attributesReady) { + DeleteProcThreadAttributeList(attributeList); + attributesReady = false; + } + }; + if (!UpdateProcThreadAttribute(attributeList, 0, kProcThreadAttributePseudoConsole, g_conpty, sizeof(g_conpty), nullptr, nullptr) || + !UpdateProcThreadAttribute(attributeList, 0, kProcThreadAttributeJobList, jobList, sizeof(jobList), nullptr, nullptr)) { + const auto error = WinError("UpdateProcThreadAttribute"); + deleteAttributes(); + throw std::runtime_error(error); + } + + STARTUPINFOEXW startup{}; + startup.StartupInfo.cb = static_cast(sizeof(startup)); + startup.StartupInfo.dwFlags = kStartfUseStdHandles; + startup.lpAttributeList = attributeList; + PROCESS_INFORMATION process{}; + std::vector command(options.commandLine.begin(), options.commandLine.end()); + command.push_back(L'\0'); + const BOOL created = CreateProcessW(options.application.c_str(), command.data(), nullptr, nullptr, + FALSE, kExtendedStartupInfo | kCreateUnicodeEnvironment, + const_cast(options.environment.data()), options.cwd.c_str(), + &startup.StartupInfo, &process); + if (!created) { + const auto error = WinError("CreateProcessW"); + deleteAttributes(); + throw std::runtime_error(error); + } + deleteAttributes(); + g_process = process.hProcess; + g_thread = process.hThread; + Close(&g_thread); + CloseHandle(g_input); + CloseHandle(g_output); + g_input = g_output = INVALID_HANDLE_VALUE; + *pid = process.dwProcessId; + return true; +} + +void Queue(const QueuedCommand& command) { + EnterCriticalSection(&g_queueLock); + if (g_commands.size() >= kMaxQueuedCommands) g_readerFailed = true; + else g_commands.push_back(command); + LeaveCriticalSection(&g_queueLock); + SetEvent(g_commandEvent); +} + +DWORD WINAPI ReadCommands(void*) { + HANDLE input = GetStdHandle(STD_INPUT_HANDLE); + while (!g_stopReader) { + Frame frame{}; + if (!ReadFrame(input, &frame)) { + if (g_stopReader) return 0; + g_parentGone = true; + AbortHelper(); + } + QueuedCommand command{frame.opcode, frame.id, 0, 0}; + if (frame.opcode == Opcode::Resize) { + if (frame.payload.size() != 8) g_readerFailed = true; + else { + std::memcpy(&command.first, frame.payload.data(), 4); + std::memcpy(&command.second, frame.payload.data() + 4, 4); + } + } else if (frame.opcode == Opcode::Kill) { + if (frame.payload.size() != 4) g_readerFailed = true; + else std::memcpy(&command.first, frame.payload.data(), 4); + } else if ((frame.opcode == Opcode::Close || frame.opcode == Opcode::Abort) && frame.payload.empty()) { + // No payload. + } else { + g_readerFailed = true; + } + if (g_readerFailed) { + AbortHelper(); + } + Queue(command); + if (g_readerFailed) { + AbortHelper(); + } + } + return 0; +} + +bool Ack(uint32_t id, const std::string& error) { + return WriteUtf8(GetStdHandle(STD_OUTPUT_HANDLE), Opcode::Ack, id, error); +} + +bool RunTarget(uint32_t pid) { + if (!WriteU32(GetStdHandle(STD_OUTPUT_HANDLE), Opcode::Spawned, 0, pid)) return false; + InitializeCriticalSection(&g_queueLock); + g_queueInitialized = true; + g_commandEvent = CreateEventW(nullptr, TRUE, FALSE, nullptr); + if (!g_commandEvent) return Fail(WinError("CreateEventW")); + g_reader = CreateThread(nullptr, 0, ReadCommands, nullptr, 0, nullptr); + if (!g_reader) return Fail(WinError("CreateThread")); + + bool done = false; + while (!done) { + if (g_parentGone || g_readerFailed) { + g_terminationSignal = 1; + CloseJob(); + break; + } + const DWORD processState = WaitForSingleObject(g_process, 0); + if (processState == WAIT_FAILED) return Fail(WinError("WaitForSingleObject")); + if (processState == WAIT_OBJECT_0) { + EnterCriticalSection(&g_queueLock); + const bool hasCommands = !g_commands.empty(); + LeaveCriticalSection(&g_queueLock); + if (!hasCommands) break; + } + const DWORD eventState = WaitForSingleObject(g_commandEvent, processState == WAIT_OBJECT_0 ? 0 : 50); + if (eventState == WAIT_TIMEOUT) continue; + if (eventState != WAIT_OBJECT_0) return Fail(WinError("WaitForSingleObject(command event)")); + if (g_parentGone || g_readerFailed) { + g_terminationSignal = 1; + CloseJob(); + break; + } + ResetEvent(g_commandEvent); + std::vector commands; + EnterCriticalSection(&g_queueLock); + commands.swap(g_commands); + LeaveCriticalSection(&g_queueLock); + for (const auto& command : commands) { + std::string error; + if (command.opcode == Opcode::Resize) { + if (command.first == 0 || command.second == 0 || command.first > 32767 || command.second > 32767) { + error = "invalid terminal dimensions"; + } else { + const COORD size{static_cast(command.first), static_cast(command.second)}; + const HRESULT result = ResizePseudoConsole(g_conpty, size); + if (FAILED(result)) error = "ResizePseudoConsole failed with HRESULT " + std::to_string(static_cast(result)); + } + } else if (command.opcode == Opcode::Kill || command.opcode == Opcode::Close || command.opcode == Opcode::Abort) { + g_terminationSignal = command.opcode == Opcode::Kill ? command.first : 1; + if (!TerminateJob(1)) error = WinError("TerminateJobObject"); + else if (command.opcode == Opcode::Close || command.opcode == Opcode::Abort) g_closeRequested = true; + } else { + error = "unexpected helper command"; + } + if (!Ack(command.id, error)) return false; + if (!error.empty() && command.opcode == Opcode::Abort) return false; + } + if (g_closeRequested) done = true; + } + + DWORD exitCode = 0; + if (WaitForSingleObject(g_process, INFINITE) != WAIT_OBJECT_0) return Fail(WinError("waiting for target exit")); + if (!GetExitCodeProcess(g_process, &exitCode)) return Fail(WinError("GetExitCodeProcess")); + // Closing the job first kills descendants that still hold ConPTY endpoints. + CloseJob(); + if (g_process) { + CloseHandle(g_process); + g_process = nullptr; + } + if (g_conpty) { + ClosePseudoConsole(g_conpty); + g_conpty = nullptr; + } + uint32_t status[] = {exitCode, g_terminationSignal.load()}; + return WriteFrame(GetStdHandle(STD_OUTPUT_HANDLE), Opcode::Exited, 0, status, static_cast(sizeof(status))); +} + +int RunHelper() { + try { + Frame start{}; + StartOptions options{}; + if (!ReadFrame(GetStdHandle(STD_INPUT_HANDLE), &start) || !ParseStart(start, &options)) { + return Fail("invalid helper START frame") ? 0 : 1; + } + uint32_t pid = 0; + if (!CreateTarget(options, &pid)) throw std::runtime_error("parent disconnected during helper startup"); + if (!RunTarget(pid)) throw std::runtime_error("helper control stream failed"); + Cleanup(); + WriteFrame(GetStdHandle(STD_OUTPUT_HANDLE), Opcode::Done, 0, nullptr, 0); + return 0; + } catch (const std::exception& error) { + Fail(error.what()); + Cleanup(); + WriteFrame(GetStdHandle(STD_OUTPUT_HANDLE), Opcode::Done, 0, nullptr, 0); + return 1; + } +} + +} // namespace pty_helper + +int wmain() { + const int result = pty_helper::RunHelper(); + ExitProcess(static_cast(result)); +} diff --git a/experiments/ffi-pty/native/windows_helper_protocol.cpp b/experiments/ffi-pty/native/windows_helper_protocol.cpp new file mode 100644 index 000000000..df7dc62e3 --- /dev/null +++ b/experiments/ffi-pty/native/windows_helper_protocol.cpp @@ -0,0 +1,107 @@ +#include "windows_helper_protocol.h" + +#include + +namespace pty_helper { +namespace { + +struct Header { + uint32_t magic; + uint32_t opcode; + uint32_t id; + uint32_t bytes; +}; +static_assert(sizeof(Header) == 16, "helper protocol header must be 16 bytes"); +} + +bool ReadExact(HANDLE handle, void* buffer, DWORD bytes) { + auto* cursor = static_cast(buffer); + DWORD complete = 0; + while (complete < bytes) { + DWORD received = 0; + if (!ReadFile(handle, cursor + complete, bytes - complete, &received, nullptr) || received == 0) return false; + complete += received; + } + return true; +} + +bool WriteExact(HANDLE handle, const void* buffer, DWORD bytes) { + const auto* cursor = static_cast(buffer); + DWORD complete = 0; + while (complete < bytes) { + DWORD sent = 0; + if (!WriteFile(handle, cursor + complete, bytes - complete, &sent, nullptr) || sent == 0) return false; + complete += sent; + } + return true; +} + +bool ReadFrame(HANDLE input, Frame* frame) { + Header header{}; + if (!ReadExact(input, &header, static_cast(sizeof(header))) || header.magic != kMagic || header.bytes > kMaxPayload) return false; + frame->opcode = static_cast(header.opcode); + frame->id = header.id; + frame->payload.resize(header.bytes); + return header.bytes == 0 || ReadExact(input, frame->payload.data(), header.bytes); +} + +bool WriteFrame(HANDLE output, Opcode opcode, uint32_t id, const void* payload, uint32_t size) { + if (size > kMaxPayload) return false; + Header header{kMagic, static_cast(opcode), id, size}; + return WriteExact(output, &header, static_cast(sizeof(header))) && (size == 0 || WriteExact(output, payload, size)); +} + +bool ReadU32(const std::vector& data, size_t* offset, uint32_t* value) { + if (*offset > data.size() || data.size() - *offset < sizeof(uint32_t)) return false; + std::memcpy(value, data.data() + *offset, sizeof(uint32_t)); + *offset += sizeof(uint32_t); + return true; +} + +bool ReadWide(const std::vector& data, size_t* offset, std::wstring* value) { + uint32_t bytes = 0; + if (!ReadU32(data, offset, &bytes) || bytes < 2u || (bytes & 1u) != 0 || + *offset > data.size() || data.size() - *offset < bytes) return false; + std::vector buffer(bytes / sizeof(wchar_t)); + std::memcpy(buffer.data(), data.data() + *offset, bytes); + *offset += bytes; + if (buffer.back() != L'\0') return false; + for (size_t index = 0; index + 1 < buffer.size(); ++index) if (buffer[index] == L'\0') return false; + value->assign(buffer.data(), buffer.size() - 1); + return true; +} + +bool ReadEnvironment(const std::vector& data, size_t* offset, std::vector* value) { + uint32_t bytes = 0; + if (!ReadU32(data, offset, &bytes) || bytes < 4u || (bytes & 1u) != 0 || + *offset > data.size() || data.size() - *offset < bytes) return false; + value->resize(bytes / sizeof(wchar_t)); + std::memcpy(value->data(), data.data() + *offset, bytes); + *offset += bytes; + if ((*value)[value->size() - 1] != L'\0' || (*value)[value->size() - 2] != L'\0') return false; + return true; +} + +bool ParseStart(const Frame& frame, StartOptions* options) { + if (frame.opcode != Opcode::Start || frame.id != 0) return false; + size_t offset = 0; + if (!ReadU32(frame.payload, &offset, &options->cols) || !ReadU32(frame.payload, &offset, &options->rows) || + options->cols == 0 || options->rows == 0 || options->cols > 32767 || options->rows > 32767) return false; + if (!ReadWide(frame.payload, &offset, &options->application) || + !ReadWide(frame.payload, &offset, &options->commandLine) || + !ReadWide(frame.payload, &offset, &options->cwd) || + !ReadEnvironment(frame.payload, &offset, &options->environment) || + !ReadWide(frame.payload, &offset, &options->inputName) || + !ReadWide(frame.payload, &offset, &options->outputName)) return false; + return offset == frame.payload.size(); +} + +bool WriteU32(HANDLE output, Opcode opcode, uint32_t id, uint32_t value) { + return WriteFrame(output, opcode, id, &value, sizeof(value)); +} + +bool WriteUtf8(HANDLE output, Opcode opcode, uint32_t id, const std::string& value) { + return WriteFrame(output, opcode, id, value.data(), static_cast(value.size())); +} + +} // namespace pty_helper diff --git a/experiments/ffi-pty/native/windows_helper_protocol.h b/experiments/ffi-pty/native/windows_helper_protocol.h new file mode 100644 index 000000000..fcb0b4438 --- /dev/null +++ b/experiments/ffi-pty/native/windows_helper_protocol.h @@ -0,0 +1,79 @@ +#pragma once + +#include +#include +#include +#include + +namespace pty_helper { + +constexpr uint32_t kMagic = 0x31595450; +constexpr uint32_t kMaxPayload = 8u * 1024u * 1024u; + +enum class Opcode : uint32_t { + Start = 1, + Connected = 2, + Resize = 3, + Kill = 4, + Close = 5, + Abort = 6, + Pipes = 101, + Spawned = 102, + Ack = 103, + Exited = 104, + Error = 105, + Done = 106, +}; + +struct Frame { + Opcode opcode; + uint32_t id; + std::vector payload; +}; + +struct StartOptions { + uint32_t cols; + uint32_t rows; + std::wstring application; + std::wstring commandLine; + std::wstring cwd; + std::vector environment; + std::wstring inputName; + std::wstring outputName; +}; + +struct QueuedCommand { + Opcode opcode; + uint32_t id; + uint32_t first; + uint32_t second; +}; + +bool ReadFrame(HANDLE input, Frame* frame); +bool WriteFrame(HANDLE output, Opcode opcode, uint32_t id, const void* payload, uint32_t size); +bool ReadExact(HANDLE handle, void* buffer, DWORD bytes); +bool WriteExact(HANDLE handle, const void* buffer, DWORD bytes); +bool ParseStart(const Frame& frame, StartOptions* options); +bool ReadU32(const std::vector& data, size_t* offset, uint32_t* value); +bool ReadWide(const std::vector& data, size_t* offset, std::wstring* value); +bool ReadEnvironment(const std::vector& data, size_t* offset, std::vector* value); +bool WriteU32(HANDLE output, Opcode opcode, uint32_t id, uint32_t value); +bool WriteUtf8(HANDLE output, Opcode opcode, uint32_t id, const std::string& value); +std::string WinError(const char* operation); +void Close(HANDLE* handle); +void StopReader(); +[[noreturn]] void AbortHelper(); +void Cleanup(); +void CloseJob(); +bool TerminateJob(DWORD code); +bool Fail(const std::string& message); +HANDLE CreatePipe(const std::wstring& name); +bool Connect(HANDLE pipe); +bool CreateTarget(const StartOptions& options, uint32_t* pid); +void Queue(const QueuedCommand& command); +DWORD WINAPI ReadCommands(void* context); +bool Ack(uint32_t id, const std::string& error = {}); +bool RunTarget(uint32_t pid); +int RunHelper(); + +} // namespace pty_helper diff --git a/experiments/ffi-pty/probe.mts b/experiments/ffi-pty/probe.mts new file mode 100644 index 000000000..d7a0aedf2 --- /dev/null +++ b/experiments/ffi-pty/probe.mts @@ -0,0 +1,19 @@ +import { spawnPty } from "./pty.mts"; + +const check = [ + "const tty = process.stdin.isTTY && process.stdout.isTTY && process.stderr.isTTY;", + "console.log(tty ? 'PTY_OK' : 'PTY_MISSING');", + "console.log('SIZE:' + process.stdout.columns + 'x' + process.stdout.rows);", + "process.exitCode = tty ? 0 : 1;", +].join(" "); + +const pty = await spawnPty(process.execPath, ["-e", check]); +const subscription = pty.onData((data) => process.stdout.write(data)); +try { + const status = await pty.exited; + console.log("\nexit", status); + if (status.exitCode !== 0) process.exitCode = 1; +} finally { + subscription.dispose(); + await pty.close(); +} diff --git a/experiments/ffi-pty/pty.mts b/experiments/ffi-pty/pty.mts new file mode 100644 index 000000000..28b5f7950 --- /dev/null +++ b/experiments/ffi-pty/pty.mts @@ -0,0 +1,33 @@ +import { createRequire } from "node:module"; +import type { Backend, FfiPty } from "./contract.mts"; +import { createPtyFromBackend } from "./events.mts"; +import { normalizeSpawnOptions } from "./validation.mts"; + +const require = createRequire(import.meta.url); +const supportedPlatforms = new Set(["darwin", "linux", "win32"]); +const supportedArchitectures = new Set(["x64", "arm64"]); + +export async function spawnPty(file: string, args: string[], options = {}): Promise { + const normalized = normalizeSpawnOptions(file, args, options); + const [major, minor] = process.versions.node.split(".").map(Number); + if (major < 26 || (major === 26 && minor < 12)) { + throw new Error("The FFI PTY experiment requires Node.js 26.12 or newer"); + } + if (!supportedPlatforms.has(process.platform) || !supportedArchitectures.has(process.arch)) { + throw new Error(`Unsupported FFI PTY platform: ${process.platform}-${process.arch}`); + } + const backendFiles = { darwin: "./darwin.mts", linux: "./linux.mts", win32: "./windows.mts" }; + const moduleName = backendFiles[process.platform as keyof typeof backendFiles]; + let platform: { createBackend(options: typeof normalized): Promise }; + try { + platform = require(moduleName) as typeof platform; + } catch (error) { + throw new Error(`FFI PTY backend unavailable for ${process.platform}`, { cause: error }); + } + const backend = await platform.createBackend(normalized); + return createPtyFromBackend(backend, normalized.cols, normalized.rows); +} + +export { createPtyFromBackend } from "./events.mts"; +export { normalizeSpawnOptions, validateDimension, validateNativeString } from "./validation.mts"; +export type { Backend, ExitStatus, FfiPty, SpawnOptions, SpawnOptionsInput } from "./contract.mts"; diff --git a/experiments/ffi-pty/unix-common.mts b/experiments/ffi-pty/unix-common.mts new file mode 100644 index 000000000..9e77ef6da --- /dev/null +++ b/experiments/ffi-pty/unix-common.mts @@ -0,0 +1,263 @@ +import { setImmediate as yieldToLoop, setTimeout as delay } from "node:timers/promises"; +import { ReadStream } from "node:tty"; +import { PassThrough } from "node:stream"; +import { writeSync } from "node:fs"; +import type { SpawnOptions, ExitStatus, Backend } from "./contract.mts"; +import { initializeNonblockingPoll } from "./unix-poll.mts"; + +export interface UnixBindings { + spawn(options: SpawnOptions): { pid: number; masterFd: number; slaveName: string }; + wait(pid: number): ExitStatus | null; + kill(pid: number, signal: string): void; + resize(slaveName: string, cols: number, rows: number): Promise; + closeFd(fd: number): void; +} + +const WRITE_QUEUE_LIMIT = 8 * 1024 * 1024; +const DRAIN_AFTER_EXIT_MS = 1500; +const CLOSE_GRACE_MS = 500; + +export async function destroyReadStream(source: ReadStream): Promise { + if (source.closed) return; + await new Promise((resolve) => { + source.once("close", resolve); + source.destroy(); + if (source.closed) resolve(); + }); +} + +export function waitForOutputDrain(readable: PassThrough, timeoutMs: number): Promise { + if (readable.readableEnded || readable.destroyed) return Promise.resolve(true); + return new Promise((resolve) => { + let remaining = timeoutMs; + let startedAt = 0; + let timer: NodeJS.Timeout | undefined; + let settled = false; + const finish = (drained: boolean) => { + if (settled) return; + settled = true; + if (timer) clearTimeout(timer); + readable.removeListener("resume", update); + readable.removeListener("pause", update); + readable.removeListener("end", onEnd); + readable.removeListener("close", onEnd); + resolve(drained); + }; + const onEnd = () => finish(true); + const update = () => { + if (readable.readableEnded || readable.destroyed) { + finish(true); + } else if (readable.readableFlowing !== false && !timer) { + startedAt = Date.now(); + timer = setTimeout(() => { + timer = undefined; + if (readable.readableFlowing !== false) finish(false); + else update(); + }, remaining); + } else if (readable.readableFlowing === false && timer) { + clearTimeout(timer); + timer = undefined; + remaining = Math.max(0, remaining - (Date.now() - startedAt)); + } + }; + readable.on("resume", update); + readable.on("pause", update); + readable.once("end", onEnd); + readable.once("close", onEnd); + update(); + }); +} + +export function createUnixBackend(options: SpawnOptions, bindings: UnixBindings): Backend { + const child = bindings.spawn(options); + let source: ReadStream; + try { + initializeNonblockingPoll(child.masterFd); + source = new ReadStream(child.masterFd); + } catch (error) { + try { + bindings.closeFd(child.masterFd); + } catch { + /* descriptor was not acquired */ + } + try { + bindings.kill(child.pid, "SIGTERM"); + } catch { + /* child may have exited */ + } + void (async () => { + const deadline = Date.now() + CLOSE_GRACE_MS; + let status = bindings.wait(child.pid); + while (Date.now() < deadline && !status) { + await delay(20); + status = bindings.wait(child.pid); + } + if (!status) { + try { + bindings.kill(child.pid, "SIGKILL"); + } catch { + /* child may have exited */ + } + while (!bindings.wait(child.pid)) await delay(20); + } + })().catch(() => {}); + throw error; + } + const readable = new PassThrough({ highWaterMark: 64 * 1024 }); + const endReadable = () => { + if (!readable.writableEnded) readable.end(); + }; + const forwardData = (chunk: Buffer) => { + if (!readable.write(chunk)) source.pause(); + }; + source.on("data", forwardData); + readable.on("drain", () => source.resume()); + source.on("end", endReadable); + source.on("close", endReadable); + source.on("error", (error: NodeJS.ErrnoException) => { + if (error.code === "EIO") endReadable(); + else readable.destroy(error); + }); + let closed = false; + let closing = false; + let reaped = false; + let queuedBytes = 0; + let writeTail = Promise.resolve(); + let closePromise: Promise | undefined; + let resolveExit!: (status: ExitStatus) => void; + let rejectExit!: (error: Error) => void; + const exited = new Promise((resolve, reject) => { + resolveExit = resolve; + rejectExit = reject; + }); + void exited.catch(() => {}); + + const write = (data: Buffer): Promise => { + if (closed || closing || source.destroyed || source.closed) + return Promise.reject(new Error("PTY is closed")); + if (reaped) return Promise.reject(new Error("PTY has exited")); + const bytes = Buffer.from(data); + if (queuedBytes + bytes.length > WRITE_QUEUE_LIMIT) { + return Promise.reject(new Error("PTY write queue exceeds 8 MiB")); + } + queuedBytes += bytes.length; + const operation = writeTail + .then(async () => { + let offset = 0; + while (offset < bytes.length) { + if (closed || closing || source.destroyed || source.closed) + throw new Error("PTY is closed"); + if (reaped) throw new Error("PTY has exited"); + let count: number; + try { + // ReadStream sets the PTY master nonblocking. A sync write avoids a + // thread-pool write racing the stream's fd close and reuse. + count = writeSync( + child.masterFd, + bytes, + offset, + Math.min(bytes.length - offset, 64 * 1024), + ); + } catch (error) { + const code = (error as NodeJS.ErrnoException).code; + if (code === "EINTR" || code === "EAGAIN" || code === "EWOULDBLOCK") { + await delay(10); + continue; + } + throw error; + } + if (!count) { + await delay(10); + continue; + } + offset += count; + await yieldToLoop(); + } + }) + .finally(() => { + queuedBytes -= bytes.length; + }); + writeTail = operation.catch(() => {}); + return operation; + }; + + const poll = async () => { + try { + for (;;) { + const status = bindings.wait(child.pid); + if (status) { + reaped = true; + // Allow buffered kernel output and inherited descendant descriptors to drain. + const drained = await waitForOutputDrain(readable, DRAIN_AFTER_EXIT_MS); + if (!drained) { + source.removeListener("data", forwardData); + await destroyReadStream(source); + endReadable(); + } + if (!source.closed) await destroyReadStream(source); + resolveExit(status); + return; + } + await delay(20); + } + } catch (error) { + reaped = true; + source.removeListener("data", forwardData); + await destroyReadStream(source).catch(() => {}); + endReadable(); + rejectExit(error instanceof Error ? error : new Error(String(error))); + } + }; + void poll(); + + return { + pid: child.pid, + readable, + write, + resize: async (cols, rows) => { + if (closed || closing || source.destroyed || source.closed) throw new Error("PTY is closed"); + if (reaped) throw new Error("PTY has exited"); + await bindings.resize(child.slaveName, cols, rows); + }, + kill: async (signal = "SIGTERM") => { + if (closed || closing || reaped || source.destroyed || source.closed) return; + bindings.kill(child.pid, signal); + }, + close: () => { + if (!closePromise) { + closing = true; + // Backend callers may bypass the facade, so close must unblock drain itself. + readable.resume(); + closePromise = (async () => { + if (!closed) { + if (!reaped) { + try { + bindings.kill(child.pid, "SIGTERM"); + } catch { + /* process may have exited */ + } + } + await Promise.race([ + exited.catch(() => undefined), + delay(CLOSE_GRACE_MS).then(() => undefined), + ]); + if (!reaped) { + try { + bindings.kill(child.pid, "SIGKILL"); + } catch { + /* process may have exited */ + } + } + await exited.catch(() => undefined); + closed = true; + source.removeListener("data", forwardData); + await destroyReadStream(source); + } + await writeTail; + })(); + } + return closePromise; + }, + exited, + }; +} diff --git a/experiments/ffi-pty/unix-native.mts b/experiments/ffi-pty/unix-native.mts new file mode 100644 index 000000000..5075cac42 --- /dev/null +++ b/experiments/ffi-pty/unix-native.mts @@ -0,0 +1,31 @@ +import { getRawPointer } from "node:ffi"; +import { accessSync, constants, statSync } from "node:fs"; +import { delimiter, isAbsolute, resolve } from "node:path"; + +export function makePointerVector(values: string[]) { + const buffers = values.map((value) => { + if (value.includes("\0")) throw new TypeError("NUL in native string"); + return Buffer.from(`${value}\0`); + }); + const pointers = Buffer.alloc((buffers.length + 1) * 8); + buffers.forEach((buffer, index) => pointers.writeBigUInt64LE(getRawPointer(buffer), index * 8)); + return { buffers, pointers }; +} + +export function resolveExecutable(file: string, cwd: string, env: Record): string { + const candidates = file.includes("/") + ? [isAbsolute(file) ? file : resolve(cwd, file)] + : (env.PATH ?? "/usr/bin:/bin") + .split(delimiter) + .map((directory) => resolve(cwd, directory || ".", file)); + for (const candidate of candidates) { + try { + if (!statSync(candidate).isFile()) continue; + accessSync(candidate, constants.X_OK); + return candidate; + } catch { + /* skip missing, non-file, or non-executable candidates */ + } + } + throw new Error(`Executable not found or not executable: ${file}`); +} diff --git a/experiments/ffi-pty/unix-poll.mts b/experiments/ffi-pty/unix-poll.mts new file mode 100644 index 000000000..f24cac8fa --- /dev/null +++ b/experiments/ffi-pty/unix-poll.mts @@ -0,0 +1,54 @@ +import { dlopen } from "node:ffi"; + +interface LibuvFunctions { + uv_loop_size(): bigint; + uv_handle_size(type: number): bigint; + uv_loop_init(loop: Buffer): number; + uv_loop_close(loop: Buffer): number; + uv_run(loop: Buffer, mode: number): number; + uv_poll_init(loop: Buffer, handle: Buffer, fd: number): number; + uv_close(handle: Buffer, callback: bigint): void; +} + +let uv: LibuvFunctions | undefined; + +export function loadLibuvFunctions(): LibuvFunctions { + if (!uv) { + uv = dlopen(null, { + uv_loop_size: { arguments: [], return: "uint64" }, + uv_handle_size: { arguments: ["int32"], return: "uint64" }, + uv_loop_init: { arguments: ["pointer"], return: "int32" }, + uv_loop_close: { arguments: ["pointer"], return: "int32" }, + uv_run: { arguments: ["pointer", "int32"], return: "int32" }, + uv_poll_init: { arguments: ["pointer", "pointer", "int32"], return: "int32" }, + uv_close: { arguments: ["pointer", "pointer"], return: "void" }, + }).functions as unknown as LibuvFunctions; + } + return uv; +} + +const UV_POLL = 8; +const UV_RUN_DEFAULT = 0; + +export function initializeNonblockingPoll(fd: number): void { + const uv = loadLibuvFunctions(); + const loop = Buffer.alloc(Number(uv.uv_loop_size())); + const handle = Buffer.alloc(Number(uv.uv_handle_size(UV_POLL))); + const loopResult = uv.uv_loop_init(loop); + if (loopResult !== 0) throw new Error(`uv_loop_init failed with ${loopResult}`); + const pollResult = uv.uv_poll_init(loop, handle, fd); + if (pollResult !== 0) { + const closeResult = uv.uv_loop_close(loop); + if (closeResult !== 0) + throw new Error( + `uv_poll_init failed with ${pollResult}; uv_loop_close failed with ${closeResult}`, + ); + throw new Error(`uv_poll_init failed with ${pollResult}`); + } + // uv_poll_init sets O_NONBLOCK. Close only the libuv handle; the PTY fd remains + // owned by ReadStream. Pump the private loop so uv_close finishes synchronously. + uv.uv_close(handle, 0n); + uv.uv_run(loop, UV_RUN_DEFAULT); + const closeResult = uv.uv_loop_close(loop); + if (closeResult !== 0) throw new Error(`uv_loop_close failed with ${closeResult}`); +} diff --git a/experiments/ffi-pty/validation.mts b/experiments/ffi-pty/validation.mts new file mode 100644 index 000000000..d98f3b18d --- /dev/null +++ b/experiments/ffi-pty/validation.mts @@ -0,0 +1,56 @@ +import { isAbsolute, resolve } from "node:path"; +import type { SpawnOptions, SpawnOptionsInput } from "./contract.mts"; + +const supported = new Set(["cols", "rows", "cwd", "env", "encoding"]); + +export function validateNativeString(value: unknown, label: string): asserts value is string { + if (typeof value !== "string" || value.includes("\0")) { + throw new TypeError(`${label} must be a string without NUL bytes`); + } +} + +export function validateDimension(value: unknown, label: string): asserts value is number { + if (!Number.isInteger(value) || (value as number) < 1 || (value as number) > 32767) { + throw new RangeError(`${label} must be an integer from 1 to 32767`); + } +} + +export function normalizeSpawnOptions( + file: string, + args: string[], + input: SpawnOptionsInput = {}, +): SpawnOptions { + validateNativeString(file, "file"); + if (!file) throw new TypeError("file must not be empty"); + if (!Array.isArray(args)) throw new TypeError("args must be an array of strings"); + args.forEach((arg, index) => validateNativeString(arg, `args[${index}]`)); + if (!input || typeof input !== "object" || Array.isArray(input)) { + throw new TypeError("options must be an object"); + } + for (const key of Object.keys(input)) { + if (!supported.has(key)) throw new TypeError(`Unsupported PTY option: ${key}`); + } + if (input.encoding !== undefined && input.encoding !== "utf8") { + throw new TypeError("Only UTF-8 encoding is supported"); + } + const cols = input.cols ?? 80; + const rows = input.rows ?? 24; + validateDimension(cols, "cols"); + validateDimension(rows, "rows"); + const cwd = input.cwd ?? process.cwd(); + validateNativeString(cwd, "cwd"); + const absoluteCwd = isAbsolute(cwd) ? cwd : resolve(cwd); + const envInput = input.env ?? process.env; + if (!envInput || typeof envInput !== "object" || Array.isArray(envInput)) { + throw new TypeError("env must be a string map"); + } + const env = Object.create(null) as Record; + for (const [key, value] of Object.entries(envInput)) { + validateNativeString(key, "environment variable name"); + validateNativeString(value, `environment variable ${key}`); + if (!key || key.includes("=")) throw new TypeError(`Invalid environment variable name: ${key}`); + env[key] = value; + } + if (!Object.hasOwn(env, "TERM")) env.TERM = "xterm-256color"; + return { file, args: [...args], cols, rows, cwd: absoluteCwd, env }; +} diff --git a/experiments/ffi-pty/windows-broker-client.mts b/experiments/ffi-pty/windows-broker-client.mts new file mode 100644 index 000000000..2aa337125 --- /dev/null +++ b/experiments/ffi-pty/windows-broker-client.mts @@ -0,0 +1,125 @@ +import { fork, type ChildProcess } from "node:child_process"; +import { fileURLToPath } from "node:url"; +import { helperStartupEnv } from "./windows-helper.mts"; +import { prepareWindowsStart } from "./windows-launch.mts"; +import type { WindowsTransport } from "./windows-transport.mts"; +import type { BrokerReply, BrokerRequest } from "./windows-protocol.mts"; +import { + type BrokerProcessRequest, + sendNodeBrokerMessage, + sendPreparedStart, +} from "./windows-broker-ipc.mts"; + +const BROKER_URL = new URL("./windows-broker.mts", import.meta.url); + +export function brokerStartupEnv(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv { + return helperStartupEnv(source); +} + +export function forkBroker(source: NodeJS.ProcessEnv = process.env): ChildProcess { + return fork(fileURLToPath(BROKER_URL), [], { + execPath: process.execPath, + execArgv: ["--experimental-ffi"], + env: brokerStartupEnv(source), + stdio: ["ignore", "ignore", "ignore", "ipc"], + serialization: "advanced", + windowsHide: true, + }); +} + +export function sendBrokerMessage( + child: ChildProcess, + message: BrokerProcessRequest, +): Promise { + return sendNodeBrokerMessage(child, message); +} + +export function notify(listeners: Set<(error: Error) => void>, cause: unknown) { + const error = cause instanceof Error ? cause : new Error(String(cause)); + for (const listener of listeners) { + try { + listener(error); + } catch { + // Transport observers cannot interfere with child cleanup. + } + } +} + +export function createNodeTransport(): WindowsTransport { + const child = forkBroker(); + const messages = new Set<(reply: BrokerReply) => void>(); + const errors = new Set<(error: Error) => void>(); + let doneReply = false; + let expectedTermination = false; + let startSent = false; + let sendTail = Promise.resolve(); + + const ready = new Promise((resolve, reject) => { + child.once("spawn", resolve); + child.once("error", reject); + }); + const closed = new Promise((resolve) => child.once("close", () => resolve())); + void ready.catch((error) => notify(errors, error)); + void closed.then(() => { + if (!expectedTermination && child.exitCode !== 0) { + notify( + errors, + new Error( + `Windows PTY subprocess exited with code ${child.exitCode ?? child.signalCode ?? "unknown"}`, + ), + ); + } + }); + child.on("error", (error) => notify(errors, error)); + child.on("disconnect", () => { + if (!doneReply && !expectedTermination) + notify(errors, new Error("Windows PTY subprocess IPC disconnected")); + }); + child.on("message", (message: BrokerReply) => { + if (!message || typeof message !== "object" || typeof message.type !== "string") { + notify(errors, new Error("Invalid Windows PTY subprocess reply")); + return; + } + if (message.type === "brokerDone") doneReply = true; + for (const listener of messages) { + try { + listener(message); + } catch (error) { + notify(errors, error); + } + } + }); + + return { + ready, + closed, + send(request: BrokerRequest): Promise { + const operation = sendTail.then(async () => { + await ready; + if (request.type === "start") { + if (startSent) throw new Error("Windows PTY subprocess START was already sent"); + const start = prepareWindowsStart(request.options); + startSent = true; + await sendPreparedStart(child, start); + } else { + await sendBrokerMessage(child, request); + } + }); + sendTail = operation.catch(() => {}); + return operation; + }, + onMessage(listener): () => void { + messages.add(listener); + return () => messages.delete(listener); + }, + onError(listener): () => void { + errors.add(listener); + return () => errors.delete(listener); + }, + async terminate(): Promise { + expectedTermination = true; + if (child.exitCode === null && child.signalCode === null) child.kill(); + await closed; + }, + }; +} diff --git a/experiments/ffi-pty/windows-broker-ipc.mts b/experiments/ffi-pty/windows-broker-ipc.mts new file mode 100644 index 000000000..a4d57fad1 --- /dev/null +++ b/experiments/ffi-pty/windows-broker-ipc.mts @@ -0,0 +1,31 @@ +import type { ChildProcess } from "node:child_process"; +import type { WindowsStart } from "./windows-launch.mts"; +import type { BrokerReply, BrokerRequest } from "./windows-protocol.mts"; + +export type BrokerProcessRequest = + | { type: "preparedStart"; start: WindowsStart } + | Exclude; + +export interface NodeBrokerChannel { + connected: boolean; + send(message: BrokerReply, callback?: (error: Error | null) => void): boolean; + on(event: "message", listener: (message: BrokerProcessRequest) => void): this; + off(event: "message", listener: (message: BrokerProcessRequest) => void): this; + on(event: "disconnect", listener: () => void): this; + off(event: "disconnect", listener: () => void): this; + disconnect(): void; +} + +export function sendPreparedStart(child: ChildProcess, start: WindowsStart): Promise { + return sendNodeBrokerMessage(child, { type: "preparedStart", start }); +} + +export function sendNodeBrokerMessage( + child: ChildProcess, + message: BrokerProcessRequest, +): Promise { + return new Promise((resolve, reject) => { + if (!child.connected) return reject(new Error("Windows PTY subprocess IPC is disconnected")); + child.send(message, (error) => (error ? reject(error) : resolve())); + }); +} diff --git a/experiments/ffi-pty/windows-broker.mts b/experiments/ffi-pty/windows-broker.mts new file mode 100644 index 000000000..d94be2c6c --- /dev/null +++ b/experiments/ffi-pty/windows-broker.mts @@ -0,0 +1,150 @@ +import { resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { createFfiWorkerTransport } from "./windows-ffi.mts"; +import type { WindowsTransport } from "./windows-transport.mts"; +import type { WindowsStart } from "./windows-launch.mts"; +import type { BrokerReply } from "./windows-protocol.mts"; +import type { BrokerProcessRequest, NodeBrokerChannel } from "./windows-broker-ipc.mts"; + +const PARENT_DISCONNECT_GRACE_MS = 300; +let brokerStarted = false; + +export function sendBrokerReply(channel: NodeBrokerChannel, message: BrokerReply): Promise { + return new Promise((resolveReply, rejectReply) => { + if (!channel.connected) + return rejectReply(new Error("Windows PTY subprocess IPC is disconnected")); + channel.send(message, (error) => (error ? rejectReply(error) : resolveReply())); + }); +} + +export function forwardBrokerRequest( + transport: WindowsTransport, + message: BrokerProcessRequest, +): Promise { + if (message.type === "preparedStart") { + return Promise.reject(new Error("Windows PTY subprocess received a duplicate START")); + } + return transport.send(message); +} + +export async function terminateWorkerBounded( + transport: WindowsTransport, + timeoutMs = PARENT_DISCONNECT_GRACE_MS, +): Promise { + let timer: NodeJS.Timeout | undefined; + try { + await Promise.race([ + transport.terminate(), + new Promise((resolveStop) => { + timer = setTimeout(resolveStop, timeoutMs); + }), + ]); + } finally { + if (timer) clearTimeout(timer); + } +} + +export async function runBroker(start: WindowsStart, channel: NodeBrokerChannel): Promise { + if (brokerStarted) throw new Error("Windows PTY subprocess can run only one session"); + brokerStarted = true; + let transport: WindowsTransport; + try { + transport = createFfiWorkerTransport({ requireModernOs: false, preparedStart: start }); + } catch (error) { + if (channel.connected) { + try { + await sendBrokerReply(channel, { type: "error", error: String(error) }); + await sendBrokerReply(channel, { type: "brokerDone" }); + } catch { + // The parent may have disconnected during startup. + } finally { + if (channel.connected) channel.disconnect(); + } + } + return; + } + let doneReply = false; + let ending = false; + let disconnectTask: Promise | undefined; + let replyTail = Promise.resolve(); + + const exitForDisconnect = () => { + if (disconnectTask) return disconnectTask; + disconnectTask = (async () => { + await terminateWorkerBounded(transport).catch(() => {}); + process.exit(1); + })(); + return disconnectTask; + }; + const sendReply = (reply: BrokerReply) => { + if (reply.type === "brokerDone") doneReply = true; + const operation = replyTail.then(() => sendBrokerReply(channel, reply)); + replyTail = operation.catch(() => { + void exitForDisconnect(); + }); + return operation; + }; + const onReply = (reply: BrokerReply) => { + void sendReply(reply).catch(() => {}); + }; + const onError = (error: Error) => onReply({ type: "error", error: String(error) }); + const onRequest = (message: BrokerProcessRequest) => { + if (message.type === "preparedStart") { + onError(new Error("Windows PTY subprocess received a duplicate START")); + void exitForDisconnect(); + return; + } + void forwardBrokerRequest(transport, message).catch((error) => onError(asError(error))); + }; + const onDisconnect = () => { + if (!ending) void exitForDisconnect(); + }; + + const removeMessage = transport.onMessage(onReply); + const removeError = transport.onError(onError); + channel.on("message", onRequest); + channel.on("disconnect", onDisconnect); + try { + await transport.ready; + await transport.closed; + await replyTail; + if (!doneReply && channel.connected) await sendReply({ type: "brokerDone" }); + } catch (error) { + if (channel.connected) { + try { + await sendReply({ type: "error", error: String(error) }); + if (!doneReply) await sendReply({ type: "brokerDone" }); + } catch { + await exitForDisconnect(); + } + } + } finally { + ending = true; + removeMessage(); + removeError(); + channel.off("message", onRequest); + channel.off("disconnect", onDisconnect); + if (channel.connected) channel.disconnect(); + } +} + +export function asError(value: unknown): Error { + return value instanceof Error ? value : new Error(String(value)); +} + +export function isBrokerEntry( + entry = process.argv[1], + modulePath = fileURLToPath(import.meta.url), +): boolean { + return Boolean(process.send && entry && resolve(entry) === resolve(modulePath)); +} + +if (isBrokerEntry()) { + const processChannel = process as unknown as NodeBrokerChannel; + const onStart = (message: BrokerProcessRequest) => { + if (message.type !== "preparedStart") return; + processChannel.off("message", onStart); + void runBroker(message.start, processChannel); + }; + processChannel.on("message", onStart); +} diff --git a/experiments/ffi-pty/windows-commandline.mts b/experiments/ffi-pty/windows-commandline.mts new file mode 100644 index 000000000..63e0bd0e9 --- /dev/null +++ b/experiments/ffi-pty/windows-commandline.mts @@ -0,0 +1,109 @@ +import { statSync } from "node:fs"; +import { win32 as path } from "node:path"; + +/** Quote one argument using the parsing rules used by CommandLineToArgvW/CRT. */ +export function quoteWindowsArgument(value: string): string { + if (value.includes("\0")) throw new Error("NUL in Windows argument"); + if (value.length > 0 && !/[\s"]/.test(value)) return value; + + let result = '"'; + let backslashes = 0; + for (const character of value) { + if (character === "\\") { + backslashes++; + continue; + } + if (character === '"') { + result += "\\".repeat(backslashes * 2 + 1) + '"'; + } else { + result += "\\".repeat(backslashes) + character; + } + backslashes = 0; + } + return result + "\\".repeat(backslashes * 2) + '"'; +} +export function buildWindowsCommandLine(file: string, args: string[]): string { + if (!file) throw new Error("Executable path must not be empty"); + return [file, ...args].map(quoteWindowsArgument).join(" "); +} + +export function windowsPipeNames(id: string): { input: string; output: string } { + if (!id || /[\\/\0]/.test(id)) throw new Error("Invalid named pipe identifier"); + return { + input: String.raw`\\.\pipe\node-pty-ffi-${id}-in`, + output: String.raw`\\.\pipe\node-pty-ffi-${id}-out`, + }; +} + +export function resolveWindowsExecutable( + file: string, + env: Record, + cwd: string, + isFile: (candidate: string) => boolean = (candidate) => { + try { + return statSync(candidate).isFile(); + } catch { + return false; + } + }, +): string { + if (!file || file.includes("\0")) throw new Error("Invalid executable path"); + if (/\.(?:bat|cmd)$/i.test(file)) + throw new Error("Windows batch scripts are not supported by the direct CreateProcess backend"); + const direct = path.isAbsolute(file) || /[\\/]/.test(file) || /^[A-Za-z]:/.test(file); + const extensions = path.extname(file) + ? [""] + : (findEnvironmentValue(env, "PATHEXT") ?? ".COM;.EXE") + .split(";") + .map((extension) => extension.trim()) + .filter((extension) => extension && !/^\.(?:bat|cmd)$/i.test(extension)); + const roots = direct ? [cwd] : [...(findEnvironmentValue(env, "PATH") ?? "").split(";"), cwd]; + for (const root of roots) { + const base = path.resolve(cwd, root.replace(/^"|"$/g, "") || cwd, file); + for (const extension of extensions) { + const candidate = + extension && !file.toLowerCase().endsWith(extension.toLowerCase()) + ? base + extension + : base; + if (isFile(candidate)) return candidate; + } + } + throw new Error(`Executable not found in child PATH: ${file}`); +} + +export function findEnvironmentValue( + env: Record, + name: string, +): string | undefined { + const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name); + return key === undefined ? undefined : env[key]; +} + +/** Build the double-NUL-terminated UTF-16 environment block required by CreateProcessW. */ +export function buildWindowsEnvironmentBlock(env: Record): Buffer { + const entries = Object.entries(env); + const seenNames = new Set(); + for (const [name, value] of entries) { + const driveDirectory = /^=[A-Za-z]:$/.test(name); + if ( + name.includes("\0") || + value.includes("\0") || + (!driveDirectory && (!name || name.includes("="))) + ) { + throw new Error(`Invalid Windows environment entry: ${JSON.stringify(name)}`); + } + const folded = name.toUpperCase(); + if (seenNames.has(folded)) throw new Error(`Duplicate Windows environment name: ${name}`); + seenNames.add(folded); + } + entries.sort(([left], [right]) => { + const leftDrive = left.startsWith("="); + const rightDrive = right.startsWith("="); + if (leftDrive !== rightDrive) return leftDrive ? -1 : 1; + const upperLeft = left.toUpperCase(); + const upperRight = right.toUpperCase(); + return upperLeft < upperRight ? -1 : upperLeft > upperRight ? 1 : 0; + }); + const text = entries.map(([name, value]) => `${name}=${value}`).join("\0") + "\0\0"; + return Buffer.from(text, "utf16le"); +} diff --git a/experiments/ffi-pty/windows-ffi-worker.mts b/experiments/ffi-pty/windows-ffi-worker.mts new file mode 100644 index 000000000..a2e5ef6fd --- /dev/null +++ b/experiments/ffi-pty/windows-ffi-worker.mts @@ -0,0 +1,401 @@ +import { setTimeout as delay } from "node:timers/promises"; +import { getRawPointer } from "node:ffi"; +import { parentPort, workerData } from "node:worker_threads"; +import type { BrokerReply, BrokerRequest } from "./windows-protocol.mts"; +import { rehydrateWindowsStart, type FfiWorkerEnvelope } from "./windows-ffi.mts"; +import { prepareWindowsStart, type WindowsStart } from "./windows-launch.mts"; +import { + initializeWindowsBindings, + INVALID_HANDLE_VALUE, + lastError, + utf16, +} from "./windows-native.mts"; + +const NULL = 0n; +const ATTRIBUTE_PSEUDOCONSOLE = 0x00020016n; +const ATTRIBUTE_JOB_LIST = 0x0002000dn; +const CREATE_UNICODE_ENVIRONMENT = 0x00000400; +const EXTENDED_STARTUPINFO_PRESENT = 0x00080000; +const STARTF_USESTDHANDLES = 0x00000100; +const ERROR_PIPE_CONNECTED = 535; +const WAIT_OBJECT_0 = 0; +const WAIT_TIMEOUT = 258; + +type Command = Extract; + +export class FfiSession { + private resolveStart!: (start: WindowsStart) => void; + private rejectStart!: (error: Error) => void; + private readonly startPromise: Promise; + private resolveConnected!: () => void; + private rejectConnected!: (error: Error) => void; + private readonly connectedPromise: Promise; + private commands: Command[] = []; + private input = 0n; + private output = 0n; + private conpty = 0n; + private job = 0n; + private processHandle = 0n; + private threadHandle = 0n; + private attrs: Buffer | undefined; + private attrsInitialized = false; + private attributeValues: Buffer[] = []; + private started = false; + private abortError: Error | undefined; + private ending = false; + private terminationSignal = 0; + private readonly startTimer: NodeJS.Timeout; + private readonly win: ReturnType; + private readonly sendReply: (reply: BrokerReply) => void; + private readonly sendError: (error: Error) => void; + + constructor( + job: bigint, + win: ReturnType, + sendReply: (reply: BrokerReply) => void, + sendError: (error: Error) => void, + preparedStart?: WindowsStart, + ) { + this.job = job; + this.win = win; + this.sendReply = sendReply; + this.sendError = sendError; + this.startPromise = new Promise((resolve, reject) => { + this.resolveStart = resolve; + this.rejectStart = reject; + }); + if (preparedStart) { + this.started = true; + this.resolveStart(rehydrateWindowsStart(preparedStart)); + } + this.connectedPromise = new Promise((resolve, reject) => { + this.resolveConnected = resolve; + this.rejectConnected = reject; + }); + void this.startPromise.catch(() => {}); + void this.connectedPromise.catch(() => {}); + this.startTimer = setTimeout(() => { + void this.fail(new Error("Timed out connecting ConPTY pipes")); + }, 15_000); + } + + async send(request: BrokerRequest): Promise { + if (this.ending) throw this.abortError ?? new Error("Windows FFI transport is closed"); + if (request.type === "start") { + if (this.started) throw new Error("Windows FFI transport can only start once"); + this.started = true; + this.resolveStart(prepareWindowsStart(request.options)); + return; + } + if (request.type === "connected") { + this.resolveConnected(); + return; + } + if (request.type === "abort") { + void this.fail(new Error(request.error ?? "PTY transport was aborted")); + return; + } + this.commands.push(request); + } + + emit(reply: BrokerReply): void { + this.sendReply(reply); + } + + async run(): Promise { + try { + const start = await this.waitForStart(); + this.input = this.createPipe(this.win, start.inputName); + this.output = this.createPipe(this.win, start.outputName); + this.emit({ type: "pipes", input: start.inputName, output: start.outputName }); + await this.waitForConnected(); + if (this.abortError) throw this.abortError; + this.connect(this.win, this.input); + this.connect(this.win, this.output); + this.createPseudoConsole(this.win, start.cols, start.rows); + this.createProcess(this.win, start); + clearTimeout(this.startTimer); + await this.monitor(this.win); + } catch (error) { + await this.fail(error instanceof Error ? error : new Error(String(error))); + } finally { + this.ending = true; + try { + await this.cleanup(); + } catch (error) { + this.report(error); + } finally { + this.emit({ type: "brokerDone" }); + } + } + } + + waitForStart(): Promise { + return this.startPromise; + } + + waitForConnected(): Promise { + return this.connectedPromise; + } + + createPipe(win: any, name: string): bigint { + const handle = win.CreateNamedPipeW( + utf16(name), + 0x00000003 | 0x00080000, + 0x00000008, + 1, + 65536, + 65536, + 0, + NULL, + ) as bigint; + if (handle === INVALID_HANDLE_VALUE) throw lastError("CreateNamedPipeW"); + return handle; + } + + connect(win: any, handle: bigint): void { + if (win.ConnectNamedPipe(handle, NULL)) return; + const error = win.GetLastError(); + if (error !== ERROR_PIPE_CONNECTED) + throw new Error(`ConnectNamedPipe failed with Win32 error ${error}`); + } + + createPseudoConsole(win: any, cols: number, rows: number): void { + const size = Buffer.alloc(4); + size.writeUInt16LE(cols, 0); + size.writeUInt16LE(rows, 2); + const result = Buffer.alloc(8); + const status = win.CreatePseudoConsole(size.readUInt32LE(), this.input, this.output, 0, result); + if (status !== 0) throw new Error(`CreatePseudoConsole failed with HRESULT ${status}`); + this.conpty = result.readBigUInt64LE(); + } + + createProcess(win: any, start: ReturnType): void { + const size = Buffer.alloc(8); + win.InitializeProcThreadAttributeList(NULL, 2, 0, size); + const bytes = size.readBigUInt64LE(); + if (!bytes || bytes > 65536n) throw new Error("Invalid process attribute list size"); + this.attrs = Buffer.alloc(Number(bytes)); + if (!win.InitializeProcThreadAttributeList(this.attrs, 2, 0, size)) + throw lastError("InitializeProcThreadAttributeList"); + this.attrsInitialized = true; + if ( + !win.UpdateProcThreadAttribute( + this.attrs, + 0, + ATTRIBUTE_PSEUDOCONSOLE, + this.conpty, + 8n, + NULL, + NULL, + ) + ) { + throw lastError("UpdateProcThreadAttribute(PSEUDOCONSOLE)"); + } + const jobValue = Buffer.alloc(8); + jobValue.writeBigUInt64LE(this.job); + this.attributeValues.push(jobValue); + if ( + !win.UpdateProcThreadAttribute(this.attrs, 0, ATTRIBUTE_JOB_LIST, jobValue, 8n, NULL, NULL) + ) { + throw lastError("UpdateProcThreadAttribute(JOB_LIST)"); + } + const startup = Buffer.alloc(112); + startup.writeUInt32LE(112, 0); + startup.writeUInt32LE(STARTF_USESTDHANDLES, 60); + const startupEx = Buffer.from(startup); + const attrPointer = Buffer.alloc(8); + attrPointer.writeBigUInt64LE(getRawPointer(this.attrs)); + attrPointer.copy(startupEx, 104); + const info = Buffer.alloc(24); + const created = win.CreateProcessW( + start.application, + start.commandLine, + NULL, + NULL, + 0, + EXTENDED_STARTUPINFO_PRESENT | CREATE_UNICODE_ENVIRONMENT, + start.environment, + start.cwd, + startupEx, + info, + ); + if (!created) throw lastError("CreateProcessW"); + this.processHandle = info.readBigUInt64LE(0); + this.threadHandle = info.readBigUInt64LE(8); + this.emit({ type: "spawned", pid: info.readUInt32LE(16) }); + this.closeHandle(win, this.threadHandle, "CloseHandle(thread)"); + this.threadHandle = 0n; + // Keep attrs and jobValue alive until DeleteProcThreadAttributeList below. + this.deleteAttributes(win); + this.closeHandle(win, this.input, "CloseHandle(input pipe)"); + this.input = 0n; + this.closeHandle(win, this.output, "CloseHandle(output pipe)"); + this.output = 0n; + } + + async monitor(win: any): Promise { + while (true) { + const status = win.WaitForSingleObject(this.processHandle, 0); + if (status !== WAIT_OBJECT_0 && status !== WAIT_TIMEOUT) + throw lastError("WaitForSingleObject"); + if (this.abortError) { + if (status !== WAIT_OBJECT_0 && this.job) { + if (!win.TerminateJobObject(this.job, 1)) { + throw lastError("TerminateJobObject after abort"); + } + this.terminationSignal = 1; + } + throw this.abortError; + } + if (status === WAIT_OBJECT_0) break; + const request = this.commands.shift(); + if (request) this.runCommand(win, request); + await delay(10); + } + const exit = Buffer.alloc(4); + if (!win.GetExitCodeProcess(this.processHandle, exit)) throw lastError("GetExitCodeProcess"); + if (!win.TerminateJobObject(this.job, 1)) { + throw lastError("TerminateJobObject after target exit"); + } + this.closeHandle(win, this.processHandle, "CloseHandle(process)"); + this.processHandle = 0n; + win.ClosePseudoConsole(this.conpty); + this.conpty = 0n; + this.emit({ type: "exited", exitCode: exit.readUInt32LE(), signal: this.terminationSignal }); + } + + runCommand(win: any, request: Command): void { + try { + if (request.command === "resize") { + const size = Buffer.alloc(4); + size.writeUInt16LE(request.cols, 0); + size.writeUInt16LE(request.rows, 2); + const result = win.ResizePseudoConsole(this.conpty, size.readUInt32LE()); + if (result !== 0) throw new Error(`ResizePseudoConsole failed with HRESULT ${result}`); + } else if (request.command === "kill" || request.command === "close") { + if (!win.TerminateJobObject(this.job, 1)) throw lastError("TerminateJobObject"); + this.terminationSignal = request.command === "close" ? 1 : request.signal; + } + this.emit({ type: "ack", id: request.id }); + } catch (error) { + this.emit({ type: "ack", id: request.id, error: String(error) }); + } + } + + async fail(error: Error): Promise { + if (this.ending) return; + this.ending = true; + this.abortError = error; + clearTimeout(this.startTimer); + this.rejectStart(error); + this.rejectConnected(error); + if (this.job) { + try { + this.win.TerminateJobObject(this.job, 1); + } catch { + // The main thread closes its kill-on-close job after this worker exits. + } + } + this.report(error); + } + + deleteAttributes(win: any): void { + if (this.attrsInitialized && this.attrs) win.DeleteProcThreadAttributeList(this.attrs); + this.attrsInitialized = false; + this.attrs = undefined; + this.attributeValues = []; + } + + report(value: unknown): void { + const error = value instanceof Error ? value : new Error(String(value)); + this.sendError(error); + } + + closeHandle(win: any, handle: bigint, operation: string): void { + if (handle && !win.CloseHandle(handle)) throw lastError(operation); + } + + async cleanup(): Promise { + const win = this.win; + if (this.job && this.processHandle) { + try { + win.TerminateJobObject(this.job, 1); + } catch (error) { + this.report(error); + } + } else if (this.processHandle) { + try { + win.TerminateProcess(this.processHandle, 1); + } catch (error) { + this.report(error); + } + } + if (this.processHandle) { + const deadline = Date.now() + 500; + while (Date.now() < deadline) { + const status = win.WaitForSingleObject(this.processHandle, 0); + if (status === WAIT_OBJECT_0) break; + if (status !== WAIT_TIMEOUT) { + this.report(lastError("WaitForSingleObject(cleanup)")); + break; + } + await delay(10); + } + } + if (this.attrsInitialized) this.deleteAttributes(win); + for (const [handle, label] of [ + [this.threadHandle, "thread"], + [this.processHandle, "process"], + [this.input, "input pipe"], + [this.output, "output pipe"], + ] as const) { + if (handle) { + try { + this.closeHandle(win, handle, `CloseHandle(${label} cleanup)`); + } catch (error) { + this.report(error); + } + } + } + this.threadHandle = this.processHandle = this.input = this.output = 0n; + if (this.conpty) { + try { + win.ClosePseudoConsole(this.conpty); + } catch (error) { + this.report(error); + } + this.conpty = 0n; + } + } +} + +const port = parentPort; +if (!port) throw new Error("Windows FFI lifecycle must run in a Worker"); + +try { + const win = initializeWindowsBindings(); + const session = new FfiSession( + workerData.jobHandle as bigint, + win, + (reply) => port.postMessage({ kind: "reply", reply } satisfies FfiWorkerEnvelope), + (error) => + port.postMessage({ kind: "error", error: error.message } satisfies FfiWorkerEnvelope), + workerData.preparedStart as WindowsStart | undefined, + ); + port.postMessage({ + kind: "threadId", + threadId: win.GetCurrentThreadId(), + } satisfies FfiWorkerEnvelope); + port.on("message", (request: BrokerRequest) => { + void session.send(request).catch((error) => session.report(error)); + }); + void session.run().finally(() => port.close()); +} catch (error) { + port.postMessage({ + kind: "error", + error: error instanceof Error ? error.message : String(error), + } satisfies FfiWorkerEnvelope); + port.postMessage({ kind: "reply", reply: { type: "brokerDone" } } satisfies FfiWorkerEnvelope); + port.close(); +} diff --git a/experiments/ffi-pty/windows-ffi.mts b/experiments/ffi-pty/windows-ffi.mts new file mode 100644 index 000000000..31c10e47d --- /dev/null +++ b/experiments/ffi-pty/windows-ffi.mts @@ -0,0 +1,242 @@ +import { Worker } from "node:worker_threads"; +import type { BrokerReply, BrokerRequest } from "./windows-protocol.mts"; +import type { WindowsTransport } from "./windows-transport.mts"; +import type { WindowsStart } from "./windows-launch.mts"; +import { getWindowsBindings, initializeWindowsBindings, lastError } from "./windows-native.mts"; +import { classifyWindowsVersion, detectWindowsVersion } from "./windows-version.mts"; + +const NULL = 0n; +const THREAD_TERMINATE = 0x0001; +const ERROR_NOT_FOUND = 1168; +const JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000; + +export type FfiWorkerEnvelope = + | { kind: "threadId"; threadId: number } + | { kind: "reply"; reply: BrokerReply } + | { kind: "error"; error: string }; + +export interface FfiWorkerOptions { + requireModernOs?: boolean; + preparedStart?: WindowsStart; +} + +export function rehydrateWindowsStart(start: WindowsStart): WindowsStart { + return { + ...start, + application: Buffer.from(start.application), + commandLine: Buffer.from(start.commandLine), + cwd: Buffer.from(start.cwd), + environment: Buffer.from(start.environment), + }; +} + +export function createKillOnCloseJob(native = getWindowsBindings()): bigint { + const job = native.CreateJobObjectW(NULL, NULL) as bigint; + if (!job || job === 0xffff_ffff_ffff_ffffn) throw lastError("CreateJobObjectW"); + const info = Buffer.alloc(144); + info.writeUInt32LE(JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE, 16); + if (!native.SetInformationJobObject(job, 9, info, info.length)) { + const error = lastError("SetInformationJobObject"); + native.CloseHandle(job); + throw error; + } + return job; +} + +export class FfiTransport implements WindowsTransport { + readonly ready = Promise.resolve(); + readonly closed: Promise; + private readonly worker: Worker; + private readonly native = getWindowsBindings(); + private job: bigint; + private readonly messages = new Set<(reply: BrokerReply) => void>(); + private readonly errors = new Set<(error: Error) => void>(); + private resolveClosed!: () => void; + private threadId: number | undefined; + private syncThreadHandle = 0n; + private cancelTimer: NodeJS.Timeout | undefined; + private abortError: Error | undefined; + private jobTerminated = false; + private brokerDone = false; + private ending = false; + + constructor(job: bigint, preparedStart?: WindowsStart) { + this.job = job; + this.closed = new Promise((resolve) => (this.resolveClosed = resolve)); + try { + this.worker = new Worker(new URL("./windows-ffi-worker.mts", import.meta.url), { + workerData: { jobHandle: job, preparedStart }, + }); + } catch (error) { + this.closeJob(); + throw error; + } + this.worker.on("message", (message: FfiWorkerEnvelope) => this.onWorkerMessage(message)); + this.worker.on("error", (error) => this.report(error)); + this.worker.on("exit", (code) => this.onWorkerExit(code)); + } + + onMessage(listener: (reply: BrokerReply) => void): () => void { + this.messages.add(listener); + return () => this.messages.delete(listener); + } + + onError(listener: (error: Error) => void): () => void { + this.errors.add(listener); + return () => this.errors.delete(listener); + } + + async send(request: BrokerRequest): Promise { + if (request.type === "abort") { + this.requestAbort(new Error(request.error ?? "PTY transport was aborted")); + return; + } + if (this.ending) throw this.abortError ?? new Error("Windows FFI transport is closed"); + try { + this.worker.postMessage(request); + } catch (error) { + this.report(error); + throw error; + } + } + + async terminate(): Promise { + if (!this.ending) this.requestAbort(new Error("PTY transport terminated")); + await this.closed; + } + + onWorkerMessage(message: FfiWorkerEnvelope): void { + if (message.kind === "threadId") { + this.threadId = message.threadId; + this.openWorkerThreadHandle(); + if (this.abortError) this.cancelSynchronousIo(); + } else if (message.kind === "error") { + this.report(new Error(message.error)); + } else { + if (message.reply.type === "brokerDone") this.brokerDone = true; + for (const listener of this.messages) { + try { + listener(message.reply); + } catch (error) { + this.report(error); + } + } + } + } + + onWorkerExit(code: number): void { + if (this.cancelTimer) clearInterval(this.cancelTimer); + this.cancelTimer = undefined; + if (this.syncThreadHandle) { + try { + this.native.CloseHandle(this.syncThreadHandle); + } catch (error) { + this.report(error); + } + this.syncThreadHandle = 0n; + } + this.closeJob(); + if (code !== 0 && !this.abortError) { + this.report(new Error(`Windows FFI worker exited with code ${code}`)); + } + if (!this.brokerDone && !this.abortError) { + this.report(new Error("Windows FFI worker exited before brokerDone")); + } + this.ending = true; + this.resolveClosed(); + } + + requestAbort(error: Error): void { + if (this.ending) return; + this.ending = true; + this.abortError = error; + this.terminateJob(); + try { + this.worker.postMessage({ type: "abort", error: error.message } satisfies BrokerRequest); + } catch (cause) { + this.report(cause); + } + this.cancelSynchronousIo(); + this.cancelTimer = setInterval(() => this.cancelSynchronousIo(), 25); + } + + terminateJob(): void { + if (this.jobTerminated) return; + this.jobTerminated = true; + try { + if (!this.native.TerminateJobObject(this.job, 1)) { + this.report(lastError("TerminateJobObject from FFI transport")); + } + } catch (error) { + this.report(error); + } + } + + openWorkerThreadHandle(): void { + if (!this.threadId) return; + if (this.syncThreadHandle) return; + try { + this.syncThreadHandle = this.native.OpenThread(THREAD_TERMINATE, 0, this.threadId) as bigint; + if (!this.syncThreadHandle) this.report(lastError("OpenThread(FFI worker)")); + } catch (error) { + this.report(error); + } + } + + cancelSynchronousIo(): void { + this.openWorkerThreadHandle(); + if (!this.syncThreadHandle) return; + try { + if (!this.native.CancelSynchronousIo(this.syncThreadHandle)) { + const code = this.native.GetLastError(); + if (code !== ERROR_NOT_FOUND) + this.report(new Error(`CancelSynchronousIo failed with Win32 error ${code}`)); + } + } catch (error) { + this.report(error); + } + } + + closeJob(): void { + if (!this.job) return; + try { + if (!this.native.CloseHandle(this.job)) { + this.report(lastError("CloseHandle(job)")); + return; + } + this.job = 0n; + } catch (error) { + this.report(error); + } + } + + report(value: unknown): void { + const error = value instanceof Error ? value : new Error(String(value)); + for (const listener of this.errors) { + try { + listener(error); + } catch { + // Error listeners must not prevent Worker cleanup. + } + } + } +} + +export function createFfiWorkerTransport(options: FfiWorkerOptions = {}): WindowsTransport { + if (process.platform !== "win32") throw new Error("Windows ConPTY FFI requires Windows"); + if (process.arch !== "x64" && process.arch !== "arm64") { + throw new Error(`Unsupported Windows FFI architecture: ${process.arch}`); + } + if ( + options.requireModernOs !== false && + classifyWindowsVersion(detectWindowsVersion()) !== "ffi" + ) { + throw new Error("Direct Windows FFI requires Windows build 26100 or newer"); + } + initializeWindowsBindings(); + return new FfiTransport(createKillOnCloseJob(), options.preparedStart); +} + +export function createFfiTransport(): WindowsTransport { + return createFfiWorkerTransport({ requireModernOs: true }); +} diff --git a/experiments/ffi-pty/windows-helper-lock.mts b/experiments/ffi-pty/windows-helper-lock.mts new file mode 100644 index 000000000..87607697a --- /dev/null +++ b/experiments/ffi-pty/windows-helper-lock.mts @@ -0,0 +1,174 @@ +import { dlopen } from "node:ffi"; +import { lstatSync, realpathSync } from "node:fs"; +import { dirname } from "node:path"; +import { win32 as windowsPath } from "node:path"; +import { encodeWindowsString } from "./windows-launch.mts"; + +const INVALID_HANDLE_VALUE = 0xffff_ffff_ffff_ffffn; +const GENERIC_READ = 0x8000_0000; +const FILE_READ_ATTRIBUTES = 0x0000_0080; +const FILE_SHARE_READ = 0x0000_0001; +const FILE_SHARE_WRITE = 0x0000_0002; +const OPEN_EXISTING = 3; +const FILE_FLAG_OPEN_REPARSE_POINT = 0x0020_0000; +const FILE_FLAG_BACKUP_SEMANTICS = 0x0200_0000; +const FILE_ATTRIBUTE_DIRECTORY = 0x0010; +const FILE_ATTRIBUTE_REPARSE_POINT = 0x0400; + +export interface LockBindings { + CreateFileW( + path: Buffer, + access: number, + share: number, + security: bigint, + disposition: number, + flags: number, + template: bigint, + ): bigint; + GetFileInformationByHandle(handle: bigint, info: Buffer): number; + CloseHandle(handle: bigint): number; + GetLastError(): number; +} + +export interface WindowsHelperLock { + readonly path: string; + release(): void; +} + +let bindings: LockBindings | undefined; + +export function loadWindowsHelperLockBindings(): LockBindings { + if (!bindings) { + bindings = dlopen("kernel32.dll", { + CreateFileW: { + arguments: ["pointer", "uint32", "uint32", "pointer", "uint32", "uint32", "pointer"], + return: "pointer", + }, + GetFileInformationByHandle: { arguments: ["pointer", "pointer"], return: "int32" }, + CloseHandle: { arguments: ["pointer"], return: "int32" }, + GetLastError: { arguments: [], return: "uint32" }, + }).functions as unknown as LockBindings; + } + return bindings; +} + +export function rejectReparsePath(path: string): void { + if (!windowsPath.isAbsolute(path)) throw new TypeError("helper path must be absolute"); + const parsed = windowsPath.parse(path); + const parts = path + .slice(parsed.root.length) + .split(/[\\/]+/) + .filter(Boolean); + let current = parsed.root; + for (const part of parts) { + current = windowsPath.resolve(current, part); + if (lstatSync(current).isSymbolicLink()) + throw new Error(`helper path contains a reparse point: ${current}`); + } +} + +export function canonicalHelperPath(path: string): string { + if (process.platform !== "win32") throw new Error("Windows helper locks require Windows"); + if (!windowsPath.isAbsolute(path)) throw new TypeError("helper path must be absolute"); + rejectReparsePath(path); + const canonical = realpathSync.native(path); + if (!windowsPath.isAbsolute(canonical)) + throw new Error("helper path did not resolve to an absolute path"); + return canonical; +} + +export function openHelperLockHandle( + native: LockBindings, + path: string, + access: number, + share: number, + flags: number, +): bigint { + const handle = native.CreateFileW( + encodeWindowsString(path), + access, + share, + 0n, + OPEN_EXISTING, + flags | FILE_FLAG_OPEN_REPARSE_POINT, + 0n, + ); + if (handle === 0n || handle === INVALID_HANDLE_VALUE) { + throw new Error(`CreateFileW failed for helper lock with Win32 error ${native.GetLastError()}`); + } + return handle; +} + +export function helperHandleAttributes(native: LockBindings, handle: bigint): number { + const info = Buffer.alloc(52); + if (!native.GetFileInformationByHandle(handle, info)) { + throw new Error(`GetFileInformationByHandle failed with Win32 error ${native.GetLastError()}`); + } + return info.readUInt32LE(0); +} + +export function assertNotReparsePoint(attributes: number, path: string): void { + if (attributes & FILE_ATTRIBUTE_REPARSE_POINT) + throw new Error(`helper path is a reparse point: ${path}`); +} + +export function closeWindowsHandlePair( + native: LockBindings, + fileHandle: bigint, + directoryHandle: bigint, +): void { + let failure: Error | undefined; + for (const handle of [fileHandle, directoryHandle]) { + if (!handle) continue; + try { + if (!native.CloseHandle(handle)) failure ??= new Error("CloseHandle failed for helper lock"); + } catch (error) { + failure ??= error instanceof Error ? error : new Error(String(error)); + } + } + if (failure) throw failure; +} + +export function lockWindowsHelper(path: string, injected?: LockBindings): WindowsHelperLock { + if (process.platform !== "win32") throw new Error("Windows helper locks require Windows"); + const canonical = canonicalHelperPath(path); + const native = injected ?? loadWindowsHelperLockBindings(); + let directoryHandle = 0n; + let fileHandle = 0n; + try { + const directory = dirname(canonical); + directoryHandle = openHelperLockHandle( + native, + directory, + FILE_READ_ATTRIBUTES, + FILE_SHARE_READ | FILE_SHARE_WRITE, + FILE_FLAG_BACKUP_SEMANTICS, + ); + const directoryAttributes = helperHandleAttributes(native, directoryHandle); + if (!(directoryAttributes & FILE_ATTRIBUTE_DIRECTORY)) + throw new Error("helper parent is not a directory"); + assertNotReparsePoint(directoryAttributes, directory); + + fileHandle = openHelperLockHandle(native, canonical, GENERIC_READ, FILE_SHARE_READ, 0); + const fileAttributes = helperHandleAttributes(native, fileHandle); + if (fileAttributes & FILE_ATTRIBUTE_DIRECTORY) throw new Error("helper path is a directory"); + assertNotReparsePoint(fileAttributes, canonical); + } catch (error) { + try { + closeWindowsHandlePair(native, fileHandle, directoryHandle); + } catch { + // Preserve the lock acquisition error after attempting both closes. + } + throw error; + } + + let released = false; + return { + path: canonical, + release() { + if (released) return; + released = true; + closeWindowsHandlePair(native, fileHandle, directoryHandle); + }, + }; +} diff --git a/experiments/ffi-pty/windows-helper-pe.mts b/experiments/ffi-pty/windows-helper-pe.mts new file mode 100644 index 000000000..5bfab9531 --- /dev/null +++ b/experiments/ffi-pty/windows-helper-pe.mts @@ -0,0 +1,114 @@ +import { closeSync, fstatSync, openSync, readSync } from "node:fs"; + +export interface PeReader { + readonly size: number; + read(offset: number, length: number): Buffer; +} + +export interface PeCertificateSniff { + present: boolean; + reason: string; +} + +export function safePeRange(size: number, offset: number, length: number): boolean { + return ( + Number.isSafeInteger(size) && + Number.isSafeInteger(offset) && + Number.isSafeInteger(length) && + size >= 0 && + offset >= 0 && + length >= 0 && + offset <= size && + length <= size - offset + ); +} + +export function inspectPeCertificate(reader: PeReader): PeCertificateSniff { + // Reject malformed or unsigned layouts as soon as the headers prove it; only + // a plausible certificate table needs its 8-byte record header (110 bytes + // requested total). The certificate payload is never read here. + if (!Number.isSafeInteger(reader.size) || reader.size < 64) + return { present: false, reason: "PE file is too small" }; + const read = (offset: number, length: number): Buffer | undefined => { + if (!safePeRange(reader.size, offset, length)) return undefined; + const data = reader.read(offset, length); + return data.length === length ? data : undefined; + }; + const dos = read(0, 64); + if (!dos || dos.toString("ascii", 0, 2) !== "MZ") + return { present: false, reason: "invalid DOS header" }; + const peOffset = dos.readUInt32LE(0x3c); + if (peOffset < 64) return { present: false, reason: "PE header overlaps the DOS header" }; + const headers = read(peOffset, 26); + if (!headers || headers.toString("binary", 0, 4) !== "PE\0\0") + return { present: false, reason: "invalid PE header bounds or signature" }; + const optionalSize = headers.readUInt16LE(20); + const magic = headers.readUInt16LE(24); + const numberOffset = magic === 0x10b ? 92 : magic === 0x20b ? 108 : -1; + const directoryOffset = magic === 0x10b ? 96 : magic === 0x20b ? 112 : -1; + const securityEntryOffset = directoryOffset + 4 * 8; + if ( + numberOffset < 0 || + optionalSize < securityEntryOffset + 8 || + !safePeRange(reader.size, peOffset + 24, optionalSize) + ) { + return { present: false, reason: "invalid PE optional header" }; + } + const optionalOffset = peOffset + 24; + const directoryCount = read(optionalOffset + numberOffset, 4); + if (!directoryCount || directoryCount.readUInt32LE(0) < 5) + return { present: false, reason: "PE security directory is absent" }; + const securityEntry = read(optionalOffset + securityEntryOffset, 8); + if (!securityEntry) return { present: false, reason: "PE security directory is truncated" }; + const certificateOffset = securityEntry.readUInt32LE(0); + const certificateSize = securityEntry.readUInt32LE(4); + if (certificateOffset === 0 && certificateSize === 0) + return { present: false, reason: "PE certificate table is absent" }; + if ( + certificateOffset === 0 || + certificateSize < 8 || + certificateOffset % 8 !== 0 || + certificateOffset < optionalOffset + optionalSize || + !safePeRange(reader.size, certificateOffset, certificateSize) + ) { + return { present: false, reason: "invalid PE certificate table bounds" }; + } + const certificate = read(certificateOffset, 8); + if (!certificate) return { present: false, reason: "PE certificate header is truncated" }; + const recordLength = certificate.readUInt32LE(0); + const revision = certificate.readUInt16LE(4); + const type = certificate.readUInt16LE(6); + if ( + recordLength < 8 || + recordLength > certificateSize || + revision !== 0x0200 || + type !== 0x0002 + ) { + return { present: false, reason: "invalid WIN_CERTIFICATE header" }; + } + return { present: true, reason: "PE certificate table is present" }; +} + +export function sniffPeCertificate(path: string): PeCertificateSniff { + let fd: number; + try { + fd = openSync(path, "r"); + } catch (error) { + return { present: false, reason: `cannot open helper: ${String(error)}` }; + } + try { + const size = fstatSync(fd).size; + return inspectPeCertificate({ + size, + read: (offset, length) => { + const data = Buffer.alloc(length); + const bytesRead = readSync(fd, data, 0, length, offset); + return bytesRead === length ? data : data.subarray(0, bytesRead); + }, + }); + } catch (error) { + return { present: false, reason: `cannot inspect PE helper: ${String(error)}` }; + } finally { + closeSync(fd); + } +} diff --git a/experiments/ffi-pty/windows-helper-protocol.mts b/experiments/ffi-pty/windows-helper-protocol.mts new file mode 100644 index 000000000..74ae1f82c --- /dev/null +++ b/experiments/ffi-pty/windows-helper-protocol.mts @@ -0,0 +1,195 @@ +import type { SpawnOptions } from "./contract.mts"; +import type { WindowsStart } from "./windows-launch.mts"; +import type { BrokerReply, BrokerRequest } from "./windows-protocol.mts"; + +export const HELPER_MAGIC = 0x31595450; +export const HELPER_MAX_PAYLOAD = 8 * 1024 * 1024; +export const HELPER_OPCODE = { + start: 1, + connected: 2, + resize: 3, + kill: 4, + close: 5, + abort: 6, + pipes: 101, + spawned: 102, + ack: 103, + exited: 104, + error: 105, + done: 106, +} as const; + +export type PreparedWindowsStart = WindowsStart; + +export type HelperRequest = + | { type: "start"; options: SpawnOptions } + | Exclude; + +export interface HelperFrame { + opcode: number; + id: number; + payload: Buffer; +} + +const OPCODE_BY_REQUEST: Record = { + connected: HELPER_OPCODE.connected, + abort: HELPER_OPCODE.abort, + resize: HELPER_OPCODE.resize, + kill: HELPER_OPCODE.kill, + close: HELPER_OPCODE.close, +}; + +function u32(value: number, label: string): Buffer { + if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) { + throw new RangeError(`${label} must be a uint32`); + } + const result = Buffer.allocUnsafe(4); + result.writeUInt32LE(value); + return result; +} + +function stringField(value: string): Buffer { + if (value.includes("\0")) throw new Error("helper string contains NUL"); + const content = Buffer.from(`${value}\0`, "utf16le"); + return Buffer.concat([u32(content.length, "string byte length"), content]); +} + +function utf16BufferField(value: Buffer, doubleNul = false): Buffer { + if (value.length < 2 || value.length % 2 !== 0 || value.readUInt16LE(value.length - 2) !== 0) { + throw new Error("prepared UTF-16 buffer must end with NUL"); + } + if (doubleNul && (value.length < 4 || value.readUInt16LE(value.length - 4) !== 0)) { + throw new Error("prepared environment block must end with two NULs"); + } + if (!doubleNul) { + for (let offset = 0; offset < value.length - 2; offset += 2) { + if (value.readUInt16LE(offset) === 0) + throw new Error("prepared UTF-16 string contains an interior NUL"); + } + } + return Buffer.concat([u32(value.length, "string byte length"), value]); +} + +export function encodeHelperFrame(opcode: number, id: number, payload = Buffer.alloc(0)): Buffer { + if (payload.length > HELPER_MAX_PAYLOAD) + throw new RangeError("helper frame payload exceeds 8 MiB"); + const header = Buffer.allocUnsafe(16); + header.writeUInt32LE(HELPER_MAGIC, 0); + header.writeUInt32LE(opcode, 4); + header.writeUInt32LE(id, 8); + header.writeUInt32LE(payload.length, 12); + return Buffer.concat([header, payload]); +} + +export function encodeHelperRequest( + request: HelperRequest, + prepared?: PreparedWindowsStart, +): Buffer { + if (request.type === "start") { + if (!prepared) throw new Error("prepared Windows start data is required"); + const payload = Buffer.concat([ + u32(prepared.cols, "columns"), + u32(prepared.rows, "rows"), + utf16BufferField(prepared.application), + utf16BufferField(prepared.commandLine), + utf16BufferField(prepared.cwd), + utf16BufferField(prepared.environment, true), + stringField(prepared.inputName), + stringField(prepared.outputName), + ]); + return encodeHelperFrame(HELPER_OPCODE.start, 0, payload); + } + + const operation = request.type === "command" ? request.command : request.type; + const opcode = OPCODE_BY_REQUEST[operation]; + if (opcode === undefined) throw new Error(`unsupported helper request: ${operation}`); + let payload = Buffer.alloc(0); + if (operation === "resize" && request.type === "command") + payload = Buffer.concat([u32(request.cols, "columns"), u32(request.rows, "rows")]); + if (operation === "kill" && request.type === "command") payload = u32(request.signal, "signal"); + return encodeHelperFrame(opcode, "id" in request ? request.id : 0, payload); +} + +export function encodeHelperReply(reply: BrokerReply): Buffer { + let payload = Buffer.alloc(0); + let id = 0; + let opcode: number; + switch (reply.type) { + case "pipes": + opcode = HELPER_OPCODE.pipes; + break; + case "spawned": + opcode = HELPER_OPCODE.spawned; + payload = u32(reply.pid, "pid"); + break; + case "ack": + opcode = HELPER_OPCODE.ack; + id = reply.id; + payload = Buffer.from(reply.error ?? "", "utf8"); + break; + case "exited": + opcode = HELPER_OPCODE.exited; + payload = Buffer.concat([u32(reply.exitCode, "exit code"), u32(reply.signal, "signal")]); + break; + case "error": + opcode = HELPER_OPCODE.error; + payload = Buffer.from(reply.error, "utf8"); + break; + case "brokerDone": + opcode = HELPER_OPCODE.done; + break; + } + return encodeHelperFrame(opcode, id, payload); +} + +export function decodeHelperReply(frame: HelperFrame): BrokerReply { + const { payload, opcode, id } = frame; + const read = (offset: number) => { + if (payload.length < offset + 4) throw new Error("truncated helper reply"); + return payload.readUInt32LE(offset); + }; + switch (opcode) { + case HELPER_OPCODE.pipes: + if (payload.length) throw new Error("PIPES reply must be empty"); + return { type: "pipes", input: "", output: "" }; + case HELPER_OPCODE.spawned: + if (payload.length !== 4) throw new Error("SPAWNED reply must contain a pid"); + return { type: "spawned", pid: read(0) }; + case HELPER_OPCODE.ack: { + const error = payload.toString("utf8"); + return error ? { type: "ack", id, error } : { type: "ack", id }; + } + case HELPER_OPCODE.exited: + if (payload.length !== 8) throw new Error("EXITED reply must contain exit code and signal"); + return { type: "exited", exitCode: read(0), signal: read(4) }; + case HELPER_OPCODE.error: + return { type: "error", error: payload.toString("utf8") }; + case HELPER_OPCODE.done: + if (payload.length) throw new Error("DONE reply must be empty"); + return { type: "brokerDone" }; + default: + throw new Error(`unknown helper reply opcode: ${opcode}`); + } +} + +export function decodeHelperFrames( + chunk: Buffer, + pending = Buffer.alloc(0), +): { frames: HelperFrame[]; pending: Buffer } { + const data = pending.length ? Buffer.concat([pending, chunk]) : chunk; + const frames: HelperFrame[] = []; + let offset = 0; + while (data.length - offset >= 16) { + if (data.readUInt32LE(offset) !== HELPER_MAGIC) throw new Error("invalid helper frame magic"); + const size = data.readUInt32LE(offset + 12); + if (size > HELPER_MAX_PAYLOAD) throw new Error("helper frame payload exceeds 8 MiB"); + if (data.length - offset < 16 + size) break; + frames.push({ + opcode: data.readUInt32LE(offset + 4), + id: data.readUInt32LE(offset + 8), + payload: Buffer.from(data.subarray(offset + 16, offset + 16 + size)), + }); + offset += 16 + size; + } + return { frames, pending: Buffer.from(data.subarray(offset)) }; +} diff --git a/experiments/ffi-pty/windows-helper-publisher.mts b/experiments/ffi-pty/windows-helper-publisher.mts new file mode 100644 index 000000000..fdb1bd0ef --- /dev/null +++ b/experiments/ffi-pty/windows-helper-publisher.mts @@ -0,0 +1,8 @@ +export interface HelperPublisherPolicy { + subject: string; + issuer?: string; +} + +// Release tooling can set the approved full subject in this trusted source file. +// An empty default deliberately keeps affected Windows builds on the Node transport. +export const helperPublisherPolicy: HelperPublisherPolicy = Object.freeze({ subject: "" }); diff --git a/experiments/ffi-pty/windows-helper-trust.mts b/experiments/ffi-pty/windows-helper-trust.mts new file mode 100644 index 000000000..8f77d7b8d --- /dev/null +++ b/experiments/ffi-pty/windows-helper-trust.mts @@ -0,0 +1,200 @@ +import { execFile } from "node:child_process"; +import { dlopen } from "node:ffi"; +import { win32 as path } from "node:path"; +import { promisify } from "node:util"; +import { helperExecutablePath } from "./windows-helper.mts"; +import { helperPublisherPolicy, type HelperPublisherPolicy } from "./windows-helper-publisher.mts"; +import { lockWindowsHelper, type WindowsHelperLock } from "./windows-helper-lock.mts"; +import { sniffPeCertificate } from "./windows-helper-pe.mts"; + +const execFileAsync = promisify(execFile); +const POWERSHELL_TIMEOUT_MS = 5000; +const POWERSHELL_MAX_BUFFER = 32 * 1024; +const SYSTEM_DIRECTORY_CAPACITY = 32768; +const POWERSHELL_SCRIPT = String.raw` +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' +$sig = Microsoft.PowerShell.Security\Get-AuthenticodeSignature -LiteralPath $env:NODE_PTY_FFI_HELPER_PATH +$subject = '' +$issuer = '' +if ($null -ne $sig.SignerCertificate) { + $subject = $sig.SignerCertificate.Subject + $issuer = $sig.SignerCertificate.Issuer +} +[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) +[ordered]@{ status = [string]$sig.Status; subject = $subject; issuer = $issuer } | Microsoft.PowerShell.Utility\ConvertTo-Json -Compress +`; + +export interface AuthenticodeResult { + status: string; + subject: string; + issuer: string; +} + +export interface SystemDirectoryBindings { + GetSystemDirectoryW(buffer: Buffer, size: number): number; +} + +export type HelperVerification = + | { kind: "node"; reason: string } + | { kind: "native"; path: string; subject: string }; + +export type AuthenticodeVerifier = ( + path: string, + policy: HelperPublisherPolicy, +) => Promise; + +export interface HelperTrustDependencies { + sniff(path: string): { present: boolean; reason: string }; + lock(path: string): WindowsHelperLock; + retain(lock: WindowsHelperLock): void; +} + +export function releaseHelperLock(lock: WindowsHelperLock): void { + try { + lock.release(); + } catch { + // Verification failures must still fall back to the Node broker. + } +} + +const retainedHelperLocks: WindowsHelperLock[] = []; +let verifiedHelperPromise: Promise | undefined; +let systemDirectoryBindings: SystemDirectoryBindings | undefined; + +export function nodeHelper(reason: string): HelperVerification { + return { kind: "node", reason }; +} + +export function classifyAuthenticodeResult( + helperPath: string, + policy: HelperPublisherPolicy, + signature: AuthenticodeResult, +): HelperVerification { + if (!policy.subject) return nodeHelper("no helper publisher is configured"); + if (signature.status !== "Valid") + return nodeHelper(`helper signature status is ${signature.status}`); + if (signature.subject !== policy.subject) + return nodeHelper("helper signer subject does not match policy"); + if (policy.issuer !== undefined && signature.issuer !== policy.issuer) { + return nodeHelper("helper signer issuer does not match policy"); + } + return { kind: "native", path: helperPath, subject: signature.subject }; +} + +export function loadSystemDirectoryBindings(): SystemDirectoryBindings { + if (!systemDirectoryBindings) { + systemDirectoryBindings = dlopen("kernel32.dll", { + GetSystemDirectoryW: { arguments: ["pointer", "uint32"], return: "uint32" }, + }).functions as unknown as SystemDirectoryBindings; + } + return systemDirectoryBindings; +} + +export function readSystemDirectory(native = loadSystemDirectoryBindings()): string { + const buffer = Buffer.alloc(SYSTEM_DIRECTORY_CAPACITY * 2); + const length = native.GetSystemDirectoryW(buffer, SYSTEM_DIRECTORY_CAPACITY); + if (!length || length >= SYSTEM_DIRECTORY_CAPACITY) throw new Error("GetSystemDirectoryW failed"); + const directory = buffer.toString("utf16le", 0, length * 2); + if (!path.isAbsolute(directory)) + throw new Error("GetSystemDirectoryW returned a non-absolute path"); + return path.normalize(directory); +} + +export function systemPowerShellPath(readDirectory: () => string = readSystemDirectory): string { + const systemDirectory = readDirectory(); + if (!path.isAbsolute(systemDirectory)) throw new Error("System directory is not absolute"); + return path.join(systemDirectory, "WindowsPowerShell", "v1.0", "powershell.exe"); +} + +export function buildAuthenticodeVerifierEnv( + source: NodeJS.ProcessEnv, + helperPath: string, + readDirectory: () => string = readSystemDirectory, +): NodeJS.ProcessEnv { + const systemDirectory = readDirectory(); + if (!path.isAbsolute(systemDirectory)) throw new Error("System directory is not absolute"); + const environment = Object.create(null) as NodeJS.ProcessEnv; + for (const [key, value] of Object.entries(source)) { + if (value !== undefined && ["TEMP", "TMP"].includes(key.toUpperCase())) + environment[key] = value; + } + const systemRoot = path.dirname(systemDirectory); + environment.SystemRoot = systemRoot; + environment.WINDIR = systemRoot; + environment.PSModulePath = path.join(systemDirectory, "WindowsPowerShell", "v1.0", "Modules"); + environment.NODE_PTY_FFI_HELPER_PATH = helperPath; + return environment; +} + +export async function runPowerShellAuthenticodeVerifier( + helperPath: string, + policy: HelperPublisherPolicy, +): Promise { + const systemDirectory = readSystemDirectory(); + const trustedDirectory = () => systemDirectory; + const shell = systemPowerShellPath(trustedDirectory); + const env = buildAuthenticodeVerifierEnv(process.env, helperPath, trustedDirectory); + const { stdout } = await execFileAsync( + shell, + ["-NoProfile", "-NonInteractive", "-Command", POWERSHELL_SCRIPT], + { + env, + timeout: POWERSHELL_TIMEOUT_MS, + maxBuffer: POWERSHELL_MAX_BUFFER, + windowsHide: true, + encoding: "utf8", + }, + ); + const result = JSON.parse(String(stdout).trim()) as Partial; + if ( + typeof result.status !== "string" || + typeof result.subject !== "string" || + typeof result.issuer !== "string" + ) { + throw new Error("PowerShell returned an invalid Authenticode result"); + } + return { status: result.status, subject: result.subject, issuer: result.issuer }; +} + +export async function verifyHelperAtPath( + helperPath: string, + policy: HelperPublisherPolicy, + verifier: AuthenticodeVerifier = runPowerShellAuthenticodeVerifier, + dependencies: Partial = {}, +): Promise { + if (!policy.subject) return nodeHelper("no helper publisher is configured"); + let lock: WindowsHelperLock | undefined; + try { + const sniff = (dependencies.sniff ?? sniffPeCertificate)(helperPath); + if (!sniff.present) return nodeHelper(sniff.reason); + lock = (dependencies.lock ?? lockWindowsHelper)(helperPath); + const signature = await verifier(lock.path, policy); + const result = classifyAuthenticodeResult(lock.path, policy, signature); + if (result.kind === "native") + (dependencies.retain ?? ((item) => retainedHelperLocks.push(item)))(lock); + else releaseHelperLock(lock); + return result; + } catch (error) { + if (lock) releaseHelperLock(lock); + return nodeHelper(`helper verification failed: ${String(error)}`); + } +} + +export function getVerifiedHelper(): Promise { + if (!verifiedHelperPromise) { + verifiedHelperPromise = Promise.resolve() + .then(async () => { + if (!helperPublisherPolicy.subject) return nodeHelper("no helper publisher is configured"); + let helperPath: string; + try { + helperPath = helperExecutablePath(); + } catch (error) { + return nodeHelper(`native helper is unavailable: ${String(error)}`); + } + return verifyHelperAtPath(helperPath, helperPublisherPolicy); + }) + .catch((error) => nodeHelper(`native helper verification failed: ${String(error)}`)); + } + return verifiedHelperPromise; +} diff --git a/experiments/ffi-pty/windows-helper.mts b/experiments/ffi-pty/windows-helper.mts new file mode 100644 index 000000000..dd9bb543f --- /dev/null +++ b/experiments/ffi-pty/windows-helper.mts @@ -0,0 +1,145 @@ +import { spawn } from "node:child_process"; +import { resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import type { Writable } from "node:stream"; +import type { WindowsTransport } from "./windows-transport.mts"; +import { prepareWindowsStart } from "./windows-launch.mts"; +import { + decodeHelperFrames, + decodeHelperReply, + encodeHelperRequest, + type PreparedWindowsStart, +} from "./windows-helper-protocol.mts"; +import type { BrokerReply, BrokerRequest } from "./windows-protocol.mts"; + +export function helperExecutablePath(arch = process.arch): string { + if (arch !== "x64" && arch !== "arm64") + throw new Error(`No Windows helper is available for ${arch}`); + return resolve( + fileURLToPath(new URL(`../../build/ffi-pty/win32-${arch}/helper.exe`, import.meta.url)), + ); +} + +export function helperStartupEnv(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv { + const allowed = new Set(["SYSTEMROOT", "WINDIR", "TEMP", "TMP"]); + const result: NodeJS.ProcessEnv = {}; + for (const [name, value] of Object.entries(source)) { + if (value !== undefined && allowed.has(name.toUpperCase())) result[name] = value; + } + return result; +} + +export function emitError(listeners: Set<(error: Error) => void>, error: unknown): void { + const normalized = error instanceof Error ? error : new Error(String(error)); + for (const listener of listeners) { + try { + listener(normalized); + } catch { + // Transport error observers cannot interfere with process cleanup. + } + } +} + +export function writePipe(stdin: Writable, data: Buffer): Promise { + return new Promise((resolveWrite, rejectWrite) => { + if (stdin.destroyed || stdin.writableEnded) { + rejectWrite(new Error("Windows helper input is closed")); + return; + } + stdin.write(data, (error) => (error ? rejectWrite(error) : resolveWrite())); + }); +} + +export function createHelperTransport(executablePath = helperExecutablePath()): WindowsTransport { + if (process.platform !== "win32") + throw new Error("The native Windows helper transport requires Windows"); + const executable = executablePath; + const child = spawn(executable, [], { + stdio: ["pipe", "pipe", "ignore"], + windowsHide: true, + env: helperStartupEnv(process.env), + }); + const errors = new Set<(error: Error) => void>(); + const messages = new Set<(reply: BrokerReply) => void>(); + let pending = Buffer.alloc(0); + let startPrepared: PreparedWindowsStart | undefined; + let startSent = false; + let expectedTermination = false; + let sendChain = Promise.resolve(); + const ready = new Promise((resolveReady, rejectReady) => { + child.once("spawn", () => resolveReady()); + child.once("error", rejectReady); + }); + const closed = new Promise((resolveClosed) => child.once("close", () => resolveClosed())); + void ready.catch((error) => emitError(errors, error)); + void closed.then(() => { + if (!expectedTermination && child.exitCode !== 0) { + emitError( + errors, + new Error(`Windows helper exited with code ${child.exitCode ?? "unknown"}`), + ); + } + }); + child.on("error", (error) => emitError(errors, error)); + child.stdout.on("data", (chunk: Buffer) => { + try { + const decoded = decodeHelperFrames(Buffer.from(chunk), pending); + pending = decoded.pending; + for (const frame of decoded.frames) { + const reply = decodeHelperReply(frame); + if (reply.type === "pipes") { + if (!startPrepared) throw new Error("helper sent PIPES before START"); + reply.input = startPrepared.inputName; + reply.output = startPrepared.outputName; + } + for (const listener of messages) { + try { + listener(reply); + } catch (error) { + emitError(errors, error); + } + } + } + } catch (error) { + emitError(errors, error); + child.kill(); + } + }); + child.stdout.on("end", () => { + if (pending.length) emitError(errors, new Error("truncated Windows helper reply frame")); + }); + child.stdin.on("error", (error) => emitError(errors, error)); + + return { + ready, + closed, + send(request: BrokerRequest): Promise { + const operation = sendChain.then(async () => { + let prepared: PreparedWindowsStart | undefined; + if (request.type === "start") { + if (startSent) throw new Error("Windows helper START was already sent"); + prepared = prepareWindowsStart(request.options); + startPrepared = prepared; + startSent = true; + } + await ready; + await writePipe(child.stdin, encodeHelperRequest(request, prepared)); + }); + sendChain = operation.catch(() => {}); + return operation; + }, + onMessage(listener): () => void { + messages.add(listener); + return () => messages.delete(listener); + }, + onError(listener): () => void { + errors.add(listener); + return () => errors.delete(listener); + }, + async terminate(): Promise { + expectedTermination = true; + if (child.exitCode === null && child.signalCode === null) child.kill(); + await closed; + }, + }; +} diff --git a/experiments/ffi-pty/windows-launch.mts b/experiments/ffi-pty/windows-launch.mts new file mode 100644 index 000000000..9bf73a8dc --- /dev/null +++ b/experiments/ffi-pty/windows-launch.mts @@ -0,0 +1,42 @@ +import { randomUUID } from "node:crypto"; +import type { SpawnOptions } from "./contract.mts"; +import { validateDimension } from "./validation.mts"; +import { + buildWindowsCommandLine, + buildWindowsEnvironmentBlock, + resolveWindowsExecutable, + windowsPipeNames, +} from "./windows-commandline.mts"; + +export interface WindowsStart { + cols: number; + rows: number; + application: Buffer; + commandLine: Buffer; + cwd: Buffer; + environment: Buffer; + inputName: string; + outputName: string; +} + +export function encodeWindowsString(value: string): Buffer { + if (value.includes("\0")) throw new TypeError("NUL in Windows string"); + return Buffer.from(`${value}\0`, "utf16le"); +} + +export function prepareWindowsStart(options: SpawnOptions): WindowsStart { + validateDimension(options.cols, "cols"); + validateDimension(options.rows, "rows"); + const application = resolveWindowsExecutable(options.file, options.env, options.cwd); + const pipes = windowsPipeNames(randomUUID()); + return { + cols: options.cols, + rows: options.rows, + application: encodeWindowsString(application), + commandLine: encodeWindowsString(buildWindowsCommandLine(options.file, options.args)), + cwd: encodeWindowsString(options.cwd), + environment: buildWindowsEnvironmentBlock(options.env), + inputName: pipes.input, + outputName: pipes.output, + }; +} diff --git a/experiments/ffi-pty/windows-native.mts b/experiments/ffi-pty/windows-native.mts new file mode 100644 index 000000000..ed1133f38 --- /dev/null +++ b/experiments/ffi-pty/windows-native.mts @@ -0,0 +1,103 @@ +import { dlopen } from "node:ffi"; + +// Bind only after the caller has checked that direct Windows FFI is supported. +let bindings: any; +export function initializeWindowsBindings() { + if (bindings) return bindings; + bindings = dlopen("kernel32.dll", { + CreateNamedPipeW: { + arguments: ["pointer", "uint32", "uint32", "uint32", "uint32", "uint32", "uint32", "pointer"], + return: "pointer", + }, + CreatePipe: { + arguments: ["pointer", "pointer", "pointer", "uint32"], + return: "int32", + }, + CreateFileW: { + arguments: ["pointer", "uint32", "uint32", "pointer", "uint32", "uint32", "pointer"], + return: "pointer", + }, + GetNamedPipeInfo: { + arguments: ["pointer", "pointer", "pointer", "pointer", "pointer"], + return: "int32", + }, + PeekNamedPipe: { + arguments: ["pointer", "pointer", "uint32", "pointer", "pointer", "pointer"], + return: "int32", + }, + ConnectNamedPipe: { arguments: ["pointer", "pointer"], return: "int32" }, + CreatePseudoConsole: { + arguments: ["uint32", "pointer", "pointer", "uint32", "pointer"], + return: "int32", + }, + ClosePseudoConsole: { arguments: ["pointer"], return: "void" }, + ResizePseudoConsole: { arguments: ["pointer", "uint32"], return: "int32" }, + InitializeProcThreadAttributeList: { + arguments: ["pointer", "uint32", "uint32", "pointer"], + return: "int32", + }, + UpdateProcThreadAttribute: { + arguments: ["pointer", "uint32", "uint64", "pointer", "uint64", "pointer", "pointer"], + return: "int32", + }, + DeleteProcThreadAttributeList: { arguments: ["pointer"], return: "void" }, + CreateProcessW: { + arguments: [ + "pointer", + "pointer", + "pointer", + "pointer", + "int32", + "uint32", + "pointer", + "pointer", + "pointer", + "pointer", + ], + return: "int32", + }, + WaitForSingleObject: { arguments: ["pointer", "uint32"], return: "uint32" }, + GetExitCodeProcess: { arguments: ["pointer", "pointer"], return: "int32" }, + TerminateProcess: { arguments: ["pointer", "uint32"], return: "int32" }, + CreateJobObjectW: { arguments: ["pointer", "pointer"], return: "pointer" }, + SetInformationJobObject: { + arguments: ["pointer", "int32", "pointer", "uint32"], + return: "int32", + }, + TerminateJobObject: { arguments: ["pointer", "uint32"], return: "int32" }, + OpenThread: { arguments: ["uint32", "int32", "uint32"], return: "pointer" }, + CancelSynchronousIo: { arguments: ["pointer"], return: "int32" }, + GetCurrentThreadId: { arguments: [], return: "uint32" }, + CloseHandle: { arguments: ["pointer"], return: "int32" }, + GetLastError: { arguments: [], return: "uint32" }, + GetCurrentProcess: { arguments: [], return: "pointer" }, + GetProcessHandleCount: { arguments: ["pointer", "pointer"], return: "int32" }, + }).functions; + return bindings; +} + +export function getWindowsBindings() { + if (!bindings) throw new Error("Win32 bindings have not been initialized"); + return bindings; +} + +export const INVALID_HANDLE_VALUE = 0xffff_ffff_ffff_ffffn; + +export function utf16(value: string, terminate = true): Buffer { + if (value.includes("\0")) throw new Error("NUL in Windows string"); + return Buffer.from(value + (terminate ? "\0" : ""), "utf16le"); +} + +export function lastError(operation: string): Error { + if (!bindings) return new Error(`${operation} failed before Win32 bindings were initialized`); + return new Error(`${operation} failed with Win32 error ${bindings.GetLastError()}`); +} + +export function getProcessHandleCount(): number { + const native = getWindowsBindings(); + const count = Buffer.alloc(4); + if (!native.GetProcessHandleCount(native.GetCurrentProcess(), count)) { + throw new Error(`GetProcessHandleCount failed with Win32 error ${native.GetLastError()}`); + } + return count.readUInt32LE(); +} diff --git a/experiments/ffi-pty/windows-protocol.mts b/experiments/ffi-pty/windows-protocol.mts new file mode 100644 index 000000000..65f39b41c --- /dev/null +++ b/experiments/ffi-pty/windows-protocol.mts @@ -0,0 +1,17 @@ +import type { SpawnOptions } from "./contract.mts"; + +export type BrokerRequest = + | { type: "start"; options: SpawnOptions } + | { type: "connected" } + | { type: "abort"; error?: string } + | { type: "command"; id: number; command: "resize"; cols: number; rows: number } + | { type: "command"; id: number; command: "kill"; signal: number } + | { type: "command"; id: number; command: "close" }; + +export type BrokerReply = + | { type: "pipes"; input: string; output: string } + | { type: "spawned"; pid: number } + | { type: "ack"; id: number; error?: string } + | { type: "exited"; exitCode: number; signal: number } + | { type: "error"; error: string } + | { type: "brokerDone" }; diff --git a/experiments/ffi-pty/windows-selection.mts b/experiments/ffi-pty/windows-selection.mts new file mode 100644 index 000000000..cc40fd16f --- /dev/null +++ b/experiments/ffi-pty/windows-selection.mts @@ -0,0 +1,67 @@ +import { createRequire } from "node:module"; +import type { WindowsTransport } from "./windows-transport.mts"; +import { + classifyWindowsVersion, + detectWindowsVersion, + type WindowsVersion, +} from "./windows-version.mts"; +import { getVerifiedHelper, type HelperVerification } from "./windows-helper-trust.mts"; + +const require = createRequire(import.meta.url); + +export interface WindowsSelectionDependencies { + verifyHelper(): Promise; + createNodeTransport(): WindowsTransport; + createHelperTransport(path: string): WindowsTransport; + createFfiTransport(): WindowsTransport; +} + +export function defaultWindowsSelectionDependencies(): WindowsSelectionDependencies { + return { + verifyHelper: getVerifiedHelper, + createNodeTransport() { + return ( + require("./windows-broker-client.mts") as { createNodeTransport(): WindowsTransport } + ).createNodeTransport(); + }, + createHelperTransport(path) { + return ( + require("./windows-helper.mts") as { createHelperTransport(path: string): WindowsTransport } + ).createHelperTransport(path); + }, + createFfiTransport() { + return ( + require("./windows-ffi.mts") as { createFfiTransport(): WindowsTransport } + ).createFfiTransport(); + }, + }; +} + +export async function createWindowsTransport( + version: WindowsVersion = detectWindowsVersion(), + dependencies = defaultWindowsSelectionDependencies(), +): Promise { + const mode = classifyWindowsVersion(version); + if (mode === "unsupported") { + throw new Error( + `Windows build ${version.major}.${version.minor}.${version.build} does not support ConPTY`, + ); + } + if (mode === "ffi") { + return dependencies.createFfiTransport(); + } + + const verified = await dependencies.verifyHelper(); + if (verified.kind === "node") { + return dependencies.createNodeTransport(); + } + let transport: WindowsTransport | undefined; + try { + transport = dependencies.createHelperTransport(verified.path); + await transport.ready; + return transport; + } catch { + await transport?.terminate().catch(() => {}); + return dependencies.createNodeTransport(); + } +} diff --git a/experiments/ffi-pty/windows-transport.mts b/experiments/ffi-pty/windows-transport.mts new file mode 100644 index 000000000..4a389c5d3 --- /dev/null +++ b/experiments/ffi-pty/windows-transport.mts @@ -0,0 +1,10 @@ +import type { BrokerReply, BrokerRequest } from "./windows-protocol.mts"; + +export interface WindowsTransport { + readonly ready: Promise; + readonly closed: Promise; + send(request: BrokerRequest): Promise; + onMessage(listener: (reply: BrokerReply) => void): () => void; + onError(listener: (error: Error) => void): () => void; + terminate(): Promise; +} diff --git a/experiments/ffi-pty/windows-version.mts b/experiments/ffi-pty/windows-version.mts new file mode 100644 index 000000000..2ef4ae439 --- /dev/null +++ b/experiments/ffi-pty/windows-version.mts @@ -0,0 +1,75 @@ +import { dlopen } from "node:ffi"; + +const RTL_OSVERSIONINFOW_SIZE = 276; +const CONPTY_MINIMUM: WindowsVersion = { major: 10, minor: 0, build: 17763 }; +const DIRECT_FFI_MINIMUM: WindowsVersion = { major: 10, minor: 0, build: 26100 }; + +export interface WindowsVersion { + major: number; + minor: number; + build: number; +} + +export type WindowsVersionMode = "unsupported" | "helper" | "ffi"; + +export interface WindowsVersionBindings { + RtlGetVersion(info: Buffer): number; +} + +let cachedBindings: WindowsVersionBindings | undefined; + +export function loadWindowsVersionBindings(): WindowsVersionBindings { + if (!cachedBindings) { + cachedBindings = dlopen("ntdll.dll", { + RtlGetVersion: { arguments: ["pointer"], return: "int32" }, + }).functions as unknown as WindowsVersionBindings; + } + return cachedBindings; +} + +export function isValidWindowsVersion(value: unknown): value is WindowsVersion { + if (!value || typeof value !== "object") return false; + const version = value as WindowsVersion; + return [version.major, version.minor, version.build].every( + (part) => Number.isInteger(part) && part >= 0 && part <= 0xffff_ffff, + ); +} + +export function parseWindowsVersion(value: string): WindowsVersion { + const match = /^(\d+)\.(\d+)\.(\d+)(?:\.\d+)?$/.exec(value); + if (!match) throw new TypeError(`Invalid Windows version: ${value}`); + const version = { major: Number(match[1]), minor: Number(match[2]), build: Number(match[3]) }; + if (!isValidWindowsVersion(version)) throw new TypeError(`Invalid Windows version: ${value}`); + return version; +} + +export function classifyWindowsVersion(version: WindowsVersion): WindowsVersionMode { + if (!isValidWindowsVersion(version)) throw new TypeError("Invalid Windows version fields"); + if (compareWindowsVersions(version, CONPTY_MINIMUM) < 0) return "unsupported"; + if (compareWindowsVersions(version, DIRECT_FFI_MINIMUM) < 0) return "helper"; + return "ffi"; +} + +export function compareWindowsVersions(left: WindowsVersion, right: WindowsVersion): number { + for (const field of ["major", "minor", "build"] as const) { + if (left[field] !== right[field]) return left[field] < right[field] ? -1 : 1; + } + return 0; +} + +export function detectWindowsVersion(platform: NodeJS.Platform = process.platform): WindowsVersion { + if (platform !== "win32") throw new Error("Windows version detection requires Windows"); + const bindings = loadWindowsVersionBindings(); + // RTL_OSVERSIONINFOW contains five DWORDs and 128 UTF-16 WCHARs (276 bytes). + const info = Buffer.alloc(RTL_OSVERSIONINFOW_SIZE); + info.writeUInt32LE(RTL_OSVERSIONINFOW_SIZE, 0); + const status = bindings.RtlGetVersion(info); + if (status !== 0) throw new Error(`RtlGetVersion failed with NTSTATUS ${status}`); + const version = { + major: info.readUInt32LE(4), + minor: info.readUInt32LE(8), + build: info.readUInt32LE(12), + }; + if (!isValidWindowsVersion(version)) throw new Error("RtlGetVersion returned invalid fields"); + return version; +} diff --git a/experiments/ffi-pty/windows.mts b/experiments/ffi-pty/windows.mts new file mode 100644 index 000000000..a4175235f --- /dev/null +++ b/experiments/ffi-pty/windows.mts @@ -0,0 +1,456 @@ +import { PassThrough } from "node:stream"; +import { createConnection, type Socket } from "node:net"; +import type { Backend, SpawnOptions, ExitStatus } from "./contract.mts"; +import { validateDimension } from "./validation.mts"; +import { buildWindowsCommandLine, buildWindowsEnvironmentBlock } from "./windows-commandline.mts"; +import type { BrokerReply, BrokerRequest } from "./windows-protocol.mts"; +import { createWindowsTransport } from "./windows-selection.mts"; + +export type { Backend, SpawnOptions } from "./contract.mts"; + +const MAX_QUEUED_INPUT = 8 * 1024 * 1024; +const STARTUP_TIMEOUT_MS = 15_000; +const COMMAND_TIMEOUT_MS = 10_000; +const GRACEFUL_STOP_MS = 1_000; +const BROKER_STOP_MS = 3_000; +export { createWindowsTransport }; + +export async function promiseWithTimeout( + promise: Promise, + ms: number, + message: string, +): Promise { + let timer: NodeJS.Timeout | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error(message)), ms); + }), + ]); + } finally { + if (timer) clearTimeout(timer); + } +} + +export function dimensions(cols: number, rows: number): void { + validateDimension(cols, "cols"); + validateDimension(rows, "rows"); +} + +export function windowsSignalNumber(signal: string): number { + const signals: Record = { SIGTERM: 15, SIGKILL: 9 }; + const value = signals[signal.toUpperCase()]; + if (value === undefined) throw new Error(`Unsupported Windows termination signal: ${signal}`); + return value; +} + +export function asError(value: unknown): Error { + return value instanceof Error ? value : new Error(String(value)); +} + +export async function createBackend(options: SpawnOptions): Promise { + if (process.platform !== "win32") throw new Error("Windows ConPTY backend requires Windows"); + if (process.arch !== "x64" && process.arch !== "arm64") + throw new Error(`Unsupported Windows architecture: ${process.arch}`); + dimensions(options.cols, options.rows); + if (!options.file || options.file.includes("\0") || options.cwd.includes("\0")) + throw new Error("Invalid executable path or cwd"); + buildWindowsCommandLine(options.file, options.args); + buildWindowsEnvironmentBlock(options.env); + + const transport = await createWindowsTransport(); + const output = new PassThrough({ highWaterMark: 64 * 1024 }); + const sockets = new Set(); + const pending = new Map< + number, + { resolve(): void; reject(error: Error): void; timer: NodeJS.Timeout } + >(); + let input: Socket | undefined; + let outputSocket: Socket | undefined; + let forwardOutput: ((chunk: Buffer) => void) | undefined; + let serial = 0; + let queued = 0; + let writeTail = Promise.resolve(); + let startupTimer: NodeJS.Timeout | undefined; + let brokerDone = false; + let transportStopped = false; + let outputEnded = false; + let remoteOutputEnded = false; + let exitStatus: ExitStatus | undefined; + let failure: Error | undefined; + let closed = false; + let closing = false; + let terminationRequested = false; + let settled = false; + let closePromise: Promise | undefined; + let cleanupPromise: Promise | undefined; + let resolvePipes!: () => void; + let rejectPipes!: (error: Error) => void; + let resolveSpawned!: (pid: number) => void; + let rejectSpawned!: (error: Error) => void; + let resolveBrokerDone!: () => void; + let rejectFailure!: (error: Error) => void; + let rejectExited!: (error: Error) => void; + let resolveExited!: (status: ExitStatus) => void; + const pipesReady = new Promise((resolve, reject) => { + resolvePipes = resolve; + rejectPipes = reject; + }); + const spawned = new Promise((resolve, reject) => { + resolveSpawned = resolve; + rejectSpawned = reject; + }); + const brokerDonePromise = new Promise((resolve) => { + resolveBrokerDone = resolve; + }); + const failurePromise = new Promise((_, reject) => { + rejectFailure = reject; + }); + const exited = new Promise((resolve, reject) => { + resolveExited = resolve; + rejectExited = reject; + }); + void pipesReady.catch(() => {}); + void spawned.catch(() => {}); + void exited.catch(() => {}); + void failurePromise.catch(() => {}); + output.on("error", () => {}); + + const allSocketsClosed = () => [...sockets].every((socket) => socket.closed); + const finishExit = () => { + if ( + !settled && + !failure && + exitStatus && + outputEnded && + brokerDone && + transportStopped && + allSocketsClosed() + ) { + settled = true; + resolveExited(exitStatus); + } + }; + const destroySockets = async () => { + await Promise.all( + [...sockets].map( + (socket) => + new Promise((resolve) => { + if (socket.closed) return resolve(); + socket.once("close", () => resolve()); + socket.destroy(); + }), + ), + ); + finishExit(); + }; + const stopBroker = (error: Error): Promise => { + if (cleanupPromise) return cleanupPromise; + cleanupPromise = (async () => { + output.resume(); + input?.destroy(); + if (outputSocket && !remoteOutputEnded) { + if (forwardOutput) outputSocket.off("data", forwardOutput); + outputSocket.on("data", () => {}); + outputSocket.resume(); + } + void transport.send({ type: "abort", error: error.message }).catch(() => {}); + try { + await promiseWithTimeout( + brokerDonePromise, + GRACEFUL_STOP_MS, + "PTY broker cleanup timed out", + ); + } catch { + await destroySockets(); + } + let cleanupError: Error | undefined; + try { + await promiseWithTimeout( + transport.terminate(), + BROKER_STOP_MS, + "Windows PTY transport termination timed out", + ); + } catch (cause) { + cleanupError = asError(cause); + } + try { + await promiseWithTimeout( + transport.closed, + BROKER_STOP_MS, + "Windows PTY transport exit timed out", + ); + } catch (cause) { + cleanupError ??= asError(cause); + } + await destroySockets(); + if (!output.destroyed) output.destroy(error); + if (cleanupError) throw cleanupError; + })(); + return cleanupPromise; + }; + const fail = (cause: unknown) => { + if (failure || settled) return; + failure = asError(cause); + if (startupTimer) clearTimeout(startupTimer); + rejectPipes(failure); + rejectSpawned(failure); + if (!settled) { + settled = true; + rejectExited(failure); + } + rejectFailure(failure); + for (const request of pending.values()) { + clearTimeout(request.timer); + request.reject(failure); + } + pending.clear(); + void stopBroker(failure).catch(() => {}); + }; + const send = async (message: BrokerRequest): Promise => { + try { + await transport.send(message); + } catch (error) { + fail(error); + throw asError(error); + } + }; + const connectPipe = (path: string, isOutput = false): Promise => { + const socket = createConnection(path); + sockets.add(socket); + if (isOutput) outputSocket = socket; + socket.on("error", (error) => { + const expectedInputEof = + !isOutput && + (closing || terminationRequested) && + (error as NodeJS.ErrnoException).code === "EOF"; + // A pending write still rejects through its write callback on deliberate shutdown. + if (!expectedInputEof) fail(error); + }); + socket.on("close", () => { + if (isOutput && !remoteOutputEnded) { + remoteOutputEnded = true; + output.end(); + } + finishExit(); + }); + return new Promise((resolve, reject) => { + const onConnect = () => { + socket.off("error", onConnectError); + socket.off("close", onCloseBeforeConnect); + resolve(socket); + }; + const onConnectError = (error: Error) => { + socket.off("connect", onConnect); + socket.off("close", onCloseBeforeConnect); + reject(error); + }; + const onCloseBeforeConnect = () => { + socket.off("connect", onConnect); + socket.off("error", onConnectError); + reject(new Error("PTY broker pipe closed before connecting")); + }; + socket.once("connect", onConnect); + socket.once("error", onConnectError); + socket.once("close", onCloseBeforeConnect); + }); + }; + const onReply = (reply: BrokerReply) => { + if (reply.type === "pipes") { + if (sockets.size || failure) return fail(new Error("Unexpected PTY broker pipe setup")); + const inputPromise = connectPipe(reply.input); + const outputPromise = connectPipe(reply.output, true); + void Promise.all([inputPromise, outputPromise]) + .then(async ([inputSocket, connectedOutput]) => { + if (failure) return; + input = inputSocket; + outputSocket = connectedOutput; + forwardOutput = (chunk: Buffer) => { + if (!output.write(chunk)) connectedOutput.pause(); + }; + connectedOutput.on("data", forwardOutput); + output.on("drain", () => connectedOutput.resume()); + connectedOutput.once("end", () => { + remoteOutputEnded = true; + output.end(); + connectedOutput.destroy(); + }); + await send({ type: "connected" }); + resolvePipes(); + }, fail) + .catch(fail); + } else if (reply.type === "spawned") { + if (startupTimer) clearTimeout(startupTimer); + resolveSpawned(reply.pid); + } else if (reply.type === "ack") { + const request = pending.get(reply.id); + if (!request) return; + pending.delete(reply.id); + clearTimeout(request.timer); + if (reply.error) request.reject(new Error(reply.error)); + else request.resolve(); + } else if (reply.type === "exited") { + exitStatus = { exitCode: reply.signal ? null : reply.exitCode, signal: reply.signal }; + input?.destroy(); + finishExit(); + } else if (reply.type === "error") { + fail(new Error(reply.error)); + } else if (reply.type === "brokerDone") { + brokerDone = true; + resolveBrokerDone(); + for (const request of pending.values()) { + clearTimeout(request.timer); + request.reject(new Error("PTY broker stopped")); + } + pending.clear(); + if (!exitStatus && !failure) fail(new Error("PTY broker stopped without an exit status")); + finishExit(); + } + }; + + startupTimer = setTimeout( + () => fail(new Error("Timed out starting ConPTY process")), + STARTUP_TIMEOUT_MS, + ); + output.once("end", () => { + outputEnded = true; + finishExit(); + }); + const removeMessageListener = transport.onMessage(onReply); + const removeErrorListener = transport.onError(fail); + void transport.closed.then(() => { + removeMessageListener(); + removeErrorListener(); + transportStopped = true; + if (!brokerDone && !failure) fail(new Error("Windows PTY transport closed before brokerDone")); + finishExit(); + }, fail); + const command = (request: Extract): Promise => { + if (closed || closing || failure || brokerDone || exitStatus) + return Promise.reject(new Error("PTY is closed or the process has exited")); + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + pending.delete(request.id); + const error = new Error(`ConPTY ${request.command} request timed out`); + reject(error); + fail(error); + }, COMMAND_TIMEOUT_MS); + pending.set(request.id, { resolve, reject, timer }); + void send(request).catch((error) => { + pending.delete(request.id); + clearTimeout(timer); + reject(asError(error)); + }); + }); + }; + + const stop = async () => { + try { + if (failure) await stopBroker(failure); + else { + output.resume(); + if (!exitStatus && !brokerDone) { + const id = ++serial; + void send({ type: "command", id, command: "close" }).catch(() => {}); + } + await promiseWithTimeout(exited, STARTUP_TIMEOUT_MS, "ConPTY process exit timed out"); + await destroySockets(); + await writeTail; + } + } catch (error) { + const failureError = asError(error); + fail(failureError); + await stopBroker(failureError).catch(() => {}); + throw error; + } + }; + + try { + await promiseWithTimeout( + Promise.race([transport.ready, failurePromise]), + STARTUP_TIMEOUT_MS, + "Windows PTY transport startup timed out", + ); + await send({ type: "start", options }); + await promiseWithTimeout(pipesReady, STARTUP_TIMEOUT_MS, "ConPTY pipes timed out"); + const pid = await promiseWithTimeout( + spawned, + STARTUP_TIMEOUT_MS, + "ConPTY process startup timed out", + ); + return { + pid, + readable: output, + write(buffer) { + if (closed || closing || failure || exitStatus || brokerDone || !input || input.destroyed) + return Promise.reject(new Error("PTY is closed")); + const copy = Buffer.from(buffer); + if (queued + copy.length > MAX_QUEUED_INPUT) + return Promise.reject(new Error("PTY input queue limit exceeded (8 MiB maximum)")); + queued += copy.length; + const operation = writeTail + .then( + () => + new Promise((resolve, reject) => { + const socket = input; + if ( + closed || + closing || + failure || + exitStatus || + brokerDone || + !socket || + socket.destroyed + ) + return reject(new Error("PTY input pipe is closed")); + socket.write(copy, (error) => (error ? reject(error) : resolve())); + }), + ) + .finally(() => { + queued -= copy.length; + }); + writeTail = operation.catch(() => {}); + return operation; + }, + resize(cols, rows) { + dimensions(cols, rows); + return command({ type: "command", id: ++serial, command: "resize", cols, rows }); + }, + kill(signal = "SIGTERM") { + let number: number; + try { + number = windowsSignalNumber(signal); + } catch (error) { + return Promise.reject(error); + } + terminationRequested = true; + return command({ type: "command", id: ++serial, command: "kill", signal: number }).catch( + (error) => { + if (!closing && !exitStatus) terminationRequested = false; + throw error; + }, + ); + }, + close() { + if (!closePromise) { + closed = true; + closing = true; + terminationRequested = true; + closePromise = stop().finally(async () => { + output.resume(); + input?.destroy(); + await destroySockets(); + await writeTail; + }); + } + return closePromise; + }, + exited, + }; + } catch (error) { + fail(error); + await stopBroker(asError(error)).catch(() => {}); + throw error; + } +} diff --git a/test/experiments/ffi-pty/build-windows-helper.test.mts b/test/experiments/ffi-pty/build-windows-helper.test.mts new file mode 100644 index 000000000..f46040436 --- /dev/null +++ b/test/experiments/ffi-pty/build-windows-helper.test.mts @@ -0,0 +1,22 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { + quoteResponsePath, + targetArchitecture, +} from "../../../experiments/ffi-pty/build-windows-helper.mts"; + +test("helper build target honors explicit and npm architecture selection", () => { + assert.equal(targetArchitecture(["--arch=arm64"], {}), "arm64"); + assert.equal(targetArchitecture([], { npm_config_arch: "x64" }), "x64"); + assert.equal(targetArchitecture([], { ARCH: "arm64" }), "arm64"); + assert.throws(() => targetArchitecture(["--arch=ia32"], {}), /supports x64 and arm64/); +}); + +test("MSVC response paths stay quoted without trailing slash escapes", () => { + assert.equal( + quoteResponsePath("C:\\Program Files\\VS\\cl.exe"), + '"C:\\Program Files\\VS\\cl.exe"', + ); + assert.equal(quoteResponsePath("C:\\build\\out/"), '"C:\\build\\out/"'); + assert.throws(() => quoteResponsePath('C:\\bad"path'), /may not contain quotes/); +}); diff --git a/test/experiments/ffi-pty/darwin-bootstrap.test.mts b/test/experiments/ffi-pty/darwin-bootstrap.test.mts new file mode 100644 index 000000000..006c17667 --- /dev/null +++ b/test/experiments/ffi-pty/darwin-bootstrap.test.mts @@ -0,0 +1,44 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + recoverTargetEnvironment, + splitTargetEnvironment, +} from "../../../experiments/ffi-pty/darwin-bootstrap.mts"; + +test("bootstrap restores target NODE_* values and private-key collisions without mutating input", () => { + const original = { + PATH: "/bin", + PTY_FFI_TARGET_NODE_ENV: JSON.stringify({ + NODE_OPTIONS: "--no-warnings", + NODE_PATH: "/target/modules", + PTY_FFI_TARGET_NODE_ENV: "target-value", + }), + }; + const target = recoverTargetEnvironment(original); + assert.deepEqual(target, { + PATH: "/bin", + NODE_OPTIONS: "--no-warnings", + NODE_PATH: "/target/modules", + PTY_FFI_TARGET_NODE_ENV: "target-value", + }); + assert.equal(typeof original.PTY_FFI_TARGET_NODE_ENV, "string"); +}); + +test("bootstrap preserves special environment keys through its target payload", () => { + const original = Object.create(null) as Record; + original.PATH = "/bin"; + original.NODE_OPTIONS = "--no-warnings"; + original.PTY_FFI_TARGET_NODE_ENV = "target-private-key"; + original.__proto__ = "target-prototype-key"; + + const bootstrapEnv = splitTargetEnvironment(original); + assert.equal(Object.getPrototypeOf(bootstrapEnv), null); + assert.equal(Object.hasOwn(bootstrapEnv, "__proto__"), true); + assert.equal(bootstrapEnv.__proto__, "target-prototype-key"); + const restored = recoverTargetEnvironment(bootstrapEnv); + assert.equal(restored.__proto__, "target-prototype-key"); + assert.equal(Object.hasOwn(restored, "__proto__"), true); + assert.equal(restored.PTY_FFI_TARGET_NODE_ENV, "target-private-key"); + assert.equal(restored.NODE_OPTIONS, "--no-warnings"); + assert.equal(original.__proto__, "target-prototype-key"); +}); diff --git a/test/experiments/ffi-pty/darwin.test.mts b/test/experiments/ffi-pty/darwin.test.mts new file mode 100644 index 000000000..524cac017 --- /dev/null +++ b/test/experiments/ffi-pty/darwin.test.mts @@ -0,0 +1,98 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { spawnPty } from "../../../experiments/ffi-pty/pty.mts"; + +test( + "Darwin backend starts a controlling-terminal session and drains output before exit", + { skip: process.platform !== "darwin" }, + async () => { + const pty = await spawnPty( + "sh", + [ + "-c", + 'test -t 0 && test -t 1 && test -t 2 && echo TTY_OK; printf \'PWD:%s TERM:%s\\n\' "$PWD" "$TERM"; exit 7', + ], + { cwd: "/tmp", env: { PATH: "/bin" } }, + ); + let output = ""; + const data = pty.onData((chunk) => { + output += chunk; + }); + try { + assert.deepEqual(await pty.exited, { exitCode: 7, signal: 0 }); + assert.match(output, /TTY_OK/); + assert.match(output, /PWD:(?:\/private)?\/tmp TERM:xterm-256color/); + } finally { + data.dispose(); + await pty.close(); + } + }, +); + +test( + "Darwin bootstrap gives a direct Node child access to /dev/tty and restores NODE_* env", + { skip: process.platform !== "darwin" }, + async () => { + const source = [ + "const fs = require('node:fs');", + "const fd = fs.openSync('/dev/tty', 'r'); fs.closeSync(fd);", + "console.log('CONTROLLING_TTY:' + process.env.FIXTURE_NODE_ENV + ' SPECIAL_ENV:' + process.env['__proto__']);", + ].join(" "); + const pty = await spawnPty(process.execPath, ["-e", source], { + env: { + PATH: "/bin", + NODE_OPTIONS: "--no-warnings", + PTY_FFI_TARGET_NODE_ENV: "original", + FIXTURE_NODE_ENV: "restored", + ["__proto__"]: "restored special key", + }, + }); + let output = ""; + const data = pty.onData((chunk) => { + output += chunk; + }); + try { + assert.deepEqual(await pty.exited, { exitCode: 0, signal: 0 }); + assert.match(output, /CONTROLLING_TTY:restored/); + assert.match(output, /SPECIAL_ENV:restored special key/); + } finally { + data.dispose(); + await pty.close(); + } + }, +); + +test( + "Darwin backend validates executable before allocating a PTY", + { skip: process.platform !== "darwin" }, + async () => { + await assert.rejects(() => spawnPty("/definitely/not/a/command", []), /Executable not found/); + }, +); + +test( + "Darwin resize updates the kernel terminal dimensions", + { skip: process.platform !== "darwin" }, + async () => { + const pty = await spawnPty("/bin/sh", ["-c", "stty -echo; echo READY; read line; stty size"]); + let output = ""; + let ready!: () => void; + const readySeen = new Promise((resolve) => { + ready = resolve; + }); + const data = pty.onData((chunk) => { + output += chunk; + if (output.includes("READY")) ready(); + }); + try { + await readySeen; + await pty.resize(117, 43); + await pty.write("\n"); + assert.deepEqual(await pty.exited, { exitCode: 0, signal: 0 }); + assert.match(output, /43 117/); + } finally { + data.dispose(); + await pty.close(); + } + }, +); diff --git a/test/experiments/ffi-pty/events.test.mts b/test/experiments/ffi-pty/events.test.mts new file mode 100644 index 000000000..2d95a7449 --- /dev/null +++ b/test/experiments/ffi-pty/events.test.mts @@ -0,0 +1,198 @@ +import assert from "node:assert/strict"; +import { PassThrough, Readable } from "node:stream"; +import { test } from "node:test"; +import type { Backend } from "../../../experiments/ffi-pty/contract.mts"; +import { createPtyFromBackend } from "../../../experiments/ffi-pty/events.mts"; + +function fake(chunks: Buffer[] = [], exitCode = 0, readable: PassThrough | undefined = undefined) { + let finish!: (value: { exitCode: number | null; signal: number }) => void; + let fail!: (error: Error) => void; + const exited = new Promise<{ exitCode: number | null; signal: number }>((resolve, reject) => { + finish = resolve; + fail = reject; + }); + const writes: Buffer[] = []; + let closeCalls = 0; + let killCalls = 0; + let resizeError: Error | undefined; + const backend: Backend = { + pid: 42, + readable: readable ?? Readable.from(chunks), + write: async (data) => { + writes.push(data); + }, + resize: async () => { + if (resizeError) throw resizeError; + }, + kill: async () => { + killCalls++; + }, + close: async () => { + closeCalls++; + }, + exited, + }; + return { + backend, + writes, + finish: () => finish({ exitCode, signal: 0 }), + fail, + get closeCalls() { + return closeCalls; + }, + get killCalls() { + return killCalls; + }, + set resizeError(error: Error | undefined) { + resizeError = error; + }, + }; +} + +test("preserves split UTF-8 sequences and resolves exit after output drains", async () => { + const encoded = Buffer.from("héllo 🐸"); + const cut = encoded.indexOf(0xc3) + 1; + const fakeBackend = fake([encoded.subarray(0, cut), encoded.subarray(cut)]); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + let data = ""; + const events: string[] = []; + pty.onData((chunk) => { + data += chunk; + events.push("data"); + }); + pty.onExit(() => events.push("exit")); + fakeBackend.finish(); + assert.deepEqual(await pty.exited, { exitCode: 0, signal: 0 }); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(data, "héllo 🐸"); + assert.equal(events.at(-1), "exit"); +}); + +test("pause buffers bounded output until resume; writes preserve buffer bytes", async () => { + const fakeBackend = fake([Buffer.from("first"), Buffer.from("second")]); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + let data = ""; + pty.onData((chunk) => { + data += chunk; + }); + pty.pause(); + await pty.write(Buffer.from([0, 255])); + assert.deepEqual(fakeBackend.writes[0], Buffer.from([0, 255])); + pty.resume(); + fakeBackend.finish(); + assert.deepEqual(await pty.exited, { exitCode: 0, signal: 0 }); + assert.equal(data, "firstsecond"); +}); + +test("waits for readable EOF after backend exit before resolving exited", async () => { + const readable = new PassThrough(); + const fakeBackend = fake([], 0, readable); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + const output: string[] = []; + pty.onData((chunk) => output.push(chunk)); + fakeBackend.finish(); + await new Promise((resolve) => setImmediate(resolve)); + let resolved = false; + void pty.exited.then(() => { + resolved = true; + }); + readable.end("last chunk"); + assert.deepEqual(await pty.exited, { exitCode: 0, signal: 0 }); + assert.equal(resolved, true); + assert.equal(output.join(""), "last chunk"); +}); + +test("waits for backend exit after readable EOF", async () => { + const readable = new PassThrough(); + const fakeBackend = fake([], 0, readable); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + readable.end("eof first"); + await new Promise((resolve) => setImmediate(resolve)); + let resolved = false; + void pty.exited.then(() => { + resolved = true; + }); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(resolved, false); + await pty.kill("SIGTERM"); + assert.equal(fakeBackend.killCalls, 1, "EOF alone does not prevent terminating a live child"); + fakeBackend.finish(); + assert.deepEqual(await pty.exited, { exitCode: 0, signal: 0 }); +}); + +test("stream errors reject exited and close the backend exactly once", async () => { + const readable = new PassThrough(); + const fakeBackend = fake([], 0, readable); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + readable.destroy(new Error("read failed")); + await assert.rejects(pty.exited, /read failed/); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(fakeBackend.closeCalls, 1); +}); + +test("backend exit rejection rejects exited and closes the backend", async () => { + const fakeBackend = fake(); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + fakeBackend.fail(new Error("wait failed")); + await assert.rejects(pty.exited, /wait failed/); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(fakeBackend.closeCalls, 1); +}); + +test("a stream error cannot later emit a successful exit event", async () => { + const readable = new PassThrough(); + const fakeBackend = fake([], 0, readable); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + readable.destroy(new Error("read failed")); + await assert.rejects(pty.exited, /read failed/); + fakeBackend.finish(); + let called = false; + pty.onExit(() => { + called = true; + }); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(called, false); +}); + +test("disposed late exit listeners do not run from the queued callback", async () => { + const fakeBackend = fake(); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + fakeBackend.finish(); + // Let the readable end and backend status settle before subscribing. + await new Promise((resolve) => setImmediate(resolve)); + await pty.exited; + let called = false; + const subscription = pty.onExit(() => { + called = true; + }); + subscription.dispose(); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(called, false); +}); + +test("close is idempotent and operations reject after natural exit", async () => { + const fakeBackend = fake(); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + fakeBackend.finish(); + await pty.exited; + await assert.rejects(pty.write("late"), /exited/); + await assert.rejects(pty.resize(90, 30), /exited/); + await pty.kill("SIGTERM"); + assert.equal(fakeBackend.killCalls, 0); + await Promise.all([pty.close(), pty.close()]); + assert.equal(fakeBackend.closeCalls, 1); + await assert.rejects(pty.write("after close"), /closed/); +}); + +test("resize updates reported dimensions only when backend resize succeeds", async () => { + const fakeBackend = fake(); + const pty = createPtyFromBackend(fakeBackend.backend, 80, 24); + fakeBackend.resizeError = new Error("resize failed"); + await assert.rejects(pty.resize(100, 40), /resize failed/); + assert.deepEqual([pty.cols, pty.rows], [80, 24]); + fakeBackend.resizeError = undefined; + await pty.resize(100, 40); + assert.deepEqual([pty.cols, pty.rows], [100, 40]); + fakeBackend.finish(); + await pty.exited; +}); diff --git a/test/experiments/ffi-pty/fixture.mts b/test/experiments/ffi-pty/fixture.mts new file mode 100644 index 000000000..6792fe418 --- /dev/null +++ b/test/experiments/ffi-pty/fixture.mts @@ -0,0 +1,95 @@ +import { createInterface } from "node:readline"; +import { closeSync, openSync } from "node:fs"; + +const mode = process.argv[2]; +if (mode === "echo" && process.stdout.isTTY) { + process.stdout.on("resize", () => { + process.stdout.write(`RESIZED:${JSON.stringify(process.stdout.getWindowSize())}\n`); + }); +} +const info = { + argv: process.argv.slice(3), + cwd: process.cwd(), + marker: process.env.TEST_MARKER ?? "", + tty: [process.stdin.isTTY, process.stdout.isTTY, process.stderr.isTTY], + size: process.stdout.isTTY ? process.stdout.getWindowSize() : null, + controllingTty: + process.platform === "win32" + ? null + : (() => { + const fd = openSync("/dev/tty", "r"); + closeSync(fd); + return true; + })(), +}; +if (mode !== "large") process.stdout.write(`INFO:${JSON.stringify(info)}\n`); + +if (mode === "exit") { + process.stdout.write("BEFORE_EXIT\n"); + process.exit(Number(process.argv[3] ?? 0)); +} else if (mode === "large") { + const total = Number(process.argv[3]); + const chunkSize = 32; + const count = Math.ceil(total / chunkSize); + const output = Array.from({ length: count }, (_, index) => { + const size = Math.min(chunkSize, total - index * chunkSize); + return `CHUNK:${String(index).padStart(4, "0")}:${"x".repeat(size)}\n`; + }).join(""); + process.stdout.write(`${output}ENDLARGE\n`); +} else if (mode === "large-input") { + const expected = Number(process.argv[3]); + let received = 0; + let nextHeartbeat = 64 * 1024; + const reportProgress = () => { + while (received >= nextHeartbeat) { + process.stdout.write(`HEARTBEAT:${received}\n`); + nextHeartbeat += 64 * 1024; + } + if (received >= expected) { + process.stdout.write(`INPUT:${received}\n`); + process.exit(0); + } + }; + if (typeof process.stdin.setRawMode !== "function") { + throw new Error("large-input test requires raw TTY input"); + } + process.stdin.setRawMode(true); + process.stdin.on("data", (chunk: Buffer) => { + received += chunk.length; + reportProgress(); + }); + process.stdout.write("INPUT_READY\n"); +} else if (mode === "echo") { + const input = createInterface({ input: process.stdin }); + input.once("line", (line) => { + process.stdout.write( + `ECHO:${JSON.stringify(line)} SIZE:${JSON.stringify(process.stdout.getWindowSize())}\n`, + ); + input.close(); + }); +} else if (mode === "twoline") { + const input = createInterface({ input: process.stdin }); + let count = 0; + input.on("line", (line) => { + process.stdout.write(`LINE:${++count}:${line}\n`); + if (count === 2) input.close(); + }); +} else if (mode === "ctrlc") { + process.on("SIGINT", () => { + process.stdout.write("INTERRUPTED\n"); + process.exit(23); + }); + process.stdin.resume(); + process.stdout.write("CTRL_C_READY\n"); +} else if (mode === "stall-input") { + process.stdin.setRawMode?.(true); + process.stdin.pause(); + process.stdout.write("STALL_READY\n"); + setInterval(() => {}, 1000); +} else if (mode === "winch") { + process.on("SIGWINCH", () => { + process.stdout.write(`WINCH:${JSON.stringify(process.stdout.getWindowSize())}\n`); + }); + process.stdin.resume(); + process.stdout.write("WINCH_READY\n"); +} diff --git a/test/experiments/ffi-pty/linux.test.mts b/test/experiments/ffi-pty/linux.test.mts new file mode 100644 index 000000000..8d4755843 --- /dev/null +++ b/test/experiments/ffi-pty/linux.test.mts @@ -0,0 +1,51 @@ +import assert from "node:assert/strict"; +import { createRequire } from "node:module"; +import { resolve } from "node:path"; +import { test } from "node:test"; + +const supportedRuntime = + process.platform === "linux" && + (() => { + const version = process.report?.getReport().header.glibcVersionRuntime; + const match = version?.match(/^(\d+)\.(\d+)/); + return !!match && (Number(match[1]) > 2 || (Number(match[1]) === 2 && Number(match[2]) >= 34)); + })(); +const load = createRequire(import.meta.url); +const linux = + process.platform === "linux" + ? (load(resolve(import.meta.dirname, "../../../experiments/ffi-pty/linux.mts")) as { + assertSupportedGlibc(version?: string): void; + getLibcFunctions(): Record; + isLinuxNativeLoaded(): boolean; + }) + : undefined; + +test( + "Linux glibc version guard accepts 2.34+ and rejects older or unknown libc", + { + skip: process.platform !== "linux", + }, + () => { + assert.doesNotThrow(() => linux!.assertSupportedGlibc("2.34")); + assert.doesNotThrow(() => linux!.assertSupportedGlibc("2.40")); + assert.doesNotThrow(() => linux!.assertSupportedGlibc("3.0")); + assert.throws(() => linux!.assertSupportedGlibc("2.33"), /glibc 2.34 or newer/); + assert.throws(() => linux!.assertSupportedGlibc("musl"), /glibc 2.34 or newer/); + assert.throws(() => linux!.assertSupportedGlibc(""), /glibc 2.34 or newer/); + }, +); + +test( + "Linux libc symbols load only when requested", + { + skip: !supportedRuntime, + }, + () => { + assert.equal(linux!.isLinuxNativeLoaded(), false); + const symbols = linux!.getLibcFunctions(); + assert.equal(typeof symbols.openpty, "function"); + assert.equal(typeof symbols.posix_spawn, "function"); + assert.equal(typeof symbols.waitpid, "function"); + assert.equal(linux!.isLinuxNativeLoaded(), true); + }, +); diff --git a/test/experiments/ffi-pty/pty.test.mts b/test/experiments/ffi-pty/pty.test.mts new file mode 100644 index 000000000..59045cba0 --- /dev/null +++ b/test/experiments/ffi-pty/pty.test.mts @@ -0,0 +1,351 @@ +import assert from "node:assert/strict"; +import { readdirSync } from "node:fs"; +import { setTimeout as delay } from "node:timers/promises"; +import { test } from "node:test"; +import { dirname, resolve } from "node:path"; +import { spawnPty } from "../../../experiments/ffi-pty/pty.mts"; + +const fixture = resolve(import.meta.dirname, "fixture.mts"); +const node = process.execPath; +const enter = process.platform === "win32" ? "\r" : "\n"; +const env = { + PATH: process.env.PATH ?? "/bin:/usr/bin", + TEST_MARKER: "ffi-pty-test", + ...(process.platform === "win32" + ? { SystemRoot: process.env.SystemRoot ?? "", WINDIR: process.env.WINDIR ?? "" } + : {}), +}; +const timeout = { timeout: 10_000 }; +const stripTerminalControls = (value: string) => + value.replace(/\u001B(?:\][^\u0007]*(?:\u0007|\u001B\\)|\[[0-?]*[ -/]*[@-~])/g, ""); + +function capture(pty: Awaited>) { + let text = ""; + pty.onData((chunk) => { + text += chunk; + }); + return { + get text() { + return text; + }, + async until(re: RegExp, ms = 5000) { + const end = Date.now() + ms; + while (Date.now() < end) { + if (re.test(text)) return text; + await delay(5); + } + throw new Error(`Timed out waiting for ${re}: ${JSON.stringify(text.slice(-300))}`); + }, + }; +} + +async function dispose(pty: Awaited>) { + await pty.close(); +} + +test( + "child has PTY stdio and receives args, environment, cwd and initial size", + timeout, + async () => { + const cwd = process.cwd(); + const pty = await spawnPty(node, [fixture, "echo", "arg one", "🐸"], { + cwd, + env, + cols: 93, + rows: 31, + }); + const out = capture(pty); + try { + const info = await out.until(/INFO:/); + const payload = JSON.parse(info.match(/INFO:(\{[^\r\n]+\})/)![1]); + assert.deepEqual(payload.argv, ["arg one", "🐸"]); + assert.equal(payload.cwd, cwd); + assert.equal(payload.marker, "ffi-pty-test"); + assert.deepEqual(payload.tty, [true, true, true]); + assert.deepEqual(payload.size, [93, 31]); + if (process.platform !== "win32") assert.equal(payload.controllingTty, true); + await pty.write(`café 🐸${enter}`); + assert.match(await out.until(/ECHO:/), /ECHO:"café 🐸"/); + assert.deepEqual(await pty.exited, { exitCode: 0, signal: 0 }); + } finally { + await dispose(pty); + } + }, +); + +test("output is delivered before exit and normal exit status is preserved", timeout, async () => { + const pty = await spawnPty(node, [fixture, "exit", "13"], { env }); + const out = capture(pty); + try { + assert.match(await out.until(/BEFORE_EXIT/), /BEFORE_EXIT/); + assert.deepEqual(await pty.exited, { exitCode: 13, signal: 0 }); + assert.match(out.text, /BEFORE_EXIT/); + } finally { + await dispose(pty); + } +}); + +test("large child output is drained without truncation", timeout, async () => { + const pty = await spawnPty(node, [fixture, "large", "262144"], { env }); + const out = capture(pty); + try { + await out.until(/ENDLARGE/); + const text = stripTerminalControls(out.text).replace(/\r\n/g, "\n").replace(/\r/g, "\n"); + const chunks = [...text.matchAll(/^CHUNK:(\d{4}):(x+)$/gm)]; + assert.equal(chunks.length, 8192); + assert.equal( + chunks.reduce((length, chunk) => length + chunk[2].length, 0), + 262144, + ); + chunks.forEach((chunk, index) => { + assert.equal(Number(chunk[1]), index); + assert.equal(chunk[2].length, 32); + }); + assert.match(text, /ENDLARGE/); + assert.equal((await pty.exited).exitCode, 0); + } finally { + await dispose(pty); + } +}); + +test( + "large parent input is written completely", + { timeout: process.platform === "win32" ? 30_000 : timeout.timeout }, + async () => { + const size = 256 * 1024; + const pty = await spawnPty(node, [fixture, "large-input", String(size)], { env }); + const out = capture(pty); + try { + await out.until(/INFO:/); + await out.until(/INPUT_READY/); + await pty.write(Buffer.alloc(size, 120)); + assert.match( + await out.until(/HEARTBEAT:/, process.platform === "win32" ? 10_000 : 5000), + /HEARTBEAT:/, + ); + const inputPattern = new RegExp(`INPUT:${size}`); + assert.match( + await out.until(inputPattern, process.platform === "win32" ? 25_000 : 5000), + inputPattern, + ); + assert.equal((await pty.exited).exitCode, 0); + } finally { + await dispose(pty); + } + }, +); + +test("pause and resume control data delivery", timeout, async () => { + const pty = await spawnPty(node, [fixture, "exit", "0"], { env }); + const out = capture(pty); + try { + pty.pause(); + await delay(100); + assert.equal(out.text, ""); + pty.resume(); + assert.match(await out.until(/BEFORE_EXIT/), /BEFORE_EXIT/); + assert.equal((await pty.exited).exitCode, 0); + } finally { + await dispose(pty); + } +}); + +test("concurrent sessions keep input and output isolated", timeout, async () => { + const a = await spawnPty(node, [fixture, "echo"], { env: { ...env, TEST_MARKER: "session-a" } }); + const ao = capture(a); + let b: Awaited> | undefined; + try { + const second = await spawnPty(node, [fixture, "echo"], { + env: { ...env, TEST_MARKER: "session-b" }, + }); + b = second; + const bo = capture(second); + await Promise.all([ao.until(/INFO:/), bo.until(/INFO:/)]); + await Promise.all([a.write(`alpha${enter}`), b.write(`beta${enter}`)]); + assert.match(await ao.until(/ECHO:/), /ECHO:"alpha"/); + assert.match(await bo.until(/ECHO:/), /ECHO:"beta"/); + assert.doesNotMatch(ao.text, /ECHO:"beta"/); + assert.doesNotMatch(bo.text, /ECHO:"alpha"/); + await Promise.all([a.exited, b.exited]); + } finally { + await Promise.all([dispose(a), ...(b ? [dispose(b)] : [])]); + } +}); + +test( + "resize updates the terminal dimensions", + { ...timeout, skip: process.platform === "win32" }, + async () => { + const pty = await spawnPty(node, [fixture, "echo"], { env }); + const out = capture(pty); + try { + await out.until(/INFO:/); + await pty.resize(117, 43); + assert.equal(pty.cols, 117); + assert.equal(pty.rows, 43); + assert.match(await out.until(/RESIZED:/), /RESIZED:\[117,43\]/); + await pty.write(`resize-check${enter}`); + assert.match(await out.until(/ECHO:"resize-check"/), /SIZE:\[117,43\]/); + } finally { + await dispose(pty); + } + }, +); + +test("bare command lookup uses the child's PATH and cwd", timeout, async () => { + const pty = await spawnPty("node", [fixture, "exit", "0"], { + env: { ...env, PATH: dirname(process.execPath) }, + }); + const out = capture(pty); + try { + assert.match(await out.until(/BEFORE_EXIT/), /BEFORE_EXIT/); + assert.equal((await pty.exited).exitCode, 0); + } finally { + await dispose(pty); + } +}); + +test("explicit termination reports its signal", timeout, async () => { + const pty = await spawnPty(node, [fixture, "echo"], { env }); + const out = capture(pty); + try { + await out.until(/INFO:/); + await pty.kill("SIGTERM"); + assert.deepEqual(await pty.exited, { exitCode: null, signal: 15 }); + } finally { + await dispose(pty); + } +}); + +test("repeated PTY sessions can exit or be killed", timeout, async () => { + const fdDirectory = process.platform === "linux" ? "/proc/self/fd" : "/dev/fd"; + const count = process.platform === "win32" ? undefined : () => readdirSync(fdDirectory).length; + const before = count?.(); + for (let i = 0; i < 3; i++) { + const exited = await spawnPty(node, [fixture, "exit", "0"], { env }); + try { + assert.equal((await exited.exited).exitCode, 0); + } finally { + await dispose(exited); + } + + const pty = await spawnPty(node, [fixture, "stall-input"], { env }); + const out = capture(pty); + try { + await out.until(/STALL_READY/); + await pty.kill("SIGTERM"); + assert.deepEqual(await pty.exited, { exitCode: null, signal: 15 }); + } finally { + await dispose(pty); + } + } + if (count) assert.equal(count(), before); +}); + +test("an existing executable with a missing child cwd fails cleanly", timeout, async () => { + const fdDirectory = process.platform === "linux" ? "/proc/self/fd" : "/dev/fd"; + const count = process.platform === "win32" ? undefined : () => readdirSync(fdDirectory).length; + const before = count?.(); + await assert.rejects( + spawnPty(node, [fixture, "exit", "0"], { + cwd: resolve(process.cwd(), "missing-ffi-pty-cwd"), + env, + }), + ); + assert.equal(count?.(), before); +}); + +test( + "resize delivers SIGWINCH to the terminal foreground child", + { + ...timeout, + skip: process.platform === "win32", + }, + async () => { + const pty = await spawnPty(node, [fixture, "winch"], { env }); + const out = capture(pty); + try { + await out.until(/WINCH_READY/); + await pty.resize(119, 45); + assert.match(await out.until(/WINCH:/), /WINCH:\[119,45\]/); + } finally { + await dispose(pty); + } + }, +); + +test("write queue rejects payloads larger than 8 MiB", timeout, async () => { + const pty = await spawnPty(node, [fixture, "stall-input"], { env }); + const out = capture(pty); + try { + await out.until(/STALL_READY/); + await assert.rejects(pty.write(Buffer.alloc(8 * 1024 * 1024 + 1)), /8 MiB|queue limit/i); + } finally { + await dispose(pty); + } +}); + +test("close unblocks an in-flight large write", timeout, async () => { + const pty = await spawnPty(node, [fixture, "stall-input"], { env }); + const out = capture(pty); + try { + await out.until(/STALL_READY/); + const writeResult = pty.write(Buffer.alloc(7 * 1024 * 1024, 120)).then( + () => ({ fulfilled: true }), + (error: Error) => ({ fulfilled: false, error }), + ); + await delay(50); + await pty.close(); + assert.equal((await writeResult).fulfilled, false); + assert.ok((await pty.exited).signal > 0); + } finally { + await dispose(pty); + } +}); + +test( + "Ctrl-C is delivered through the terminal foreground process group", + { ...timeout, skip: process.platform === "win32" }, + async () => { + const pty = await spawnPty(node, [fixture, "ctrlc"], { env }); + const out = capture(pty); + try { + await out.until(/CTRL_C_READY/); + await pty.write("\x03"); + assert.match(await out.until(/INTERRUPTED/), /INTERRUPTED/); + assert.deepEqual(await pty.exited, { exitCode: 23, signal: 0 }); + } finally { + await dispose(pty); + } + }, +); + +test("close terminates a live child and settles exit", timeout, async () => { + const pty = await spawnPty(node, [fixture, "echo"], { env }); + try { + await delay(50); + await pty.close(); + const status = await pty.exited; + assert.ok(status.signal > 0 || status.exitCode !== null); + } finally { + await dispose(pty); + } +}); + +test( + "failed spawn and invalid input leave no file descriptors behind", + { + ...timeout, + skip: process.platform === "win32", + }, + async () => { + const fdDirectory = process.platform === "linux" ? "/proc/self/fd" : "/dev/fd"; + const count = () => readdirSync(fdDirectory).length; + const before = count(); + for (let i = 0; i < 5; i++) { + await assert.rejects(spawnPty("/no-such-ffi-pty-command", [], { env })); + await assert.rejects(spawnPty(node, ["bad\0arg"], { env })); + } + assert.equal(count(), before); + }, +); diff --git a/test/experiments/ffi-pty/structure.test.mts b/test/experiments/ffi-pty/structure.test.mts new file mode 100644 index 000000000..c06dc5dc7 --- /dev/null +++ b/test/experiments/ffi-pty/structure.test.mts @@ -0,0 +1,48 @@ +import assert from "node:assert/strict"; +import { readdirSync, readFileSync } from "node:fs"; +import { stripTypeScriptTypes } from "node:module"; +import { join } from "node:path"; +import { test } from "node:test"; +import { fileURLToPath } from "node:url"; + +test("FFI PTY source modules stay at or below 500 lines", () => { + const root = fileURLToPath(new URL("../../../experiments/ffi-pty/", import.meta.url)); + const extensions = new Set([".mts", ".cc", ".cpp", ".h", ".hpp"]); + const sources: string[] = []; + const visit = (directory: string) => { + for (const entry of readdirSync(directory, { withFileTypes: true })) { + const path = join(directory, entry.name); + if (entry.isDirectory()) visit(path); + else if (extensions.has(entry.name.slice(entry.name.lastIndexOf(".")))) sources.push(path); + } + }; + visit(root); + const oversized = sources + .map((path) => { + const source = readFileSync(path, "utf8"); + const lines = source.split(/\r?\n/).length - (source.endsWith("\n") ? 1 : 0); + return { path: path.slice(root.length), lines }; + }) + .filter(({ lines }) => lines > 500); + assert.deepEqual(oversized, [], "split large modules into focused files"); +}); + +test("FFI PTY MTS modules use Node's supported type-erasure syntax", () => { + const root = fileURLToPath(new URL("../../../experiments/ffi-pty/", import.meta.url)); + const sources: string[] = []; + const visit = (directory: string) => { + for (const entry of readdirSync(directory, { withFileTypes: true })) { + const path = join(directory, entry.name); + if (entry.isDirectory()) visit(path); + else if (entry.name.endsWith(".mts")) sources.push(path); + } + }; + visit(root); + for (const path of sources) { + assert.doesNotThrow( + () => stripTypeScriptTypes(readFileSync(path, "utf8"), { mode: "strip" }), + undefined, + path.slice(root.length), + ); + } +}); diff --git a/test/experiments/ffi-pty/unix-common.test.mts b/test/experiments/ffi-pty/unix-common.test.mts new file mode 100644 index 000000000..6ba094738 --- /dev/null +++ b/test/experiments/ffi-pty/unix-common.test.mts @@ -0,0 +1,143 @@ +import assert from "node:assert/strict"; +import { createRequire } from "node:module"; +import { setTimeout as delay } from "node:timers/promises"; +import { PassThrough } from "node:stream"; +import { test } from "node:test"; +import { spawnPty } from "../../../experiments/ffi-pty/pty.mts"; +import { normalizeSpawnOptions } from "../../../experiments/ffi-pty/validation.mts"; +import { waitForOutputDrain } from "../../../experiments/ffi-pty/unix-common.mts"; + +const require = createRequire(import.meta.url); + +test( + "closing a PTY cancels a large write when the child is not reading", + { timeout: 10_000, skip: process.platform === "win32" }, + async () => { + const code = + "setInterval(() => {}, 1000); process.stdin.setRawMode(true); process.stdin.pause(); console.log('STALL_READY');"; + const pty = await spawnPty(process.execPath, ["-e", code]); + let ready!: () => void; + const readySeen = new Promise((resolve) => (ready = resolve)); + const data = pty.onData((chunk) => { + if (chunk.includes("STALL_READY")) ready(); + }); + let writeDone = false; + let writeError: unknown; + try { + await readySeen; + const write = pty.write(Buffer.alloc(7 * 1024 * 1024, 120)).then( + () => { + writeDone = true; + }, + (error: unknown) => { + writeDone = true; + writeError = error; + }, + ); + await delay(50); + assert.equal(writeDone, false, "the child's input queue should be full"); + let timerRan = false; + setTimeout(() => (timerRan = true), 0); + await pty.close(); + const status = await pty.exited; + await write; + assert.equal(timerRan, true, "the event loop stays responsive while writing"); + assert.ok(writeError instanceof Error, "close rejects the pending write"); + assert.notEqual(status.signal, 0, "close terminates the stalled child"); + } finally { + data.dispose(); + await pty.close(); + } + }, +); + +test("paused output does not consume the post-exit drain timeout", async () => { + const readable = new PassThrough(); + let received = ""; + let settled = false; + readable.on("data", (chunk: Buffer) => (received += chunk.toString())); + readable.pause(); + const drained = waitForOutputDrain(readable, 25).then((result) => { + settled = true; + return result; + }); + await delay(60); + assert.equal(settled, false, "the paused interval does not expire the budget"); + readable.resume(); + readable.end(Buffer.from("pending")); + assert.equal(await drained, true); + assert.equal(received, "pending"); + for (const event of ["resume", "pause", "end", "close"]) { + assert.equal(readable.listenerCount(event), 0, `${event} listener is removed`); + } +}); + +test("resuming restarts the remaining drain budget", async () => { + const readable = new PassThrough(); + readable.on("data", () => {}); + let settled = false; + const startedAt = Date.now(); + const drained = waitForOutputDrain(readable, 80).then((result) => { + settled = true; + return result; + }); + await delay(25); + readable.pause(); + await delay(100); + assert.equal(settled, false, "the paused interval does not expire the budget"); + const resumedAt = Date.now(); + readable.resume(); + assert.equal(await drained, false, "a flowing stream expires after its remaining budget"); + const activeDuration = Date.now() - resumedAt; + assert.ok(activeDuration >= 30, `remaining budget lasted ${activeDuration}ms`); + assert.ok(Date.now() - startedAt >= 100); + for (const event of ["resume", "pause", "end", "close"]) { + assert.equal(readable.listenerCount(event), 0, `${event} listener is removed`); + } + readable.destroy(); +}); + +test("unconsumed output still has a bounded drain deadline", async () => { + const readable = new PassThrough(); + assert.equal(await waitForOutputDrain(readable, 25), false); + readable.destroy(); +}); + +test( + "backend close resumes output while paused and remains bounded", + { timeout: 5000, skip: process.platform === "win32" }, + async () => { + const code = "process.stdout.write('READY\\n'); setInterval(() => {}, 1000);"; + const input = normalizeSpawnOptions(process.execPath, ["-e", code]); + const backendFile = process.platform === "darwin" ? "darwin.mts" : "linux.mts"; + const backendModule = require(`../../../experiments/ffi-pty/${backendFile}`) as { + createBackend(options: typeof input): Promise<{ + pid: number; + readable: PassThrough; + close(): Promise; + exited: Promise<{ exitCode: number | null; signal: number }>; + }>; + }; + const backend = await backendModule.createBackend(input); + let ready!: () => void; + const readySeen = new Promise((resolve) => (ready = resolve)); + backend.readable.on("data", (chunk: Buffer) => { + if (chunk.includes("READY")) { + backend.readable.pause(); + ready(); + } + }); + try { + await readySeen; + await Promise.race([ + backend.close(), + delay(3000).then(() => { + throw new Error("close did not finish while output was paused"); + }), + ]); + assert.notEqual((await backend.exited).signal, 0); + } finally { + await backend.close(); + } + }, +); diff --git a/test/experiments/ffi-pty/unix-native.test.mts b/test/experiments/ffi-pty/unix-native.test.mts new file mode 100644 index 000000000..9bfb73256 --- /dev/null +++ b/test/experiments/ffi-pty/unix-native.test.mts @@ -0,0 +1,41 @@ +import assert from "node:assert/strict"; +import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { delimiter, join } from "node:path"; +import { tmpdir } from "node:os"; +import { test } from "node:test"; +import { makePointerVector, resolveExecutable } from "../../../experiments/ffi-pty/unix-native.mts"; + +test("native pointer vectors keep NUL-terminated buffers and a null terminator", () => { + const vector = makePointerVector(["program", "argument"]); + assert.deepEqual( + vector.buffers.map((buffer) => buffer.toString()), + ["program\0", "argument\0"], + ); + assert.notEqual(vector.pointers.readBigUInt64LE(0), 0n); + assert.notEqual(vector.pointers.readBigUInt64LE(8), 0n); + assert.equal(vector.pointers.readBigUInt64LE(16), 0n); + assert.throws(() => makePointerVector(["bad\0value"]), /NUL/); +}); + +test("executable lookup uses child cwd and relative PATH entries without changing parent env", () => { + const root = mkdtempSync(join(tmpdir(), "ffi-pty-path-")); + const oldPath = process.env.PATH; + try { + const first = join(root, "first"); + const second = join(root, "second"); + mkdirSync(join(first, "tool"), { recursive: true }); // directories are not executable candidates + mkdirSync(second); + const executable = join(second, "tool"); + writeFileSync(executable, "#!/bin/sh\nexit 0\n"); + chmodSync(executable, 0o755); + + const childEnv = { PATH: `first${delimiter}second` }; + assert.equal(resolveExecutable("tool", root, childEnv), executable); + assert.equal(resolveExecutable("./second/tool", root, childEnv), executable); + assert.throws(() => resolveExecutable("missing-tool", root, childEnv), /not found/); + assert.deepEqual(childEnv, { PATH: `first${delimiter}second` }); + assert.equal(process.env.PATH, oldPath); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); diff --git a/test/experiments/ffi-pty/unix-poll.test.mts b/test/experiments/ffi-pty/unix-poll.test.mts new file mode 100644 index 000000000..00dfd67da --- /dev/null +++ b/test/experiments/ffi-pty/unix-poll.test.mts @@ -0,0 +1,32 @@ +import assert from "node:assert/strict"; +import { closeSync, fstatSync } from "node:fs"; +import { test } from "node:test"; +import { dlopen } from "node:ffi"; +import { initializeNonblockingPoll } from "../../../experiments/ffi-pty/unix-poll.mts"; + +test( + "libuv poll initialization leaves the descriptor open and handles invalid fds", + { + timeout: 5000, + skip: process.platform !== "darwin", + }, + () => { + const { functions: c } = dlopen(null, { + pipe: { arguments: ["pointer"], return: "int32" }, + }); + assert.throws(() => initializeNonblockingPoll(-1), /uv_poll_init/); + const pipeOut = Buffer.alloc(8); + assert.equal(c.pipe(pipeOut), 0); + const readFd = pipeOut.readInt32LE(), + writeFd = pipeOut.readInt32LE(4); + try { + initializeNonblockingPoll(writeFd); + assert.doesNotThrow(() => fstatSync(writeFd)); + assert.throws(() => initializeNonblockingPoll(-1), /uv_poll_init/); + assert.doesNotThrow(() => fstatSync(writeFd)); + } finally { + closeSync(writeFd); + closeSync(readFd); + } + }, +); diff --git a/test/experiments/ffi-pty/validation.test.mts b/test/experiments/ffi-pty/validation.test.mts new file mode 100644 index 000000000..b2b6198ae --- /dev/null +++ b/test/experiments/ffi-pty/validation.test.mts @@ -0,0 +1,34 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { isAbsolute } from "node:path"; +import { + normalizeSpawnOptions, + validateDimension, + validateNativeString, +} from "../../../experiments/ffi-pty/validation.mts"; + +test("normalizes defaults and copies the requested arguments", () => { + const args = ["-c", "echo ok"]; + const options = normalizeSpawnOptions("sh", args, { env: { PATH: "/bin" } }); + args.push("later"); + assert.deepEqual(options.args, ["-c", "echo ok"]); + assert.equal(options.cols, 80); + assert.equal(options.rows, 24); + assert.equal(options.env.TERM, "xterm-256color"); + assert.equal(isAbsolute(options.cwd), true); +}); + +test("rejects unsupported options and invalid native strings before allocation", () => { + assert.throws(() => normalizeSpawnOptions("sh", [], { uid: 10 }), /Unsupported/); + assert.throws(() => normalizeSpawnOptions("sh", ["bad\0arg"]), /NUL/); + assert.throws(() => normalizeSpawnOptions("sh", [], { cols: 32768 }), /32767/); + assert.throws(() => normalizeSpawnOptions("sh", [], { encoding: "latin1" }), /UTF-8/); + assert.throws(() => normalizeSpawnOptions("sh", [], { env: { "BAD=NAME": "x" } }), /Invalid/); +}); + +test("native string and dimension validators accept supported boundary values", () => { + assert.equal(validateNativeString("ok", "value"), undefined); + assert.equal(validateDimension(32767, "cols"), undefined); + assert.throws(() => validateNativeString("bad\0value", "value"), /NUL/); + assert.throws(() => validateDimension(0, "rows"), /1 to 32767/); +}); diff --git a/test/experiments/ffi-pty/windows-broker-client.test.mts b/test/experiments/ffi-pty/windows-broker-client.test.mts new file mode 100644 index 000000000..daa814594 --- /dev/null +++ b/test/experiments/ffi-pty/windows-broker-client.test.mts @@ -0,0 +1,43 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + brokerStartupEnv, + createNodeTransport, +} from "../../../experiments/ffi-pty/windows-broker-client.mts"; + +test("broker startup environment excludes target and Node injection variables", () => { + assert.deepEqual( + brokerStartupEnv({ + SystemRoot: "C:\\Windows", + WINDIR: "C:\\Windows", + TEMP: "C:\\Temp", + TMP: "C:\\Temp", + PATH: "target-path", + NODE_OPTIONS: "--require injected.js", + NODE_PATH: "target-modules", + }), + { + SystemRoot: "C:\\Windows", + WINDIR: "C:\\Windows", + TEMP: "C:\\Temp", + TMP: "C:\\Temp", + }, + ); +}); + +test("Node fallback transport starts and terminates its subprocess", async () => { + const transport = createNodeTransport(); + let timer: NodeJS.Timeout; + try { + await Promise.race([ + transport.ready, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error("broker subprocess did not become ready")), 5000); + }), + ]); + } finally { + clearTimeout(timer!); + await transport.terminate(); + } + await transport.closed; +}); diff --git a/test/experiments/ffi-pty/windows-broker-ipc.test.mts b/test/experiments/ffi-pty/windows-broker-ipc.test.mts new file mode 100644 index 000000000..f5ab4b42c --- /dev/null +++ b/test/experiments/ffi-pty/windows-broker-ipc.test.mts @@ -0,0 +1,20 @@ +import assert from "node:assert/strict"; +import type { ChildProcess } from "node:child_process"; +import { test } from "node:test"; +import { sendNodeBrokerMessage } from "../../../experiments/ffi-pty/windows-broker-ipc.mts"; + +test("broker IPC rejects sends after disconnect", async () => { + const child = { connected: false } as ChildProcess; + await assert.rejects(sendNodeBrokerMessage(child, { type: "connected" }), /IPC is disconnected/); +}); + +test("broker IPC propagates child send callback errors", async () => { + const child = { + connected: true, + send(_message: unknown, callback: (error: Error | null) => void) { + callback(new Error("IPC channel closed")); + return false; + }, + } as unknown as ChildProcess; + await assert.rejects(sendNodeBrokerMessage(child, { type: "connected" }), /IPC channel closed/); +}); diff --git a/test/experiments/ffi-pty/windows-broker-lifecycle.test.mts b/test/experiments/ffi-pty/windows-broker-lifecycle.test.mts new file mode 100644 index 000000000..4055bacd9 --- /dev/null +++ b/test/experiments/ffi-pty/windows-broker-lifecycle.test.mts @@ -0,0 +1,155 @@ +import assert from "node:assert/strict"; +import { createConnection, type Socket } from "node:net"; +import { test } from "node:test"; +import { createNodeTransport } from "../../../experiments/ffi-pty/windows-broker-client.mts"; +import type { BrokerReply } from "../../../experiments/ffi-pty/windows-protocol.mts"; + +const supported = process.platform === "win32" && ["x64", "arm64"].includes(process.arch); +const environment = Object.fromEntries( + Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined), +); + +function waitReply( + replies: BrokerReply[], + listeners: Set<(reply: BrokerReply) => void>, + predicate: (reply: BrokerReply) => boolean, + label: string, +): Promise { + const existing = replies.find(predicate); + if (existing) return Promise.resolve(existing); + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + listeners.delete(listener); + reject(new Error(`Timed out waiting for ${label}`)); + }, 15000); + const listener = (reply: BrokerReply) => { + if (!predicate(reply)) return; + clearTimeout(timer); + listeners.delete(listener); + resolve(reply); + }; + listeners.add(listener); + }); +} + +function connectPipe(name: string, sockets: Socket[]): Promise { + return new Promise((resolve, reject) => { + const socket = createConnection(name); + sockets.push(socket); + socket.on("data", () => {}); + socket.on("error", () => {}); + const onConnect = () => { + socket.off("error", onError); + socket.off("close", onClose); + resolve(socket); + }; + const onError = (error: Error) => { + socket.off("connect", onConnect); + socket.off("close", onClose); + reject(error); + }; + const onClose = () => { + socket.off("connect", onConnect); + socket.off("error", onError); + reject(new Error("broker pipe closed before connect")); + }; + socket.once("connect", onConnect); + socket.once("error", onError); + socket.once("close", onClose); + }); +} + +async function destroySockets(sockets: Socket[]) { + await Promise.all( + sockets.map( + (socket) => + new Promise((resolve) => { + if (socket.closed) return resolve(); + socket.once("close", resolve); + socket.destroy(); + }), + ), + ); +} + +test( + "Node fallback sends prepared Windows launch data and handles resize and close", + { skip: !supported, timeout: 30000 }, + async () => { + const transport = createNodeTransport(); + const replies: BrokerReply[] = []; + const listeners = new Set<(reply: BrokerReply) => void>(); + const sockets: Socket[] = []; + const errors: Error[] = []; + const removeMessage = transport.onMessage((reply) => { + replies.push(reply); + for (const listener of listeners) listener(reply); + }); + const removeError = transport.onError((error) => errors.push(error)); + let closed = false; + try { + await transport.ready; + const options = { + file: process.execPath, + args: ["-e", "setInterval(() => {}, 1000)"], + cwd: process.cwd(), + env: environment, + cols: 80, + rows: 24, + }; + await transport.send({ type: "start", options }); + const pipes = await waitReply( + replies, + listeners, + (reply) => reply.type === "pipes", + "pipe setup", + ); + assert.equal(pipes.type, "pipes"); + await Promise.all([connectPipe(pipes.input, sockets), connectPipe(pipes.output, sockets)]); + await transport.send({ type: "connected" }); + const spawned = await waitReply( + replies, + listeners, + (reply) => reply.type === "spawned", + "target startup", + ); + assert.equal(spawned.type, "spawned"); + assert.ok(Number.isSafeInteger(spawned.pid) && spawned.pid > 0); + + await transport.send({ type: "command", id: 1, command: "resize", cols: 91, rows: 32 }); + const resized = await waitReply( + replies, + listeners, + (reply) => reply.type === "ack" && reply.id === 1, + "resize ACK", + ); + assert.deepEqual(resized, { type: "ack", id: 1 }); + + await transport.send({ type: "command", id: 2, command: "close" }); + const closedAck = await waitReply( + replies, + listeners, + (reply) => reply.type === "ack" && reply.id === 2, + "close ACK", + ); + assert.deepEqual(closedAck, { type: "ack", id: 2 }); + const exited = await waitReply( + replies, + listeners, + (reply) => reply.type === "exited", + "target exit", + ); + assert.equal(exited.type, "exited"); + assert.equal(exited.signal, 1); + await waitReply(replies, listeners, (reply) => reply.type === "brokerDone", "broker cleanup"); + await transport.closed; + closed = true; + assert.deepEqual(errors, []); + } finally { + removeMessage(); + removeError(); + await destroySockets(sockets); + if (!closed) await transport.terminate(); + } + }, +); diff --git a/test/experiments/ffi-pty/windows-broker.test.mts b/test/experiments/ffi-pty/windows-broker.test.mts new file mode 100644 index 000000000..d4c99f750 --- /dev/null +++ b/test/experiments/ffi-pty/windows-broker.test.mts @@ -0,0 +1,54 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { Worker } from "node:worker_threads"; +import { + asError, + forwardBrokerRequest, + isBrokerEntry, + runBroker, + terminateWorkerBounded, +} from "../../../experiments/ffi-pty/windows-broker.mts"; + +test("broker implementation can be imported without starting a lifecycle", () => { + assert.equal(typeof runBroker, "function"); + assert.equal(isBrokerEntry(), false); + assert.equal(asError("failure").message, "failure"); + const forwarded: string[] = []; + const transport = { + send: async (request: { type: string }) => { + forwarded.push(request.type); + }, + } as any; + return forwardBrokerRequest(transport, { type: "connected" }).then(() => { + assert.deepEqual(forwarded, ["connected"]); + }); +}); + +test("broker termination waits only for its bounded worker grace", async () => { + const transport = { terminate: () => new Promise(() => {}) } as any; + const started = Date.now(); + await terminateWorkerBounded(transport, 20); + assert.ok(Date.now() - started < 1000); +}); + +test("broker module import in an idle worker exits without a lifecycle", async () => { + const worker = new Worker( + new URL("../../../experiments/ffi-pty/windows-broker.mts", import.meta.url), + { workerData: null }, + ); + await new Promise((resolve, reject) => { + const timer = setTimeout(() => { + void worker.terminate(); + reject(new Error("idle worker did not exit after broker import")); + }, 3000); + worker.once("error", (error) => { + clearTimeout(timer); + reject(error); + }); + worker.once("exit", (code) => { + clearTimeout(timer); + if (code === 0) resolve(); + else reject(new Error(`idle Windows worker exited with code ${code}`)); + }); + }); +}); diff --git a/test/experiments/ffi-pty/windows-commandline.test.mts b/test/experiments/ffi-pty/windows-commandline.test.mts new file mode 100644 index 000000000..8f881eb30 --- /dev/null +++ b/test/experiments/ffi-pty/windows-commandline.test.mts @@ -0,0 +1,75 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + buildWindowsCommandLine, + buildWindowsEnvironmentBlock, + quoteWindowsArgument, + resolveWindowsExecutable, + windowsPipeNames, +} from "../../../experiments/ffi-pty/windows-commandline.mts"; + +test("Windows argument quoting preserves whitespace, quotes, and trailing backslashes", () => { + assert.equal(quoteWindowsArgument("plain"), "plain"); + assert.equal(quoteWindowsArgument("two words"), '"two words"'); + assert.equal(quoteWindowsArgument('a\\"b'), '"a\\\\\\"b"'); + assert.equal(quoteWindowsArgument("path with space\\"), '"path with space\\\\"'); + assert.equal( + buildWindowsCommandLine("C:\\Program Files\\shell.exe", ["-c", "echo 🐸"]), + '"C:\\Program Files\\shell.exe" -c "echo 🐸"', + ); +}); +test("Windows command lines reject NULs and empty executable paths", () => { + assert.throws(() => quoteWindowsArgument("bad\0arg"), /NUL/); + assert.throws(() => buildWindowsCommandLine("shell.exe", ["bad\0arg"]), /NUL/); + assert.throws(() => buildWindowsCommandLine("", []), /empty/); +}); + +test("named pipe paths use the exact local Win32 pipe namespace", () => { + const names = windowsPipeNames("fixed-id"); + assert.equal(names.input, "\\\\.\\pipe\\node-pty-ffi-fixed-id-in"); + assert.equal(names.output, "\\\\.\\pipe\\node-pty-ffi-fixed-id-out"); + assert.throws(() => windowsPipeNames("bad/name"), /identifier/); +}); + +test("executable lookup uses case-insensitive child PATH and PATHEXT", () => { + const resolved = resolveWindowsExecutable( + "node", + { pAtH: "C:\\runtime", pathext: ".EXE;.CMD" }, + "C:\\work", + (candidate) => candidate === "C:\\runtime\\node.EXE", + ); + assert.equal(resolved, "C:\\runtime\\node.EXE"); + assert.equal( + resolveWindowsExecutable( + "node", + { PATH: "bin", PATHEXT: ".EXE" }, + "C:\\child", + (candidate) => candidate === "C:\\child\\bin\\node.EXE", + ), + "C:\\child\\bin\\node.EXE", + ); + assert.throws( + () => resolveWindowsExecutable("missing", { PATH: "C:\\empty" }, "C:\\work", () => false), + /child PATH/, + ); + assert.throws( + () => resolveWindowsExecutable("npm.cmd", {}, "C:\\work", () => true), + /batch scripts/, + ); +}); + +test("environment block is UTF-16LE, case-insensitively sorted, and double NUL terminated", () => { + const block = buildWindowsEnvironmentBlock({ + ZED: "last", + Path: "C:\\bin", + A: "🐸", + "=C:": "C:\\work", + }); + assert.equal(block.toString("utf16le"), "=C:=C:\\work\0A=🐸\0Path=C:\\bin\0ZED=last\0\0"); +}); + +test("environment entries reject names or values that cannot appear in a block", () => { + assert.throws(() => buildWindowsEnvironmentBlock({ "bad=name": "x" }), /Invalid/); + assert.throws(() => buildWindowsEnvironmentBlock({ A: "bad\0value" }), /Invalid/); + assert.throws(() => buildWindowsEnvironmentBlock({ Path: "a", PATH: "b" }), /Duplicate/); +}); diff --git a/test/experiments/ffi-pty/windows-controller.test.mts b/test/experiments/ffi-pty/windows-controller.test.mts new file mode 100644 index 000000000..77ca0a515 --- /dev/null +++ b/test/experiments/ffi-pty/windows-controller.test.mts @@ -0,0 +1,54 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + asError, + createWindowsTransport, + promiseWithTimeout, +} from "../../../experiments/ffi-pty/windows.mts"; + +test("asError preserves Error instances and wraps other failures", () => { + const original = new Error("native failure"); + assert.equal(asError(original), original); + assert.equal(asError("native failure").message, "native failure"); +}); + +test("Windows transport selector rejects versions below the ConPTY minimum", async () => { + await assert.rejects( + createWindowsTransport({ major: 10, minor: 0, build: 17762 }), + /does not support ConPTY/, + ); +}); + +test("promiseWithTimeout preserves rejection and clears its timer", async () => { + const originalSetTimeout = globalThis.setTimeout; + const originalClearTimeout = globalThis.clearTimeout; + const scheduled = new Set>(); + const cleared = new Set>(); + const globals = globalThis as unknown as { + setTimeout: typeof setTimeout; + clearTimeout: typeof clearTimeout; + }; + globals.setTimeout = ((...args: Parameters) => { + const timer = originalSetTimeout(...args); + scheduled.add(timer); + return timer; + }) as typeof setTimeout; + globals.clearTimeout = ((timer: ReturnType) => { + if (scheduled.has(timer)) cleared.add(timer); + originalClearTimeout(timer); + }) as typeof clearTimeout; + + try { + const original = new Error("startup failed"); + await assert.rejects( + promiseWithTimeout(Promise.reject(original), 1000, "timeout"), + (error) => error === original, + ); + assert.equal(cleared.size, 1); + assert.equal(await promiseWithTimeout(Promise.resolve(42), 1000, "timeout"), 42); + assert.equal(cleared.size, 2); + } finally { + globals.setTimeout = originalSetTimeout; + globals.clearTimeout = originalClearTimeout; + } +}); diff --git a/test/experiments/ffi-pty/windows-ffi-resize-probe.mts b/test/experiments/ffi-pty/windows-ffi-resize-probe.mts new file mode 100644 index 000000000..7ca25a632 --- /dev/null +++ b/test/experiments/ffi-pty/windows-ffi-resize-probe.mts @@ -0,0 +1,204 @@ +import { rmSync } from "node:fs"; +import { setTimeout as delay } from "node:timers/promises"; +import { createFfiTransport } from "../../../experiments/ffi-pty/windows-ffi.mts"; +import { + getWindowsBindings, + INVALID_HANDLE_VALUE, + utf16, +} from "../../../experiments/ffi-pty/windows-native.mts"; +import type { SpawnOptions } from "../../../experiments/ffi-pty/contract.mts"; +import type { BrokerReply } from "../../../experiments/ffi-pty/windows-protocol.mts"; + +const report = process.argv[2]; +if (!report) throw new Error("Probe needs a backpressure report path"); +const options: SpawnOptions = { + file: process.execPath, + args: [ + "-e", + "const chunk=Buffer.alloc(16384,120); setInterval(()=>process.stdout.write(chunk),0);", + ], + cwd: process.cwd(), + env: Object.fromEntries( + Object.entries(process.env).filter( + (entry): entry is [string, string] => entry[1] !== undefined, + ), + ), + cols: 80, + rows: 24, +}; + +const transport = createFfiTransport(); +const native = getWindowsBindings(); +let inputPipe = 0n; +let outputPipe = 0n; +let heartbeatTimer: NodeJS.Timeout | undefined; +let cancelTimer: NodeJS.Timeout | undefined; +let ackMonitor: NodeJS.Timeout | undefined; +let resizeAcks = 0; +let resizeCount = 0; +let cancellationStarted = false; +let lastAckAt = Date.now(); +const ACK_STALL_MS = 1500; + +function signalPipeBufferSize(): number { + const native = getWindowsBindings(); + const read = Buffer.alloc(8); + const write = Buffer.alloc(8); + if (!native.CreatePipe(read, write, 0n, 0)) { + throw new Error(`CreatePipe failed with Win32 error ${native.GetLastError()}`); + } + const readHandle = read.readBigUInt64LE(); + const writeHandle = write.readBigUInt64LE(); + try { + const outSize = Buffer.alloc(4); + const inSize = Buffer.alloc(4); + if (!native.GetNamedPipeInfo(readHandle, 0n, outSize, inSize, 0n)) { + throw new Error(`GetNamedPipeInfo failed with Win32 error ${native.GetLastError()}`); + } + return Math.max(outSize.readUInt32LE(), inSize.readUInt32LE()); + } finally { + native.CloseHandle(readHandle); + native.CloseHandle(writeHandle); + } +} + +const signalBufferBytes = signalPipeBufferSize(); +resizeCount = Math.max(1500, Math.ceil(signalBufferBytes / 6) + 64); + +function openPipe(path: string, access: number): bigint { + const handle = native.CreateFileW(utf16(path), access, 0, 0n, 3, 0, 0n) as bigint; + if (!handle || handle === INVALID_HANDLE_VALUE) { + throw new Error(`CreateFileW(${path}) failed with Win32 error ${native.GetLastError()}`); + } + return handle; +} + +function peekOutput(): number { + const available = Buffer.alloc(4); + if (!native.PeekNamedPipe(outputPipe, 0n, 0, 0n, available, 0n)) { + throw new Error(`PeekNamedPipe failed with Win32 error ${native.GetLastError()}`); + } + return available.readUInt32LE(); +} + +function outputPipeCapacity(): number { + const size = Buffer.alloc(4); + if (!native.GetNamedPipeInfo(outputPipe, 0n, size, 0n, 0n)) { + throw new Error(`GetNamedPipeInfo(output) failed with Win32 error ${native.GetLastError()}`); + } + const capacity = size.readUInt32LE(); + if (capacity === 0) throw new Error("ConPTY output pipe reported a zero buffer capacity"); + return capacity; +} + +function closePipeHandles(): void { + if (outputPipe) native.CloseHandle(outputPipe); + if (inputPipe) native.CloseHandle(inputPipe); + outputPipe = inputPipe = 0n; +} + +function requestCancellation(): void { + if (cancellationStarted) return; + cancellationStarted = true; + if (ackMonitor) clearInterval(ackMonitor); + if (cancelTimer) clearTimeout(cancelTimer); + process.stdout.write("CANCELLING\n"); + const stopping = transport.terminate(); + closePipeHandles(); + void stopping.then(() => { + if (heartbeatTimer) clearInterval(heartbeatTimer); + process.stdout.write("CANCELLED\n"); + }); +} + +async function waitForSaturation(capacity: number): Promise { + const deadline = Date.now() + 15000; + while (Date.now() < deadline) { + const available = peekOutput(); + if (available >= capacity) return available; + await delay(20); + } + throw new Error(`ConPTY output pipe did not fill to its ${capacity} byte quota`); +} + +transport.onError((error) => { + if (cancellationStarted && error.message === "PTY transport terminated") return; + process.stderr.write(`ERROR ${error.message}\n`); +}); +transport.onMessage((reply: BrokerReply) => { + if (reply.type === "pipes") { + try { + inputPipe = openPipe(reply.input, 0x40000000); + outputPipe = openPipe(reply.output, 0x80000000); + void transport.send({ type: "connected" }); + } catch (error) { + process.stderr.write(`ERROR ${String(error)}\n`); + void transport.send({ type: "abort", error: String(error) }); + } + } else if (reply.type === "spawned") { + void (async () => { + const capacity = outputPipeCapacity(); + const outputBytes = await waitForSaturation(capacity); + process.stdout.write( + `BURST ${resizeCount} ${signalBufferBytes} ${capacity} ${outputBytes}\n`, + ); + heartbeatTimer = setInterval(() => process.stdout.write("HEARTBEAT\n"), 50); + for (let id = 1; id <= resizeCount; id++) { + void transport.send({ + type: "command", + id, + command: "resize", + cols: 80 + (id % 40), + rows: 24 + (id % 20), + }); + } + const minAcks = Math.min( + resizeCount - 1, + Math.max(100, Math.ceil(signalBufferBytes / 6) - 64), + ); + ackMonitor = setInterval(() => { + if (resizeAcks >= minAcks && Date.now() - lastAckAt >= ACK_STALL_MS) { + process.stdout.write(`ACKSTALL ${resizeAcks}\n`); + requestCancellation(); + } + }, 100); + cancelTimer = setTimeout( + () => { + process.stderr.write(`RESIZE_ACKS_DID_NOT_STALL ${resizeAcks}\n`); + requestCancellation(); + }, + resizeCount * 10 + 5000, + ); + })().catch((error) => { + process.stderr.write(`ERROR ${String(error)}\n`); + void transport.send({ type: "abort", error: String(error) }); + }); + } else if (reply.type === "ack") { + if (!reply.error) { + resizeAcks++; + lastAckAt = Date.now(); + return; + } + if (reply.error) { + const match = /HRESULT (-?\d+)/.exec(reply.error); + const hresult = match ? Number(match[1]) >>> 0 : 0; + const expectedCancel = + cancellationStarted && (hresult & 0x8000_0000) !== 0 && (hresult & 0xffff) === 995; + if (!expectedCancel) process.stderr.write(`ACK_ERROR ${reply.error}\n`); + } + } +}); + +try { + await transport.ready; + await transport.send({ type: "start", options }); + await transport.closed; + process.stdout.write("DONE\n"); +} finally { + if (heartbeatTimer) clearInterval(heartbeatTimer); + if (cancelTimer) clearTimeout(cancelTimer); + if (ackMonitor) clearInterval(ackMonitor); + await transport.terminate(); + closePipeHandles(); + rmSync(report, { force: true }); +} diff --git a/test/experiments/ffi-pty/windows-ffi-resize.test.mts b/test/experiments/ffi-pty/windows-ffi-resize.test.mts new file mode 100644 index 000000000..ce52ff332 --- /dev/null +++ b/test/experiments/ffi-pty/windows-ffi-resize.test.mts @@ -0,0 +1,121 @@ +import assert from "node:assert/strict"; +import { spawn } from "node:child_process"; +import { mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { test } from "node:test"; +import { + classifyWindowsVersion, + detectWindowsVersion, +} from "../../../experiments/ffi-pty/windows-version.mts"; + +const modern = + process.platform === "win32" && classifyWindowsVersion(detectWindowsVersion()) === "ffi"; + +test( + "direct FFI resize stays responsive while ConPTY output is backpressured", + { skip: !modern, timeout: 60000 }, + async () => { + const dir = mkdtempSync(join(tmpdir(), "ffi-pty-resize-probe-")); + const report = join(dir, "backpressure.txt"); + const probePath = fileURLToPath(new URL("./windows-ffi-resize-probe.mts", import.meta.url)); + const probe = spawn( + process.execPath, + [ + "--disable-warning=ExperimentalWarning", + "--experimental-ffi", + "--experimental-strip-types", + probePath, + report, + ], + { stdio: ["ignore", "pipe", "pipe"] }, + ); + let output = ""; + let errors = ""; + let sawBurst = false; + let sawAckStall = false; + let sawCancelling = false; + let sawDone = false; + let sawCancelled = false; + let heartbeats = 0; + let lastHeartbeat = Date.now(); + let timeout: NodeJS.Timeout | undefined; + const armDeadline = (ms: number) => { + if (timeout) clearTimeout(timeout); + timeout = setTimeout(() => { + probe.kill(); + rejectProbe(new Error(`Resize probe exceeded its ${ms} ms deadline`)); + }, ms); + }; + let rejectProbe!: (error: Error) => void; + const stopped = new Promise((resolve, reject) => { + rejectProbe = reject; + const watchdog = setInterval(() => { + if (sawBurst && Date.now() - lastHeartbeat > 2500) { + probe.kill(); + clearInterval(watchdog); + reject(new Error("Probe heartbeat stopped during resize stress")); + } + }, 100); + armDeadline(30000); + const onLine = (line: string) => { + output += `${line}\n`; + if (line.startsWith("BURST ")) { + sawBurst = true; + const count = Number(line.split(" ")[1]); + armDeadline(count * 10 + 20000); + } else if (line.startsWith("ACKSTALL ")) sawAckStall = true; + else if (line === "CANCELLING") sawCancelling = true; + else if (line === "HEARTBEAT") { + heartbeats++; + lastHeartbeat = Date.now(); + } else if (line === "CANCELLED") sawCancelled = true; + else if (line === "DONE") sawDone = true; + }; + let stdout = ""; + probe.stdout.setEncoding("utf8"); + probe.stdout.on("data", (chunk: string) => { + stdout += chunk; + const lines = stdout.split("\n"); + stdout = lines.pop() ?? ""; + for (const line of lines) onLine(line); + }); + probe.stderr.setEncoding("utf8"); + probe.stderr.on("data", (chunk: string) => (errors += chunk)); + probe.once("error", reject); + probe.once("close", (code) => { + clearInterval(watchdog); + clearTimeout(timeout); + if (code !== 0) reject(new Error(`Probe exited with ${code}.\n${output}\n${errors}`)); + else resolve(); + }); + }); + try { + await stopped; + assert.ok(sawBurst, `Probe did not reach the resize burst.\n${output}\n${errors}`); + assert.ok( + sawAckStall, + `Resize ACKs never stalled under output backpressure.\n${output}\n${errors}`, + ); + assert.ok( + sawCancelling, + `Probe did not exercise cancellation during resize stress.\n${output}\n${errors}`, + ); + assert.ok( + sawCancelled, + `Worker did not clean up after stress cancellation.\n${output}\n${errors}`, + ); + assert.ok(sawDone, `Probe did not finish its cleanup.\n${output}\n${errors}`); + assert.equal(errors, "", `Probe reported stress errors.\n${output}`); + assert.ok(heartbeats >= 3, `Only ${heartbeats} heartbeats ran during the resize burst`); + } finally { + if (probe.exitCode === null) probe.kill(); + await new Promise((resolve) => { + if (probe.exitCode !== null) return resolve(); + probe.once("close", () => resolve()); + }); + rmSync(dir, { recursive: true, force: true }); + } + }, +); diff --git a/test/experiments/ffi-pty/windows-ffi.test.mts b/test/experiments/ffi-pty/windows-ffi.test.mts new file mode 100644 index 000000000..6200eb58e --- /dev/null +++ b/test/experiments/ffi-pty/windows-ffi.test.mts @@ -0,0 +1,153 @@ +import assert from "node:assert/strict"; +import { setTimeout as delay } from "node:timers/promises"; +import { createConnection, type Socket } from "node:net"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; +import { + createKillOnCloseJob, + createFfiTransport, + rehydrateWindowsStart, +} from "../../../experiments/ffi-pty/windows-ffi.mts"; +import type { WindowsStart } from "../../../experiments/ffi-pty/windows-launch.mts"; +import type { SpawnOptions } from "../../../experiments/ffi-pty/contract.mts"; +import type { BrokerReply } from "../../../experiments/ffi-pty/windows-protocol.mts"; +import { + classifyWindowsVersion, + detectWindowsVersion, +} from "../../../experiments/ffi-pty/windows-version.mts"; + +const modern = + process.platform === "win32" && classifyWindowsVersion(detectWindowsVersion()) === "ffi"; + +test("direct transport factory refuses non-Windows systems before loading kernel32", () => { + if (process.platform === "win32") return; + assert.throws(() => createFfiTransport(), /requires Windows/); +}); + +test("rehydrates structured-cloned launch bytes into Buffers before Win32 FFI", () => { + const start = { + cols: 80, + rows: 24, + application: Uint8Array.from([65, 0]), + commandLine: Uint8Array.from([66, 0]), + cwd: Uint8Array.from([67, 0]), + environment: Uint8Array.from([0, 0]), + inputName: "in", + outputName: "out", + } as unknown as WindowsStart; + const result = rehydrateWindowsStart(start); + for (const field of ["application", "commandLine", "cwd", "environment"] as const) { + assert.ok(Buffer.isBuffer(result[field])); + assert.deepEqual([...result[field]], [...start[field]]); + } +}); + +test("main thread creates and configures its kill-on-close job", () => { + let configured: Buffer | undefined; + let closed = false; + const native = { + CreateJobObjectW: () => 42n, + SetInformationJobObject: (_job: bigint, _class: number, info: Buffer) => { + configured = info; + return 1; + }, + CloseHandle: () => { + closed = true; + return 1; + }, + }; + assert.equal(createKillOnCloseJob(native as never), 42n); + assert.equal(configured?.length, 144); + assert.equal(configured?.readUInt32LE(16), 0x00002000); + assert.equal(closed, false); +}); + +test( + "direct FFI starts in this process and keeps the event loop responsive", + { skip: !modern, timeout: 30000 }, + async () => { + const dir = mkdtempSync(join(tmpdir(), "ffi-pty-direct-")); + const report = join(dir, "child.json"); + const env = Object.fromEntries( + Object.entries(process.env).filter( + (entry): entry is [string, string] => entry[1] !== undefined, + ), + ); + const options: SpawnOptions = { + file: process.execPath, + args: [ + "-e", + `require('node:fs').writeFileSync(${JSON.stringify(report)}, JSON.stringify({pid:process.pid,ppid:process.ppid})); setInterval(()=>{},1000)`, + ], + cwd: process.cwd(), + env, + cols: 80, + rows: 24, + }; + const transport = createFfiTransport(); + const sockets: Socket[] = []; + let serial = 0; + const replies: BrokerReply[] = []; + transport.onMessage((reply) => { + replies.push(reply); + if (reply.type === "pipes") { + for (const path of [reply.input, reply.output]) { + const socket = createConnection(path); + sockets.push(socket); + } + void Promise.all( + sockets.map( + (socket) => + new Promise((resolve, reject) => { + socket.once("connect", resolve); + socket.once("error", reject); + }), + ), + ).then(() => transport.send({ type: "connected" })); + } + }); + try { + await transport.ready; + await transport.send({ type: "start", options }); + const deadline = Date.now() + 5000; + let child: { pid: number; ppid: number } | undefined; + while (Date.now() < deadline) { + try { + child = JSON.parse(readFileSync(report, "utf8")) as { pid: number; ppid: number }; + break; + } catch { + await delay(10); + } + } + assert.ok(child, "target did not write its process report"); + assert.equal( + child.ppid, + process.pid, + "CreateProcess should spawn directly from this process", + ); + let heartbeat = 0; + const timer = setInterval(() => heartbeat++, 10); + await delay(100); + clearInterval(timer); + assert.ok(heartbeat >= 5, `event loop heartbeat only advanced ${heartbeat} times`); + await transport.send({ type: "command", id: ++serial, command: "close" }); + await transport.closed; + assert.ok(replies.some((reply) => reply.type === "exited")); + } finally { + await transport.terminate(); + await Promise.all( + sockets.map( + (socket) => + new Promise((resolve) => { + if (socket.closed) return resolve(); + socket.once("close", resolve); + socket.destroy(); + }), + ), + ); + rmSync(dir, { recursive: true, force: true }); + } + }, +); diff --git a/test/experiments/ffi-pty/windows-helper-lifecycle.test.mts b/test/experiments/ffi-pty/windows-helper-lifecycle.test.mts new file mode 100644 index 000000000..44eb19fee --- /dev/null +++ b/test/experiments/ffi-pty/windows-helper-lifecycle.test.mts @@ -0,0 +1,441 @@ +import assert from "node:assert/strict"; +import { fork, spawn, type ChildProcess } from "node:child_process"; +import { once } from "node:events"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { createConnection, type Socket } from "node:net"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { setTimeout as delay } from "node:timers/promises"; +import { test } from "node:test"; +import { + helperExecutablePath, + helperStartupEnv, +} from "../../../experiments/ffi-pty/windows-helper.mts"; +import { prepareWindowsStart } from "../../../experiments/ffi-pty/windows-launch.mts"; +import { + decodeHelperFrames, + decodeHelperReply, + encodeHelperFrame, + encodeHelperRequest, +} from "../../../experiments/ffi-pty/windows-helper-protocol.mts"; +import type { BrokerReply } from "../../../experiments/ffi-pty/windows-protocol.mts"; + +const supported = process.platform === "win32" && ["x64", "arm64"].includes(process.arch); +const baseEnv = Object.fromEntries( + Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined), +); +const targetOptions = (report: string, exitRoot = false) => { + const script = ` + const { spawn } = require('node:child_process'); + const fs = require('node:fs'); + const descendant = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'inherit' }); + fs.writeFileSync(process.env.FFI_PTY_REPORT, JSON.stringify({ pid: process.pid, brokerPid: process.ppid, descendantPid: descendant.pid })); + ${exitRoot ? "process.exit(0);" : "setInterval(() => {}, 1000);"} + `; + return { + file: process.execPath, + args: ["-e", script], + cwd: process.cwd(), + env: { ...baseEnv, FFI_PTY_REPORT: report }, + cols: 80, + rows: 24, + }; +}; + +function withTimeout(promise: Promise, ms: number, label: string): Promise { + let timer: NodeJS.Timeout; + return Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error(`Timed out ${label}`)), ms); + }), + ]).finally(() => clearTimeout(timer!)); +} + +async function connectPipe(name: string, sockets: Socket[]): Promise { + return await new Promise((resolve, reject) => { + const socket = createConnection(name); + sockets.push(socket); + socket.on("data", () => {}); + socket.on("error", () => {}); + const connected = () => { + socket.off("error", failed); + socket.off("close", closedBeforeConnect); + resolve(socket); + }; + const failed = (error: Error) => { + socket.off("connect", connected); + socket.off("close", closedBeforeConnect); + reject(error); + }; + const closedBeforeConnect = () => { + socket.off("connect", connected); + socket.off("error", failed); + reject(new Error("helper named pipe closed before connection")); + }; + socket.once("connect", connected); + socket.once("error", failed); + socket.once("close", closedBeforeConnect); + }); +} + +function waitReply( + replies: BrokerReply[], + listeners: Set<(reply: BrokerReply) => void>, + predicate: (reply: BrokerReply) => boolean, + ms: number, + label: string, +) { + const found = replies.find(predicate); + if (found) return Promise.resolve(found); + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + listeners.delete(listener); + reject(new Error(`Timed out ${label}`)); + }, ms); + const listener = (reply: BrokerReply) => { + if (!predicate(reply)) return; + listeners.delete(listener); + clearTimeout(timer); + resolve(reply); + }; + listeners.add(listener); + }); +} + +async function startRawHelper(reportPath: string, exitRoot = false) { + const child = spawn(helperExecutablePath(), [], { + stdio: ["pipe", "pipe", "ignore"], + windowsHide: true, + env: helperStartupEnv(process.env), + }); + const closed = once(child, "close"); + const sockets: Socket[] = []; + const replies: BrokerReply[] = []; + const listeners = new Set<(reply: BrokerReply) => void>(); + let startPrepared: ReturnType | undefined; + let pending = Buffer.alloc(0); + child.stdout.on("data", (chunk: Buffer) => { + try { + const decoded = decodeHelperFrames(Buffer.from(chunk), pending); + pending = decoded.pending; + for (const frame of decoded.frames) { + const reply = decodeHelperReply(frame); + replies.push(reply); + for (const listener of listeners) listener(reply); + if (reply.type === "pipes") { + if (!startPrepared) throw new Error("PIPES arrived before helper start"); + void Promise.all([ + connectPipe(startPrepared.inputName, sockets), + connectPipe(startPrepared.outputName, sockets), + ]) + .then(() => write(child, encodeHelperRequest({ type: "connected" }))) + .catch((error) => child.kill()); + } + } + } catch { + child.kill(); + } + }); + child.once("error", () => {}); + try { + await withTimeout( + once(child, "spawn").then(() => undefined), + 10000, + "helper startup", + ); + const options = targetOptions(reportPath, exitRoot); + const prepared = prepareWindowsStart(options); + startPrepared = prepared; + await write(child, encodeHelperRequest({ type: "start", options }, prepared)); + const reply = await waitReply( + replies, + listeners, + (value) => value.type === "spawned" || value.type === "error", + 15000, + "target startup", + ); + if (reply.type === "error") throw new Error(reply.error); + return { child, sockets, pid: reply.pid, replies, listeners, closed }; + } catch (error) { + await destroySockets(sockets); + if (child.exitCode === null && child.signalCode === null) { + child.kill(); + await withTimeout(closed, 5000, "failed helper cleanup").catch(() => {}); + } + throw error; + } +} + +function write(child: ChildProcess, data: Buffer): Promise { + return new Promise((resolve, reject) => { + if (!child.stdin || child.stdin.destroyed) return reject(new Error("helper stdin is closed")); + child.stdin.write(data, (error) => (error ? reject(error) : resolve())); + }); +} + +async function waitReport(path: string) { + const deadline = Date.now() + 10000; + while (Date.now() < deadline) { + try { + const report = JSON.parse(readFileSync(path, "utf8")) as Record; + for (const key of ["pid", "brokerPid", "descendantPid"] as const) { + assert.ok( + Number.isSafeInteger(report[key]) && report[key] > 0, + `invalid ${key}: ${report[key]}`, + ); + } + return report as { pid: number; brokerPid: number; descendantPid: number }; + } catch { + await delay(25); + } + } + throw new Error("target did not write its process report"); +} + +async function waitDead(pid: number, label: string) { + const deadline = Date.now() + 10000; + while (Date.now() < deadline) { + try { + process.kill(pid, 0); + } catch { + return; + } + await delay(50); + } + assert.fail(`${label} process ${pid} is still alive`); +} + +async function waitAlive(pid: number, label: string) { + const deadline = Date.now() + 5000; + while (Date.now() < deadline) { + try { + process.kill(pid, 0); + return; + } catch { + await delay(50); + } + } + assert.fail(`${label} process ${pid} did not become alive`); +} + +async function destroySockets(sockets: Socket[]) { + await Promise.all( + sockets.map( + (socket) => + new Promise((resolve) => { + if (socket.closed) return resolve(); + socket.once("close", resolve); + socket.destroy(); + }), + ), + ); +} + +test( + "native helper rejects malformed startup framing", + { skip: !supported, timeout: 10000 }, + async () => { + const child = spawn(helperExecutablePath(), [], { + stdio: ["pipe", "pipe", "ignore"], + windowsHide: true, + env: helperStartupEnv(process.env), + }); + const chunks: Buffer[] = []; + child.stdout.on("data", (chunk: Buffer) => chunks.push(Buffer.from(chunk))); + child.once("error", () => {}); + const closed = once(child, "close"); + await withTimeout( + once(child, "spawn").then(() => undefined), + 5000, + "helper startup", + ); + const invalid = Buffer.alloc(16); + invalid.writeUInt32LE(0, 0); + child.stdin.end(invalid); + const [code] = await withTimeout(closed, 5000, "invalid frame rejection"); + assert.equal(code, 1); + const decoded = decodeHelperFrames(Buffer.concat(chunks)); + assert.equal(decodeHelperReply(decoded.frames[0]).type, "error"); + }, +); + +test( + "helper exits cleanly when the parent disconnects between PIPES and CONNECTED", + { skip: !supported, timeout: 15000 }, + async () => { + const child = spawn(helperExecutablePath(), [], { + stdio: ["pipe", "pipe", "ignore"], + windowsHide: true, + env: helperStartupEnv(process.env), + }); + let pending = Buffer.alloc(0); + let resolvePipes!: () => void; + const pipes = new Promise((resolve) => { + resolvePipes = resolve; + }); + child.stdout.on("data", (chunk: Buffer) => { + try { + const decoded = decodeHelperFrames(Buffer.from(chunk), pending); + pending = decoded.pending; + if (decoded.frames.some((frame) => decodeHelperReply(frame).type === "pipes")) + resolvePipes(); + } catch { + child.kill(); + } + }); + child.once("error", () => {}); + const closed = once(child, "close"); + await withTimeout( + once(child, "spawn").then(() => undefined), + 5000, + "helper startup", + ); + const options = targetOptions(join(tmpdir(), `ffi-pty-no-connect-${process.pid}.json`)); + try { + await write( + child, + encodeHelperRequest({ type: "start", options }, prepareWindowsStart(options)), + ); + await withTimeout(pipes, 5000, "helper PIPES reply"); + child.stdin.end(); + const [code] = await withTimeout(closed, 5000, "helper startup abort"); + assert.notEqual(code, null); + } finally { + if (child.exitCode === null && child.signalCode === null) child.kill(); + await withTimeout(closed, 5000, "helper startup test cleanup").catch(() => {}); + } + }, +); + +test( + "native helper natural target exit kills descendants holding the console", + { skip: !supported, timeout: 30000 }, + async () => { + const directory = mkdtempSync(join(tmpdir(), "ffi-pty-helper-natural-")); + const reportPath = join(directory, "processes.json"); + const { child, sockets, replies, listeners, closed } = await startRawHelper(reportPath, true); + try { + const report = await waitReport(reportPath); + const exited = await waitReply( + replies, + listeners, + (reply) => reply.type === "exited", + 15000, + "target exit", + ); + assert.equal(exited.type, "exited"); + await withTimeout(closed, 5000, "natural helper close"); + await waitDead(report.descendantPid, "console descendant"); + } finally { + await destroySockets(sockets); + if (child.exitCode === null && child.signalCode === null) child.kill(); + rmSync(directory, { recursive: true, force: true }); + } + }, +); + +test( + "native helper aborts the job on malformed control while a target is live", + { skip: !supported, timeout: 30000 }, + async () => { + const directory = mkdtempSync(join(tmpdir(), "ffi-pty-helper-invalid-control-")); + const reportPath = join(directory, "processes.json"); + const { child, sockets, closed } = await startRawHelper(reportPath); + try { + const report = await waitReport(reportPath); + await waitAlive(report.pid, "target before malformed control"); + await waitAlive(report.descendantPid, "descendant before malformed control"); + await write(child, encodeHelperFrame(999, 55)); + const [code] = await withTimeout(closed, 10000, "helper abort after malformed control"); + assert.notEqual(code, null); + await waitDead(report.pid, "target after malformed control"); + await waitDead(report.descendantPid, "descendant after malformed control"); + } finally { + await destroySockets(sockets); + if (child.exitCode === null && child.signalCode === null) child.kill(); + rmSync(directory, { recursive: true, force: true }); + } + }, +); + +test( + "hard helper death closes its job and terminates the target tree", + { skip: !supported, timeout: 30000 }, + async () => { + const directory = mkdtempSync(join(tmpdir(), "ffi-pty-helper-death-")); + const reportPath = join(directory, "processes.json"); + const { child, sockets, pid, replies, listeners, closed } = await startRawHelper(reportPath); + try { + const report = await waitReport(reportPath); + assert.equal(report.pid, pid); + await waitAlive(report.pid, "target before helper death"); + await waitAlive(report.descendantPid, "descendant before helper death"); + await write( + child, + encodeHelperRequest({ + type: "command", + id: 9, + command: "resize", + cols: 92, + rows: 31, + }), + ); + const resizeAck = await waitReply( + replies, + listeners, + (reply) => reply.type === "ack" && reply.id === 9, + 5000, + "resize acknowledgment", + ); + assert.deepEqual(resizeAck, { type: "ack", id: 9 }); + child.kill(); + await withTimeout(closed, 10000, "helper process exit"); + await waitDead(report.pid, "target"); + await waitDead(report.descendantPid, "target descendant"); + } finally { + await destroySockets(sockets); + if (child.exitCode === null && child.signalCode === null) child.kill(); + rmSync(directory, { recursive: true, force: true }); + } + }, +); + +test( + "hard parent death cleans up the selected Windows transport", + { skip: !supported, timeout: 30000 }, + async () => { + const directory = mkdtempSync(join(tmpdir(), "ffi-pty-parent-death-")); + const reportPath = join(directory, "processes.json"); + const fixture = fork( + fileURLToPath(new URL("./windows-parent-death-fixture.mts", import.meta.url)), + [reportPath], + { execArgv: ["--experimental-ffi"], stdio: ["ignore", "ignore", "ignore", "ipc"] }, + ); + try { + await withTimeout( + new Promise((resolve, reject) => { + fixture.once("message", (message: any) => + message?.type === "started" ? resolve() : reject(new Error("fixture did not start")), + ); + fixture.once("error", reject); + }), + 15000, + "parent fixture startup", + ); + const report = await waitReport(reportPath); + await waitAlive(report.pid, "target before parent death"); + await waitAlive(report.descendantPid, "descendant before parent death"); + const parentExit = once(fixture, "close"); + fixture.kill(); + await withTimeout(parentExit, 10000, "fixture process exit"); + await waitDead(report.pid, "target after parent death"); + await waitDead(report.descendantPid, "descendant after parent death"); + await waitDead(report.brokerPid, "transport process after parent death"); + } finally { + if (fixture.exitCode === null && fixture.signalCode === null) fixture.kill(); + rmSync(directory, { recursive: true, force: true }); + } + }, +); diff --git a/test/experiments/ffi-pty/windows-helper-lock.test.mts b/test/experiments/ffi-pty/windows-helper-lock.test.mts new file mode 100644 index 000000000..befcfc2d2 --- /dev/null +++ b/test/experiments/ffi-pty/windows-helper-lock.test.mts @@ -0,0 +1,106 @@ +import assert from "node:assert/strict"; +import { mkdtempSync, writeFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; +import { + assertNotReparsePoint, + closeWindowsHandlePair, + lockWindowsHelper, + type LockBindings, +} from "../../../experiments/ffi-pty/windows-helper-lock.mts"; + +function fakeBindings(attributes: number[], failInfoAt = 0) { + let infoCalls = 0; + let next = 1n; + const closed: bigint[] = []; + const native: LockBindings = { + CreateFileW() { + return next++; + }, + GetFileInformationByHandle(handle, info) { + infoCalls++; + if (infoCalls === failInfoAt) return 0; + info.writeUInt32LE(attributes[Number(handle) - 1] ?? 0, 0); + return 1; + }, + CloseHandle(handle) { + closed.push(handle); + return 1; + }, + GetLastError() { + return 5; + }, + }; + return { native, closed }; +} + +test( + "helper lock releases file and directory handles exactly once", + { skip: process.platform !== "win32" }, + () => { + const directory = mkdtempSync(join(tmpdir(), "pty-lock-")); + const helper = join(directory, "helper.exe"); + writeFileSync(helper, "placeholder"); + try { + const { native, closed } = fakeBindings([0x10, 0]); + const lock = lockWindowsHelper(helper, native); + lock.release(); + lock.release(); + assert.deepEqual(closed, [2n, 1n]); + } finally { + rmSync(directory, { recursive: true, force: true }); + } + }, +); + +test( + "helper lock closes both handles if file inspection fails", + { skip: process.platform !== "win32" }, + () => { + const directory = mkdtempSync(join(tmpdir(), "pty-lock-")); + const helper = join(directory, "helper.exe"); + writeFileSync(helper, "placeholder"); + try { + const { native, closed } = fakeBindings([0x10, 0], 2); + assert.throws(() => lockWindowsHelper(helper, native), /GetFileInformationByHandle/); + assert.deepEqual(closed, [2n, 1n]); + } finally { + rmSync(directory, { recursive: true, force: true }); + } + }, +); + +test( + "helper lock rejects a reparse parent and closes its handle", + { skip: process.platform !== "win32" }, + () => { + const directory = mkdtempSync(join(tmpdir(), "pty-lock-")); + const helper = join(directory, "helper.exe"); + writeFileSync(helper, "placeholder"); + try { + const { native, closed } = fakeBindings([0x10 | 0x400]); + assert.throws(() => lockWindowsHelper(helper, native), /reparse point/); + assert.deepEqual(closed, [1n]); + } finally { + rmSync(directory, { recursive: true, force: true }); + } + }, +); + +test("reparse attributes are rejected", () => { + assert.throws(() => assertNotReparsePoint(0x400, "helper.exe"), /reparse point/); + assert.doesNotThrow(() => assertNotReparsePoint(0, "helper.exe")); +}); + +test("both handles are closed even when closing the first fails", () => { + const closed: bigint[] = []; + const native = fakeBindings([0, 0]).native; + native.CloseHandle = (handle) => { + closed.push(handle); + if (handle === 1n) throw new Error("simulated close failure"); + return 1; + }; + assert.throws(() => closeWindowsHandlePair(native, 1n, 2n), /simulated close failure/); + assert.deepEqual(closed, [1n, 2n]); +}); diff --git a/test/experiments/ffi-pty/windows-helper-pe.test.mts b/test/experiments/ffi-pty/windows-helper-pe.test.mts new file mode 100644 index 000000000..23f57f873 --- /dev/null +++ b/test/experiments/ffi-pty/windows-helper-pe.test.mts @@ -0,0 +1,133 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + inspectPeCertificate, + type PeReader, +} from "../../../experiments/ffi-pty/windows-helper-pe.mts"; + +function peFixture(bits: 32 | 64, certificate = true): Buffer { + const peOffset = 0x80; + const optionalSize = bits === 32 ? 224 : 240; + const optionalOffset = peOffset + 24; + const certificateOffset = optionalOffset + optionalSize; + const file = Buffer.alloc(certificate ? certificateOffset + 8 : certificateOffset); + file.write("MZ", 0, "ascii"); + file.writeUInt32LE(peOffset, 0x3c); + file.write("PE\0\0", peOffset, "binary"); + file.writeUInt16LE(optionalSize, peOffset + 20); + file.writeUInt16LE(bits === 32 ? 0x10b : 0x20b, peOffset + 24); + const numberOffset = bits === 32 ? 92 : 108; + const directoryOffset = bits === 32 ? 96 : 112; + file.writeUInt32LE(16, optionalOffset + numberOffset); + if (certificate) { + file.writeUInt32LE(certificateOffset, optionalOffset + directoryOffset + 4 * 8); + file.writeUInt32LE(8, optionalOffset + directoryOffset + 4 * 8 + 4); + file.writeUInt32LE(8, certificateOffset); + file.writeUInt16LE(0x0200, certificateOffset + 4); + file.writeUInt16LE(2, certificateOffset + 6); + } + return file; +} + +function trackedReader(file: Buffer, size = file.length) { + let bytesRequested = 0; + const reader: PeReader = { + size, + read(offset, length) { + bytesRequested += length; + return file.subarray(offset, offset + length); + }, + }; + return { + reader, + get bytesRequested() { + return bytesRequested; + }, + }; +} + +for (const bits of [32, 64] as const) { + test(`PE${bits} certificate sniff checks header and certificate record`, () => { + const tracked = trackedReader(peFixture(bits)); + assert.equal(inspectPeCertificate(tracked.reader).present, true); + assert.equal(tracked.bytesRequested, 110); + }); + + test(`PE${bits} absent certificate table stops after 102 header bytes`, () => { + const tracked = trackedReader(peFixture(bits, false)); + assert.equal(inspectPeCertificate(tracked.reader).present, false); + assert.ok(tracked.bytesRequested <= 102); + }); +} + +test("DOS header overlap stops after 64 bytes without reading the PE header", () => { + const file = peFixture(64); + file.writeUInt32LE(32, 0x3c); + const tracked = trackedReader(file); + assert.equal(inspectPeCertificate(tracked.reader).present, false); + assert.equal(tracked.bytesRequested, 64); +}); + +test("certificate offset overlapping optional header is rejected", () => { + const file = peFixture(64); + const peOffset = file.readUInt32LE(0x3c); + const optionalOffset = peOffset + 24; + const directoryOffset = optionalOffset + 112 + 4 * 8; + file.writeUInt32LE(optionalOffset, directoryOffset); + const tracked = trackedReader(file); + assert.equal(inspectPeCertificate(tracked.reader).present, false); + assert.equal(tracked.bytesRequested, 102); +}); + +test("claimed payload size does not increase header bytes read", () => { + const tracked = trackedReader(peFixture(64), 0x7fff_ffff); + assert.equal(inspectPeCertificate(tracked.reader).present, true); + assert.equal(tracked.bytesRequested, 110); +}); + +test("out-of-range PE offset stops after the 64-byte DOS header", () => { + const file = peFixture(64); + file.writeUInt32LE(0xffff_ffff, 0x3c); + const tracked = trackedReader(file); + assert.equal(inspectPeCertificate(tracked.reader).present, false); + assert.equal(tracked.bytesRequested, 64); +}); + +test("out-of-range certificate size is rejected from headers", () => { + const file = peFixture(64); + const optionalOffset = file.readUInt32LE(0x3c) + 24; + const entry = optionalOffset + 112 + 4 * 8; + file.writeUInt32LE(0xffff_ffff, entry + 4); + const tracked = trackedReader(file); + assert.equal(inspectPeCertificate(tracked.reader).present, false); + assert.equal(tracked.bytesRequested, 102); +}); + +test("bad optional magic, directory count, and certificate record are rejected", () => { + const badMagic = peFixture(64); + badMagic.writeUInt16LE(0x777, badMagic.readUInt32LE(0x3c) + 24); + assert.equal(inspectPeCertificate(trackedReader(badMagic).reader).present, false); + + const noDirectories = peFixture(64); + const optionalOffset = noDirectories.readUInt32LE(0x3c) + 24; + noDirectories.writeUInt32LE(4, optionalOffset + 108); + const noDirectoryRead = trackedReader(noDirectories); + assert.equal(inspectPeCertificate(noDirectoryRead.reader).present, false); + assert.equal(noDirectoryRead.bytesRequested, 94); + + const badRecord = peFixture(64); + const certOffset = badRecord.readUInt32LE(optionalOffset + 112 + 4 * 8); + badRecord.writeUInt16LE(0x0100, certOffset + 4); + assert.equal(inspectPeCertificate(trackedReader(badRecord).reader).present, false); +}); + +test("short positional reads are rejected safely", () => { + const full = peFixture(64); + const reader: PeReader = { + size: full.length, + read(offset, length) { + return full.subarray(offset, offset + Math.max(0, length - 1)); + }, + }; + assert.equal(inspectPeCertificate(reader).present, false); +}); diff --git a/test/experiments/ffi-pty/windows-helper-protocol.test.mts b/test/experiments/ffi-pty/windows-helper-protocol.test.mts new file mode 100644 index 000000000..1c4ec8d39 --- /dev/null +++ b/test/experiments/ffi-pty/windows-helper-protocol.test.mts @@ -0,0 +1,129 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { + decodeHelperFrames, + decodeHelperReply, + encodeHelperFrame, + encodeHelperReply, + encodeHelperRequest, + HELPER_MAGIC, + HELPER_OPCODE, + type PreparedWindowsStart, +} from "../../../experiments/ffi-pty/windows-helper-protocol.mts"; + +function utf16(value: string): Buffer { + return Buffer.from(`${value}\0`, "utf16le"); +} + +const prepared: PreparedWindowsStart = { + cols: 101, + rows: 37, + application: utf16("C:\\🧪\\shell.exe"), + commandLine: utf16('"C:\\🧪\\shell.exe" "hello world"'), + cwd: utf16("C:\\工作"), + environment: Buffer.from("Path=C:\\bin\0UNICODE=🍎\0\0", "utf16le"), + inputName: "\\\\.\\pipe\\pty-test-in", + outputName: "\\\\.\\pipe\\pty-test-out", +}; + +test("START carries six length-prefixed UTF-16 fields and an exact environment double NUL", () => { + const frame = encodeHelperRequest( + { type: "start", options: { file: "unused", args: [], cols: 1, rows: 1, cwd: ".", env: {} } }, + prepared, + ); + assert.equal(frame.readUInt32LE(0), HELPER_MAGIC); + assert.equal(frame.readUInt32LE(4), HELPER_OPCODE.start); + assert.equal(frame.readUInt32LE(8), 0); + let offset = 24; + const fields: Buffer[] = []; + for (let i = 0; i < 6; i += 1) { + const length = frame.readUInt32LE(offset); + offset += 4; + fields.push(frame.subarray(offset, offset + length)); + offset += length; + } + assert.equal(offset, frame.length); + assert.equal(fields[0].toString("utf16le"), "C:\\🧪\\shell.exe\0"); + assert.equal(fields[1].toString("utf16le"), '"C:\\🧪\\shell.exe" "hello world"\0'); + assert.equal(fields[2].toString("utf16le"), "C:\\工作\0"); + assert.equal(fields[3].toString("utf16le"), "Path=C:\\bin\0UNICODE=🍎\0\0"); + assert.equal(fields[4].toString("utf16le"), "\\\\.\\pipe\\pty-test-in\0"); + assert.equal(fields[5].toString("utf16le"), "\\\\.\\pipe\\pty-test-out\0"); +}); + +test("frame decoder handles split headers and coalesced frames", () => { + const first = encodeHelperFrame(HELPER_OPCODE.spawned, 0, Buffer.from([42, 0, 0, 0])); + const second = encodeHelperReply({ type: "ack", id: 9 }); + const split = decodeHelperFrames(first.subarray(0, 9)); + assert.equal(split.frames.length, 0); + const combined = decodeHelperFrames(Buffer.concat([first.subarray(9), second]), split.pending); + assert.deepEqual(combined.frames.map(decodeHelperReply), [ + { type: "spawned", pid: 42 }, + { type: "ack", id: 9 }, + ]); + assert.equal(combined.pending.length, 0); +}); + +test("command requests encode the locked opcode, id, and payload shape", () => { + const resize = encodeHelperRequest({ + type: "command", + id: 41, + command: "resize", + cols: 100, + rows: 40, + }); + assert.equal(resize.readUInt32LE(4), HELPER_OPCODE.resize); + assert.equal(resize.readUInt32LE(8), 41); + assert.equal(resize.readUInt32LE(16), 100); + assert.equal(resize.readUInt32LE(20), 40); + const kill = encodeHelperRequest({ type: "command", id: 42, command: "kill", signal: 9 }); + assert.equal(kill.readUInt32LE(4), HELPER_OPCODE.kill); + assert.equal(kill.readUInt32LE(8), 42); + assert.equal(kill.readUInt32LE(16), 9); +}); + +test("frame decoder rejects invalid magic and oversized payload", () => { + const invalid = encodeHelperFrame(HELPER_OPCODE.done, 0); + invalid.writeUInt32LE(0, 0); + assert.throws(() => decodeHelperFrames(invalid), /magic/); + const oversized = Buffer.alloc(16); + oversized.writeUInt32LE(HELPER_MAGIC); + oversized.writeUInt32LE(HELPER_OPCODE.error, 4); + oversized.writeUInt32LE(8 * 1024 * 1024 + 1, 12); + assert.throws(() => decodeHelperFrames(oversized), /8 MiB/); +}); + +test("reply codec preserves ACK ids, error text, and process status", () => { + for (const reply of [ + { type: "ack", id: 2 }, + { type: "ack", id: 3, error: "resize failed" }, + { type: "exited", exitCode: 17, signal: 0 }, + { type: "error", error: "CreateProcessW failed" }, + { type: "brokerDone" }, + ] as const) { + assert.deepEqual( + decodeHelperReply(decodeHelperFrames(encodeHelperReply(reply)).frames[0]), + reply, + ); + } +}); + +test("START rejects malformed prepared UTF-16 fields", () => { + const bad = { ...prepared, cwd: Buffer.from("not utf16 NUL") }; + assert.throws( + () => + encodeHelperRequest( + { type: "start", options: { file: "x", args: [], cols: 1, rows: 1, cwd: ".", env: {} } }, + bad, + ), + /UTF-16/, + ); + assert.throws( + () => + encodeHelperRequest( + { type: "start", options: { file: "x", args: [], cols: 1, rows: 1, cwd: ".", env: {} } }, + { ...prepared, cwd: Buffer.from("a\0b\0", "utf16le") }, + ), + /interior NUL/, + ); +}); diff --git a/test/experiments/ffi-pty/windows-helper-trust.integration.test.mts b/test/experiments/ffi-pty/windows-helper-trust.integration.test.mts new file mode 100644 index 000000000..140a786b0 --- /dev/null +++ b/test/experiments/ffi-pty/windows-helper-trust.integration.test.mts @@ -0,0 +1,244 @@ +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { + appendFileSync, + closeSync, + copyFileSync, + existsSync, + openSync, + mkdtempSync, + realpathSync, + readFileSync, + renameSync, + rmSync, + writeFileSync, + writeSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { promisify } from "node:util"; +import test from "node:test"; +import { helperExecutablePath } from "../../../experiments/ffi-pty/windows-helper.mts"; +import { + buildAuthenticodeVerifierEnv, + readSystemDirectory, + systemPowerShellPath, + verifyHelperAtPath, +} from "../../../experiments/ffi-pty/windows-helper-trust.mts"; + +const execFileAsync = promisify(execFile); +const SIGN_SCRIPT = String.raw` +$ErrorActionPreference = 'Stop' +$ProgressPreference = 'SilentlyContinue' +$securityModule = Join-Path $PSHOME 'Modules\Microsoft.PowerShell.Security\Microsoft.PowerShell.Security.psd1' +$pkiModule = Join-Path $PSHOME 'Modules\PKI\PKI.psd1' +[Console]::Error.WriteLine('[trust-test] importing certificate modules') +Import-Module -Name $securityModule -ErrorAction Stop +Import-Module -Name $pkiModule -ErrorAction Stop +$subject = $env:NODE_PTY_TEST_CERT_SUBJECT +[Console]::Error.WriteLine('[trust-test] creating ephemeral code-signing certificate') +$cert = New-SelfSignedCertificate -Type CodeSigningCert -Subject $subject -CertStoreLocation 'Cert:\CurrentUser\My' -KeyAlgorithm RSA -KeyLength 2048 -NotAfter (Get-Date).AddDays(2) +try { + [Console]::Error.WriteLine('[trust-test] exporting temporary certificate') + Export-Certificate -Cert $cert -FilePath $env:NODE_PTY_TEST_CERT_FILE | Out-Null + [Console]::Error.WriteLine('[trust-test] adding trust to disposable runner LocalMachine Root') + Import-Certificate -FilePath $env:NODE_PTY_TEST_CERT_FILE -CertStoreLocation 'Cert:\LocalMachine\Root' | Out-Null + [Console]::Error.WriteLine('[trust-test] signing helper executable') + $signed = Set-AuthenticodeSignature -FilePath $env:NODE_PTY_TEST_HELPER -Certificate $cert -HashAlgorithm SHA256 + if ([string]$signed.Status -ne 'Valid') { throw "Signing failed: $($signed.Status)" } + [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) + [ordered]@{ subject = $cert.Subject; issuer = $cert.Issuer; thumbprint = $cert.Thumbprint } | ConvertTo-Json -Compress +} catch { + Remove-Item -LiteralPath "Cert:\CurrentUser\My\$($cert.Thumbprint)" -DeleteKey -Force -ErrorAction SilentlyContinue + Remove-Item -LiteralPath "Cert:\LocalMachine\Root\$($cert.Thumbprint)" -Force -ErrorAction SilentlyContinue + throw +} +`; + +const CLEANUP_SCRIPT = String.raw` +$ErrorActionPreference = 'Stop' +$securityModule = Join-Path $PSHOME 'Modules\Microsoft.PowerShell.Security\Microsoft.PowerShell.Security.psd1' +$pkiModule = Join-Path $PSHOME 'Modules\PKI\PKI.psd1' +[Console]::Error.WriteLine('[trust-test] importing certificate modules for cleanup') +Import-Module -Name $securityModule -ErrorAction Stop +Import-Module -Name $pkiModule -ErrorAction Stop +$thumbprint = $env:NODE_PTY_TEST_CERT_THUMBPRINT +$subject = $env:NODE_PTY_TEST_CERT_SUBJECT +foreach ($store in @('Cert:\CurrentUser\My', 'Cert:\LocalMachine\Root')) { + $certificates = Get-ChildItem -LiteralPath $store | Where-Object { + $_.Subject -eq $subject -or ($thumbprint -and $_.Thumbprint -eq $thumbprint) + } + foreach ($cert in $certificates) { + if ($store -eq 'Cert:\CurrentUser\My') { + Remove-Item -LiteralPath "$store\$($cert.Thumbprint)" -DeleteKey -Force + } else { + Remove-Item -LiteralPath "$store\$($cert.Thumbprint)" -Force + } + } +} +`; + +interface TestCertificate { + subject: string; + issuer: string; + thumbprint: string; +} + +async function runPowerShell(script: string, variables: Record): Promise { + const env = buildAuthenticodeVerifierEnv(process.env, "", readSystemDirectory); + Object.assign(env, variables); + try { + const { stdout } = await execFileAsync( + systemPowerShellPath(readSystemDirectory), + ["-NoProfile", "-NonInteractive", "-Command", script], + { env, windowsHide: true, timeout: 45_000, maxBuffer: 64 * 1024, encoding: "utf8" }, + ); + return String(stdout).trim(); + } catch (error) { + const failure = error as Error & { stderr?: string }; + throw new Error(`${failure.message}${failure.stderr ? `\nPowerShell stderr:\n${failure.stderr}` : ""}`, { + cause: error, + }); + } +} + +export async function timedStage(name: string, operation: () => Promise): Promise { + const started = Date.now(); + try { + return await operation(); + } finally { + process.stderr.write(`[trust-test] ${name} completed in ${Date.now() - started}ms\n`); + } +} + +export function canRunMachineCertificateIntegration( + platform = process.platform, + actions = process.env.GITHUB_ACTIONS, + runner = process.env.RUNNER_ENVIRONMENT, +): boolean { + return platform === "win32" && actions === "true" && runner === "github-hosted"; +} + +test("machine certificate integration is limited to GitHub-hosted Windows runners", () => { + assert.equal(canRunMachineCertificateIntegration("win32", "true", "github-hosted"), true); + assert.equal(canRunMachineCertificateIntegration("win32", "true", "self-hosted"), false); + assert.equal(canRunMachineCertificateIntegration("win32", "false", "github-hosted"), false); + assert.equal(canRunMachineCertificateIntegration("darwin", "true", "github-hosted"), false); +}); + +test( + "verified signed helper is locked, wrong publisher falls back, and tampering is rejected", + { skip: !canRunMachineCertificateIntegration(), timeout: 120_000 }, + async () => { + const directory = mkdtempSync(join(tmpdir(), "node-pty-helper-trust-")); + const helper = join(directory, "helper.exe"); + const alternate = join(directory, "replacement.exe"); + const certificateFile = join(directory, "test.cer"); + const subject = `CN=Node Pty FFI Test ${process.pid}-${Date.now()}`; + let certificate: TestCertificate | undefined; + let retainedRelease: (() => void) | undefined; + let testFailure: unknown; + const cleanupFailures: unknown[] = []; + try { + copyFileSync(helperExecutablePath(), helper); + writeFileSync(alternate, readFileSync(helper)); + const signOutput = await timedStage("sign helper", () => runPowerShell(SIGN_SCRIPT, { + NODE_PTY_TEST_CERT_SUBJECT: subject, + NODE_PTY_TEST_CERT_FILE: certificateFile, + NODE_PTY_TEST_HELPER: helper, + })); + certificate = JSON.parse(signOutput) as TestCertificate; + assert.equal(typeof certificate.thumbprint, "string"); + assert.equal(certificate.subject, subject); + + const approved = await timedStage("verify signed helper", () => verifyHelperAtPath( + helper, + { subject: certificate.subject, issuer: certificate.issuer }, + undefined, + { + retain: (lock) => { + retainedRelease = () => lock.release(); + }, + }, + )); + assert.equal(approved.kind, "native"); + if (approved.kind === "native") { + assert.equal(approved.path.toLowerCase(), realpathSync.native(helper).toLowerCase()); + assert.equal(approved.subject, certificate.subject); + } + assert.ok(retainedRelease, "successful verification retains the helper lock"); + let writeHandle: number | undefined; + try { + writeHandle = openSync(helper, "r+"); + } catch { + // The retained verification handle denies write sharing. + } + if (writeHandle !== undefined) { + closeSync(writeHandle); + assert.fail("retained helper lock allowed a write handle"); + } + assert.throws(() => appendFileSync(helper, Buffer.from([0]))); + assert.throws(() => { + // ReplaceFile/MoveFile must not replace a helper while verification is retained. + renameSync(alternate, helper); + }); + + retainedRelease(); + retainedRelease = undefined; + const rejectedPublisher = await timedStage("reject wrong publisher", () => verifyHelperAtPath(helper, { + subject: `${certificate.subject}-wrong`, + issuer: certificate.issuer, + })); + assert.equal(rejectedPublisher.kind, "node"); + + const file = readFileSync(helper); + const peOffset = file.readUInt32LE(0x3c); + const sectionCount = file.readUInt16LE(peOffset + 6); + const optionalSize = file.readUInt16LE(peOffset + 20); + const firstSection = peOffset + 24 + optionalSize; + assert.ok(sectionCount > 0, "signed helper has at least one PE section"); + const tamperOffset = file.readUInt32LE(firstSection + 20); + assert.ok(tamperOffset > 0 && tamperOffset < file.length, "first section data is inside helper"); + const tamperHandle = openSync(helper, "r+"); + try { + writeSync(tamperHandle, Buffer.from([file[tamperOffset]! ^ 1]), 0, 1, tamperOffset); + } finally { + closeSync(tamperHandle); + } + const tampered = await timedStage("reject tampered helper", () => verifyHelperAtPath(helper, { + subject: certificate.subject, + issuer: certificate.issuer, + })); + assert.equal(tampered.kind, "node"); + if (tampered.kind === "node") assert.match(tampered.reason, /HashMismatch/i); + } catch (error) { + testFailure = error; + } finally { + try { + retainedRelease?.(); + } catch (error) { + cleanupFailures.push(error); + } + if (subject) { + await timedStage("certificate cleanup", () => runPowerShell(CLEANUP_SCRIPT, { + NODE_PTY_TEST_CERT_THUMBPRINT: certificate?.thumbprint ?? "", + NODE_PTY_TEST_CERT_SUBJECT: subject, + })).catch((error) => { + cleanupFailures.push(error); + }); + } + try { + if (existsSync(directory)) rmSync(directory, { recursive: true, force: true }); + } catch (error) { + cleanupFailures.push(error); + } + } + if (testFailure && cleanupFailures.length) { + throw new AggregateError([testFailure, ...cleanupFailures], "trust test and cleanup failed", { + cause: testFailure, + }); + } + if (testFailure) throw testFailure; + if (cleanupFailures.length) throw new AggregateError(cleanupFailures, "trust test cleanup failed"); + }, +); diff --git a/test/experiments/ffi-pty/windows-helper-trust.test.mts b/test/experiments/ffi-pty/windows-helper-trust.test.mts new file mode 100644 index 000000000..6603004f7 --- /dev/null +++ b/test/experiments/ffi-pty/windows-helper-trust.test.mts @@ -0,0 +1,156 @@ +import assert from "node:assert/strict"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; +import { + classifyAuthenticodeResult, + buildAuthenticodeVerifierEnv, + getVerifiedHelper, + runPowerShellAuthenticodeVerifier, + systemPowerShellPath, + verifyHelperAtPath, + type AuthenticodeResult, +} from "../../../experiments/ffi-pty/windows-helper-trust.mts"; +import type { HelperPublisherPolicy } from "../../../experiments/ffi-pty/windows-helper-publisher.mts"; +import type { WindowsHelperLock } from "../../../experiments/ffi-pty/windows-helper-lock.mts"; + +const policy: HelperPublisherPolicy = { subject: "CN=PTY Test", issuer: "CN=Test CA" }; +const valid: AuthenticodeResult = { + status: "Valid", + subject: policy.subject, + issuer: policy.issuer, +}; + +test("Authenticode trust requires exact valid status, subject, and configured issuer", () => { + assert.deepEqual(classifyAuthenticodeResult("helper.exe", policy, valid), { + kind: "native", + path: "helper.exe", + subject: policy.subject, + }); + assert.equal( + classifyAuthenticodeResult("helper.exe", policy, { ...valid, status: "HashMismatch" }).kind, + "node", + ); + assert.equal( + classifyAuthenticodeResult("helper.exe", policy, { ...valid, subject: "CN=Other" }).kind, + "node", + ); + assert.equal( + classifyAuthenticodeResult("helper.exe", policy, { ...valid, issuer: "CN=Other" }).kind, + "node", + ); + assert.equal(classifyAuthenticodeResult("helper.exe", { subject: "" }, valid).kind, "node"); +}); + +test("empty default publisher policy caches Node fallback without inspecting a file", async () => { + const first = getVerifiedHelper(); + assert.equal(first, getVerifiedHelper()); + assert.equal((await first).kind, "node"); +}); + +test("PowerShell location and module path ignore caller SystemRoot and PSModulePath", () => { + const trustedSystemDirectory = "C:\\Windows\\System32"; + const source = Object.assign(Object.create(null), { + SystemRoot: "C:\\attacker\\root", + WINDIR: "C:\\attacker\\windir", + PSModulePath: "C:\\attacker\\modules", + PATH: "C:\\attacker\\bin", + TEMP: "C:\\temp", + }) as NodeJS.ProcessEnv; + const systemDirectory = () => trustedSystemDirectory; + const env = buildAuthenticodeVerifierEnv(source, "C:\\trusted\\helper.exe", systemDirectory); + assert.equal( + systemPowerShellPath(systemDirectory), + "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", + ); + assert.equal(env.SystemRoot, "C:\\Windows"); + assert.equal(env.WINDIR, "C:\\Windows"); + assert.equal(env.PSModulePath, "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\Modules"); + assert.equal(env.TEMP, "C:\\temp"); + assert.equal(env.PATH, undefined); +}); + +test("unsigned or unreadable helper exits before lock and verifier", async () => { + let locks = 0; + let verifications = 0; + const result = await verifyHelperAtPath( + "helper.exe", + policy, + async () => { + verifications++; + return valid; + }, + { + sniff: () => ({ present: false, reason: "missing certificate" }), + lock: () => { + locks++; + throw new Error("must not lock"); + }, + }, + ); + assert.equal(result.kind, "node"); + assert.equal(locks, 0); + assert.equal(verifications, 0); +}); + +test("positive verification retains the lock; failed verification releases it", async () => { + let retained = 0; + let released = 0; + const makeLock = (): WindowsHelperLock => ({ path: "locked.exe", release: () => released++ }); + const deps = { + sniff: () => ({ present: true, reason: "certificate table present" }), + lock: () => makeLock(), + retain: () => retained++, + }; + assert.equal( + (await verifyHelperAtPath("helper.exe", policy, async () => valid, deps)).kind, + "native", + ); + assert.equal(retained, 1); + assert.equal(released, 0); + const failure = await verifyHelperAtPath( + "helper.exe", + policy, + async () => { + throw new Error("bad signature"); + }, + deps, + ); + assert.equal(failure.kind, "node"); + assert.equal(released, 1); +}); + +test( + "missing helper falls back without invoking Authenticode", + { skip: process.platform !== "win32" }, + async () => { + let invoked = false; + const result = await verifyHelperAtPath( + "C:\\definitely-missing\\pty-helper.exe", + policy, + async () => { + invoked = true; + return valid; + }, + ); + assert.equal(result.kind, "node"); + assert.equal(invoked, false); + }, +); + +test( + "PowerShell reports a real unsigned file as untrusted", + { skip: process.platform !== "win32" }, + async () => { + const directory = mkdtempSync(join(tmpdir(), "pty-unsigned-")); + const file = join(directory, "unsigned.exe"); + writeFileSync(file, "unsigned helper fixture"); + try { + const result = await runPowerShellAuthenticodeVerifier(file, policy); + assert.notEqual(result.status, "Valid"); + } finally { + rmSync(directory, { recursive: true, force: true }); + } + }, +); diff --git a/test/experiments/ffi-pty/windows-helper.test.mts b/test/experiments/ffi-pty/windows-helper.test.mts new file mode 100644 index 000000000..f5d8df8c5 --- /dev/null +++ b/test/experiments/ffi-pty/windows-helper.test.mts @@ -0,0 +1,24 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { + helperExecutablePath, + helperStartupEnv, +} from "../../../experiments/ffi-pty/windows-helper.mts"; + +test("helper process receives only startup environment variables", () => { + assert.deepEqual( + helperStartupEnv({ + SystemRoot: "C:\\Windows", + TEMP: "C:\\Temp", + PATH: "secret-path", + NODE_OPTIONS: "--inspect", + }), + { SystemRoot: "C:\\Windows", TEMP: "C:\\Temp" }, + ); +}); + +test("helper path is architecture-specific and rejects unsupported targets", () => { + assert.match(helperExecutablePath("x64"), /win32-x64[\\/]helper\.exe$/); + assert.match(helperExecutablePath("arm64"), /win32-arm64[\\/]helper\.exe$/); + assert.throws(() => helperExecutablePath("ia32"), /No Windows helper/); +}); diff --git a/test/experiments/ffi-pty/windows-launch.test.mts b/test/experiments/ffi-pty/windows-launch.test.mts new file mode 100644 index 000000000..03f11c2d1 --- /dev/null +++ b/test/experiments/ffi-pty/windows-launch.test.mts @@ -0,0 +1,55 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + encodeWindowsString, + prepareWindowsStart, +} from "../../../experiments/ffi-pty/windows-launch.mts"; +import type { SpawnOptions } from "../../../experiments/ffi-pty/contract.mts"; + +test("Windows strings are UTF-16LE terminated and reject embedded NUL", () => { + const encoded = encodeWindowsString("frog 🐸"); + assert.equal(encoded.toString("utf16le"), "frog 🐸\0"); + assert.equal(encoded.readUInt16LE(encoded.length - 2), 0); + assert.throws(() => encodeWindowsString("bad\0value"), /NUL/); +}); + +test("launch preparation validates dimensions before executable lookup", () => { + const options = { + file: "missing.exe", + args: [], + cols: 0, + rows: 24, + cwd: "C:\\work", + env: {}, + }; + assert.throws(() => prepareWindowsStart(options), /cols must be an integer/); +}); + +test( + "Windows launch data contains resolved executable, arguments, environment, and fresh pipes", + { skip: process.platform !== "win32" }, + () => { + const options: SpawnOptions = { + file: process.execPath, + args: ["-e", "console.log('ok')"], + cols: 101, + rows: 37, + cwd: process.cwd(), + env: Object.fromEntries( + Object.entries(process.env).filter( + (entry): entry is [string, string] => entry[1] !== undefined, + ), + ), + }; + const first = prepareWindowsStart(options); + const second = prepareWindowsStart(options); + assert.equal(first.cols, options.cols); + assert.equal(first.rows, options.rows); + assert.match(first.application.toString("utf16le"), /\.exe\0$/i); + assert.match(first.commandLine.toString("utf16le"), /console\.log\('ok'\)\0$/); + assert.equal(first.cwd.toString("utf16le"), `${options.cwd}\0`); + assert.ok(first.environment.toString("utf16le").endsWith("\0\0")); + assert.notEqual(first.inputName, second.inputName); + assert.notEqual(first.outputName, second.outputName); + }, +); diff --git a/test/experiments/ffi-pty/windows-parent-death-fixture.mts b/test/experiments/ffi-pty/windows-parent-death-fixture.mts new file mode 100644 index 000000000..c4f032043 --- /dev/null +++ b/test/experiments/ffi-pty/windows-parent-death-fixture.mts @@ -0,0 +1,25 @@ +import { createBackend } from "../../../experiments/ffi-pty/windows.mts"; + +const reportFile = process.argv[2]; +if (!reportFile) throw new Error("missing report file path"); +const script = ` + const { spawn } = require('node:child_process'); + const fs = require('node:fs'); + const descendant = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'inherit' }); + fs.writeFileSync(process.env.FFI_PTY_REPORT, JSON.stringify({ pid: process.pid, brokerPid: process.ppid, descendantPid: descendant.pid })); + setInterval(() => {}, 1000); +`; +const env = Object.fromEntries( + Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined), +); +env.FFI_PTY_REPORT = reportFile; +const backend = await createBackend({ + file: process.execPath, + args: ["-e", script], + cwd: process.cwd(), + env, + cols: 80, + rows: 24, +}); +backend.readable.resume(); +process.send?.({ type: "started", pid: backend.pid }); diff --git a/test/experiments/ffi-pty/windows-resource.test.mts b/test/experiments/ffi-pty/windows-resource.test.mts new file mode 100644 index 000000000..315683b73 --- /dev/null +++ b/test/experiments/ffi-pty/windows-resource.test.mts @@ -0,0 +1,85 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { setTimeout as delay } from "node:timers/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { createBackend } from "../../../experiments/ffi-pty/windows.mts"; +import { + getProcessHandleCount, + initializeWindowsBindings, +} from "../../../experiments/ffi-pty/windows-native.mts"; + +const supported = + process.platform === "win32" && (process.arch === "x64" || process.arch === "arm64"); +const options = (script: string) => ({ + file: process.execPath, + args: ["-e", script], + cwd: process.cwd(), + env: Object.fromEntries( + Object.entries(process.env).filter( + (entry): entry is [string, string] => entry[1] !== undefined, + ), + ), + cols: 80, + rows: 24, +}); +async function stableHandleCount() { + let previous = -1; + let repeated = 0; + const deadline = Date.now() + 3000; + const samples: number[] = []; + while (Date.now() < deadline) { + const count = getProcessHandleCount(); + samples.push(count); + repeated = count === previous ? repeated + 1 : 1; + if (repeated === 3) return count; + previous = count; + await delay(50); + } + assert.fail(`process handle count did not stabilize within 3s: ${samples}`); +} +async function waitForHandleCount(expected: number, phase: string) { + const deadline = Date.now() + 5000; + const samples: number[] = []; + let consecutive = 0; + while (Date.now() < deadline) { + const count = getProcessHandleCount(); + samples.push(count); + consecutive = count === expected ? consecutive + 1 : 0; + if (consecutive === 5) return; + await delay(100); + } + assert.fail( + `process handle count did not return to ${expected} after ${phase}: ${samples.join(",")}`, + ); +} +test( + "Windows backend releases process handles after normal, forced, and failed sessions", + { skip: !supported, timeout: 30000 }, + async () => { + initializeWindowsBindings(); + const warmup = await createBackend(options("process.exit(0)")); + warmup.readable.resume(); + await warmup.exited; + await warmup.close(); + + const baseline = await stableHandleCount(); + for (let index = 0; index < 3; index++) { + const natural = await createBackend(options("process.exit(0)")); + natural.readable.resume(); + await natural.exited; + await natural.close(); + await waitForHandleCount(baseline, `natural exit ${index}`); + + const forced = await createBackend(options("setInterval(() => {}, 1000)")); + forced.readable.resume(); + await forced.close(); + await waitForHandleCount(baseline, `forced close ${index}`); + + const missing = join(tmpdir(), `ffi-pty-missing-${process.pid}-${index}`); + await assert.rejects(createBackend({ ...options(""), cwd: missing })); + await waitForHandleCount(baseline, `failed startup ${index}`); + } + await waitForHandleCount(baseline, "all sessions"); + }, +); diff --git a/test/experiments/ffi-pty/windows-selection.test.mts b/test/experiments/ffi-pty/windows-selection.test.mts new file mode 100644 index 000000000..eada9d489 --- /dev/null +++ b/test/experiments/ffi-pty/windows-selection.test.mts @@ -0,0 +1,108 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + createWindowsTransport, + type WindowsSelectionDependencies, +} from "../../../experiments/ffi-pty/windows-selection.mts"; +import type { WindowsTransport } from "../../../experiments/ffi-pty/windows-transport.mts"; + +function transport(ready: Promise = Promise.resolve()) { + let terminated = 0; + const value: WindowsTransport = { + ready, + closed: Promise.resolve(), + async send() {}, + onMessage() { + return () => {}; + }, + onError() { + return () => {}; + }, + async terminate() { + terminated++; + }, + }; + return { + value, + get terminated() { + return terminated; + }, + }; +} + +function dependencies(overrides: Partial = {}) { + const node = transport(); + const helper = transport(); + const ffi = transport(); + const selected: string[] = []; + const deps: WindowsSelectionDependencies = { + async verifyHelper() { + return { kind: "node", reason: "unsigned" }; + }, + createNodeTransport() { + selected.push("node"); + return node.value; + }, + createHelperTransport() { + selected.push("helper"); + return helper.value; + }, + createFfiTransport() { + selected.push("ffi"); + return ffi.value; + }, + ...overrides, + }; + return { deps, node, helper, ffi, selected }; +} + +test("modern Windows selects direct FFI without checking helper trust", async () => { + const state = dependencies({ + async verifyHelper() { + throw new Error("should not inspect helper"); + }, + }); + assert.equal( + await createWindowsTransport({ major: 10, minor: 0, build: 26100 }, state.deps), + state.ffi.value, + ); + assert.deepEqual(state.selected, ["ffi"]); +}); + +test("affected Windows falls back to Node when no trusted helper is available", async () => { + const state = dependencies(); + assert.equal( + await createWindowsTransport({ major: 10, minor: 0, build: 22631 }, state.deps), + state.node.value, + ); + assert.deepEqual(state.selected, ["node"]); +}); + +test("affected Windows starts a verified helper at its locked path", async () => { + const state = dependencies({ + async verifyHelper() { + return { kind: "native", path: "locked.exe", subject: "CN=PTY" }; + }, + }); + assert.equal( + await createWindowsTransport({ major: 10, minor: 0, build: 22631 }, state.deps), + state.helper.value, + ); + assert.deepEqual(state.selected, ["helper"]); +}); + +test("helper startup failure terminates helper and falls back to Node", async () => { + const state = dependencies({ + async verifyHelper() { + return { kind: "native", path: "locked.exe", subject: "CN=PTY" }; + }, + createHelperTransport() { + return transport(Promise.reject(new Error("cannot start"))).value; + }, + }); + assert.equal( + await createWindowsTransport({ major: 10, minor: 0, build: 22631 }, state.deps), + state.node.value, + ); + assert.deepEqual(state.selected, ["node"]); +}); diff --git a/test/experiments/ffi-pty/windows-version.test.mts b/test/experiments/ffi-pty/windows-version.test.mts new file mode 100644 index 000000000..1abf7169f --- /dev/null +++ b/test/experiments/ffi-pty/windows-version.test.mts @@ -0,0 +1,48 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + classifyWindowsVersion, + detectWindowsVersion, + isValidWindowsVersion, + parseWindowsVersion, +} from "../../../experiments/ffi-pty/windows-version.mts"; + +test("parses Windows version strings and optional revision numbers", () => { + assert.deepEqual(parseWindowsVersion("10.0.22631"), { major: 10, minor: 0, build: 22631 }); + assert.deepEqual(parseWindowsVersion("10.0.26100.1"), { major: 10, minor: 0, build: 26100 }); + for (const invalid of ["", "Windows 11", "10.0", "10.x.26100", "10.0.4294967296"]) { + assert.throws(() => parseWindowsVersion(invalid), /Invalid Windows version/); + } +}); + +test("classifies Windows build boundaries for ConPTY and direct FFI", () => { + const cases = [ + [[10, 0, 17762], "unsupported"], + [[10, 0, 17763], "helper"], + [[10, 0, 22000], "helper"], + [[10, 0, 22621], "helper"], + [[10, 0, 22631], "helper"], + [[10, 0, 26099], "helper"], + [[10, 0, 26100], "ffi"], + [[10, 0, 26200], "ffi"], + [[10, 0, 20348], "helper"], + ] as const; + for (const [[major, minor, build], expected] of cases) { + assert.equal(classifyWindowsVersion({ major, minor, build }), expected, `build ${build}`); + } + assert.equal(classifyWindowsVersion({ major: 6, minor: 3, build: 9600 }), "unsupported"); +}); + +test("validates parsed Windows version fields", () => { + assert.equal(isValidWindowsVersion({ major: 10, minor: 0, build: 26100 }), true); + assert.equal(isValidWindowsVersion({ major: 10, minor: -1, build: 26100 }), false); + assert.equal(isValidWindowsVersion({ major: 10, minor: 0, build: Number.NaN }), false); + assert.throws( + () => classifyWindowsVersion({ major: 10, minor: 0, build: -1 }), + /Invalid Windows version fields/, + ); +}); + +test("version detection rejects calls away from Windows", () => { + assert.throws(() => detectWindowsVersion("linux"), /requires Windows/); +}); diff --git a/test/experiments/ffi-pty/windows.test.mts b/test/experiments/ffi-pty/windows.test.mts new file mode 100644 index 000000000..20a12e60b --- /dev/null +++ b/test/experiments/ffi-pty/windows.test.mts @@ -0,0 +1,277 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { setTimeout as delay } from "node:timers/promises"; +import { linkSync, mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { + createBackend, + dimensions, + windowsSignalNumber, +} from "../../../experiments/ffi-pty/windows.mts"; + +const supported = + process.platform === "win32" && (process.arch === "x64" || process.arch === "arm64"); +const options = (script: string, extra: Partial<{ cols: number; rows: number }> = {}) => ({ + file: process.execPath, + args: ["-e", script], + cwd: process.cwd(), + env: Object.fromEntries( + Object.entries(process.env).filter( + (entry): entry is [string, string] => entry[1] !== undefined, + ), + ), + cols: extra.cols ?? 80, + rows: extra.rows ?? 24, +}); + +async function collect(backend: Awaited>, timeoutMs = 10000) { + let text = ""; + const done = new Promise((resolve, reject) => { + const timer = setTimeout( + () => reject(new Error(`Timed out; output was ${JSON.stringify(text.slice(-500))}`)), + timeoutMs, + ); + backend.readable.setEncoding("utf8"); + backend.readable.on("data", (part: string) => { + text += part; + }); + backend.exited.then(() => { + clearTimeout(timer); + resolve(text); + }, reject); + }); + return done; +} +async function until( + backend: Awaited>, + pattern: RegExp, + timeoutMs = 5000, +) { + let text = ""; + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + cleanup(); + reject(new Error(`Timed out waiting for ${pattern}: ${text.slice(-300)}`)); + }, timeoutMs); + const onData = (part: Buffer) => { + text += part.toString(); + if (pattern.test(text)) { + cleanup(); + resolve(text); + } + }; + const onExit = () => { + cleanup(); + reject(new Error(`Process exited before ${pattern}: ${text.slice(-300)}`)); + }; + const cleanup = () => { + clearTimeout(timer); + backend.readable.off("data", onData); + }; + backend.readable.on("data", onData); + backend.exited.then(onExit, onExit); + }); +} + +async function waitForSize(file: string, expected: [number, number], timeoutMs = 5000) { + const deadline = Date.now() + timeoutMs; + while (Date.now() < deadline) { + try { + if (JSON.stringify(JSON.parse(readFileSync(file, "utf8"))) === JSON.stringify(expected)) + return; + } catch { + // The child may be midway through replacing the result file. + } + await delay(20); + } + throw new Error(`Timed out waiting for native console size ${expected}`); +} + +test( + "Windows ConPTY starts a Unicode executable, cwd, argument, and environment", + { skip: !supported, timeout: 30000 }, + async () => { + const directory = mkdtempSync(join(tmpdir(), "ffi-pty-🐸-")); + const executable = join(directory, "node 🐸.exe"); + linkSync(process.execPath, executable); + const env = { ...options("").env, FFI_MARK: "héllo" }; + let backend: Awaited> | undefined; + try { + backend = await createBackend({ + file: executable, + args: [ + "-e", + "console.log(JSON.stringify([process.cwd(), process.argv[1], process.env.FFI_MARK]))", + "café 🐸", + ], + cwd: directory, + env, + cols: 80, + rows: 24, + }); + const text = await collect(backend); + assert.match(text, /héllo/); + assert.match(text, /café 🐸/); + assert.ok(text.includes(JSON.stringify(directory))); + } finally { + await backend?.close(); + rmSync(directory, { recursive: true, force: true }); + } + }, +); + +test( + "Windows ConPTY resolves bare commands from the child PATH", + { skip: !supported, timeout: 30000 }, + async () => { + const env = Object.fromEntries( + Object.entries(options("").env).filter(([key]) => key.toUpperCase() !== "PATH"), + ); + env.Path = dirname(process.execPath); + const backend = await createBackend({ + ...options("console.log('PATH_OK')"), + file: "node", + env, + }); + try { + assert.match(await collect(backend), /PATH_OK/); + } finally { + await backend.close(); + } + }, +); + +test("resize updates the console dimensions", { skip: !supported, timeout: 30000 }, async () => { + const directory = mkdtempSync(join(tmpdir(), "ffi-pty-resize-")); + const sizeFile = join(directory, "size.json"); + const script = `const {dlopen}=require('node:ffi'); const {functions:k}=dlopen('kernel32.dll',{GetStdHandle:{arguments:['uint32'],return:'pointer'},GetConsoleScreenBufferInfo:{arguments:['pointer','pointer'],return:'int32'}}); const h=k.GetStdHandle(0xfffffff5); const b=Buffer.alloc(22); setInterval(()=>{if(k.GetConsoleScreenBufferInfo(h,b)){const s=[b.readInt16LE(14)-b.readInt16LE(10)+1,b.readInt16LE(16)-b.readInt16LE(12)+1];require('node:fs').writeFileSync(process.env.FFI_SIZE_FILE,JSON.stringify(s))}},30)`; + const child = options(script); + child.args = ["--experimental-ffi", "-e", script]; + child.env.FFI_SIZE_FILE = sizeFile; + let backend: Awaited> | undefined; + try { + backend = await createBackend(child); + await waitForSize(sizeFile, [80, 24]); + await backend.resize(107, 39); + await waitForSize(sizeFile, [107, 39]); + } finally { + await backend?.close(); + rmSync(directory, { recursive: true, force: true }); + } +}); + +test( + "large output and input flow through asynchronous pipe sockets", + { skip: !supported, timeout: 30000 }, + async () => { + const backend = await createBackend( + options( + "process.stdin.once('data', () => process.stdout.write('x'.repeat(12 * 1024 * 1024), () => process.exit(0)))", + ), + ); + try { + backend.readable.pause(); + await backend.write(Buffer.from("go\r")); + await delay(100); + backend.readable.resume(); + const textPromise = collect(backend, 20000); + const text = await textPromise; + assert.ok(Buffer.byteLength(text) >= 12 * 1024 * 1024); + } finally { + await backend.close(); + } + }, +); + +test( + "close drains ConPTY output while the readable stream is paused", + { skip: !supported, timeout: 30000 }, + async () => { + const backend = await createBackend( + options( + "process.stdin.once('data', () => process.stdout.write('x'.repeat(12 * 1024 * 1024), () => process.exit(0)))", + ), + ); + backend.readable.pause(); + await backend.write(Buffer.from("go\r")); + await delay(100); + try { + await backend.close(); + await backend.exited; + } finally { + await backend.close(); + } + }, +); + +test( + "raw UTF-8 input reaches a Windows console child unchanged", + { skip: !supported, timeout: 30000 }, + async () => { + const script = + "if (typeof process.stdin.setRawMode !== 'function') { process.stdout.write('RAW_UNSUPPORTED'); process.exit(31); } process.stdin.setRawMode(true); process.stdin.setEncoding('utf8'); process.stdin.once('data', (text) => process.stdout.write('RAW_TEXT:' + text, () => process.exit(0))); process.stdout.write('RAW_READY:function\\r\\n')"; + const backend = await createBackend(options(script)); + try { + assert.match(await until(backend, /RAW_READY:/), /RAW_READY:function/); + await backend.write(Buffer.from("🐸")); + assert.match(await collect(backend), /RAW_TEXT:🐸/); + } finally { + await backend.close(); + } + }, +); + +test( + "termination reports the requested Windows signal and rejects unsupported signals", + { skip: !supported, timeout: 30000 }, + async () => { + const backend = await createBackend(options("setInterval(() => {}, 1000)")); + try { + backend.readable.resume(); + await assert.rejects(backend.kill("SIGINT"), /Unsupported Windows termination signal/); + await backend.kill("SIGTERM"); + assert.deepEqual(await backend.exited, { exitCode: null, signal: 15 }); + } finally { + await backend.close(); + } + }, +); + +test("dimensions and Windows signal names validate consistently", () => { + assert.doesNotThrow(() => dimensions(80, 24)); + assert.throws(() => dimensions(0, 24), /cols must be an integer/); + assert.equal(windowsSignalNumber("sigterm"), 15); + assert.equal(windowsSignalNumber("SIGKILL"), 9); + assert.throws(() => windowsSignalNumber("SIGINT"), /Unsupported/); +}); + +test( + "two sessions run independently and report natural exit codes", + { skip: !supported, timeout: 30000 }, + async () => { + const [first, second] = await Promise.all([ + createBackend(options("console.log('FIRST'); process.exit(7)")), + createBackend(options("console.log('SECOND'); process.exit(9)")), + ]); + try { + const [a, b] = await Promise.all([collect(first), collect(second)]); + assert.match(a, /FIRST/); + assert.match(b, /SECOND/); + assert.equal((await first.exited).exitCode, 7); + assert.equal((await second.exited).exitCode, 9); + } finally { + await Promise.all([first.close(), second.close()]); + } + }, +); + +test( + "invalid executable and arguments reject without hanging", + { skip: !supported, timeout: 30000 }, + async () => { + await assert.rejects(createBackend({ ...options(""), file: "Z:\\missing\\program.exe" })); + await assert.rejects(createBackend(options("", { cols: 0 })), /cols must be an integer/); + await assert.rejects(createBackend({ ...options(""), args: ["bad\0arg"] }), /NUL/); + }, +);