Refactor: Update the parameters for DWDS.start

dwds/CHANGELOG.md

@@ -1,4 +1,8 @@
-## 21.1.0-wip
+## 22.0.0-wip
+
+**Breaking changes**
+
+- Refactor the parameters to `Dwds.start`. - [#2231](https://github.com/dart-lang/webdev/pull/2231).
 
 - Update the interface for ChromeProxyService.getSourceReport to match the VM service. - [#2235](https://github.com/dart-lang/webdev/pull/2235)
 

dwds/lib/asset_reader.dart

@@ -3,4 +3,4 @@
 // BSD-style license that can be found in the LICENSE file.
 
 export 'src/readers/asset_reader.dart'
-    show AssetReader, UrlEncoder, PackageUriMapper, stripLeadingSlashes;
+    show AssetReader, PackageUriMapper, stripLeadingSlashes;

dwds/lib/config.dart

@@ -0,0 +1,11 @@
+// Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+export 'src/config/tool_configuration.dart'
+    show
+        AppMetadata,
+        ToolConfiguration,
+        UrlEncoder,
+        DevToolsLauncher,
+        DebugSettings;

dwds/lib/dart_web_debug_service.dart

@@ -5,18 +5,16 @@
 import 'dart:async';
 
 import 'package:dwds/data/build_result.dart';
+import 'package:dwds/src/config/tool_configuration.dart';
 import 'package:dwds/src/connections/app_connection.dart';
 import 'package:dwds/src/connections/debug_connection.dart';
 import 'package:dwds/src/events.dart';
 import 'package:dwds/src/handlers/dev_handler.dart';
 import 'package:dwds/src/handlers/injector.dart';
 import 'package:dwds/src/handlers/socket_connections.dart';
-import 'package:dwds/src/loaders/strategy.dart';
 import 'package:dwds/src/readers/asset_reader.dart';
 import 'package:dwds/src/servers/devtools.dart';
 import 'package:dwds/src/servers/extension_backend.dart';
-import 'package:dwds/src/services/expression_compiler.dart';
-import 'package:dwds/src/utilities/globals.dart';
 import 'package:logging/logging.dart';
 import 'package:shelf/shelf.dart';
 import 'package:sse/server/sse_handler.dart';
@@ -66,36 +64,16 @@ class Dwds {
     required AssetReader assetReader,
     required Stream<BuildResult> buildResults,
     required ConnectionProvider chromeConnection,
-    required LoadStrategy loadStrategy,
-    required bool enableDebugging,
-    // TODO(annagrin): make expressionCompiler argument required
-    // [issue 881](https://github.com/dart-lang/webdev/issues/881)
-    ExpressionCompiler? expressionCompiler,
-    bool enableDebugExtension = false,
-    String hostname = 'localhost',
-    bool useSseForDebugProxy = true,
-    bool useSseForDebugBackend = true,
-    bool useSseForInjectedClient = true,
-    UrlEncoder? urlEncoder,
-    bool spawnDds = true,
-    // TODO(elliette): DevTools is inconsistently capitalized throughout this
-    // file. Change all occurrences of devtools/Devtools to devTools/DevTools.
-    bool enableDevtoolsLaunch = true,
-    DevtoolsLauncher? devtoolsLauncher,
-    bool launchDevToolsInNewWindow = true,
-    bool emitDebugEvents = true,
-    bool isInternalBuild = false,
-    Future<bool> Function()? isFlutterApp,
+    required ToolConfiguration toolConfiguration,
   }) async {
-    globalLoadStrategy = loadStrategy;
-    globalIsInternalBuild = isInternalBuild;
-    isFlutterApp ??= () => Future.value(true);
-
+    globalToolConfiguration = toolConfiguration;
+    final debugSettings = toolConfiguration.debugSettings;
+    final appMetadata = toolConfiguration.appMetadata;
     DevTools? devTools;
     Future<String>? extensionUri;
     ExtensionBackend? extensionBackend;
-    if (enableDebugExtension) {
-      final handler = useSseForDebugBackend
+    if (debugSettings.enableDebugExtension) {
+      final handler = debugSettings.useSseForDebugBackend
           ? SseSocketHandler(
               SseHandler(
                 Uri.parse('/\$debug'),
@@ -108,58 +86,56 @@ class Dwds {
             )
           : WebSocketSocketHandler();
 
-      extensionBackend = await ExtensionBackend.start(handler, hostname);
+      extensionBackend =
+          await ExtensionBackend.start(handler, appMetadata.hostname);
       extensionUri = Future.value(
         Uri(
-          scheme: useSseForDebugBackend ? 'http' : 'ws',
+          scheme: debugSettings.useSseForDebugBackend ? 'http' : 'ws',
           host: extensionBackend.hostname,
           port: extensionBackend.port,
           path: r'$debug',
         ).toString(),
       );
-      if (urlEncoder != null) extensionUri = urlEncoder(await extensionUri);
+      final urlEncoder = debugSettings.urlEncoder;
+      if (urlEncoder != null) {
+        extensionUri = urlEncoder(await extensionUri);
+      }
     }
 
-    final serveDevTools = devtoolsLauncher != null;
-    if (serveDevTools) {
-      devTools = await devtoolsLauncher(hostname);
+    final devToolsLauncher = debugSettings.devToolsLauncher;
+    if (devToolsLauncher != null) {
+      devTools = await devToolsLauncher(appMetadata.hostname);
       final uri =
           Uri(scheme: 'http', host: devTools.hostname, port: devTools.port);
       _logger.info('Serving DevTools at $uri\n');
     }
 
     final injected = DwdsInjector(
-      loadStrategy,
-      useSseForInjectedClient: useSseForInjectedClient,
       extensionUri: extensionUri,
-      enableDevtoolsLaunch: enableDevtoolsLaunch,
-      emitDebugEvents: emitDebugEvents,
-      isInternalBuild: isInternalBuild,
-      isFlutterApp: isFlutterApp,
     );
 
     final devHandler = DevHandler(
       chromeConnection,
       buildResults,
       devTools,
       assetReader,
-      hostname,
+      appMetadata.hostname,
       extensionBackend,
-      urlEncoder,
-      useSseForDebugProxy,
-      useSseForInjectedClient,
-      expressionCompiler,
+      debugSettings.urlEncoder,
+      debugSettings.useSseForDebugProxy,
+      debugSettings.useSseForInjectedClient,
+      debugSettings.expressionCompiler,
       injected,
-      spawnDds,
-      launchDevToolsInNewWindow,
+      debugSettings.spawnDds,
+      debugSettings.launchDevToolsInNewWindow,
     );
 
     return Dwds._(
       injected.middleware,
       devTools,
       devHandler,
       assetReader,
-      enableDebugging,
+      debugSettings.enableDebugging,
     );
   }
 }

dwds/lib/dwds.dart

@@ -3,6 +3,13 @@
 // BSD-style license that can be found in the LICENSE file.
 
 export 'dart_web_debug_service.dart' show Dwds, ConnectionProvider;
+export 'src/config/tool_configuration.dart'
+    show
+        AppMetadata,
+        UrlEncoder,
+        DevToolsLauncher,
+        DebugSettings,
+        ToolConfiguration;
 export 'src/connections/app_connection.dart' show AppConnection;
 export 'src/connections/debug_connection.dart' show DebugConnection;
 export 'src/debugging/metadata/provider.dart'
@@ -17,8 +24,7 @@ export 'src/loaders/frontend_server_require.dart'
 export 'src/loaders/legacy.dart' show LegacyStrategy;
 export 'src/loaders/require.dart' show RequireStrategy;
 export 'src/loaders/strategy.dart' show LoadStrategy, ReloadConfiguration;
-export 'src/readers/asset_reader.dart'
-    show AssetReader, UrlEncoder, PackageUriMapper;
+export 'src/readers/asset_reader.dart' show AssetReader, PackageUriMapper;
 export 'src/readers/frontend_server_asset_reader.dart'
     show FrontendServerAssetReader;
 export 'src/readers/proxy_server_asset_reader.dart' show ProxyServerAssetReader;

dwds/lib/src/config/tool_configuration.dart

@@ -0,0 +1,83 @@
+// Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:dwds/src/loaders/strategy.dart';
+import 'package:dwds/src/servers/devtools.dart';
+import 'package:dwds/src/services/expression_compiler.dart';
+
+/// Configuration about the app, debug settings, and file system.
+///
+/// This is set by the code runner and passed to DWDS on start up.
+class ToolConfiguration {
+  final LoadStrategy loadStrategy;
+  final DebugSettings debugSettings;
+  final AppMetadata appMetadata;
+
+  ToolConfiguration({
+    required this.loadStrategy,
+    required this.debugSettings,
+    required this.appMetadata,
+  });
+}
+
+/// The tool configuration for the connected app.
+///
+/// TODO(elliette): Consider making this final (would require updating tests
+/// that currently depend on changing the configuration between test cases).
+late ToolConfiguration _globalToolConfiguration;
+set globalToolConfiguration(ToolConfiguration configuration) =>
+    _globalToolConfiguration = configuration;
+ToolConfiguration get globalToolConfiguration => _globalToolConfiguration;
+
+/// Metadata for the connected app.
+///
+/// These are set by the code runner and passed to DWDS on start up.
+class AppMetadata {
+  final String hostname;
+  final bool isInternalBuild;
+  Future<bool> Function() isFlutterApp;
+
+  AppMetadata({
+    this.hostname = 'localhost',
+    this.isInternalBuild = false,
+    Future<bool> Function()? isFlutterApp,
+  }) : isFlutterApp = isFlutterApp ?? (() => Future.value(true));
+}
+
+typedef UrlEncoder = Future<String> Function(String url);
+
+typedef DevToolsLauncher = Future<DevTools> Function(String hostname);
+
+/// Debug settings for the connected app.
+///
+/// These are set by the code runner and passed to DWDS on start up.
+class DebugSettings {
+  final bool enableDebugging;
+  final bool enableDebugExtension;
+  final bool useSseForDebugProxy;
+  final bool useSseForDebugBackend;
+  final bool useSseForInjectedClient;
+  final bool spawnDds;
+  final bool enableDevToolsLaunch;
+  final bool launchDevToolsInNewWindow;
+  final bool emitDebugEvents;
+  final DevToolsLauncher? devToolsLauncher;
+  final ExpressionCompiler? expressionCompiler;
+  final UrlEncoder? urlEncoder;
+
+  DebugSettings({
+    this.enableDebugging = true,
+    this.enableDebugExtension = false,
+    this.useSseForDebugProxy = true,
+    this.useSseForDebugBackend = true,
+    this.useSseForInjectedClient = true,
+    this.spawnDds = true,
+    this.enableDevToolsLaunch = true,
+    this.launchDevToolsInNewWindow = true,
+    this.emitDebugEvents = true,
+    this.devToolsLauncher,
+    this.expressionCompiler,
+    this.urlEncoder,
+  });
+}

dwds/lib/src/debugging/classes.dart

@@ -2,10 +2,10 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+import 'package:dwds/src/config/tool_configuration.dart';
 import 'package:dwds/src/debugging/metadata/class.dart';
 import 'package:dwds/src/services/chrome_debug_exception.dart';
 import 'package:dwds/src/utilities/domain.dart';
-import 'package:dwds/src/utilities/globals.dart';
 import 'package:dwds/src/utilities/shared.dart';
 import 'package:vm_service/vm_service.dart';
 import 'package:webkit_inspection_protocol/webkit_inspection_protocol.dart';
@@ -79,7 +79,7 @@ class ClassHelper extends Domain {
 
     final expression = '''
       (function() {
-        const sdk = ${globalLoadStrategy.loadModuleSnippet}('dart_sdk');
+        const sdk = ${globalToolConfiguration.loadStrategy.loadModuleSnippet}('dart_sdk');
         const dart = sdk.dart;
         return dart.getClassMetadata('$libraryUri', '$className');
       })()

dwds/lib/src/debugging/debugger.dart

@@ -4,6 +4,7 @@
 
 import 'dart:async';
 
+import 'package:dwds/src/config/tool_configuration.dart';
 import 'package:dwds/src/debugging/dart_scope.dart';
 import 'package:dwds/src/debugging/frame_computer.dart';
 import 'package:dwds/src/debugging/location.dart';
@@ -12,7 +13,6 @@ import 'package:dwds/src/debugging/skip_list.dart';
 import 'package:dwds/src/services/chrome_debug_exception.dart';
 import 'package:dwds/src/utilities/dart_uri.dart';
 import 'package:dwds/src/utilities/domain.dart';
-import 'package:dwds/src/utilities/globals.dart';
 import 'package:dwds/src/utilities/objects.dart' show Property;
 import 'package:dwds/src/utilities/server.dart';
 import 'package:dwds/src/utilities/shared.dart';
@@ -585,7 +585,9 @@ class Debugger extends Domain {
           throw StateError('Stepping failed in script $scriptId');
         }
 
-        if (url.contains(globalLoadStrategy.loadLibrariesModule)) {
+        if (url.contains(
+          globalToolConfiguration.loadStrategy.loadLibrariesModule,
+        )) {
           await _remoteDebugger.stepOut();
           return;
         } else if ((await _sourceLocation(e)) == null) {

dwds/lib/src/debugging/inspector.dart

@@ -6,6 +6,7 @@ import 'dart:math' as math;
 
 import 'package:async/async.dart';
 import 'package:collection/collection.dart';
+import 'package:dwds/src/config/tool_configuration.dart';
 import 'package:dwds/src/connections/app_connection.dart';
 import 'package:dwds/src/debugging/classes.dart';
 import 'package:dwds/src/debugging/debugger.dart';
@@ -18,7 +19,6 @@ import 'package:dwds/src/readers/asset_reader.dart';
 import 'package:dwds/src/utilities/conversions.dart';
 import 'package:dwds/src/utilities/dart_uri.dart';
 import 'package:dwds/src/utilities/domain.dart';
-import 'package:dwds/src/utilities/globals.dart';
 import 'package:dwds/src/utilities/objects.dart';
 import 'package:dwds/src/utilities/server.dart';
 import 'package:dwds/src/utilities/shared.dart';
@@ -195,7 +195,7 @@ class AppInspector implements AppInspectorInterface {
   Future<RemoteObject> loadField(RemoteObject receiver, String fieldName) {
     final load = '''
         function() {
-          return ${globalLoadStrategy.loadModuleSnippet}("dart_sdk").dart.dloadRepl(this, "$fieldName");
+          return ${globalToolConfiguration.loadStrategy.loadModuleSnippet}("dart_sdk").dart.dloadRepl(this, "$fieldName");
         }
         ''';
     return jsCallFunctionOn(receiver, load, []);
@@ -217,7 +217,7 @@ class AppInspector implements AppInspectorInterface {
     final send = '''
         function () {
           if (!(this.__proto__)) { return 'Instance of PlainJavaScriptObject';}
-          return ${globalLoadStrategy.loadModuleSnippet}("dart_sdk").dart.dsendRepl(this, "$methodName", arguments);
+          return ${globalToolConfiguration.loadStrategy.loadModuleSnippet}("dart_sdk").dart.dsendRepl(this, "$methodName", arguments);
         }
         ''';
     final remote = await jsCallFunctionOn(receiver, send, positionalArgs);
@@ -350,7 +350,7 @@ class AppInspector implements AppInspectorInterface {
     }
     final findLibrary = '''
       (function() {
-        const sdk = ${globalLoadStrategy.loadModuleSnippet}('dart_sdk');
+        const sdk = ${globalToolConfiguration.loadStrategy.loadModuleSnippet}('dart_sdk');
         const dart = sdk.dart;
         const library = dart.getLibrary('$libraryUri');
         if (!library) throw 'cannot find library for $libraryUri';
@@ -637,7 +637,7 @@ class AppInspector implements AppInspectorInterface {
     // want. To make those alternatives easier in JS, pass both count and end.
     final expression = '''
       function (offset, count) {
-        const sdk = ${globalLoadStrategy.loadModuleSnippet}("dart_sdk");
+        const sdk = ${globalToolConfiguration.loadStrategy.loadModuleSnippet}("dart_sdk");
         const dart = sdk.dart;
         return dart.getSubRange(this, offset, count);
       }
@@ -695,7 +695,7 @@ class AppInspector implements AppInspectorInterface {
   /// Returns the list of scripts refs cached.
   Future<List<ScriptRef>> _populateScriptCaches() {
     return _scriptCacheMemoizer.runOnce(() async {
-      final scripts = await globalLoadStrategy
+      final scripts = await globalToolConfiguration.loadStrategy
           .metadataProviderFor(appConnection.request.entrypointPath)
           .scripts;
       // For all the non-dart: libraries, find their parts and create scriptRefs
@@ -746,7 +746,7 @@ class AppInspector implements AppInspectorInterface {
   /// Runs an eval on the page to compute all existing registered extensions.
   Future<List<String>> _getExtensionRpcs() async {
     final expression =
-        "${globalLoadStrategy.loadModuleSnippet}('dart_sdk').developer._extensions.keys.toList();";
+        "${globalToolConfiguration.loadStrategy.loadModuleSnippet}('dart_sdk').developer._extensions.keys.toList();";
     final extensionRpcs = <String>[];
     final params = {
       'expression': expression,