Skip to content

Commit 5f62db4

Browse files
committed
refactor(apple-runner): isolate startup budget mechanics
1 parent c58fe85 commit 5f62db4

3 files changed

Lines changed: 130 additions & 123 deletions

File tree

‎packages/platform-apple/src/runner/__tests__/runner-request-cancellation.test.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -73,11 +73,8 @@ import {
7373
createRequestCanceledError,
7474
isRequestCanceledError,
7575
} from '@agent-device/kernel/errors';
76-
import {
77-
abortAllIosRunnerSessions,
78-
DEFAULT_RUNNER_START_BUDGET_MS,
79-
readRunnerSessionLiveness,
80-
} from '../runner-session.ts';
76+
import { abortAllIosRunnerSessions, readRunnerSessionLiveness } from '../runner-session.ts';
77+
import { DEFAULT_RUNNER_START_BUDGET_MS } from '../runner-start-budget.ts';
8178
import { RUNNER_STARTUP_TIMEOUT_MS } from '../runner-startup-transport.ts';
8279
import type { RunnerLease } from '../runner-lease.ts';
8380
import { executeRunnerCommand, prepareLocalIosRunner } from '../runner-lifecycle.ts';

‎packages/platform-apple/src/runner/runner-session.ts‎

Lines changed: 4 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,4 @@
1-
import {
2-
AppError,
3-
createRequestCanceledError,
4-
isRequestCanceledError,
5-
} from '@agent-device/kernel/errors';
1+
import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
62
import {
73
withKeyedLock,
84
Deadline,
@@ -39,7 +35,6 @@ import {
3935
decodeRunnerResponseBody,
4036
isRunnerResponseOk,
4137
readRunnerResponseData,
42-
resolveRunnerStartupSignal,
4338
withRunnerCommandId,
4439
type RunnerCommand,
4540
} from './runner-contract.ts';
@@ -96,6 +91,7 @@ import {
9691
} from './runner-session-types.ts';
9792
import { launchRunnerProcess, type LaunchedRunnerProcess } from './runner-process-launch.ts';
9893
import { isSameRunnerSimulator } from './runner-device-set.ts';
94+
import type { RunnerStartBudget } from './runner-start-budget.ts';
9995

10096
export type { RunnerSession } from './runner-session-types.ts';
10197

@@ -134,33 +130,6 @@ function withRunnerSessionLock<T>(deviceId: string, task: () => Promise<T>): Pro
134130
return withKeyedLock(runnerSessionLocks, deviceId, task);
135131
}
136132

