Support running DWDS without a Chrome Debug Port (web-socket-based) #2639

jyameo · 2025-06-26T18:15:13Z

Implemented a WebSocket-based communication protocol that provides essential developer tooling (hot reload, service extensions) when Chrome debugger access is unavailable. - #2605
Added WebSocket-based hot reload and service extension support via new WebSocketProxyService class that implements VM service protocol over WebSockets.
Created new files: WebSocketProxyService, WebSocketDebugService, WebSocketAppDebugServices, and WebSocketDwdsVmClient to support socket-based DWDS functionality.
Enhanced DevHandler with useWebSocketConnection flag to toggle between Chrome-based and WebSocket-based communication protocols.

Required Flutter Tools changes: flutter/flutter#171648

dwds/CHANGELOG.md

biggs0125 · 2025-07-18T19:27:53Z

dwds/lib/data/service_extension_request.dart

As a follow-up (in a different change) should we update the ChromeProxyService to also use this Built object for service extensions?

The ChromeProxyService leverages the inspector to evaluate JavaScript expressions via invokeExtensionJsExpression (as seen in the _callServiceExtension method). This pattern is consistently used throughout ChromeProxyService for all interactions with the dartDevEmbedder. It evaluates JavaScript expressions directly in the browser context rather than sending structured messages. Since ChromeProxyService operates by executing JavaScript in the browser, using a Built object here wouldn't align with ChromeProxyService's JavaScript evaluation approach. The current pattern maintains consistency with how ChromeProxyService handles all other browser interactions.

biggs0125 · 2025-07-19T06:17:34Z

dwds/lib/src/connections/debug_connection.dart

