[ DWDS ] Serve DevTools from DDS by default (#2681)

In order to reduce the number of ways DevTools is served across the
ecosystem, we're working on serving DevTools from DDS by default in all
tools that spawn DDS.

This change exposes some new DDS related configuration options that
allow for specifying whether or not DevTools should be served via DDS
and whether or not an existing DevTools server should be used.

The `devToolsLauncher` parameter has been marked as deprecated as it
will be removed in a future major release, but will continue to act as
the default way to launch DevTools if it is provided. Other DDS related
properties that have been merged into the new
`DartDevelopmentServiceConfiguration` class are also marked as
deprecated.

Author: bkonyi

dwds/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 25.1.0
+
+- Added `DartDevelopmentServiceConfiguration` to allow for configuring DDS behavior.
+- Added support for serving DevTools via DDS. This will become the sole method of serving
+  DevTools from DWDS in a future major release.
+- Deprecated `spawnDds`, `ddsPort`, and `devToolsLauncher` properties in `DebugSettings`.
+- Added `ddsConfiguration` to `DebugSettings`.
+
 ## 25.0.4
 
 ### Bug Fixes:

dwds/lib/dart_web_debug_service.dart

@@ -115,15 +115,20 @@ class Dwds {
       }
     }
 
+    // TODO(bkonyi): only allow for serving DevTools via DDS.
+    // ignore: deprecated_member_use_from_same_package
     final devToolsLauncher = debugSettings.devToolsLauncher;
