diff --git a/src/reference/ReferenceSourceReader.ts b/src/reference/ReferenceSourceReader.ts index 96bc879f52..58d3284e74 100644 --- a/src/reference/ReferenceSourceReader.ts +++ b/src/reference/ReferenceSourceReader.ts @@ -4,7 +4,11 @@ import { ArtifactReaderFailure, type ArtifactResourceScope, } from "../resources/index.js"; -import { traverseDirectory } from "./ReferenceSourceReaderEntries.js"; +import { + prefetchDirectoryValidations, + settleDirectoryAdmissions, + traverseDirectory, +} from "./ReferenceSourceReaderEntries.js"; import type { ReferenceSourceReaderOptions, ReferenceSourceRead, @@ -76,6 +80,8 @@ const readSource = async ( entries: [], exclusions: [], pending: [{ path: canonicalRoot }], + settling: [], + openingLookups: 0, bytesRead: 0, }; const traversal = await traverse(state); @@ -117,12 +123,30 @@ const readSource = async ( const traverse = async ( state: TraversalState, ): Promise> => { - while (state.pending.length > 0) { - if (isAborted(state.signal)) return err(cancelled(state.signal)); - const current = state.pending.pop(); - if (current === undefined) break; - const result = await traverseDirectory(state, current); - if (!result.ok) return result; + try { + while (state.pending.length > 0) { + if (isAborted(state.signal)) { + await settleDirectoryAdmissions(state); + return err(cancelled(state.signal)); + } + prefetchDirectoryValidations(state); + const current = state.pending.pop(); + if (current === undefined) break; + const result = await traverseDirectory(state, current); + if (!result.ok) { + await settleDirectoryAdmissions(state); + return result; + } + } + await settleDirectoryAdmissions(state); + return isAborted(state.signal) + ? err(cancelled(state.signal)) + : ok(undefined); + } finally { + // No observation started ahead of its turn outlives the read. + await Promise.allSettled([ + ...state.settling, + ...state.pending.flatMap(({ validation }) => validation ?? []), + ]); } - return ok(undefined); }; diff --git a/src/reference/ReferenceSourceReaderEntries.ts b/src/reference/ReferenceSourceReaderEntries.ts index 4cd8ab3d36..a269013cb2 100644 --- a/src/reference/ReferenceSourceReaderEntries.ts +++ b/src/reference/ReferenceSourceReaderEntries.ts @@ -64,16 +64,64 @@ const recordDirectoryFailure = ( ); }; +/** + * How many identity observations run ahead of their turn: the next pending + * directories' opening admissions, the metadata of the next listed names + * within a directory, and the closing admissions of directories already + * enumerated. Each is a read-only lookup. Callbacks run and the first error + * is returned in traversal order, every started lookup settles before the + * read returns, and the inventory is sorted; only the syscalls overlap. + * Measured on macOS (#11365), 4 gives the gain of 8, 16 and 32: libuv runs + * four filesystem calls at once by default. + */ +const OBSERVATION_WINDOW = 4; + +/** A started observation stays handled until its turn consumes it. */ +const ahead = (observation: Promise): Promise => { + observation.catch(() => undefined); + return observation; +}; + +/** + * Start identity admission for the directories traversal pops next. Children + * pushed later bury older siblings whose lookups may still run, so the count + * of running lookups, not only the stack positions, is bounded. + */ +export const prefetchDirectoryValidations = (state: TraversalState): void => { + const { pending } = state; + for ( + let index = pending.length - 1; + index >= Math.max(0, pending.length - OBSERVATION_WINDOW) && + state.openingLookups < OBSERVATION_WINDOW; + index -= 1 + ) { + const directory = pending[index]!; + if (directory.validation !== undefined) continue; + state.openingLookups += 1; + directory.validation = ahead( + validateDirectory( + state.root, + state.rootIdentity, + directory.path, + state.signal, + ).finally(() => { + state.openingLookups -= 1; + }), + ); + } +}; + export const traverseDirectory = async ( state: TraversalState, current: PendingDirectory, ): Promise> => { - const before = await validateDirectory( - state.root, - state.rootIdentity, - current.path, - state.signal, - ); + const before = await (current.validation ?? + validateDirectory( + state.root, + state.rootIdentity, + current.path, + state.signal, + )); if (!before.ok) { recordDirectoryFailure( state, @@ -121,6 +169,17 @@ export const traverseDirectory = async ( const owner = new OwnedDirectoryHandle(handle); let result: ReferenceSourceResult = ok(undefined); let cleanup: ArtifactCleanupAttempt; + // Names listed ahead of processing, each with its metadata lookup started. + const listed: { readonly name: string; readonly metadata: Metadata }[] = []; + let listingComplete = false; + // A listing failure takes effect after the names listed before it, as if + // each had been processed before the next read. + let listingFailure: + | { + readonly detail: FilesystemFailureDetail; + readonly cause?: { readonly value: unknown }; + } + | undefined; try { // A directory that cannot be opened retains its ordinary partial-entry // failure; only an opened directory needs policy before enumeration. @@ -132,32 +191,60 @@ export const traverseDirectory = async ( if (result.ok && isAborted(state.signal)) result = err(cancelled(state.signal)); while (result.ok) { - let child: Dirent | null; - try { - child = await handle.read(); - } catch (cause: unknown) { - readFailureCause = { value: cause }; - if (current.path === state.root) - state.rootFailureCause = readFailureCause; - readFailure = recordReadFailure(directoryReadFailure(cause)); - break; - } - if (child === null) break; - if (!Buffer.isBuffer(child.name)) { - readFailure = recordReadFailure({ - message: "Directory entry name was not returned as raw bytes", + while (!listingComplete && listed.length < OBSERVATION_WINDOW) { + let child: Dirent | null; + try { + child = await handle.read(); + } catch (cause: unknown) { + listingFailure = { + detail: directoryReadFailure(cause), + cause: { value: cause }, + }; + listingComplete = true; + break; + } + if (child === null) { + listingComplete = true; + break; + } + if (!Buffer.isBuffer(child.name)) { + listingFailure = { + detail: { + message: "Directory entry name was not returned as raw bytes", + }, + }; + listingComplete = true; + break; + } + const decoded = decodeDirectoryEntryName(child.name); + if (decoded.kind === "unrepresentable") { + unrepresentableNameCount += 1; + firstUnrepresentableNameHex ??= decoded.rawHex; + continue; + } + listed.push({ + name: decoded.name, + metadata: ahead(readMetadata(join(current.path, decoded.name))), }); - break; } - const decoded = decodeDirectoryEntryName(child.name); - if (decoded.kind === "unrepresentable") { - unrepresentableNameCount += 1; - firstUnrepresentableNameHex ??= decoded.rawHex; - continue; - } - result = await processEntry(state, current, decoded.name, directories); + const next = listed.shift(); + if (next === undefined) break; + result = await processEntry( + state, + current, + next.name, + next.metadata, + directories, + ); + } + if (result.ok && listingFailure !== undefined) { + readFailureCause = listingFailure.cause; + if (current.path === state.root && readFailureCause !== undefined) + state.rootFailureCause = readFailureCause; + readFailure = recordReadFailure(listingFailure.detail); } } finally { + await Promise.allSettled(listed.map(({ metadata }) => metadata)); cleanup = await state.resources.release({ kind: "directory-handle", handle: owner, @@ -216,41 +303,53 @@ export const traverseDirectory = async ( : ok(undefined); } if (isAborted(state.signal)) return err(cancelled(state.signal)); - const after = await validateDirectory( + // The closing admission decides only this directory's own record; its + // children are scheduled either way, so traversal continues while it runs. + const settled = validateDirectory( state.root, state.rootIdentity, current.path, state.signal, - ); - if (!after.ok || !sameFile(before.stats, after.stats)) { - recordDirectoryFailure( - state, - current.path, - after.ok ? "changed" : after.code, - after.ok ? "Directory changed while it was read" : after.message, - after.ok ? undefined : after.localDiagnostic, - ); - scheduleObservedDirectories(state, directories); - return isAborted(state.signal) - ? err(cancelled(state.signal)) - : ok(undefined); - } - if (isAborted(state.signal)) return err(cancelled(state.signal)); - if (unrepresentableNameCount > 0) { - recordDirectoryFailure( - state, - current.path, - "unsupported", - `Directory contains ${String(unrepresentableNameCount)} entry name(s) that are not valid UTF-8; no filesystem operations were performed for them. First raw basename bytes: ${firstUnrepresentableNameHex ?? "unknown"}.`, - ); - } else if (current.path !== state.root) - state.entries.push({ - status: "read", - kind: "directory", - path: pathFromRoot(state.root, current.path), - }); + ).then((after) => { + if (!after.ok || !sameFile(before.stats, after.stats)) + recordDirectoryFailure( + state, + current.path, + after.ok ? "changed" : after.code, + after.ok ? "Directory changed while it was read" : after.message, + after.ok ? undefined : after.localDiagnostic, + ); + else if (isAborted(state.signal)) return; + else if (unrepresentableNameCount > 0) + recordDirectoryFailure( + state, + current.path, + "unsupported", + `Directory contains ${String(unrepresentableNameCount)} entry name(s) that are not valid UTF-8; no filesystem operations were performed for them. First raw basename bytes: ${firstUnrepresentableNameHex ?? "unknown"}.`, + ); + else if (current.path !== state.root) + state.entries.push({ + status: "read", + kind: "directory", + path: pathFromRoot(state.root, current.path), + }); + }); scheduleObservedDirectories(state, directories); - return { ok: true, value: undefined }; + state.settling.push(ahead(settled)); + if (state.settling.length > OBSERVATION_WINDOW) await state.settling.shift(); + return ok(undefined); +}; + +/** + * Wait for every directory's closing admission. One that threw precedes, in + * traversal order, any result returned after it, so its throw wins. + */ +export const settleDirectoryAdmissions = async ( + state: TraversalState, +): Promise => { + const settled = await Promise.allSettled(state.settling.splice(0)); + const thrown = settled.find((outcome) => outcome.status === "rejected"); + if (thrown !== undefined) throw thrown.reason; }; const scheduleObservedDirectories = ( @@ -266,12 +365,13 @@ const directoryReadFailure = (cause: unknown): FilesystemFailureDetail => { return detail; }; -const readMetadata = async ( - path: string, -): Promise< +/** One entry's no-follow metadata lookup, started when its name was listed. */ +type Metadata = Promise< | { readonly ok: true; readonly value: BigIntStats } | ({ readonly ok: false } & FilesystemFailureDetail) -> => { +>; + +const readMetadata = async (path: string): Metadata => { try { return { ok: true, value: await bigLstat(path) }; } catch (cause: unknown) { @@ -288,13 +388,14 @@ const processEntry = async ( state: TraversalState, current: PendingDirectory, name: string, + metadataLookup: Metadata, directories: PendingDirectory[], ): Promise> => { - if (isAborted(state.signal)) - return { ok: false, error: cancelled(state.signal) }; const absolute = join(current.path, name); const path = pathFromRoot(state.root, absolute); - const metadata = await readMetadata(absolute); + // The lookup started when the name was listed; a failure it observed is + // retained even if cancellation arrived meanwhile. + const metadata = await metadataLookup; if (!metadata.ok) { const excluded = applyExclusion(state.shouldExclude, path, "unknown"); if (!excluded.ok) diff --git a/src/reference/ReferenceSourceReaderTraversal.ts b/src/reference/ReferenceSourceReaderTraversal.ts index 2321ce1747..55a6493974 100644 --- a/src/reference/ReferenceSourceReaderTraversal.ts +++ b/src/reference/ReferenceSourceReaderTraversal.ts @@ -7,10 +7,16 @@ import type { ReferenceSourceResult, ReferenceSourceRootFailure, } from "./ReferenceSourceReaderTypes.js"; +import type { DirectoryValidation } from "./ReferenceSourceReaderValidate.js"; /** Traversal state private to the reader; not part of its contract. */ export type PendingDirectory = { readonly path: string; + /** + * Identity admission started ahead of this directory's turn. It is an + * observation only; traversal consumes it in its original order. + */ + validation?: Promise; }; export type TraversalState = { @@ -32,6 +38,10 @@ export type TraversalState = { readonly kind: ReferenceSourceExclusionKind; }>; readonly pending: PendingDirectory[]; + /** Closing admissions of enumerated directories, oldest first. */ + readonly settling: Promise[]; + /** Opening admissions started ahead of their turn and still running. */ + openingLookups: number; rootFailure?: ReferenceSourceRootFailure; rootFailureCause?: { readonly value: unknown }; bytesRead: number; diff --git a/src/reference/ReferenceSourceReaderValidate.ts b/src/reference/ReferenceSourceReaderValidate.ts index b0b36ebe9d..63a08f2e40 100644 --- a/src/reference/ReferenceSourceReaderValidate.ts +++ b/src/reference/ReferenceSourceReaderValidate.ts @@ -31,20 +31,22 @@ export const isAborted = (signal?: AbortSignal): boolean => export const noFollowOpenSupported = (): boolean => Number.isSafeInteger(constants.O_NOFOLLOW) && constants.O_NOFOLLOW !== 0; -export const validateDirectory = async ( - root: string, - rootIdentity: BigIntStats, - path: string, - signal?: AbortSignal, -): Promise< +/** A directory's identity admission: its metadata, or why it was refused. */ +export type DirectoryValidation = | { readonly ok: true; readonly stats: BigIntStats } | { readonly ok: false; readonly code: ReferenceSourceFailureCode; readonly message: string; readonly localDiagnostic?: string; - } -> => { + }; + +export const validateDirectory = async ( + root: string, + rootIdentity: BigIntStats, + path: string, + signal?: AbortSignal, +): Promise => { if (isAborted(signal)) return { ok: false, diff --git a/tests/boundary/filesystem/referenceSourceCleanupOwnership.test.ts b/tests/boundary/filesystem/referenceSourceCleanupOwnership.test.ts index 74e47f2b77..02218947ed 100644 --- a/tests/boundary/filesystem/referenceSourceCleanupOwnership.test.ts +++ b/tests/boundary/filesystem/referenceSourceCleanupOwnership.test.ts @@ -6,7 +6,8 @@ import { writeFile, type FileHandle, } from "node:fs/promises"; -import { join } from "node:path"; +import { dirname, join } from "node:path"; +import { setTimeout as delay } from "node:timers/promises"; import type { Dirent } from "node:fs"; import { afterEach, beforeEach, expect, it, onTestFinished, vi } from "vitest"; @@ -592,3 +593,139 @@ it("preserves null cancellation and retained directory cleanup across retry", as expect(resources.cleanupResources).toEqual([root]); expect(closeCalls).toBe(1); }); + +// Directory admissions run ahead of their turn (#11365). Each later lookup +// below finishes sooner than the one before it, so completion order reverses +// start order; policy must still run, and refuse first, in traversal order. +it("runs directory policy in traversal order when prefetched admissions finish out of order", async () => { + const root = await createTestTempDirectory("rea-reference-ordered-"); + for (const name of ["a", "b", "c", "d", "e", "f"]) + await mkdir(join(root, name)); + const resources = new ArtifactResourceScope(); + onTestFinished(() => resources.close()); + let started = 0; + lstatMock.mockImplementation(async (...args) => { + if (dirname(String(args[0])) === root) { + started += 1; + await delay(Math.max(0, 80 - started * 10)); + } + return actual.lstat(...args); + }); + const listed: string[] = []; + const policy: string[] = []; + const result = await readReferenceSource(root, resources, { + shouldExclude: (path, kind) => { + if (kind === "directory") listed.push(path); + return false; + }, + beforeDirectory: async (path) => { + policy.push(path); + return path === "." + ? ok(undefined) + : err({ + tag: "reference-source-reader", + code: "io", + message: `refused ${path}`, + }); + }, + }); + expect(listed).toHaveLength(6); + expect(policy).toEqual([".", listed[0]]); + expect(result).toMatchObject({ + ok: false, + error: { code: "io", message: `refused ${listed[0]}` }, + }); +}); + +it("settles every lookup started ahead of its turn before a cancelled read returns", async () => { + const root = await createTestTempDirectory("rea-reference-settled-"); + for (const name of ["a", "b", "c", "d", "e", "f"]) { + await mkdir(join(root, name)); + await writeFile(join(root, name, "source.ts"), "observed"); + } + const resources = new ArtifactResourceScope(); + onTestFinished(() => resources.close()); + // Each later lookup takes longer, so lookups started ahead of the cancelled + // directory are still running when it stops. + let started = 0; + let inFlight = 0; + lstatMock.mockImplementation(async (...args) => { + started += 1; + inFlight += 1; + try { + await delay(started * 3); + return await actual.lstat(...args); + } finally { + inFlight -= 1; + } + }); + const controller = new AbortController(); + const result = await readReferenceSource(root, resources, { + signal: controller.signal, + beforeDirectory: async (path) => { + if (path !== ".") controller.abort("stop at the first child"); + return ok(undefined); + }, + }); + expect(inFlight).toBe(0); + expect(result).toMatchObject({ ok: false, error: { code: "cancelled" } }); +}); + +// Children pushed during descent bury older siblings whose admissions are +// still running; the number running at once stays bounded at every depth. +it("bounds running directory admissions while slow siblings are buried by deeper levels", async () => { + const root = await createTestTempDirectory("rea-reference-bounded-"); + const levels = 6; + let parent = root; + for (let level = 0; level < levels; level += 1) { + for (const sibling of [1, 2, 3]) + await mkdir(join(parent, `s${String(level)}-${String(sibling)}`)); + parent = join(parent, `d${String(level)}`); + await mkdir(parent); + } + const resources = new ArtifactResourceScope(); + onTestFinished(() => resources.close()); + // List names in byte order, so each level descends ("d") before its + // siblings ("s") are popped. + opendirMock.mockImplementation(async (...args) => { + const directory = await actual.opendir(...args); + const children: Dirent[] = []; + for await (const child of directory) children.push(child); + children.sort((left, right) => + Buffer.compare( + Buffer.from(left.name as unknown as Uint8Array), + Buffer.from(right.name as unknown as Uint8Array), + ), + ); + const operations: DirectoryOperations = directory; + vi.spyOn(operations, "read").mockImplementation(async () => + Promise.resolve(children.shift() ?? null), + ); + vi.spyOn(operations, "close").mockImplementation(async () => undefined); + return directory; + }); + // A directory's second lookup is its opening admission (the first is its + // parent's metadata lookup); hold the siblings' admissions open. + const lookups = new Map(); + let running = 0; + let peak = 0; + lstatMock.mockImplementation(async (...args) => { + const path = String(args[0]); + const count = (lookups.get(path) ?? 0) + 1; + lookups.set(path, count); + if (count !== 2 || !/\/s\d+-\d+$/u.test(path)) return actual.lstat(...args); + running += 1; + peak = Math.max(peak, running); + try { + await delay(100); + return await actual.lstat(...args); + } finally { + running -= 1; + } + }); + const result = await readReferenceSource(root, resources); + if (!result.ok) throw result.error; + expect(result.value.entries).toHaveLength(levels * 4); + // Four started ahead plus the popped directory's own admission. + expect(peak).toBeLessThanOrEqual(5); +});