+        remoteDebugger.onClose.first.then((_) => close());
+      }
+    } catch (_) {
+      // Chrome proxy service not available in WebSocket-only mode - ignore


What exceptions are we now catching and ignoring here?

If we're in "websocket-only mode" (does this mean -d web-server?) then I would expect the debugger to never even be connected. But if we're not in websocket-only mode (-d chrome?) then it seems like it should at least be a warning if we get an exception here.

Can you add more context on what this is doing?

This was because we were throwing an UnsupportedError in the web_socket_app_debug_services when accessing chromeProxyService. I have changed the logic to return null instead, so we can now simply do: _appDebugServices.chromeProxyService?.remoteDebugger.onClose.first.then((_) { close(); });

~~I believe there could be a debugger connected when in "web-server" mode after the application starts if the user manually connects it using the Dart DevTools chrome extension.~~

Actually now I think I agree, what errors are we swallowing here?

Initially, the UnsupportedError was being thrown when accessing chromeProxyService from web_socket_app_debug_services, which isn't supposed to happen since that service doesn’t support Chrome debugging. I’ve since refactored the code so both app_debug_services and web_socket_app_debug_services implement a common interface. As part of that, chromeProxyService has been removed in favour of a unified proxyService interface, which can be type-checked as needed.

biggs0125 · 2025-07-19T06:20:24Z

dwds/lib/src/connections/debug_connection.dart

@@ -22,9 +22,20 @@ class DebugConnection {
  Future<void>? _closed;

  DebugConnection(this._appDebugServices) {
-    _appDebugServices.chromeProxyService.remoteDebugger.onClose.first.then((_) {


Can this all just be:

_appDebugServices.chromeProxyService?.remoteDebugger.onClose.first.then((_) { close(); });

All the new code here looks to be doing all the same checks as close below.

Done! I've simplified the constructor now

biggs0125 · 2025-07-19T06:23:39Z

dwds/lib/src/handlers/dev_handler.dart

      } on StateError catch (e) {
        // The sink has already closed (app is disconnected), or another StateError occurred.
        _logger.warning(
-          'Failed to send request to client, connection likely closed. Error: $e',
+          'Failed to send request to client ${injectedConnection.hashCode}, '


Does the hashCode actually add any information to these messages? I'm assuming the injected clients don't override hashCode so it'll just be a random number every time.

Ah yes, you are right! I was using the hashCode as a simple way to differentiate between multiple connections in log messages, but it's not very useful since there is no persistence and it's hard to track.

dwds/lib/src/services/app_debug_services.dart

dwds/lib/src/services/web_socket_debug_service.dart

dwds/lib/src/services/web_socket_proxy_service.dart

dwds/lib/src/web_socket_dwds_vm_client.dart

dwds/lib/src/connections/debug_connection.dart

nshahan · 2025-07-21T17:50:42Z

dwds/web/reloader/manager.dart

+  Future<Map<String, dynamic>?> handleServiceExtension(
+    String method,
+    Map<String, dynamic> args,
+  ) async {


Is there a missing await somewhere in this method?

Good catch! thanks

srujzs · 2025-07-21T19:14:52Z

dwds/lib/src/handlers/dev_handler.dart

+      await webSocketProxyService.isInitialized;
+      _logger.fine('WebSocket proxy service initialized successfully');
+    } else {
+      _logger.warning('WebSocket proxy service is null');


Is there ever an instance where this is okay? Should we throw/assert instead? Similar question below.

good catch! I have updated the code to use try/catch/throw instead!

srujzs · 2025-07-21T19:40:52Z

dwds/lib/src/services/web_socket_proxy_service.dart

+          appConnection.runMain();
+          _mainHasStarted = true;
+        } catch (e) {
+          if (e.toString().contains('Main has already started')) {


Do we need to catch this? I would assume the check on line 900 prevents this from occurring.

Yes, the try/catch block is needed here to handle race conditions where multiple concurrent resume() calls can pass the if (!_mainHasStarted) check before any of them complete and set _mainHasStarted = true

dwds/web/reloader/ddc_library_bundle_restarter.dart

…default createIsolate and destroyIsolate in ProxyService

…type

nshahan · 2025-07-23T18:09:46Z

dwds/lib/src/services/app_debug_services.dart

-  ///
-  /// All subsequent calls to [close] will return this future.
+/// Chrome-based debug services container.
+class AppDebugServices implements IAppDebugServices {


Would it make sense to name this ChromeAppDebugServices and the interface AppDebugServices?

That's a good idea. I have updated the name for the classes and interface to be more clear.

dwds/lib/src/services/debug_service.dart

nshahan · 2025-07-23T18:12:58Z

dwds/lib/src/services/debug_service.dart

+          port: port,
+          path: authToken,
+        ),
+        serviceUri: Uri(scheme: 'http', host: hostname, port: ddsPort ?? 0),


Is 0 a valid default port realistically? Does it make sense to require a ddsPort so we don't need to try and pick a default here?

this is what we have been doing for chrome previous to my changes so I kept the existing behavior

nshahan · 2025-07-23T18:14:35Z

dwds/lib/src/services/debug_service.dart

+      webSocketProxyService,
+    );
+
+    final server = await startHttpServer(hostname, port: 0);


Similar question here. Why are we using port: 0?

Ah! Good catch here. I updated this to be port: 44456 which is what we currently have for chrome

nshahan

Thanks @jyameo! Pending final round of reviews but LGTM.

biggs0125 · 2025-07-23T22:35:00Z

dwds/lib/src/services/debug_service.dart

 /// A Dart Web Debug Service.
 ///
 /// Creates a [ChromeProxyService] from an existing Chrome instance.
-class DebugService {
+class ChromeDebugService implements DebugService {
  static String? _ddsUri;

  final VmServiceInterface chromeProxyService;


It seems like this should be typed as ChromeProxyService chromeProxyService

biggs0125 · 2025-07-23T22:35:34Z

dwds/lib/src/services/app_debug_services.dart

+
+  @override
+  ProxyService get proxyService =>
+      debugService.chromeProxyService as ChromeProxyService;


See below, think we can get rid of this cast.

biggs0125 · 2025-07-23T22:37:12Z

dwds/lib/src/services/app_debug_services.dart

+  final WebSocketDebugService _debugService;
+  final WebSocketDwdsVmClient _dwdsVmClient;
+  Future<void>? _closed;
+  String? _connectedInstanceId;


You should just be able to change this to:

@override String? connectedInstanceId;

and get rid of the getter and setter below.

jyameo added 3 commits June 26, 2025 12:00

implemented socket-based dwds

1fe0895

fix issue with run main at start

2707a41

updated changelog

489dbcc

github-actions bot added the package:dwds label Jun 26, 2025

simulate debugExtension in websocket-based execution flow

a4e0dd0

nshahan mentioned this pull request Jun 30, 2025

Hot restart is broken when running DWDS without Chrome Debug Port #2642

Open

jyameo mentioned this pull request Jul 2, 2025

Support running DWDS without a Chrome Debug Port #2605

Open

1 task

jyameo added 10 commits July 11, 2025 14:30

added multiwindow support

412bda3

refactoring and removing unused method

8f7c645

support page refresh from vsCode

91c7b41

refactor createisolate and resume method

871f388

implemented pause/resume logic

d7dad51

improve canReuseConnection logic

6f40567

comments cleanup

b4d5cb1

fixed canReuseConnection logic

0edf3d8

implemented _handleConnectionClosed and fix issue with getVM

340baad

fix issue with handling isolate cleanup

fa5feb0

jyameo requested review from srujzs and nshahan July 18, 2025 19:12

biggs0125 requested changes Jul 20, 2025

View reviewed changes

jyameo added 3 commits July 21, 2025 12:06

6ba7f5b

addressed comments regarding closing remoteDebugger

afe9fc9

code cleanup

18617bd

nshahan reviewed Jul 21, 2025

View reviewed changes

created common interface for debugService and webSocketDebugService

32f165e

srujzs reviewed Jul 21, 2025

View reviewed changes

jyameo added 4 commits July 22, 2025 10:39

remove use of _acceptNewConnections in WebSocketDebugService

49b234a

created proxy_service.dart and consolidated all duplicated code

af9763f

consolidate webSocketAppDebugService and AppDebugServices

a61bde1

consolidate dwdsVmClient and WebSocketDwdsVmClient

813765e

jyameo added 7 commits July 22, 2025 14:47

refactored can remove duplicate methods

14e2a2a

remove use of dynamic

dea7f56

fix dev_handler error

5340ab0

consolidate handleChromeMessages and handleWebSocketMessages created …

be31caa

…default createIsolate and destroyIsolate in ProxyService

updated logg message in _sendRequestToClients

cf526af

updated dev_handler to throw error if proxy_service is not the right …

4937508

…type

Merge branch 'main' into websocketproxyservice

8bce65a

jyameo requested review from biggs0125, srujzs and nshahan July 23, 2025 15:35

addressing analyzer issues

3d0d4ea

nshahan reviewed Jul 23, 2025

View reviewed changes

jyameo added 4 commits July 23, 2025 14:26

removed unused variable

3e919ce

updated port to 44456

cd5b810

refactored classes to and interface names to be more clear

1c55263

fix variable name error

956c323

jyameo requested a review from nshahan July 23, 2025 19:03

nshahan approved these changes Jul 23, 2025

View reviewed changes

biggs0125 approved these changes Jul 23, 2025

View reviewed changes

updated variable to be type

fb5057b

Support running DWDS without a Chrome Debug Port (web-socket-based) #2639

Are you sure you want to change the base?

Support running DWDS without a Chrome Debug Port (web-socket-based) #2639

Uh oh!

Conversation

jyameo commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nshahan Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nshahan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jyameo commented Jun 26, 2025 •

edited

Loading

nshahan Jul 21, 2025 •

edited

Loading