Skip to content

Commit 96a401c

Browse files
authored
[web] Fix hang when Chromium cannot bind remote debugging port (flutter#193461)
When Chromium cannot bind its assigned remote debugging port (e.g. because the port is already in use on loopback), it logs `Cannot start http server for devtools.` to stderr and stays alive without printing `DevTools listening`. Previously, `ChromiumLauncher._spawnChromiumProcess` awaited `devToolsListening.future` indefinitely without a timeout or failure detection, causing `flutter test --platform chrome` and `flutter run -d chrome` to hang indefinitely. Furthermore, the debugging port was selected once before the retry loop, and failed Chrome processes were left alive across retries, causing subsequent attempts to hit Chromium's `SingletonLock` on the profile directory. This change: 1. Detects `Cannot start http server for devtools.` in Chrome stderr to fail fast without waiting. 2. Adds a 30-second timeout backstop (`kDevToolsListeningTimeout`) while waiting for `DevTools listening`. 3. Selects a fresh debugging port on each retry attempt via `findFreePort()`. 4. Immediately sends `process.kill()` to the failed process and awaits its termination before starting the next attempt so that it releases its remote debugging port and profile lock. Fixes flutter#192013 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant in-code documentation (doc comments with `///`). - [ ] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [ ] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.
1 parent 4956c97 commit 96a401c

2 files changed

Lines changed: 187 additions & 23 deletions

File tree

‎packages/flutter_tools/lib/src/web/chrome.dart‎

Lines changed: 68 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,23 @@ const kWindowsEdgeExecutable = r'Microsoft\Edge\Application\msedge.exe';
5252
/// Inconsistency detected by ld.so: ../elf/dl-tls.c: 493: _dl_allocate_tls_init: Assertion `listp->slotinfo[cnt].gen <= GL(dl_tls_generation)' failed!
5353
const _kGlibcError = 'Inconsistency detected by ld.so';
5454

55+
/// Printed by Chromium to stderr when it fails to bind the remote debugging
56+
/// port (e.g. because the port is already taken on both IPv4 and IPv6
57+
/// loopback). Chromium keeps running after this, so it never prints
58+
/// "DevTools listening" and never exits on its own.
59+
///
60+
/// See: https://github.com/flutter/flutter/issues/192013
61+
const _kDevToolsServerFailure = 'Cannot start http server for devtools';
62+
63+
/// How long to wait for Chromium to print "DevTools listening" before giving
64+
/// up on the current launch attempt.
65+
///
66+
/// This is a backstop for failure modes that keep Chromium alive without ever
67+
/// reporting that DevTools is listening. Known failure modes (e.g.
68+
/// [_kDevToolsServerFailure]) are detected eagerly without waiting this long.
69+
@visibleForTesting
70+
const kDevToolsListeningTimeout = Duration(seconds: 30);
71+
5572
/// Filters out non-fatal D-Bus connection error messages emitted by Chromium.
5673
///
5774
/// Headless Linux Chrome attempts to query Linux D-Bus desktop services (such as
@@ -242,8 +259,7 @@ class ChromiumLauncher {
242259
_restoreUserSessionInformation(cacheDir, userDataDir);
243260
}
244261

245-
final int port = debugPort ?? await _operatingSystemUtils.findFreePort();
246-
final args = <String>[
262+
List<String> buildArgs(int port) => <String>[
247263
chromeExecutable,
248264
// Using a tmp directory ensures that a new instance of chrome launches
249265
// allowing for the remote debug port to be enabled.
@@ -299,8 +315,9 @@ class ChromiumLauncher {
299315
url,
300316
];
301317

302-
final _SpawnResult spawnResult = await _spawnChromiumProcess(args, chromeExecutable);
318+
final _SpawnResult spawnResult = await _spawnChromiumProcess(buildArgs, debugPort);
303319
final Process process = spawnResult.process;
320+
final int port = spawnResult.port;
304321

305322
// When the process exits, copy the user settings back to the provided data-dir.
306323
if (cacheDir != null) {
@@ -330,13 +347,23 @@ class ChromiumLauncher {
330347
);
331348
}
332349

333-
Future<_SpawnResult> _spawnChromiumProcess(List<String> args, String chromeExecutable) async {
350+
/// Spawns Chromium, retrying on known failures.
351+
///
352+
/// If [debugPort] is null, a new free port is picked for every attempt, so
353+
/// that losing the race inherent in [OperatingSystemUtils.findFreePort] on one
354+
/// attempt does not doom the following attempts.
355+
Future<_SpawnResult> _spawnChromiumProcess(
356+
List<String> Function(int port) buildArgs,
357+
int? debugPort,
358+
) async {
334359
// Keep attempting to launch the browser until one of:
335360
// - Chrome launched successfully, in which case we just return from the loop.
336361
// - The tool reached the maximum retry count, in which case we throw ToolExit.
337362
const kMaxRetries = 3;
338363
var retry = 0;
339364
while (true) {
365+
final int port = debugPort ?? await _operatingSystemUtils.findFreePort();
366+
final List<String> args = buildArgs(port);
340367
final Process process = await _processManager.start(args);
341368
final logBuffer = ListQueue<String>(200);
342369

@@ -374,6 +401,15 @@ class ChromiumLauncher {
374401
devToolsListening.complete();
375402
}
376403
}
404+
// Chromium stays alive after failing to bind the debugging port, so
405+
// neither "DevTools listening" nor process exit will ever unblock us.
406+
if (line.contains(_kDevToolsServerFailure)) {
407+
if (!devToolsListening.isCompleted) {
408+
devToolsListening.completeError(
409+
Exception('Chrome failed to start the DevTools server on port $port.'),
410+
);
411+
}
412+
}
377413
},
378414
);
379415

@@ -389,13 +425,22 @@ class ChromiumLauncher {
389425
);
390426

391427
try {
392-
await devToolsListening.future;
428+
await devToolsListening.future.timeout(
429+
kDevToolsListeningTimeout,
430+
onTimeout: () => throw Exception(
431+
'Chrome did not report "DevTools listening" within '
432+
'${kDevToolsListeningTimeout.inSeconds} seconds.',
433+
),
434+
);
393435
} on Object catch (error) {
394436
if (retry >= kMaxRetries) {
395437
logBuffer.forEach(_logger.printError);
396438
_logger.printError(
397439
'Failed to launch browser after $kMaxRetries tries. Command used to launch it: ${args.join(' ')}',
398440
);
441+
// The process may still be alive (e.g. DevTools server failure or
442+
// timeout). Don't leave it behind.
443+
process.kill();
399444
throwToolExit(
400445
'Failed to launch browser. Make sure you are using an up-to-date '
401446
'Chrome or Edge. Otherwise, consider using -d web-server instead '
@@ -407,27 +452,26 @@ class ChromiumLauncher {
407452
}
408453

409454
if (!hitGlibcBug && !shouldRetry) {
410-
return _SpawnResult(process, logBuffer.toList());
455+
return _SpawnResult(process, port, logBuffer.toList());
411456
}
412457

413458
retry += 1;
414459

415-
// Clean up subscriptions.
416-
await stdoutSub.cancel();
417-
await stderrSub.cancel();
418-
419-
// A precaution that avoids accumulating browser processes, in case the
420-
// glibc bug doesn't cause the browser to quit and we keep looping and
421-
// launching more processes.
422-
unawaited(
423-
process.exitCode.timeout(
424-
const Duration(seconds: 1),
425-
onTimeout: () {
426-
process.kill();
427-
// sigterm
428-
return 15;
429-
},
430-
),
460+
// Clean up subscriptions. Not awaited: nothing depends on the pipes being
461+
// fully torn down before the next attempt, and cancelling a completed
462+
// subscription can return a root-zone future.
463+
unawaited(stdoutSub.cancel());
464+
unawaited(stderrSub.cancel());
465+
466+
// Terminate the failed browser process so it releases its debugging port
467+
// and profile lock before the next attempt starts.
468+
process.kill();
469+
await process.exitCode.timeout(
470+
const Duration(seconds: 2),
471+
onTimeout: () {
472+
ProcessSignal.sigkill.kill(process);
473+
return 137;
474+
},
431475
);
432476
}
433477
}
@@ -733,7 +777,8 @@ Future<ChromeTab?> getChromeTabGuarded(
733777
}
734778

735779
class _SpawnResult {
736-
_SpawnResult(this.process, this.logBuffer);
780+
_SpawnResult(this.process, this.port, this.logBuffer);
737781
final Process process;
782+
final int port;
738783
final List<String> logBuffer;
739784
}

‎packages/flutter_tools/test/web.shard/chrome_test.dart‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -835,6 +835,115 @@ DevTools listening on ws://127.0.0.1:12345/devtools/browser/
835835
expect(logger.errorText, contains('nothing in the std error indicating glibc error'));
836836
});
837837

838+
group('Chrome stays alive without reporting DevTools listening', () {
839+
// Regression tests for https://github.com/flutter/flutter/issues/192013.
840+
const devToolsServerFailureStderr =
841+
'[ERROR:net/socket/socket_posix.cc:153] bind() failed: Address already in use (48)\n'
842+
'[ERROR:content/browser/devtools/devtools_http_handler.cc:313] '
843+
'Cannot start http server for devtools.\n';
844+
845+
List<String> headlessArgs(int port) => <String>[
846+
'example_chrome',
847+
'--user-data-dir=/.tmp_rand0/flutter_tools_chrome_device.rand0',
848+
'--remote-debugging-port=$port',
849+
...kChromeArgs,
850+
'--no-sandbox',
851+
'--headless',
852+
'--window-size=1024,1024',
853+
'example_url',
854+
];
855+
856+
ChromiumLauncher createLauncher(OperatingSystemUtils osUtils, Logger logger) {
857+
return ChromiumLauncher(
858+
fileSystem: fileSystem,
859+
platform: platform,
860+
processManager: processManager,
861+
operatingSystemUtils: osUtils,
862+
browserFinder: findChromeExecutable,
863+
logger: logger,
864+
);
865+
}
866+
867+
testWithoutContext('retries on a fresh port when the DevTools server fails to start', () async {
868+
// A Chrome that never exits on its own.
869+
final neverExits = Completer<void>();
870+
processManager.addCommand(
871+
FakeCommand(
872+
command: headlessArgs(12345),
873+
stderr: devToolsServerFailureStderr,
874+
completer: neverExits,
875+
),
876+
);
877+
processManager.addCommand(FakeCommand(command: headlessArgs(12346), stderr: kDevtoolsStderr));
878+
879+
final ChromiumLauncher launcher = createLauncher(
880+
_SequentialPortOperatingSystemUtils(12345),
881+
BufferLogger.test(),
882+
);
883+
final Chromium chrome = await launcher.launch('example_url', skipCheck: true, headless: true);
884+
885+
expect(chrome.debugPort, 12346);
886+
expect(processManager, hasNoRemainingExpectations);
887+
});
888+
889+
testWithoutContext('gives up when the DevTools server repeatedly fails to start', () async {
890+
final neverExits = Completer<void>();
891+
for (var i = 0; i < 4; i++) {
892+
processManager.addCommand(
893+
FakeCommand(
894+
command: headlessArgs(12345),
895+
stderr: devToolsServerFailureStderr,
896+
completer: neverExits,
897+
),
898+
);
899+
}
900+
901+
final logger = BufferLogger.test();
902+
await expectToolExitLater(
903+
createLauncher(
904+
operatingSystemUtils,
905+
logger,
906+
).launch('example_url', skipCheck: true, headless: true, debugPort: 12345),
907+
contains('Chrome failed to start the DevTools server on port 12345.'),
908+
);
909+
expect(logger.errorText, contains('Cannot start http server for devtools'));
910+
expect(processManager, hasNoRemainingExpectations);
911+
});
912+
913+
testWithoutContext('times out when Chrome never reports DevTools listening', () async {
914+
final neverExits = Completer<void>();
915+
for (var i = 0; i < 4; i++) {
916+
processManager.addCommand(
917+
FakeCommand(command: headlessArgs(12345), stderr: 'unrelated', completer: neverExits),
918+
);
919+
}
920+
921+
// Results are captured inside the FakeAsync zone: futures completed there
922+
// deliver their callbacks via FakeAsync's microtask queue, so awaiting
923+
// them from outside would never complete.
924+
Object? error;
925+
var completed = false;
926+
FakeAsync().run((FakeAsync time) {
927+
createLauncher(operatingSystemUtils, BufferLogger.test())
928+
.launch('example_url', skipCheck: true, headless: true)
929+
.then<void>((_) => completed = true, onError: (Object e) => error = e);
930+
for (var i = 0; i < 4; i++) {
931+
time.flushMicrotasks();
932+
expect(error, isNull, reason: 'attempt ${i + 1} should still be waiting');
933+
time.elapse(kDevToolsListeningTimeout + const Duration(seconds: 2));
934+
}
935+
time.flushMicrotasks();
936+
});
937+
938+
expect(completed, isFalse);
939+
await expectToolExitLater(
940+
Future<void>.error(error!),
941+
contains('Chrome did not report "DevTools listening" within'),
942+
);
943+
expect(processManager, hasNoRemainingExpectations);
944+
});
945+
});
946+
838947
testWithoutContext('Logs an error and exits if connection check fails.', () async {
839948
final logger = BufferLogger.test();
840949
final chromiumLauncher = ChromiumLauncher(
@@ -1186,3 +1295,13 @@ class FakeWipConnection extends Fake implements WipConnection {
11861295
}
11871296
}
11881297
}
1298+
1299+
/// Returns [_nextPort], [_nextPort] + 1, ... on successive [findFreePort] calls.
1300+
class _SequentialPortOperatingSystemUtils extends FakeOperatingSystemUtils {
1301+
_SequentialPortOperatingSystemUtils(this._nextPort);
1302+
1303+
int _nextPort;
1304+
1305+
@override
1306+
Future<int> findFreePort({bool ipv6 = false}) async => _nextPort++;
1307+
}

0 commit comments

Comments
 (0)