Skip to content

Commit 6c0f4e3

Browse files
fix(apple): key the runner toolchain memo on the selection's real dir
The reviewer's xcodes case: a tool swaps the Xcode bundle behind a stable path, so `xcode-select -p` answers the same string and the key never moves. Resolve the host's selection link to the dir it really names, and follow the same path for a client's DEVELOPER_DIR so one toolchain lands on one entry. The link is read first, so a warm read costs no spawn; `xcode-select -p` is the fallback. Restore TTL renewal on a hit, which #3300 asked to keep: the key now moves with the selection, so a hit is evidence the entry still answers for this host. Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
1 parent b4adfdc commit 6c0f4e3

4 files changed

Lines changed: 217 additions & 19 deletions

File tree

‎packages/platform-apple/src/runner/__tests__/apple-toolchain-fixtures.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
import { beforeEach, vi } from 'vitest';
2+
import fs from 'node:fs';
23
import { AppError } from '@agent-device/kernel/errors';
34
import { appleRunnerTestHost } from '../test-host.ts';
5+
import { XCODE_SELECT_LINK_PATH } from '../runner-toolchain-probe.ts';
46
import type { ExecOptions, ExecResult } from '@agent-device/host-kit/command';
57

68
export const STUBBED_APPLE_TOOLCHAIN = {
@@ -43,6 +45,7 @@ export function appleToolchainProbeResult(command: string, args: readonly string
4345
* make a probe fail.
4446
*/
4547
export function stubAppleToolchainProbes(): ReturnType<typeof vi.fn> {
48+
stubAppleSelectionLink();
4649
const runCmdSync = vi.fn(appleToolchainProbeResult);
4750
beforeEach(() => {
4851
runCmdSync.mockImplementation(appleToolchainProbeResult);
@@ -54,6 +57,31 @@ export function stubAppleToolchainProbes(): ReturnType<typeof vi.fn> {
5457
return runCmdSync;
5558
}
5659

60+
/**
61+
* The host's default selection link as the Apple toolchain probes see it. Undefined keeps the link
62+
* unreadable, which sends every read down the `xcode-select -p` fallback a case already scripts; a
63+
* case that owns a link points it at a path it created.
64+
*/
65+
export const appleSelectionLink: { target: string | undefined } = { target: undefined };
66+
67+
/**
68+
* Hides the selection link of the machine running the suite, so a case decides the host's selection
69+
* rather than inheriting it. The real host has one, and where it points is not this suite's business.
70+
*/
71+
export function stubAppleSelectionLink(): void {
72+
const realRealpathSync = fs.realpathSync;
73+
beforeEach(() => {
74+
appleSelectionLink.target = undefined;
75+
vi.spyOn(fs, 'realpathSync').mockImplementation((target: fs.PathLike) => {
76+
if (String(target) !== XCODE_SELECT_LINK_PATH) return realRealpathSync(target);
77+
if (appleSelectionLink.target === undefined) {
78+
throw Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' });
79+
}
80+
return realRealpathSync(appleSelectionLink.target);
81+
});
82+
});
83+
}
84+
5785
/**
5886
* The fingerprint budget's clock, advanced only by an exec that blocks for the whole timeout it was
5987
* handed. Without it a mock that throws immediately proves nothing about a deadline: no time passes,

‎packages/platform-apple/src/runner/__tests__/runner-cache-metadata.test.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -792,22 +792,23 @@ test('a default selection the host moved does not answer from the fingerprint it
792792
);
793793
});
794794

795-
test('a toolchain fingerprint expires at the end of the TTL its read started, hits included', () => {
795+
test('a toolchain fingerprint is renewed by each hit and expires once nothing uses it', () => {
796796
vi.useFakeTimers();
797797
try {
798798
appleRunnerTestHost.update({
799799
commandDeveloperDir: () => '/Applications/Xcode-A.app/Contents/Developer',
800800
});
801801
resolveExpectedRunnerCacheMetadata(IOS_SIMULATOR);
802802
runCmdSync.mockClear();
803-
// A hit answers the read and leaves the expiry where the read put it. Hits used to push it
804-
// ahead of themselves, so a busy daemon never re-resolved what it was answering for (#3300).
803+
// The key names the dir the read resolved, so a hit is evidence the entry still answers for
804+
// this host and renews itself (#3300 asked to keep this). What an idle entry cannot outlast is
805+
// the TTL, measured from the hit that last renewed it.
805806
vi.advanceTimersByTime(9 * 60_000);
806807
resolveExpectedRunnerCacheMetadata(IOS_SIMULATOR);
807808
expect(runCmdSync).not.toHaveBeenCalled();
808809
expect(memoizedRunnerXcodeVersion(IOS_SIMULATOR)).toBe(STUBBED_APPLE_TOOLCHAIN.xcodeVersion);
809810

810-
vi.advanceTimersByTime(60_001);
811+
vi.advanceTimersByTime(10 * 60_001);
811812
expect(memoizedRunnerXcodeVersion(IOS_SIMULATOR)).toBeUndefined();
812813
resolveExpectedRunnerCacheMetadata(IOS_SIMULATOR);
813814
expect(runCmdSync.mock.calls.map(([command]) => command)).toEqual([

‎packages/platform-apple/src/runner/__tests__/runner-toolchain-probe.test.ts‎

Lines changed: 118 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,28 @@
11
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
22
import assert from 'node:assert/strict';
3+
import fs from 'node:fs';
4+
import path from 'node:path';
35
import { isRequestCanceledError } from '@agent-device/kernel/errors';
46
import { resetAllProcessMemosForTests } from '@agent-device/kernel/ttl-memo';
57
import type { ExecOptions, ExecResult } from '@agent-device/host-kit/command';
68
import { IOS_SIMULATOR } from './device-fixtures.ts';
79
import { appleRunnerTestHost } from '../test-host.ts';
810
import {
911
appleToolchainProbeResult,
12+
appleSelectionLink,
1013
blockForWholeTimeout,
1114
installToolchainProbeClock,
1215
selectedDeveloperDirResult,
1316
STUBBED_APPLE_TOOLCHAIN,
17+
stubAppleSelectionLink,
1418
valueProbeCommands,
1519
} from './apple-toolchain-fixtures.ts';
1620
import {
1721
memoizedRunnerXcodeVersion,
1822
requireRunnerToolchainFingerprint,
1923
} from '../runner-toolchain-probe.ts';
2024
import { createRunnerPhaseBudget, type RunnerPhaseBudget } from '../runner-phase-budget.ts';
25+
import { mkdtempForTestSync } from './tmp-dir.ts';
2126
import { COLD_TOOLCHAIN_PROBE_TIMEOUT_MS } from '../apple-runner-platform.ts';
2227

2328
// The fingerprint memo is process-wide and the selection it keys on is host state, so these cases
@@ -35,9 +40,15 @@ const runCmdSync = vi.fn();
3540
let selectedDeveloperDir = XCODE_A;
3641
let nowMs = 1_700_000_000_000;
3742

43+
stubAppleSelectionLink();
44+
45+
/** A scratch root the case's fake developer dirs and selection links live under. */
46+
let tempRoot: string;
47+
3848
beforeEach(() => {
3949
resetAllProcessMemosForTests();
4050
selectedDeveloperDir = XCODE_A;
51+
tempRoot = mkdtempForTestSync('runner-selection-');
4152
runCmdSync.mockReset().mockImplementation(appleToolchainProbeResult);
4253
appleRunnerTestHost.update({
4354
runCmdSync,
@@ -50,6 +61,16 @@ afterEach(() => {
5061
vi.restoreAllMocks();
5162
});
5263

64+
/**
65+
* A developer dir the host can resolve, standing in for an installed Xcode at `dir`. `realpath` only
66+
* answers for a dir that exists, so a key built from a missing one would be no key at all.
67+
*/
68+
function realSelectionDir(dir: string): string {
69+
const created = path.join(tempRoot, dir);
70+
fs.mkdirSync(created, { recursive: true });
71+
return created;
72+
}
73+
5374
/** Two Xcodes and the `sudo xcode-select -s` that moves the host's default selection between them. */
5475
function scriptSelectableXcodes(): void {
5576
runCmdSync.mockImplementation((command: string, args: readonly string[]) =>
@@ -203,6 +224,87 @@ describe('the developer dir a toolchain fingerprint answers for', () => {
203224
expect(memoizedRunnerXcodeVersion(IOS_SIMULATOR)).toBeUndefined();
204225
});
205226

227+
test('a warm read resolves its key from the selection link without spawning anything', () => {
228+
appleSelectionLink.target = realSelectionDir(XCODE_A);
229+
readFingerprint();
230+
runCmdSync.mockClear();
231+
232+
readFingerprint();
233+
234+
// The link is what a warm read reads, so the memo costs no process at all. `xcode-select -p` is
235+
// the fallback, not the per-read cost, which is what made the key change expensive before.
236+
expect(runCmdSync.mock.calls).toEqual([]);
237+
});
238+
239+
test('a selection link naming a toolchain answers from that toolchain, not from xcode-select', () => {
240+
appleSelectionLink.target = realSelectionDir(XCODE_A);
241+
expect(readFingerprint().xcodeBuildVersion).toBe(STUBBED_APPLE_TOOLCHAIN.xcodeBuildVersion);
242+
243+
// The two sources disagree, which is what a host whose selection moved without its link keeping
244+
// up looks like. The link is what `xcode-select -s` writes, so it is the one that names it.
245+
scriptSelectableXcodes();
246+
selectedDeveloperDir = XCODE_B;
247+
runCmdSync.mockClear();
248+
249+
expect(readFingerprint().xcodeBuildVersion).toBe(STUBBED_APPLE_TOOLCHAIN.xcodeBuildVersion);
250+
expect(runCmdSync.mock.calls).toEqual([]);
251+
});
252+
253+
test('a selection link moved to another developer dir moves the key with it', () => {
254+
appleSelectionLink.target = realSelectionDir(XCODE_A);
255+
readFingerprint();
256+
257+
appleSelectionLink.target = realSelectionDir(XCODE_B);
258+
runCmdSync.mockClear();
259+
260+
// The entry under the dir the host left cannot answer for the dir it moved to.
261+
expect(readFingerprint().xcodeBuildVersion).toBe(STUBBED_APPLE_TOOLCHAIN.xcodeBuildVersion);
262+
expect(valueProbeCommands(runCmdSync.mock.calls)).toEqual(['xcodebuild', 'xcrun', 'xcrun']);
263+
expect(runCmdSync.mock.calls.some(([command]) => command === 'xcode-select')).toBe(false);
264+
});
265+
266+
test('a bundle swapped behind a stable selection path moves the key', () => {
267+
// What a tool like xcodes does: it replaces the Xcode.app bundle, so the selection keeps naming
268+
// the same path while the toolchain behind it changes. Keying on the link's raw target would
269+
// keep answering for the Xcode that path used to reach, so the key follows the real dir.
270+
const stable = path.join(tempRoot, 'Xcode.app');
271+
const first = path.join(tempRoot, 'Xcode-1.app');
272+
const second = path.join(tempRoot, 'Xcode-2.app');
273+
for (const bundle of [first, second]) {
274+
fs.mkdirSync(path.join(bundle, 'Contents', 'Developer'), { recursive: true });
275+
}
276+
fs.symlinkSync(path.basename(first), stable);
277+
appleSelectionLink.target = stable;
278+
279+
readFingerprint();
280+
fs.unlinkSync(stable);
281+
fs.symlinkSync(path.basename(second), stable);
282+
283+
runCmdSync.mockClear();
284+
expect(readFingerprint().xcodeBuildVersion).toBe(STUBBED_APPLE_TOOLCHAIN.xcodeBuildVersion);
285+
expect(valueProbeCommands(runCmdSync.mock.calls)).toEqual(['xcodebuild', 'xcrun', 'xcrun']);
286+
});
287+
288+
test('a selection reported with its trailing newline keys on the dir alone', () => {
289+
// `xcode-select -p` answers with a newline. A key that kept it would never match the dir a
290+
// client's DEVELOPER_DIR names, so one Xcode would look like two toolchains.
291+
const reported = realSelectionDir(XCODE_A);
292+
runCmdSync.mockImplementation((command: string, args: readonly string[]) =>
293+
command === 'xcode-select'
294+
? { exitCode: 0, stdout: `${reported}\n`, stderr: '' }
295+
: appleToolchainProbeResult(command, args),
296+
);
297+
298+
expect(readFingerprint().xcodeBuildVersion).toBe(STUBBED_APPLE_TOOLCHAIN.xcodeBuildVersion);
299+
runCmdSync.mockClear();
300+
301+
appleRunnerTestHost.update({ commandDeveloperDir: () => reported });
302+
expect(readFingerprint().xcodeBuildVersion).toBe(STUBBED_APPLE_TOOLCHAIN.xcodeBuildVersion);
303+
304+
// The client-named dir hit the entry the newline-built key stored, so nothing re-read.
305+
expect(runCmdSync.mock.calls).toEqual([]);
306+
});
307+
206308
test('a selection that answers nothing, or dies on exec, is no dir rather than a bad one', () => {
207309
for (const unanswered of [
208310
{ exitCode: 0, stdout: ' \n', stderr: '' } satisfies ExecResult,
@@ -325,11 +427,12 @@ describe('the lifetime of a memoized toolchain fingerprint', () => {
325427
nowMs += ms;
326428
}
327429

328-
test('a hit answers to the end of the TTL its read started, and no longer', () => {
430+
test('a hit renews the entry it answered from, because its key is still the selection', () => {
329431
readFingerprint();
330432

331-
// Hits used to push expiry ahead of themselves, so a daemon reading more often than the TTL
332-
// never re-resolved its selection at all (#3300).
433+
// The key names the dir this host selects, so a hit is itself evidence the entry is still the
434+
// answer for that host. #3300 asked to keep this renewal; the stale answer it could once serve
435+
// now costs a key change instead of a TTL.
333436
advance(FINGERPRINT_TTL_MS / 2);
334437
runCmdSync.mockClear();
335438
readFingerprint();
@@ -338,6 +441,18 @@ describe('the lifetime of a memoized toolchain fingerprint', () => {
338441
advance(FINGERPRINT_TTL_MS / 2);
339442
runCmdSync.mockClear();
340443
readFingerprint();
444+
expect(valueProbeCommands(runCmdSync.mock.calls)).toEqual([]);
445+
});
446+
447+
test('an entry no read takes expires at the TTL its storing read started', () => {
448+
readFingerprint();
449+
450+
advance(FINGERPRINT_TTL_MS);
451+
runCmdSync.mockClear();
452+
readFingerprint();
453+
454+
// Renewal is for entries in use. One that nothing has asked for goes away, which is also the
455+
// ceiling on how long a failure report can name a selection no request is using.
341456
expect(valueProbeCommands(runCmdSync.mock.calls)).toEqual(['xcodebuild', 'xcrun', 'xcrun']);
342457
});
343458

‎packages/platform-apple/src/runner/runner-toolchain-probe.ts‎

Lines changed: 66 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import {
1212
isCommandTimeoutError,
1313
runCmdSync,
1414
} from './host.ts';
15+
import fs from 'node:fs';
1516
import {
1617
COLD_TOOLCHAIN_PROBE_TIMEOUT_MS,
1718
resolveRunnerPlatformName,
@@ -33,12 +34,20 @@ import {
3334
const TOOLCHAIN_FINGERPRINT_BUDGET_MS = 45_000;
3435

3536
/**
36-
* Ceiling on one `xcode-select -p` attempt. `xcode-select -p` answers in tens of milliseconds, so
37-
* this is headroom rather than an expected cost, and it stays small enough that a stalled probe
38-
* cannot take the cold-start ceiling away from the value probes whose entry it is deciding. A
39-
* selection this process cannot resolve leaves the read with no dir to key on.
37+
* Ceiling on one `xcode-select -p` attempt, which the cache key needs only when the host's selection
38+
* link cannot be read. `xcode-select -p` answers in tens of milliseconds, so this is headroom rather
39+
* than an expected cost, and it stays small enough that a stalled probe cannot take the cold-start
40+
* ceiling away from the value probes whose entry it is deciding. A selection this process cannot
41+
* resolve leaves the read with no dir to key on.
4042
*/
4143
const XCODE_SELECT_PROBE_TIMEOUT_MS = 2_000;
44+
45+
/**
46+
* The symlink `xcode-select -s` writes and `xcode-select -p` reads back. Reading it directly answers
47+
* which developer dir the host selects, without a subprocess, and the cache needs that answer on
48+
* every hit and not only on a miss. Named so a suite can script the host's selection.
49+
*/
50+
export const XCODE_SELECT_LINK_PATH = '/var/db/xcode_select_link';
4251
const TOOLCHAIN_PROBE_MAX_BUFFER = 128 * 1024;
4352
const TOOLCHAIN_PROBE_DETAIL_MAX_LENGTH = 200;
4453
const TOOLCHAIN_PROBE_HINT =
@@ -110,11 +119,11 @@ function createToolchainProbeClock(budget: RunnerPhaseBudget | undefined): Toolc
110119
// before the composition root binds the host. Only a complete, parsed
111120
// fingerprint is ever memoized, so nothing unavailable can outlive the probe
112121
// that could not answer. The key carries the developer dir the read answers for,
113-
// and the TTL runs from the read rather than from the last hit, so a host that
114-
// switched its default Xcode selection is answered for at most
115-
// TOOLCHAIN_FINGERPRINT_TTL_MS after that switch (#3300). The same ceiling bounds
116-
// how long a failure report can name a selection no request is using any more,
117-
// which is why a dir no request reads must not stay for the daemon's lifetime.
122+
// so an entry is stale only until its own key stops being the host's selection,
123+
// which is what let a daemon serve the Xcode a host had left (#3300). A hit
124+
// therefore renews the entry, as it did before: an idle entry still goes away
125+
// after TOOLCHAIN_FINGERPRINT_TTL_MS, which also bounds how long a failure report
126+
// can name a selection no request is using any more.
118127
const TOOLCHAIN_FINGERPRINT_TTL_MS = 10 * 60_000;
119128
let lazyToolchainFingerprintCache: TtlMemo<string, RunnerToolchainFingerprint> | undefined;
120129
function toolchainFingerprintCache(): TtlMemo<string, RunnerToolchainFingerprint> {
@@ -144,7 +153,12 @@ export function requireRunnerToolchainFingerprint(
144153
const clock = createToolchainProbeClock(budget);
145154
clock.throwIfCanceled();
146155
const chosenDir = commandDeveloperDir();
147-
const developerDir = chosenDir ?? probeSelectedDeveloperDir(clock);
156+
// Both sources are resolved to the dir they really name, so a client naming a symlinked Xcode and
157+
// a daemon reading the selection link land on one entry for one toolchain.
158+
const developerDir =
159+
chosenDir !== undefined
160+
? (resolveRealDeveloperDir(chosenDir) ?? chosenDir)
161+
: resolveDefaultDeveloperDir(clock);
148162
// A read that cannot tell which Xcode it answers for has no entry to read or write: a shared
149163
// unknown key would let one host selection answer for the next, which is the fault here.
150164
if (developerDir === undefined) return requireFreshRunnerToolchainFingerprint(sdkName, clock);
@@ -162,7 +176,12 @@ function requireMemoizedRunnerToolchainFingerprint(
162176
clock: ToolchainProbeClock,
163177
): RunnerToolchainFingerprint {
164178
const cached = toolchainFingerprintCache().get(cacheKey);
165-
if (cached) return cached;
179+
if (cached) {
180+
// A hit can only be an entry keyed on the dir this read resolved, so it is still the host's
181+
// selection and renews itself. Only an entry no request reads expires (#3300).
182+
toolchainFingerprintCache().set(cacheKey, cached);
183+
return cached;
184+
}
166185
const fingerprint = requireFreshRunnerToolchainFingerprint(sdkName, clock);
167186
toolchainFingerprintCache().set(cacheKey, fingerprint);
168187
return fingerprint;
@@ -181,6 +200,37 @@ function requireFreshRunnerToolchainFingerprint(
181200
return fingerprint.value;
182201
}
183202

203+
/**
204+
* The dir the host's default selection points at, symlinks followed. The selection link is read
205+
* first because the memo needs its key on every hit and not only on a miss, and spawning
206+
* `xcode-select` costs a few milliseconds on a warm read. A link this process cannot read falls back
207+
* to `xcode-select -p`, and a selection neither can name leaves the read with no key at all.
208+
*/
209+
function resolveDefaultDeveloperDir(clock: ToolchainProbeClock): string | undefined {
210+
const selectedLink = resolveRealDeveloperDir(XCODE_SELECT_LINK_PATH);
211+
if (selectedLink) return selectedLink;
212+
const reported = probeSelectedDeveloperDir(clock);
213+
if (reported === undefined) return undefined;
214+
// A selection the host names but this process cannot follow is still that host's selection, so it
215+
// keys on the name. Keying on nothing instead would let one host answer for the next.
216+
return resolveRealDeveloperDir(reported) ?? reported;
217+
}
218+
219+
/**
220+
* The dir `candidate` really names, or undefined when nothing is there to name. `realpath` rather
221+
* than the link's raw target because a tool like xcodes swaps the Xcode.app bundle behind a stable
222+
* path: the raw target survives that swap, so a key built from it would keep answering for the Xcode
223+
* the host replaced.
224+
*/
225+
function resolveRealDeveloperDir(candidate: string | undefined): string | undefined {
226+
if (candidate === undefined) return undefined;
227+
try {
228+
return fs.realpathSync(candidate.trim()) || undefined;
229+
} catch {
230+
return undefined;
231+
}
232+
}
233+
184234
/**
185235
* The dir `xcode-select` currently selects, or undefined when it will not say. Best effort: a read
186236
* that cannot resolve its own entry spends what is left of its budget on the probes that carry the
@@ -213,7 +263,11 @@ function probeSelectedDeveloperDir(clock: ToolchainProbeClock): string | undefin
213263
* describes, and the dir its entry is keyed on is the one that read resolved.
214264
*/
215265
export function memoizedRunnerXcodeVersion(device: DeviceInfo): string | undefined {
216-
const developerDir = commandDeveloperDir() ?? recordedDefaultSelection;
266+
const chosenDir = commandDeveloperDir();
267+
const developerDir =
268+
chosenDir !== undefined
269+
? (resolveRealDeveloperDir(chosenDir) ?? chosenDir)
270+
: recordedDefaultSelection;
217271
if (developerDir === undefined) return undefined;
218272
return toolchainFingerprintCache().get(
219273
toolchainFingerprintCacheKey(

0 commit comments

Comments
 (0)