fix(cli): a browser install goes on when Windows holds a file for a moment (#7194)

* fix(cli): a browser install goes on when Windows holds a file for a moment

* chore(cli): shorten the lock-retry comment

* fix(cli): keep the lock check private

* chore(cli): wrap the lock-check comment
This commit is contained in:
Miguel Ángel
2026-11-05 01:50:43 +00:00
committed by GitHub
parent f6ae9bfb43
commit 2372fc34a1
2 changed files with 116 additions and 8 deletions
+72
View File
@@ -1294,6 +1294,78 @@ describe("findBrowser — cache resolution", () => {
}
});
describe("retryWhileLocked", () => {
const lock = (code: string) =>
Object.assign(new Error(`${code}: operation not permitted, rename 'a' -> 'b'`), { code });
const quickly = async (): Promise<void> => {};
const onWindows = async (run: () => Promise<void>) => {
const real = Object.getOwnPropertyDescriptor(process, "platform");
Object.defineProperty(process, "platform", { value: "win32" });
try {
await run();
} finally {
if (real) Object.defineProperty(process, "platform", real);
}
};
// fails without the fix: a file a virus scanner held for a moment failed the whole install with EPERM.
it.each(["EBUSY", "EPERM", "EACCES"])(
"on Windows, goes on after a %s that clears, waiting longer each time",
async (code) => {
await onWindows(async () => {
const { retryWhileLocked } = await import("./manager.js");
const waits: number[] = [];
const run = vi
.fn<() => Promise<string>>()
.mockRejectedValueOnce(lock(code))
.mockRejectedValueOnce(lock(code))
.mockResolvedValue("moved");
const cleared = vi.fn();
await expect(
retryWhileLocked(run, cleared, 5, async (ms) => void waits.push(ms)),
).resolves.toBe("moved");
expect(run).toHaveBeenCalledTimes(3);
expect(cleared).toHaveBeenCalledTimes(2);
expect(waits).toEqual([250, 500]);
});
},
);
it("on Windows, gives the lock's error after the last attempt", async () => {
await onWindows(async () => {
const { retryWhileLocked } = await import("./manager.js");
const run = vi.fn<() => Promise<string>>().mockRejectedValue(lock("EPERM"));
await expect(retryWhileLocked(run, undefined, 3, quickly)).rejects.toThrow("EPERM");
expect(run).toHaveBeenCalledTimes(3);
});
});
it("on Windows, reads the lock from the message when a child process carried it without a code", async () => {
await onWindows(async () => {
const { retryWhileLocked } = await import("./manager.js");
const run = vi
.fn<() => Promise<string>>()
.mockRejectedValueOnce(new Error("EBUSY: resource busy or locked, unlink 'x'"))
.mockResolvedValue("ok");
await expect(retryWhileLocked(run, undefined, 3, quickly)).resolves.toBe("ok");
});
});
it("does not retry any other error, or a lock error off Windows", async () => {
const { retryWhileLocked } = await import("./manager.js");
const missing = vi.fn(async () => {
throw lock("ENOENT");
});
await expect(retryWhileLocked(missing, undefined, 3, quickly)).rejects.toThrow();
expect(missing).toHaveBeenCalledTimes(1);
const here = vi.fn(async () => {
throw lock("EPERM");
});
await expect(retryWhileLocked(here, undefined, 3, quickly)).rejects.toThrow();
expect(here).toHaveBeenCalledTimes(1);
});
});
it("withBrowserWaitNotice speaks every 15 s while the task runs and stops when it ends", async () => {
vi.useFakeTimers();
try {
+44 -8
View File
@@ -751,6 +751,34 @@ export async function retryOnStall<T>(
}
}
const LOCK_ATTEMPTS = 5;
const LOCK_FIRST_WAIT_MS = 250;
/** Windows refuses to rename or unlink a file a scanner has open, for a moment.
* A real permission error is retried too, then thrown. */
function isLockedFileError(err: unknown): boolean {
if (process.platform !== "win32") return false;
const said = `${(err as NodeJS.ErrnoException | undefined)?.code ?? ""} ${normalizeErrorMessage(err)}`;
return /\b(EBUSY|EPERM|EACCES)\b/.test(said);
}
export async function retryWhileLocked<T>(
run: () => Promise<T> | T,
onRetry: () => void = () => {},
attempts = LOCK_ATTEMPTS,
wait: (ms: number) => Promise<void> = sleep,
): Promise<T> {
for (let attempt = 1; ; attempt++) {
try {
return await run();
} catch (err) {
if (!isLockedFileError(err) || attempt >= attempts) throw err;
await wait(LOCK_FIRST_WAIT_MS * 2 ** (attempt - 1));
onRetry();
}
}
}
function downloadHostOf(
browsers: PuppeteerBrowsers,
platform: Parameters<PuppeteerBrowsers["getDownloadUrl"]>[1],
@@ -830,25 +858,33 @@ async function downloadBrowser(options?: EnsureBrowserOptions): Promise<BrowserR
// Same filesystem as CACHE_DIR so the final rename is atomic.
const stagingDir = join(CACHE_ROOT_DIR, `${STAGING_PREFIX}${randomUUID()}`);
const clearStaging = () => rmSync(stagingDir, { recursive: true, force: true });
const clearStaging = () =>
rmSync(stagingDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
// install() only debug-logs each failed unzip tool before trying the next one; keep those lines.
const unzipLog = { lines: [] as string[] };
const runInstall = stagedInstaller(browsers, platform, stagingDir, options, unzipLog);
try {
const staged = await retryOnStall(
const staged = await retryWhileLocked(
() =>
installWithCorruptArchiveRecovery(runInstall, clearStaging, (err) =>
console.warn(
`[hyperframes] Downloaded browser archive was corrupt (${normalizeErrorMessage(err)}); re-downloading.`,
),
retryOnStall(
() =>
installWithCorruptArchiveRecovery(runInstall, clearStaging, (err) =>
console.warn(
`[hyperframes] Downloaded browser archive was corrupt (${normalizeErrorMessage(err)}); re-downloading.`,
),
),
clearStaging,
options?.downloadAttempts,
),
clearStaging,
options?.downloadAttempts,
);
assertExecutableUnpacked(stagingDir, staged.executablePath);
unzipLog.lines = [];
return { executablePath: moveStagedInstallIntoCache(stagingDir, staged), source: "download" };
const executablePath = await retryWhileLocked(() =>
moveStagedInstallIntoCache(stagingDir, staged),
);
return { executablePath, source: "download" };
} catch (err) {
throw wrapDownloadFailureWithBrowserPathHint(err, unzipLog.lines);
} finally {