137-
/**
138-
* What a runner start may spend when its caller sets no `startupTimeoutMs`: the reuse probe,
139-
* adoption, boot, device readiness, the xctestrun build and the launch, on one clock the start owns
140-
* (#2894). Sized for a cold build: `prepare` defaults to 240 s for the same work plus its health
141-
* check (`PREPARE_STARTUP_BUDGET_MS`), the iOS CI lane gives a cold `prepare` on a shared macOS
142-
* runner 420 s (`AGENT_DEVICE_IOS_PREPARE_TIMEOUT_MS`), and a daemon queued on another process's
143-
* build of the same artifact already gives up after 10 minutes
144-
* (`RUNNER_XCTESTRUN_CACHE_LOCK_TIMEOUT_MS`). The two ceilings agree, so a start never waits on a
145-
* peer's build longer than it would spend on its own.
146-
*/
147-
export const DEFAULT_RUNNER_START_BUDGET_MS = 10 * 60_000;
148-
149-
/**
150-
* The budget one runner start spends, with the clock that enforces it. The abort fires when the
151-
* deadline is spent, so every step that takes the signal (the xctestrun build and the launch kill
152-
* their process tree through exec, the probes stop retrying) ends on the same clock the deadline
153-
* reads. `close` retires the timer once the start has settled: a registered session is bounded by
154-
* its {@link RunnerSession.launchDeadline} from then on, never by this abort.
155-
*/
156-
type RunnerStartBudget = Readonly<{
157-
phase: RunnerPhaseBudget;
158-
timeoutMs: number;
159-
explicit: boolean;
160-
exhausted: AbortSignal;
161-
close: () => void;
162-
}>;
163-
164133
export async function ensureRunnerSession(
165134
device: DeviceInfo,
166135
options: RunnerSessionOptions,
@@ -169,6 +138,7 @@ export async function ensureRunnerSession(
169138
// from a retained-after-close runner no longer applies.
170139
cancelIosRunnerIdleStop(device.id);
171140
const start = withRunnerSessionLock(device.id, async () => {
141+
const { openRunnerStartBudget } = await import('./runner-start-budget.ts');
172142
// One budget for the whole start, opened once the lock is held so a start queued behind
173143
// another does not spend its clock waiting: the reuse check's toolchain probes, adoption and
174144
// the startup itself all read it. The request's cancellation rides with it, so a client
@@ -195,94 +165,10 @@ export async function ensureRunnerSession(
195165
budget.close();
196166
}
197167
});
168+
const { raceRunnerStartAgainstCaller } = await import('./runner-start-budget.ts');
198169
return await raceRunnerStartAgainstCaller(start, options.signal);
199170
}
200171

201-
/**
202-
* Opens the start's budget from `startupTimeoutMs`, or {@link DEFAULT_RUNNER_START_BUDGET_MS}
203-
* when the caller sets none. The startup signal (a cancelled request, never a caller's deadline)
204-
* and the budget's own expiry abort the same signal.
205-
*/
206-
function openRunnerStartBudget(options: RunnerSessionOptions): RunnerStartBudget {
207-
const explicitTimeoutMs = normalizeRunnerStartupTimeoutMs(options.startupTimeoutMs);
208-
const timeoutMs = explicitTimeoutMs ?? DEFAULT_RUNNER_START_BUDGET_MS;
209-
const exhausted = new AbortController();
210-
const timer = setTimeout(() => {
211-
exhausted.abort(runnerStartBudgetExhaustedError(timeoutMs, explicitTimeoutMs !== undefined));
212-
}, timeoutMs);
213-
timer.unref?.();
214-
const startupSignal = resolveRunnerStartupSignal(options);
215-
const signal = startupSignal
216-
? AbortSignal.any([startupSignal, exhausted.signal])
217-
: exhausted.signal;
218-
return {
219-
phase: createRunnerPhaseBudget(timeoutMs, signal),
220-
timeoutMs,
221-
explicit: explicitTimeoutMs !== undefined,
222-
exhausted: exhausted.signal,
223-
close: () => clearTimeout(timer),
224-
};
225-
}
226-
227-
/** Says the start's own budget ran out, whichever step it was in; the next request starts over. */
228-
function runnerStartBudgetExhaustedError(timeoutMs: number, explicit: boolean): AppError {
229-
return new AppError(
230-
'COMMAND_FAILED',
231-
`Apple runner start exceeded its ${explicit ? 'startup timeout' : 'default start budget'} of ${timeoutMs}ms`,
232-
{
233-
reason: 'runner_start_budget_exhausted',
234-
timeoutMs,
235-
retriable: true,
236-
hint: explicit
237-
? 'Raise the startup timeout, or run `prepare ios-runner` first so the runner is built before it is needed.'
238-
: 'Run `prepare ios-runner --timeout <ms>` so the cold build has a budget of your choosing; the session runner.log names the step that stalled.',
239-
},
240-
);
241-
}
242-
243-
/**
244-
* The start runs detached under the session lock; the caller only waits for it as long as its own
245-
* signal allows. A caller whose deadline lands during a cold xctestrun build leaves on time, the
246-
* build keeps going under the lock, and the next request for the device queues behind it and joins
247-
* the session it registers (#2894). Whatever the abort reason, the caller sees the same cancelled
248-
* request it would have seen from any later step; a cancelled request's abort also reaches the
249-
* start through its own startup signal, so nothing here decides whether the start survives. A
250-
* start that fails after its caller left has nobody to report to, so its failure is logged here.
251-
*/
252-
async function raceRunnerStartAgainstCaller(
253-
start: Promise<RunnerSession>,
254-
signal: AbortSignal | undefined,
255-
): Promise<RunnerSession> {
256-
if (!signal) return await start;
257-
return await new Promise<RunnerSession>((resolve, reject) => {
258-
const abort = () => {
259-
reject(createRequestCanceledError(undefined, signal.reason));
260-
start.catch(emitDetachedRunnerStartFailed);
261-
};
262-
if (signal.aborted) {
263-
abort();
264-
} else {
265-
signal.addEventListener('abort', abort, { once: true });
266-
}
267-
start.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
268-
});
269-
}
270-
271-
/** A cancelled request killed its start on purpose; any other failure of a start nobody awaits is news. */
272-
function emitDetachedRunnerStartFailed(error: unknown): void {
273-
if (isRequestCanceledError(error)) return;
274-
const appErr = error instanceof AppError ? error : undefined;
275-
emitDiagnostic({
276-
level: 'warn',
277-
phase: 'ios_runner_detached_start_failed',
278-
data: {
279-
code: appErr?.code,
280-
reason: appErr?.details?.reason,
281-
error: error instanceof Error ? error.message : String(error),
282-
},
283-
});
284-
}
285-
286172
/** How long the device-readiness probe may take, bounded by the startup budget it runs inside. */
287173
const RUNNER_DEVICE_READINESS_BUDGET_MS = 10_000;
288174

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
import {
2+
AppError,
3+
createRequestCanceledError,
4+
isRequestCanceledError,
5+
} from '@agent-device/kernel/errors';
6+
import { emitDiagnostic } from './host.ts';
7+
import { resolveRunnerStartupSignal } from './runner-contract.ts';
8+
import { createRunnerPhaseBudget, type RunnerPhaseBudget } from './runner-xctestrun.ts';
9+
import { normalizeRunnerStartupTimeoutMs, type RunnerSession } from './runner-session-types.ts';
10+
import type { AppleRunnerLifecycleOptions } from './runner-provider.ts';
11+
12+
type RunnerSessionOptions = AppleRunnerLifecycleOptions;
13+
14+
/**
15+
* What a runner start may spend when its caller sets no `startupTimeoutMs`: the reuse probe,
16+
* adoption, boot, device readiness, the xctestrun build and the launch, on one clock the start owns
17+
* (#2894). Sized for a cold build: `prepare` defaults to 240 s for the same work plus its health
18+
* check (`PREPARE_STARTUP_BUDGET_MS`), the iOS CI lane gives a cold `prepare` on a shared macOS
19+
* runner 420 s (`AGENT_DEVICE_IOS_PREPARE_TIMEOUT_MS`), and a daemon queued on another process's
20+
* build of the same artifact already gives up after 10 minutes
21+
* (`RUNNER_XCTESTRUN_CACHE_LOCK_TIMEOUT_MS`). The two ceilings agree, so a start never waits on a
22+
* peer's build longer than it would spend on its own.
23+
*/
24+
export const DEFAULT_RUNNER_START_BUDGET_MS = 10 * 60_000;
25+
26+
/**
27+
* The budget one runner start spends, with the clock that enforces it. The abort fires when the
28+
* deadline is spent, so every step that takes the signal (the xctestrun build and the launch kill
29+
* their process tree through exec, the probes stop retrying) ends on the same clock the deadline
30+
* reads. `close` retires the timer once the start has settled: a registered session is bounded by
31+
* its {@link RunnerSession.launchDeadline} from then on, never by this abort.
32+
*/
33+
export type RunnerStartBudget = Readonly<{
34+
phase: RunnerPhaseBudget;
35+
timeoutMs: number;
36+
explicit: boolean;
37+
exhausted: AbortSignal;
38+
close: () => void;
39+
}>;
40+
41+
/**
42+
* Opens the start's budget from `startupTimeoutMs`, or {@link DEFAULT_RUNNER_START_BUDGET_MS}
43+
* when the caller sets none. The startup signal (a cancelled request, never a caller's deadline)
44+
* and the budget's own expiry abort the same signal.
45+
*/
46+
export function openRunnerStartBudget(options: RunnerSessionOptions): RunnerStartBudget {
47+
const explicitTimeoutMs = normalizeRunnerStartupTimeoutMs(options.startupTimeoutMs);
48+
const timeoutMs = explicitTimeoutMs ?? DEFAULT_RUNNER_START_BUDGET_MS;
49+
const exhausted = new AbortController();
50+
const timer = setTimeout(() => {
51+
exhausted.abort(runnerStartBudgetExhaustedError(timeoutMs, explicitTimeoutMs !== undefined));
52+
}, timeoutMs);
53+
timer.unref?.();
54+
const startupSignal = resolveRunnerStartupSignal(options);
55+
const signal = startupSignal
56+
? AbortSignal.any([startupSignal, exhausted.signal])
57+
: exhausted.signal;
58+
return {
59+
phase: createRunnerPhaseBudget(timeoutMs, signal),
60+
timeoutMs,
61+
explicit: explicitTimeoutMs !== undefined,
62+
exhausted: exhausted.signal,
63+
close: () => clearTimeout(timer),
64+
};
65+
}
66+
67+
/** Says the start's own budget ran out, whichever step it was in; the next request starts over. */
68+
function runnerStartBudgetExhaustedError(timeoutMs: number, explicit: boolean): AppError {
69+
return new AppError(
70+
'COMMAND_FAILED',
71+
`Apple runner start exceeded its ${explicit ? 'startup timeout' : 'default start budget'} of ${timeoutMs}ms`,
72+
{
73+
reason: 'runner_start_budget_exhausted',
74+
timeoutMs,
75+
retriable: true,
76+
hint: explicit
77+
? 'Raise the startup timeout, or run `prepare ios-runner` first so the runner is built before it is needed.'
78+
: 'Run `prepare ios-runner --timeout <ms>` so the cold build has a budget of your choosing; the session runner.log names the step that stalled.',
79+
},
80+
);
81+
}
82+
83+
/**
84+
* The start runs detached under the session lock; the caller only waits for it as long as its own
85+
* signal allows. A caller whose deadline lands during a cold xctestrun build leaves on time, the
86+
* build keeps going under the lock, and the next request for the device queues behind it and joins
87+
* the session it registers (#2894). Whatever the abort reason, the caller sees the same cancelled
88+
* request it would have seen from any later step; a cancelled request's abort also reaches the
89+
* start through its own startup signal, so nothing here decides whether the start survives. A
90+
* start that fails after its caller left has nobody to report to, so its failure is logged here.
91+
*/
92+
export async function raceRunnerStartAgainstCaller(
93+
start: Promise<RunnerSession>,
94+
signal: AbortSignal | undefined,
95+
): Promise<RunnerSession> {
96+
if (!signal) return await start;
97+
return await new Promise<RunnerSession>((resolve, reject) => {
98+
const abort = () => {
99+
reject(createRequestCanceledError(undefined, signal.reason));
100+
start.catch(emitDetachedRunnerStartFailed);
101+
};
102+
if (signal.aborted) {
103+
abort();
104+
} else {
105+
signal.addEventListener('abort', abort, { once: true });
106+
}
107+
start.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
108+
});
109+
}
110+
111+
/** A cancelled request killed its start on purpose; any other failure of a start nobody awaits is news. */
112+
function emitDetachedRunnerStartFailed(error: unknown): void {
113+
if (isRequestCanceledError(error)) return;
114+
const appErr = error instanceof AppError ? error : undefined;
115+
emitDiagnostic({
116+
level: 'warn',
117+
phase: 'ios_runner_detached_start_failed',
118+
data: {
119+
code: appErr?.code,
120+
reason: appErr?.details?.reason,
121+
error: error instanceof Error ? error.message : String(error),
122+
},
123+
});
124+
}

0 commit comments

Comments
 (0)