Skip to content

Commit eb51a88

Browse files
fix(android): wait out a device-offline refusal and retry once (#3055)
* fix(android): wait out a device-offline refusal and retry once An emulator drops to offline for a few seconds after boot while adbd restarts. adb refuses commands on the host side then, so a helper install could fail with 'adb: device offline'. The device-scoped executor now waits for the device and runs the command once more. The wait and retry stay inside the caller's timeoutMs (wait gets at most half, 15s cap). A device that stays offline through its wait fails fast for 30s instead of making every call wait. * fix(android): retry only the bare host refusal, inside the remaining budget - match only stderr that is exactly adb's device-offline refusal, empty stdout, no timeout, so device output never triggers a rerun - wait takes half of the remaining budget; no budget left, refusal stands - wait uses the command's adb server and env - timeouts and cancels keep the stayed-offline mark - key the mark by adb server and serial * test(android): prove the offline retry gets only the budget the wait left The wait stub now moves the clock 1500 ms, so the retry must get 4000 - 1500 ms; a retry given the caller's full timeout fails the test. The abort and timeout cases assert the error they reject with. The stayed-offline key takes the route's installed adb server first, as the route itself does. * fix(android): key the offline retry on the classifier's typed host refusal The adb failure classifier now records hostRefusal (adbHostRefusal on thrown errors) when stderr is exactly the host adb's device-offline refusal, stdout is empty, and the command did not time out. The retry keys only on that detail, so the separate stderr predicate is gone. The broad device_offline family is unchanged. Stayed-offline marks move to their own module, which drops lapsed marks when it records a new one. * refactor(android): classify each adb attempt's outcome in its own helper attemptAdb asks isOfflineRefusalResult or isOfflineRefusalError instead of reading the classification inline, which keeps it under the fallow complexity threshold. * refactor(android): keep the stayed-offline record in the adb provider scope A separate module added one module to the eager import closure of platform-android mechanics.ts, which failed the eager-closure budget. --------- Co-authored-by: Michał Pierzchała <[email protected]>
1 parent 0a7221d commit eb51a88

5 files changed

Lines changed: 471 additions & 25 deletions

File tree

‎packages/platform-android/src/__tests__/adb-executor.test.ts‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -495,16 +495,17 @@ test('the local adb executor attaches classified hints to thrown command failure
495495
assert.equal(Object.hasOwn(error.details ?? {}, 'retriable'), false);
496496
});
497497