-    if (devToolsLauncher != null) {
+    Uri? launchedDevToolsUri;
+    if (devToolsLauncher != null &&
+        // If DDS is configured to serve DevTools, use its instance.
+        !debugSettings.ddsConfiguration.serveDevTools) {
       devTools = await devToolsLauncher(appMetadata.hostname);
-      final uri = Uri(
+      launchedDevToolsUri = Uri(
         scheme: 'http',
         host: devTools.hostname,
         port: devTools.port,
       );
-      _logger.info('Serving DevTools at $uri\n');
+      _logger.info('Serving DevTools at $launchedDevToolsUri\n');
     }
 
     final injected = DwdsInjector(extensionUri: extensionUri);
@@ -140,8 +145,17 @@ class Dwds {
       debugSettings.useSseForInjectedClient,
       debugSettings.expressionCompiler,
       injected,
-      debugSettings.spawnDds,
-      debugSettings.ddsPort,
+      DartDevelopmentServiceConfiguration(
+        // This technically isn't correct, but DartDevelopmentServiceConfiguration.enable
+        // is true by default, so this won't break unmigrated tools.
+        // ignore: deprecated_member_use_from_same_package
+        enable: debugSettings.spawnDds && debugSettings.ddsConfiguration.enable,
+        // ignore: deprecated_member_use_from_same_package
+        port: debugSettings.ddsPort ?? debugSettings.ddsConfiguration.port,
+        devToolsServerAddress:
+            launchedDevToolsUri ??
+            debugSettings.ddsConfiguration.devToolsServerAddress,
+      ),
       debugSettings.launchDevToolsInNewWindow,
       useWebSocketConnection: useDwdsWebSocketConnection,
     );

dwds/lib/dwds.dart

@@ -7,6 +7,7 @@ export 'src/config/tool_configuration.dart'
     show
         AppMetadata,
         UrlEncoder,
+        DartDevelopmentServiceConfiguration,
         DevToolsLauncher,
         DebugSettings,
         ToolConfiguration;

dwds/lib/src/config/tool_configuration.dart

@@ -51,6 +51,20 @@ typedef UrlEncoder = Future<String> Function(String url);
 
 typedef DevToolsLauncher = Future<DevTools> Function(String hostname);
 
+class DartDevelopmentServiceConfiguration {
+  const DartDevelopmentServiceConfiguration({
+    this.enable = true,
+    this.port,
+    this.serveDevTools = true,
+    this.devToolsServerAddress,
+  });
+
+  final bool enable;
+  final int? port;
+  final bool serveDevTools;
+  final Uri? devToolsServerAddress;
+}
+
 /// Debug settings for the connected app.
 ///
 /// These are set by the code runner and passed to DWDS on start up.
@@ -60,28 +74,41 @@ class DebugSettings {
   final bool useSseForDebugProxy;
   final bool useSseForDebugBackend;
   final bool useSseForInjectedClient;
+
+  @Deprecated('Use ddsConfiguration instead.')
   final bool spawnDds;
+  @Deprecated('Use ddsConfiguration instead.')
   final int? ddsPort;
   final bool enableDevToolsLaunch;
   final bool launchDevToolsInNewWindow;
   final bool emitDebugEvents;
+  @Deprecated(
+    'Use ddsConfigurationInstead. DevTools will eventually only be '
+    'served via DDS.',
+  )
   final DevToolsLauncher? devToolsLauncher;
   final ExpressionCompiler? expressionCompiler;
   final UrlEncoder? urlEncoder;
+  final DartDevelopmentServiceConfiguration ddsConfiguration;
 
   const DebugSettings({
     this.enableDebugging = true,
     this.enableDebugExtension = false,
     this.useSseForDebugProxy = true,
     this.useSseForDebugBackend = true,
     this.useSseForInjectedClient = true,
-    this.spawnDds = true,
-    this.ddsPort,
+    @Deprecated('Use ddsConfiguration instead.') this.spawnDds = true,
+    @Deprecated('Use ddsConfiguration instead.') this.ddsPort,
     this.enableDevToolsLaunch = true,
     this.launchDevToolsInNewWindow = true,
     this.emitDebugEvents = true,
+    @Deprecated(
+      'Use ddsConfigurationInstead. DevTools will eventually only be '
+      'served via DDS.',
+    )
     this.devToolsLauncher,
     this.expressionCompiler,
     this.urlEncoder,
+    this.ddsConfiguration = const DartDevelopmentServiceConfiguration(),
   });
 }

dwds/lib/src/connections/debug_connection.dart

@@ -35,9 +35,12 @@ class DebugConnection {
   /// The endpoint of the Dart VM Service.
   String get uri => _appDebugServices.debugService.uri;
 
-  // The endpoint of the Dart Development Service (DDS).
+  /// The endpoint of the Dart Development Service (DDS).
   String? get ddsUri => _appDebugServices.ddsUri?.toString();
 
+  /// The endpoint of the Dart DevTools instance.
+  String? get devToolsUri => _appDebugServices.devToolsUri?.toString();
+
   /// A client of the Dart VM Service with DWDS specific extensions.
   VmService get vmService => _appDebugServices.dwdsVmClient.client;
 

dwds/lib/src/handlers/dev_handler.dart

@@ -6,6 +6,8 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
+import 'package:collection/collection.dart';
+import 'package:dds/dds_launcher.dart';
 import 'package:dwds/data/build_result.dart';
 import 'package:dwds/data/connect_request.dart';
 import 'package:dwds/data/debug_event.dart';
@@ -70,8 +72,7 @@ class DevHandler {
   final UrlEncoder? _urlEncoder;
   final bool _useSseForDebugProxy;
   final bool _useSseForInjectedClient;
-  final bool _spawnDds;
-  final int? _ddsPort;
+  final DartDevelopmentServiceConfiguration _ddsConfig;
   final bool _launchDevToolsInNewWindow;
   final ExpressionCompiler? _expressionCompiler;
   final DwdsInjector _injected;
@@ -97,8 +98,8 @@ class DevHandler {
     this._useSseForInjectedClient,
     this._expressionCompiler,
     this._injected,
-    this._spawnDds,
-    this._ddsPort,
+
+    this._ddsConfig,
     this._launchDevToolsInNewWindow, {
     this.useWebSocketConnection = false,
   }) {
@@ -251,8 +252,7 @@ class DevHandler {
       // This will provide a websocket based service.
       useSse: false,
       expressionCompiler: _expressionCompiler,
-      spawnDds: _spawnDds,
-      ddsPort: _ddsPort,
+      ddsConfig: _ddsConfig,
     );
   }
 
@@ -451,7 +451,7 @@ class DevHandler {
     AppConnection appConnection,
     SocketConnection sseConnection,
   ) async {
-    if (_devTools == null) {
+    if (_devTools == null && !_ddsConfig.serveDevTools) {
       sseConnection.sink.add(
         jsonEncode(
           serializers.serialize(
@@ -548,6 +548,7 @@ class DevHandler {
       await _launchDevTools(
         chromeProxy.remoteDebugger,
         _constructDevToolsUri(
+          appServices,
           appServices.debugService.uri,
           ideQueryParam: 'Dwds',
         ),
@@ -853,21 +854,21 @@ class DevHandler {
     ChromeDebugService debugService,
   ) async {
     final dwdsStats = DwdsStats();
-    Uri? ddsUri;
-    if (_spawnDds) {
-      final dds = await debugService.startDartDevelopmentService();
-      ddsUri = dds.wsUri;
+    DartDevelopmentServiceLauncher? dds;
+    if (_ddsConfig.enable) {
+      dds = await debugService.startDartDevelopmentService();
     }
     final vmClient = await ChromeDwdsVmClient.create(
       debugService,
       dwdsStats,
-      ddsUri,
+      dds?.wsUri,
     );
     final appDebugService = ChromeAppDebugServices(
       debugService,
       vmClient,
       dwdsStats,
-      ddsUri,
+      dds?.wsUri,
+      dds?.devToolsUri,
     );
     final encodedUri = await debugService.encodedUri;
     _logger.info('Debug service listening on $encodedUri\n');
@@ -985,8 +986,7 @@ class DevHandler {
         },
         useSse: _useSseForDebugProxy,
         expressionCompiler: _expressionCompiler,
-        spawnDds: _spawnDds,
-        ddsPort: _ddsPort,
+        ddsConfig: _ddsConfig,
       );
       appServices = await _createAppDebugServices(debugService);
       extensionDebugger.sendEvent('dwds.debugUri', debugService.uri);
@@ -1026,27 +1026,17 @@ class DevHandler {
     emitEvent(DwdsEvent.devtoolsLaunch());
     // Send the DevTools URI to the Dart Debug Extension so that it can open it:
     final devToolsUri = _constructDevToolsUri(
+      appServices,
       encodedUri,
       ideQueryParam: 'ChromeDevTools',
     );
     return extensionDebugger.sendEvent('dwds.devtoolsUri', devToolsUri);
   }
 
-  DevTools _ensureDevTools() {
-    final devTools = _devTools;
-    if (devTools == null) {
-      throw StateError('DevHandler: DevTools is not available');
-    }
-    return devTools;
-  }
-
   Future<void> _launchDevTools(
     RemoteDebugger remoteDebugger,
     String devToolsUri,
   ) async {
-    // TODO(annagrin): move checking whether devtools should be started
-    // and the creation of the uri logic here so it is easier to follow.
-    _ensureDevTools();
     // TODO(grouma) - We may want to log the debugServiceUri if we don't launch
     // DevTools so that users can manually connect.
     emitEvent(DwdsEvent.devtoolsLaunch());
@@ -1057,20 +1047,28 @@ class DevHandler {
   }
 
   String _constructDevToolsUri(
-    String debugServiceUri, {
+    AppDebugServices appDebugServices,
+    String serviceUri, {
     String ideQueryParam = '',
   }) {
-    final devTools = _ensureDevTools();
-    return Uri(
-      scheme: 'http',
-      host: devTools.hostname,
-      port: devTools.port,
-      path: 'debugger',
-      queryParameters: {
-        'uri': debugServiceUri,
-        if (ideQueryParam.isNotEmpty) 'ide': ideQueryParam,
-      },
-    ).toString();
+    final devToolsUri = _devTools?.uri ?? appDebugServices.devToolsUri;
+    if (devToolsUri == null) {
+      throw StateError('DevHandler: DevTools is not available');
+    }
+    return devToolsUri
+        .replace(
+          pathSegments: [
+            // Strips any trailing slashes from the original path
+            ...devToolsUri.pathSegments.whereNot((e) => e.isEmpty),
+            'debugger',
+          ],
+          queryParameters: {
+            ...devToolsUri.queryParameters,
+            'uri': serviceUri,
+            if (ideQueryParam.isNotEmpty) 'ide': ideQueryParam,
+          },
+        )
+        .toString();
   }
 
   static void _maybeEmitDwdsAttachEvent(DevToolsRequest request) {

dwds/lib/src/injected/client.js

@@ -10,6 +10,8 @@ class DevTools {
   final int port;
   final HttpServer _server;
 
+  Uri get uri => Uri(scheme: 'http', host: hostname, port: port);
+
   /// Null until [close] is called.
   ///
   /// All subsequent calls to [close] will return this future.

dwds/lib/src/servers/devtools.dart

@@ -13,6 +13,7 @@ abstract class AppDebugServices {
   DwdsVmClient get dwdsVmClient;
   DwdsStats? get dwdsStats;
   Uri? get ddsUri;
+  Uri? get devToolsUri;
   String? get connectedInstanceId;
   set connectedInstanceId(String? id);
   Future<void> close();
@@ -25,6 +26,7 @@ class ChromeAppDebugServices implements AppDebugServices {
   final ChromeDwdsVmClient _dwdsVmClient;
   final DwdsStats _dwdsStats;
   final Uri? _ddsUri;
+  final Uri? _devToolsUri;
   Future<void>? _closed;
   String? _connectedInstanceId;
 
@@ -33,6 +35,7 @@ class ChromeAppDebugServices implements AppDebugServices {
     this._dwdsVmClient,
     this._dwdsStats,
     this._ddsUri,
+    this._devToolsUri,
   );
 
   @override
@@ -47,6 +50,9 @@ class ChromeAppDebugServices implements AppDebugServices {
   @override
   Uri? get ddsUri => _ddsUri;
 
+  @override
+  Uri? get devToolsUri => _devToolsUri;
+
   @override
   String? get connectedInstanceId => _connectedInstanceId;
 
@@ -81,7 +87,10 @@ class WebSocketAppDebugServices implements AppDebugServices {
   @override
   DwdsStats? get dwdsStats => null;
   @override
+  // TODO(bkonyi): DDS should still start in WebSocket mode.
   Uri? get ddsUri => null;
+  @override
+  Uri? get devToolsUri => null;
 
   @override
   ProxyService get proxyService => _debugService.webSocketProxyService;