From 65f78edce526277a5a563c44bc70418b50d1136f Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 07:57:51 +0800 Subject: [PATCH] perf(reference): overlap reference-source identity lookups in traversal order (#11585) The reference-source reader made about nine serial filesystem calls per directory. It now runs its read-only identity lookups ahead of their turn, bounded to four running at once (libuv's default filesystem concurrency): opening admissions of the next pending directories, metadata of the next listed names, and closing admissions of directories already enumerated. Results are applied in traversal order: policy and exclusion callbacks keep their order, the first error in traversal order is returned, a failure a started lookup observed is retained, and every started lookup settles before the read returns. Running opening admissions are counted, so older siblings buried by deeper levels cannot raise concurrency with tree depth. Measured on macOS, Node 24.22.1: the 130,000-directory regression's reference-source read 27.5 s -> 17.2 s; a 20,000-directory flat tree 2.1-2.3 s -> 1.2 s; an 8,641-file source tree 1.41 s -> 1.31 s. Refs #11365 --- src/reference/ReferenceSourceReader.ts | 40 ++- src/reference/ReferenceSourceReaderEntries.ts | 231 +++++++++++++----- .../ReferenceSourceReaderTraversal.ts | 10 + .../ReferenceSourceReaderValidate.ts | 18 +- .../referenceSourceCleanupOwnership.test.ts | 139 ++++++++++- 5 files changed, 356 insertions(+), 82 deletions(-) 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); +});