diff --git a/src/application/FilesystemSnapshot.test.ts b/src/application/FilesystemSnapshot.test.ts new file mode 100644 index 000000000..3725fc149 --- /dev/null +++ b/src/application/FilesystemSnapshot.test.ts @@ -0,0 +1,122 @@ +import { fstatSync } from "node:fs"; +import { + mkdtemp, + lstat, + open, + readdir, + rm, + utimes, + writeFile, +} from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { expect, it } from "vitest"; + +import { hashFile } from "./FilesystemSnapshot.js"; + +const countOpenDescriptorsFor = async (path: string): Promise => { + const directory = process.platform === "linux" ? "/proc/self/fd" : "/dev/fd"; + const expected = await lstat(path); + const descriptors = await readdir(directory); + const matches = await Promise.all( + descriptors.map(async (descriptor) => { + if (!/^\d+$/u.test(descriptor)) return false; + try { + const stats = fstatSync(Number(descriptor)); + return stats.dev === expected.dev && stats.ino === expected.ino; + } catch (cause: unknown) { + if (cause instanceof Error && "code" in cause && cause.code === "EBADF") + return false; + throw cause; + } + }), + ); + return matches.filter(Boolean).length; +}; + +it("does not hash a replacement file using the earlier path metadata", async () => { + const directory = await mkdtemp(join(tmpdir(), "rea-snapshot-identity-")); + const path = join(directory, "observed-file"); + try { + await writeFile(path, "captured file\n"); + const expected = await lstat(path); + await rm(path); + await writeFile(path, "replacement with a different identity and size\n"); + + await expect(hashFile(path, expected, 1_000)).resolves.toBeNull(); + } finally { + await rm(directory, { recursive: true, force: true }); + } +}); + +it("rejects a same-size rewrite even when its modification time is restored", async () => { + const directory = await mkdtemp(join(tmpdir(), "rea-snapshot-ctime-")); + const path = join(directory, "observed-file"); + try { + const fixedMtime = new Date("2020-01-02T03:04:05.000Z"); + await writeFile(path, "before\n"); + await utimes(path, fixedMtime, fixedMtime); + const expected = await lstat(path); + await writeFile(path, "after!\n"); + await utimes(path, fixedMtime, fixedMtime); + const rewritten = await lstat(path); + + expect(rewritten).toMatchObject({ + dev: expected.dev, + ino: expected.ino, + mode: expected.mode, + size: expected.size, + mtimeMs: expected.mtimeMs, + }); + expect(rewritten.ctimeMs).not.toBe(expected.ctimeMs); + + await expect(hashFile(path, expected, 1_000)).resolves.toBeNull(); + } finally { + await rm(directory, { recursive: true, force: true }); + } +}); + +it("rejects cancellation for an empty file before returning its digest", async () => { + const directory = await mkdtemp(join(tmpdir(), "rea-snapshot-empty-cancel-")); + const path = join(directory, "observed-file"); + try { + await writeFile(path, ""); + const expected = await lstat(path); + const controller = new AbortController(); + controller.abort(); + + await expect( + hashFile(path, expected, 1_000, controller.signal), + ).rejects.toMatchObject({ name: "AbortError" }); + } finally { + await rm(directory, { recursive: true, force: true }); + } +}); + +it.skipIf(process.platform === "win32")( + "closes the opened file when cancellation arrives during open", + async () => { + const directory = await mkdtemp(join(tmpdir(), "rea-snapshot-cancel-")); + const path = join(directory, "observed-file"); + try { + await writeFile(path, "captured file\n"); + const expected = await lstat(path); + const controller = new AbortController(); + const held = await open(path, "r"); + expect(await countOpenDescriptorsFor(path)).toBe(1); + await held.close(); + expect(await countOpenDescriptorsFor(path)).toBe(0); + const hashing = hashFile(path, expected, 1_000, controller.signal); + // hashFile reaches `open` synchronously before its first suspension, so + // this abort is observed after the descriptor is acquired and is handled + // by the `finally` close path. + controller.abort(); + + await expect(hashing).rejects.toMatchObject({ name: "AbortError" }); + expect(await countOpenDescriptorsFor(path)).toBe(0); + } finally { + await rm(directory, { recursive: true, force: true }); + } + }, +); diff --git a/src/application/FilesystemSnapshot.ts b/src/application/FilesystemSnapshot.ts index 246497d4a..4fbfe8c94 100644 --- a/src/application/FilesystemSnapshot.ts +++ b/src/application/FilesystemSnapshot.ts @@ -19,6 +19,16 @@ const hasSameIdentity = ( before.ino === after.ino && (expected === "directory" ? after.isDirectory() : after.isSymbolicLink()); +const hasSameFileState = (before: Stats, after: Stats): boolean => + before.dev === after.dev && + before.ino === after.ino && + before.isFile() && + after.isFile() && + before.mode === after.mode && + before.size === after.size && + before.mtimeMs === after.mtimeMs && + before.ctimeMs === after.ctimeMs; + const lstatIfPresent = async (path: string): Promise => { try { return await lstat(path); @@ -29,18 +39,26 @@ const lstatIfPresent = async (path: string): Promise => { } }; -const hashFile = async ( +/** Hash a file only when its opened descriptor still matches the captured path state. */ +export const hashFile = async ( path: string, + expected: Stats, maxBytes: number, signal?: AbortSignal, ): Promise => { + signal?.throwIfAborted(); const handle = await open( path, - fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0), + fsConstants.O_RDONLY | + (fsConstants.O_NOFOLLOW ?? 0) | + (fsConstants.O_NONBLOCK ?? 0), ); try { + signal?.throwIfAborted(); const stats = await handle.stat(); - if (!stats.isFile() || stats.size > maxBytes) return null; + signal?.throwIfAborted(); + if (!hasSameFileState(expected, stats) || stats.size > maxBytes) + return null; const hash = createHash("sha256"); const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes)); let position = 0; @@ -57,8 +75,8 @@ const hashFile = async ( position += bytesRead; } const after = await handle.stat(); - if (after.size !== stats.size || after.mtimeMs !== stats.mtimeMs) - return null; + signal?.throwIfAborted(); + if (!hasSameFileState(stats, after)) return null; return hash.digest("hex"); } finally { await handle.close(); @@ -110,7 +128,7 @@ export const snapshotRoots = async ( if (stats.isFile()) { const sha256 = remainingBytes >= stats.size - ? await hashFile(path, remainingBytes, signal) + ? await hashFile(path, stats, remainingBytes, signal) : null; remainingBytes -= sha256 === null ? 0 : stats.size; if (sha256 === null) truncated = true; diff --git a/src/application/ProcessCaptureLifecycle.ts b/src/application/ProcessCaptureLifecycle.ts index 1ea4b47e9..5810f5461 100644 --- a/src/application/ProcessCaptureLifecycle.ts +++ b/src/application/ProcessCaptureLifecycle.ts @@ -449,6 +449,7 @@ export const resolveProcessResult = ( export const prepareProcessCapture = async ( scenario: ProcessScenario, signal: AbortSignal | undefined, + captureSnapshot: typeof snapshotRoots = snapshotRoots, host: ProcessPreparationHost = systemProcessPreparationHost, ): Promise<{ readonly temporaryRoot: string; @@ -456,7 +457,7 @@ export const prepareProcessCapture = async ( readonly before: SnapshotResult; }> => { assertNotCancelled(signal); - const before = await snapshotRoots(scenario, signal); + const before = await captureSnapshot(scenario, signal); const temporaryRoot = await host.createTemporaryRoot(); try { const runId = randomUUID(); diff --git a/src/application/ProcessHarness.ts b/src/application/ProcessHarness.ts index 822f8f989..94609cc8e 100644 --- a/src/application/ProcessHarness.ts +++ b/src/application/ProcessHarness.ts @@ -233,6 +233,20 @@ const finishProcessRun = async (options: { ); }; +const normalizeCaptureFailure = ( + cause: unknown, + signal: AbortSignal | undefined, +): unknown => { + if (cause instanceof ProcessCaptureError) return cause; + if ( + signal?.aborted === true && + (cause === signal.reason || + (cause instanceof Error && cause.name === "AbortError")) + ) + return processCaptureCancelled(); + return cause; +}; + const completeCapture = async (options: { readonly scenario: ProcessScenario; readonly hostPlatform: NodeJS.Platform; @@ -245,6 +259,7 @@ const completeCapture = async (options: { readonly interactions: readonly InteractionEvent[]; readonly exit: Awaited>; readonly signal?: AbortSignal; + readonly captureSnapshot: typeof snapshotRoots; readonly initiallyTruncated: boolean; readonly eventJournal: readonly ProcessCaptureEventJournalEntry[]; readonly recordEvent: RecordProcessCaptureEvent; @@ -262,7 +277,7 @@ const completeCapture = async (options: { const samplingPartial = (await runtime.stopSampler()).partial; await settleProcessCaptureJournal(options.eventJournal); assertNotCancelled(options.signal); - const after = await snapshotRoots(scenario, options.signal); + const after = await options.captureSnapshot(scenario, options.signal); options.recordEvent("filesystem_checkpoints", 1); const renderedFrames = await runtime.renderer.frames(); const checkpoints: UnverifiedProcessCapture["filesystem_checkpoints"] = [ @@ -319,10 +334,12 @@ const runProcessScenario = async ( signal?: AbortSignal, hostEnvironment: Readonly> = process.env, hostPlatform: NodeJS.Platform = process.platform, + captureSnapshot: typeof snapshotRoots = snapshotRoots, ): Promise => { const { temporaryRoot, runId, before } = await prepareProcessCapture( scenario, signal, + captureSnapshot, ); const frames: TerminalFrame[] = []; const samples: ProcessSample[] = []; @@ -377,11 +394,12 @@ const runProcessScenario = async ( initiallyTruncated: before.truncated, eventJournal, recordEvent, + captureSnapshot, ...(signal === undefined ? {} : { signal }), }); } catch (cause: unknown) { runtime?.terminal.kill("SIGKILL"); - executionFailure = cause; + executionFailure = normalizeCaptureFailure(cause, signal); } return finishProcessRun({ runtime, @@ -401,6 +419,7 @@ export const captureProcessScenario = async ( signal?: AbortSignal, platform: NodeJS.Platform = process.platform, environment: Readonly> = process.env, + captureSnapshot: typeof snapshotRoots = snapshotRoots, ): Promise> => { const ownershipReason = processCaptureOwnershipUnavailableReason(platform); if (ownershipReason !== undefined) @@ -419,12 +438,19 @@ export const captureProcessScenario = async ( environment, ); return ok( - await runProcessScenario(resolvedScenario, signal, environment, platform), + await runProcessScenario( + resolvedScenario, + signal, + environment, + platform, + captureSnapshot, + ), ); } catch (cause: unknown) { + const failure = normalizeCaptureFailure(cause, signal); return err( - cause instanceof ProcessCaptureError - ? cause + failure instanceof ProcessCaptureError + ? failure : new ProcessCaptureError("process capture failed", { cause }), ); } diff --git a/tests/boundary/process/filesystemSnapshotFifoRace.test.ts b/tests/boundary/process/filesystemSnapshotFifoRace.test.ts new file mode 100644 index 000000000..14d0f77cb --- /dev/null +++ b/tests/boundary/process/filesystemSnapshotFifoRace.test.ts @@ -0,0 +1,54 @@ +import { randomUUID } from "node:crypto"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { expect, it } from "vitest"; + +import { + ProviderProcessSupervisor, + spawnOwnedProviderProcess, +} from "../../../src/process/ProviderProcess.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +it.skipIf(process.platform === "win32")( + "does not block when an observed regular file is replaced by a FIFO", + async () => { + const directory = await createTestTempDirectory("rea-snapshot-fifo-"); + const probe = fileURLToPath( + new URL( + "../../fixtures/filesystemSnapshotFifoProbe.mjs", + import.meta.url, + ), + ); + const snapshotModule = fileURLToPath( + new URL( + "../../../dist/application/FilesystemSnapshot.js", + import.meta.url, + ), + ); + const launch = await spawnOwnedProviderProcess({ + command: process.execPath, + arguments: [probe, snapshotModule, directory], + runId: `rea-snapshot-fifo-${randomUUID()}`, + cwd: tmpdir(), + hostEnvironment: process.env, + }); + const supervisor = new ProviderProcessSupervisor({ + ...launch, + ownsProcessLifetime: true, + }); + + try { + const closed = await supervisor.waitForOutputClose(2_000); + expect(closed).toBe(true); + expect(supervisor.snapshot().stdout.text.trim()).toBe("rejected"); + } finally { + const stopped = await supervisor.stop({ + terminationGraceMs: 100, + killGraceMs: 500, + }); + expect(stopped.status).not.toBe("incomplete"); + } + }, +); diff --git a/tests/boundary/process/processCaptureLifecycle.test.ts b/tests/boundary/process/processCaptureLifecycle.test.ts index 6e16c4524..23e1df4d4 100644 --- a/tests/boundary/process/processCaptureLifecycle.test.ts +++ b/tests/boundary/process/processCaptureLifecycle.test.ts @@ -1,5 +1,5 @@ import { execFile } from "node:child_process"; -import { rm, symlink } from "node:fs/promises"; +import { rm, symlink, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { promisify } from "node:util"; @@ -8,11 +8,15 @@ import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { itWithCaptureCapability } from "./processCaptureCapability.js"; import { captureProcessScenario } from "../../../src/application/ProcessHarness.js"; +import { snapshotRoots } from "../../../src/application/FilesystemSnapshot.js"; import { parseProcessScenario } from "../../../src/domain/processCapture.js"; const processFixture = fileURLToPath( new URL("../../fixtures/processFidelity.mjs", import.meta.url), ); +const snapshotCancellationFixture = fileURLToPath( + new URL("../../fixtures/processSnapshotCancellation.mjs", import.meta.url), +); const execFileAsync = promisify(execFile); itWithCaptureCapability( @@ -83,6 +87,114 @@ itWithCaptureCapability( }, ); +itWithCaptureCapability( + "classifies cancellation raised by the initial filesystem snapshot", + async () => { + const root = await createTestTempDirectory("rea-snapshot-initial-cancel-"); + const path = join(root, "input"); + await writeFile(path, "observed\n"); + const controller = new AbortController(); + const { signal } = controller; + const throwIfAborted = signal.throwIfAborted.bind(signal); + Object.defineProperty(signal, "throwIfAborted", { + value: () => { + controller.abort(); + throwIfAborted(); + }, + }); + + const result = await captureProcessScenario( + parseProcessScenario({ + executable: process.execPath, + working_directory: root, + filesystem_observation_paths: [path], + }), + signal, + ); + + expect(result.ok).toBe(false); + if (result.ok) throw new Error("expected initial snapshot cancellation"); + expect(result.error).toMatchObject({ + reason: "cancelled", + userCategory: "cancelled", + }); + }, +); + +itWithCaptureCapability( + "classifies cancellation raised by the final filesystem snapshot", + async () => { + const root = await createTestTempDirectory("rea-snapshot-final-cancel-"); + const controller = new AbortController(); + let initialSnapshotCompleted = false; + const captureSnapshot: typeof snapshotRoots = async (scenario, signal) => { + if (initialSnapshotCompleted) controller.abort(); + const snapshot = await snapshotRoots(scenario, signal); + initialSnapshotCompleted = true; + return snapshot; + }; + const resultPromise = captureProcessScenario( + parseProcessScenario({ + executable: process.execPath, + arguments: [snapshotCancellationFixture, root], + working_directory: dirname(snapshotCancellationFixture), + filesystem_observation_paths: [root], + settle_ms: 0, + }), + controller.signal, + process.platform, + process.env, + captureSnapshot, + ); + + const result = await resultPromise; + expect(result.ok).toBe(false); + if (result.ok) throw new Error("expected final snapshot cancellation"); + expect(initialSnapshotCompleted).toBe(true); + expect(result.error).toMatchObject({ + reason: "cancelled", + userCategory: "cancelled", + }); + }, +); + +itWithCaptureCapability( + "preserves filesystem errors that are not caller cancellation", + async () => { + const root = await createTestTempDirectory("rea-snapshot-io-error-"); + const obstruction = join(root, "not-a-directory"); + await writeFile(obstruction, "file"); + const controller = new AbortController(); + const captureSnapshot: typeof snapshotRoots = async (scenario, signal) => { + try { + return await snapshotRoots(scenario, signal); + } catch (cause: unknown) { + controller.abort(); + throw cause; + } + }; + + const result = await captureProcessScenario( + parseProcessScenario({ + executable: process.execPath, + working_directory: root, + filesystem_observation_paths: [join(obstruction, "child")], + }), + controller.signal, + process.platform, + process.env, + captureSnapshot, + ); + + expect(result.ok).toBe(false); + if (result.ok) throw new Error("expected filesystem observation failure"); + expect(result.error).toMatchObject({ + reason: "capture_failed", + cause: { code: "ENOTDIR" }, + }); + }, +); + itWithCaptureCapability( "captures input, Unicode, and resize across PTY startup", async () => { diff --git a/tests/fixtures/filesystemSnapshotFifoProbe.mjs b/tests/fixtures/filesystemSnapshotFifoProbe.mjs new file mode 100644 index 000000000..de3e466b3 --- /dev/null +++ b/tests/fixtures/filesystemSnapshotFifoProbe.mjs @@ -0,0 +1,23 @@ +import { execFileSync } from "node:child_process"; +import { lstat, unlink, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { pathToFileURL } from "node:url"; + +const [snapshotModulePath, directory] = process.argv.slice(2); +if (snapshotModulePath === undefined || directory === undefined) + throw new Error( + "Filesystem snapshot FIFO probe requires a module path and directory", + ); + +const { hashFile } = await import(pathToFileURL(snapshotModulePath)); +const path = join(directory, "observed-file"); +await writeFile(path, "regular file\n"); +const expected = await lstat(path); +await unlink(path); +execFileSync("mkfifo", [path]); +// This invokes the production lstat-to-open hashing seam with a known captured +// regular-file identity. The owner test bounds this child so an O_RDONLY FIFO +// regression cannot hang Vitest. +const digest = await hashFile(path, expected, 1_000); +if (digest !== null) throw new Error("Expected the FIFO to be rejected"); +process.stdout.write("rejected\n"); diff --git a/tests/fixtures/processSnapshotCancellation.mjs b/tests/fixtures/processSnapshotCancellation.mjs new file mode 100644 index 000000000..6da752d82 --- /dev/null +++ b/tests/fixtures/processSnapshotCancellation.mjs @@ -0,0 +1,8 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +const [root] = process.argv.slice(2); +if (root === undefined) + throw new Error("Snapshot cancellation fixture requires an observation root"); + +await writeFile(join(root, "created-after-start"), "x");