authorgravatar for snorteman@gmail.comScott Norteman <snorteman@gmail.com> 2026-10-08 16:19:09-04:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2026-10-08 13:19:09-07:00
logbd565bd1794f49f176ad137555faa46224716138
treef0e16ce24bbfefe6047ef0d8f797b57f9fd5d24c
parent2a93885bac5798a79d55069a0b5dc3e53c6176bc
signature Signed by PGP key B5690EEEBB952194

fix(shared): relay client install waits out a brief Windows file lock (#16998)

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

2 files changed, 183 insertions(+), 11 deletions(-)

packages/shared/src/relayClient.test.ts+155-2
......@@ -2,12 +2,16 @@ import { sha256 } from "@noble/hashes/sha2";
22import * as NodeServices from "@effect/platform-node/NodeServices";
33import { describe, expect, it } from "@effect/vitest";
44import * as ConfigProvider from "effect/ConfigProvider";
5import * as Deferred from "effect/Deferred";
56import * as Effect from "effect/Effect";
67import * as Hex from "effect/encoding/Hex";
8import * as Fiber from "effect/Fiber";
79import * as FileSystem from "effect/FileSystem";
810import * as Layer from "effect/Layer";
11import * as PlatformError from "effect/PlatformError";
912import * as Sink from "effect/Sink";
1013import * as Stream from "effect/Stream";
14import * as TestClock from "effect/testing/TestClock";
1115import { HttpClient, HttpClientResponse } from "effect/http";
1216import { ChildProcess, ChildProcessSpawner } from "effect/process";
1317import { HostProcessArchitecture, HostProcessPlatform } from "./hostProcess.ts";
......@@ -18,9 +22,9 @@ import * as RelayClient from "./relayClient.ts";
1822// POSIX exec bits that NTFS never reports; the win32 branch skips that check.
1923const windowsHost = HostProcessPlatform.defaultValue() === "win32";
2024
21const layerHostRuntime = (env: Record<string, string> = {}) =>
25const layerHostRuntime = (env: Record<string, string> = {}, platform: NodeJS.Platform = "linux") =>
2226 Layer.mergeAll(
23 Layer.succeed(HostProcessPlatform, "linux"),
27 Layer.succeed(HostProcessPlatform, platform),
2428 Layer.succeed(HostProcessArchitecture, "x64"),
2529 ConfigProvider.layer(ConfigProvider.fromEnv({ env })),
2630 );
......@@ -91,6 +95,64 @@ type RelayClientTestServices =
9195const managedPathFor = (baseDir: string, version: string) =>
9296 `${baseDir}/tools/cloudflared/${version}/linux-x64/cloudflared`;
9397
98const renameError = (code: string, path: string) =>
99 PlatformError.systemError({
100 _tag: code === "EBUSY" ? "Busy" : code === "EACCES" ? "PermissionDenied" : "Unknown",
101 module: "FileSystem",
102 method: "rename",
103 pathOrDescriptor: path,
104 cause: Object.assign(new Error(code), { code }),
105 });
106
107type InstallRename = "staging" | "activation";
108
109/**
110 * Fails the first `failures` staging or activation renames with `code`, as Windows does while
111 * another process holds the file. Staging moves the binary to a `.tmp` name beside its final path.
112 */
113const makeLockedRenames = (
114 fileSystem: FileSystem.FileSystem,
115 input: { readonly rename: InstallRename; readonly failures: number; readonly code: string },
116) =>
117 Effect.gen(function* () {
118 const firstAttempt = yield* Deferred.make<void>();
119 const renames = { attempts: 0 };
120 const locked = FileSystem.make({
121 ...fileSystem,
122 rename: (from, to) =>
123 Effect.suspend(() => {
124 if ((to.endsWith(".tmp") ? "staging" : "activation") !== input.rename) {
125 return fileSystem.rename(from, to);
126 }
127 renames.attempts += 1;
128 return renames.attempts <= input.failures
129 ? Deferred.succeed(firstAttempt, undefined).pipe(
130 Effect.andThen(Effect.fail(renameError(input.code, to))),
131 )
132 : fileSystem.rename(from, to);
133 }),
134 });
135 return { locked, renames, firstAttempt };
136 });
137
138const testBinary = new TextEncoder().encode("test-cloudflared-binary");
139const testReleaseAsset = {
140 url: "https://example.test/cloudflared",
141 sha256: Hex.encode(sha256(testBinary)),
142 archive: "binary",
143} as const;
144
145const layerInstallRuntime = (platform: NodeJS.Platform) =>
146 Layer.mergeAll(
147 NodeServices.layer,
148 layerHttpClient(testBinary),
149 layerSpawner([]),
150 layerHostRuntime({ PATH: "" }, platform),
151 );
152
153const managedDirectory = (baseDir: string, platform: NodeJS.Platform) =>
154 `${baseDir}/tools/cloudflared/${RelayClient.CLOUDFLARED_VERSION}/${platform}-x64`;
155
94156describe("RelayClient", () => {
95157 it.effect.skipIf(windowsHost)(
96158 "resolves explicit overrides before managed and PATH executables",
......@@ -481,4 +543,95 @@ describe("RelayClient", () => {
481543 expect(RelayClient.compareCloudflaredVersions("2025.10.0", "2025.6.1")).toBeGreaterThan(0);
482544 expect(RelayClient.compareCloudflaredVersions("2023.8.2", "2025.6.1")).toBeLessThan(0);
483545 });
546
547 it.effect.each([
548 ["staging", "EBUSY"],
549 ["activation", "EACCES"],
550 ] as const)("retries %s on Windows while another process holds the binary", ([rename, code]) =>
551 Effect.gen(function* () {
552 const fileSystem = yield* FileSystem.FileSystem;
553 const baseDir = yield* fileSystem.makeTempDirectoryScoped({
554 prefix: "t3-cloudflared-test-",
555 });
556 const { locked, renames, firstAttempt } = yield* makeLockedRenames(fileSystem, {
557 rename,
558 failures: 2,
559 code,
560 });
561 const manager = yield* RelayClient.makeCloudflaredRelayClient({
562 baseDir,
563 releaseAsset: testReleaseAsset,
564 }).pipe(Effect.provideService(FileSystem.FileSystem, locked));
565
566 const installing = yield* manager.install.pipe(Effect.forkChild);
567 yield* Deferred.await(firstAttempt);
568 yield* TestClock.adjust("1 second");
569 const installed = yield* Fiber.join(installing);
570
571 expect(renames.attempts).toBe(3);
572 expect(new TextDecoder().decode(yield* fileSystem.readFile(installed.executablePath))).toBe(
573 "test-cloudflared-binary",
574 );
575 expect(yield* fileSystem.readDirectory(managedDirectory(baseDir, "win32"))).toEqual([
576 "cloudflared.exe",
577 ]);
578 }).pipe(Effect.scoped, Effect.provide(layerInstallRuntime("win32"))),
579 );
580
581 it.effect.each([
582 ["staging", "EPERM", "Could not stage the relay client."],
583 ["activation", "EBUSY", "Could not activate the relay client."],
584 ] as const)("gives up on a Windows %s lock that does not clear", ([rename, code, message]) =>
585 Effect.gen(function* () {
586 const fileSystem = yield* FileSystem.FileSystem;
587 const baseDir = yield* fileSystem.makeTempDirectoryScoped({
588 prefix: "t3-cloudflared-test-",
589 });
590 const { locked, renames, firstAttempt } = yield* makeLockedRenames(fileSystem, {
591 rename,
592 failures: Infinity,
593 code,
594 });
595 const manager = yield* RelayClient.makeCloudflaredRelayClient({
596 baseDir,
597 releaseAsset: testReleaseAsset,
598 }).pipe(Effect.provideService(FileSystem.FileSystem, locked));
599
600 const installing = yield* manager.install.pipe(Effect.flip, Effect.forkChild);
601 yield* Deferred.await(firstAttempt);
602 yield* TestClock.adjust("1 minute");
603 const error = yield* Fiber.join(installing);
604
605 expect(error.message).toBe(message);
606 expect(renames.attempts).toBe(41);
607 // Nothing is installed, and the staged copy, download folder, and install lock are gone.
608 expect(yield* fileSystem.readDirectory(managedDirectory(baseDir, "win32"))).toEqual([]);
609 }).pipe(Effect.scoped, Effect.provide(layerInstallRuntime("win32"))),
610 );
611
612 it.effect.each([
613 ["linux", "EBUSY"],
614 ["win32", "EXDEV"],
615 ] as const)("fails staging at once on %s for %s", ([platform, code]) =>
616 Effect.gen(function* () {
617 const fileSystem = yield* FileSystem.FileSystem;
618 const baseDir = yield* fileSystem.makeTempDirectoryScoped({
619 prefix: "t3-cloudflared-test-",
620 });
621 const { locked, renames } = yield* makeLockedRenames(fileSystem, {
622 rename: "staging",
623 failures: Infinity,
624 code,
625 });
626 const manager = yield* RelayClient.makeCloudflaredRelayClient({
627 baseDir,
628 releaseAsset: testReleaseAsset,
629 }).pipe(Effect.provideService(FileSystem.FileSystem, locked));
630
631 const error = yield* manager.install.pipe(Effect.flip);
632
633 expect(error.message).toBe("Could not stage the relay client.");
634 expect(renames.attempts).toBe(1);
635 }).pipe(Effect.scoped, Effect.provide(layerInstallRuntime(platform))),
636 );
484637});
packages/shared/src/relayClient.ts+28-9
......@@ -17,6 +17,7 @@ import * as Layer from "effect/Layer";
1717import * as Option from "effect/Option";
1818import * as Path from "effect/Path";
1919import * as PlatformError from "effect/PlatformError";
20import * as Schedule from "effect/Schedule";
2021import * as Semaphore from "effect/Semaphore";
2122import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
2223import { ChildProcess, ChildProcessSpawner } from "effect/process";
......@@ -116,6 +117,9 @@ const INSTALL_LOCK_RETRY_DELAY = "100 millis";
116117const INSTALL_LOCK_STALE_MS = 5 * 60 * 1_000;
117118const VERSION_PROBE_TIMEOUT = "10 seconds";
118119
120const ACTIVATE_RETRY_COUNT = 40;
121const ACTIVATE_RETRY_DELAY = "250 millis";
122
119123const trimmedString = (name: string) =>
120124 Config.String(name).pipe(
121125 Config.option,
......@@ -205,6 +209,13 @@ function isAlreadyExists(error: PlatformError.PlatformError): boolean {
205209 return error.reason._tag === "AlreadyExists";
206210}
207211
212// Windows refuses to rename a file another process briefly holds open, such as a virus
213// scanner reading the binary that just ran. These codes clear once it lets go.
214function isTransientWindowsLock(error: PlatformError.PlatformError): boolean {
215 const code = (error.reason.cause as NodeJS.ErrnoException | undefined)?.code;
216 return code === "EBUSY" || code === "EPERM" || code === "EACCES";
217}
218
208219const wrapInstallFailure =
209220 (
210221 reason: RelayClientInstallError["reason"],
......@@ -397,6 +408,16 @@ export const makeCloudflaredRelayClient = Effect.fn("cloudflared.make")(function
397408 }
398409 }).pipe(Effect.withSpan("cloudflared.pruneManagedVersions"));
399410
411 /** Moves the new binary toward its final path, waiting out a brief Windows lock. */
412 const renameWhenUnlocked = (from: string, to: string) =>
413 fileSystem.rename(from, to).pipe(
414 Effect.retry({
415 times: ACTIVATE_RETRY_COUNT,
416 schedule: Schedule.spaced(ACTIVATE_RETRY_DELAY),
417 while: (error) => platform === "win32" && isTransientWindowsLock(error),
418 }),
419 );
420
400421 const runCommand = Effect.fn("cloudflared.runCommand")(function* (
401422 command: string,
402423 args: ReadonlyArray<string>,
......@@ -574,15 +595,13 @@ export const makeCloudflaredRelayClient = Effect.fn("cloudflared.make")(function
574595
575596 const stagedPath = `${managedPath}.${yield* crypto.randomUUIDv4}.tmp`;
576597 yield* report("activating");
577 yield* fileSystem
578 .rename(executablePath, stagedPath)
579 .pipe(wrapInstallFailure("write_failed", "Could not stage the relay client."));
580 yield* fileSystem
581 .rename(stagedPath, managedPath)
582 .pipe(
583 wrapInstallFailure("write_failed", "Could not activate the relay client."),
584 Effect.ensuring(fileSystem.remove(stagedPath, { force: true }).pipe(Effect.ignore)),
585 );
598 yield* renameWhenUnlocked(executablePath, stagedPath).pipe(
599 wrapInstallFailure("write_failed", "Could not stage the relay client."),
600 );
601 yield* renameWhenUnlocked(stagedPath, managedPath).pipe(
602 wrapInstallFailure("write_failed", "Could not activate the relay client."),
603 Effect.ensuring(fileSystem.remove(stagedPath, { force: true }).pipe(Effect.ignore)),
604 );
586605 return {
587606 status: "available",
588607 executablePath: managedPath,