Skip to content

Commit 712926a

Browse files
ScottN-PVclaude
authored andcommitted
fix(shared): relay client install waits out a brief Windows file lock
On Windows the installer renames cloudflared.exe right after running it for validation. A process that still holds the file without delete sharing, such as a virus scanner, makes that rename fail with EBUSY, and the install stops with "Could not stage the relay client." Each of the two renames now retries up to 40 times, 250 ms apart, on Windows when it fails with EBUSY, EPERM, or EACCES. Fixes #16945 Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 2a93885 commit 712926a

2 files changed

Lines changed: 183 additions & 11 deletions

File tree

‎packages/shared/src/relayClient.test.ts‎

Lines changed: 155 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,16 @@ import { sha256 } from "@noble/hashes/sha2";
22
import * as NodeServices from "@effect/platform-node/NodeServices";
33
import { describe, expect, it } from "@effect/vitest";
44
import * as ConfigProvider from "effect/ConfigProvider";
5+
import * as Deferred from "effect/Deferred";
56
import * as Effect from "effect/Effect";
67
import * as Hex from "effect/encoding/Hex";
8+
import * as Fiber from "effect/Fiber";
79
import * as FileSystem from "effect/FileSystem";
810
import * as Layer from "effect/Layer";
11+
import * as PlatformError from "effect/PlatformError";
912
import * as Sink from "effect/Sink";
1013
import * as Stream from "effect/Stream";
14+
import * as TestClock from "effect/testing/TestClock";
1115
import { HttpClient, HttpClientResponse } from "effect/http";
1216
import { ChildProcess, ChildProcessSpawner } from "effect/process";
1317
import { 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.
1923
const windowsHost = HostProcessPlatform.defaultValue() === "win32";
2024

21-
const layerHostRuntime = (env: Record<string, string> = {}) =>
25+
const 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 =
9195
const managedPathFor = (baseDir: string, version: string) =>
9296
`${baseDir}/tools/cloudflared/${version}/linux-x64/cloudflared`;
9397

98+
const 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+
107+
type 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+
*/
113+
const 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+
138+
const testBinary = new TextEncoder().encode("test-cloudflared-binary");
139+
const testReleaseAsset = {
140+
url: "https://example.test/cloudflared",
141+
sha256: Hex.encode(sha256(testBinary)),
142+
archive: "binary",
143+
} as const;
144+
145+
const layerInstallRuntime = (platform: NodeJS.Platform) =>
146+
Layer.mergeAll(
147+
NodeServices.layer,
148+
layerHttpClient(testBinary),
149+
layerSpawner([]),
150+
layerHostRuntime({ PATH: "" }, platform),
151+
);
152+
153+
const managedDirectory = (baseDir: string, platform: NodeJS.Platform) =>
154+
`${baseDir}/tools/cloudflared/${RelayClient.CLOUDFLARED_VERSION}/${platform}-x64`;
155+
94156
describe("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‎

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ import * as Layer from "effect/Layer";
1717
import * as Option from "effect/Option";
1818
import * as Path from "effect/Path";
1919
import * as PlatformError from "effect/PlatformError";
20+
import * as Schedule from "effect/Schedule";
2021
import * as Semaphore from "effect/Semaphore";
2122
import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
2223
import { ChildProcess, ChildProcessSpawner } from "effect/process";
@@ -116,6 +117,9 @@ const INSTALL_LOCK_RETRY_DELAY = "100 millis";
116117
const INSTALL_LOCK_STALE_MS = 5 * 60 * 1_000;
117118
const VERSION_PROBE_TIMEOUT = "10 seconds";
118119

120+
const ACTIVATE_RETRY_COUNT = 40;
121+
const ACTIVATE_RETRY_DELAY = "250 millis";
122+
119123
const 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.
214+
function 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+
208219
const 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,

0 commit comments

Comments
 (0)