498-
test('the local adb executor flags transient transport failures retriable', async () => {
498+
test('the local adb executor flags a device that stays offline retriable', async () => {
499499
mockRunCmd.mockClear();
500-
mockRunCmd.mockRejectedValueOnce(
501-
new AppError('COMMAND_FAILED', 'adb exited with code 1', {
502-
exitCode: 1,
503-
stdout: '',
504-
stderr: 'adb: device offline',
505-
processExitError: true,
506-
}),
507-
);
500+
const offline = new AppError('COMMAND_FAILED', 'adb exited with code 1', {
501+
exitCode: 1,
502+
stdout: '',
503+
stderr: 'adb: device offline',
504+
processExitError: true,
505+
});
506+
mockRunCmd.mockRejectedValueOnce(offline);
507+
mockRunCmd.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 });
508+
mockRunCmd.mockRejectedValueOnce(offline);
508509
const adb = createDeviceAdbExecutor({
509510
platform: 'android',
510511
id: 'emulator-5554',
@@ -521,6 +522,8 @@ test('the local adb executor flags transient transport failures retriable', asyn
521522
assert.ok(error instanceof AppError);
522523
assert.equal(error.details?.adbFailure, 'device_offline');
523524
assert.equal(error.details?.retriable, true);
525+
assert.equal(mockRunCmd.mock.calls.length, 3);
526+
assert.ok(mockRunCmd.mock.calls[1]?.[1].includes('wait-for-device'));
524527
});
525528

526529
test('the local adb executor classifies exec-layer timeouts as a wedged adb server', async () => {

‎packages/platform-android/src/adb-failure.test.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,38 @@ test('ADB failure classification keeps transport on stderr and install verdicts
2323
);
2424
});
2525

26+
test('only the bare host adb device-offline refusal is classified as a host refusal', () => {
27+
for (const stderr of ['adb: device offline\n', "error: device 'emulator-5554' offline"]) {
28+
assert.deepEqual(classifyAndroidAdbFailure(stderr), {
29+
reason: 'device_offline',
30+
hint: classifyAndroidAdbFailure('device offline')?.hint,
31+
retriable: true,
32+
hostRefusal: true,
33+
});
34+
}
35+
for (const [stderr, stdout] of [
36+
['adb: device offline', 'partial'],
37+
['flash: device offline, giving up', ''],
38+
] as const) {
39+
const failure = classifyAndroidAdbFailure(stderr, stdout);
40+
assert.equal(failure?.reason, 'device_offline');
41+
assert.equal(failure?.hostRefusal, undefined);
42+
}
43+
44+
const refused = attachAdbFailureHint(
45+
new AppError('COMMAND_FAILED', 'adb exited with code 1', { stderr: 'adb: device offline' }),
46+
);
47+
assert.equal(refused.details?.adbHostRefusal, true);
48+
const timedOut = attachAdbFailureHint(
49+
new AppError('COMMAND_FAILED', 'adb timed out after 10ms', {
50+
stderr: 'adb: device offline',
51+
timeoutMs: 10,
52+
}),
53+
);
54+
assert.equal(timedOut.details?.adbFailure, 'timeout');
55+
assert.equal(Object.hasOwn(timedOut.details ?? {}, 'adbHostRefusal'), false);
56+
});
57+
2658
test('ADB discovery classifies transport failures from stderr without trusting stdout', () => {
2759
const stdoutOnly = androidDiscoveryCommandError(
2860
'adb devices failed',

‎packages/platform-android/src/adb-failure.ts‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ export type AndroidAdbFailureClassification = Readonly<{
1616
reason: AndroidAdbFailureReason;
1717
hint: string;
1818
retriable?: boolean;
19+
/** The host adb refused the command before it reached the device, so it had no effect there. */
20+
hostRefusal?: true;
1921
}>;
2022

2123
type AndroidAdbFailureMatcher = readonly [
@@ -24,6 +26,20 @@ type AndroidAdbFailureMatcher = readonly [
2426
matchStdout?: true,
2527
];
2628

29+
const ANDROID_ADB_DEVICE_OFFLINE_FAILURE = {
30+
reason: 'device_offline',
31+
hint: 'The device is connected but offline — wait for it to finish booting or run adb reconnect, then retry.',
32+
retriable: true,
33+
} as const satisfies AndroidAdbFailureClassification;
34+
35+
/** The entire stderr, lowercased, of a command the host adb refused because the device was offline. */
36+
const ADB_DEVICE_OFFLINE_HOST_REFUSAL = /^(?:adb|error): device (?:'[^']*' )?offline$/;
37+
38+
const ANDROID_ADB_DEVICE_OFFLINE_HOST_REFUSAL: AndroidAdbFailureClassification = Object.freeze({
39+
...ANDROID_ADB_DEVICE_OFFLINE_FAILURE,
40+
hostRefusal: true,
41+
});
42+
2743
const ANDROID_ADB_FAILURE_MATCHERS = [
2844
[
2945
/device unauthorized|device still authorizing/,
@@ -32,14 +48,7 @@ const ANDROID_ADB_FAILURE_MATCHERS = [
3248
hint: 'USB debugging is not authorized — accept the authorization prompt on the device screen (re-plug the cable if none appears), then retry.',
3349
},
3450
],
35-
[
36-
/device offline/,
37-
{
38-
reason: 'device_offline',
39-
hint: 'The device is connected but offline — wait for it to finish booting or run adb reconnect, then retry.',
40-
retriable: true,
41-
},
42-
],
51+
[/device offline/, ANDROID_ADB_DEVICE_OFFLINE_FAILURE],
4352
[
4453
/more than one (?:device\/emulator|device and emulator)/,
4554
{
@@ -126,6 +135,9 @@ export function classifyAndroidAdbFailure(
126135
): AndroidAdbFailureClassification | undefined {
127136
const stderrText = stderr.toLowerCase();
128137
const stdoutText = stdout.toLowerCase();
138+
if (stdoutText === '' && ADB_DEVICE_OFFLINE_HOST_REFUSAL.test(stderrText.trim())) {
139+
return ANDROID_ADB_DEVICE_OFFLINE_HOST_REFUSAL;
140+
}
129141
for (const [pattern, classification, matchStdout] of ANDROID_ADB_FAILURE_MATCHERS) {
130142
if (pattern.test(stderrText) || (matchStdout && pattern.test(stdoutText))) {
131143
return classification;
@@ -141,7 +153,8 @@ import type { AndroidAdbExecutorResult } from './adb-transport.ts';
141153

142154
/**
143155
* Enriches a failed adb command error in place with the classified hint,
144-
* `retriable` flag, and machine-readable `adbFailure` family, so every adb call
156+
* `retriable` flag, machine-readable `adbFailure` family, and `adbHostRefusal` when the host adb
157+
* refused the command before it reached the device, so every adb call
145158
* site surfaces guidance without per-site classification. Exec-layer timeouts
146159
* classify as `timeout` even though they leave no stderr. No-op for errors that
147160
* are not adb command failures or that carry no recognized failure signal; an
@@ -154,6 +167,7 @@ export function attachAdbFailureHint<T>(error: T): T {
154167
error.details = {
155168
...error.details,
156169
adbFailure: classification.reason,
170+
...(classification.hostRefusal ? { adbHostRefusal: true } : {}),
157171
...(typeof error.details?.hint === 'string' ? {} : { hint: classification.hint }),
158172
...(classification.retriable !== undefined && error.details?.retriable === undefined
159173
? { retriable: classification.retriable }

0 commit comments

Comments
 (0)