Public API to support Flutter CLI (#483)

- Rename `dwds/lib/service.dart` to `dwds/lib/src/services/debug_service.dart`
- Move `chrome_proxy_service.dart` and `app_debug_services.dart` to `dwds/lib/src/services`
- Rename `DevConnection` to `AppConnection` and promote as a public abstraction
- Create new public `DebugConnection` abstraction
- Create new public entrypoint `dwds.dart`
  - This entrypoint exposes a `handler` to be used with shelf (see changes to `webdev`)
- Update `webdev` to no longer import from `dwds`'s source

This mostly completes #475. In a follow up PR I'll shuffle the tests around so there is a better separation between `webdev` and `dwds` tests.

cc @jonahwilliams

Author: grouma

dwds/CHANGELOG.md

@@ -3,6 +3,8 @@
 - Move `data` abstractions from `package:webdev` into `package:dwds`.
 - Move debugging related handlers from `package:webdev` into `package:dwds`.
 - Move injected client from `package:webdev` into `package:dwds`.
+- Create new public entrypoint `dwds.dart`. Existing public API `services.dart`
+  is now private.
 
 ## 0.3.3
 

dwds/lib/dwds.dart

@@ -0,0 +1,91 @@
+// Copyright (c) 2019, 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 'dart:async';
+
+import 'package:build_daemon/data/build_status.dart';
+import 'package:logging/logging.dart';
+import 'package:meta/meta.dart';
+import 'package:shelf/shelf.dart';
+import 'package:webkit_inspection_protocol/webkit_inspection_protocol.dart';
+
+import 'src/connections/app_connection.dart';
+import 'src/connections/debug_connection.dart';
+import 'src/devtools.dart';
+import 'src/handlers/asset_handler.dart';
+import 'src/handlers/dev_handler.dart';
+import 'src/handlers/injected_handler.dart';
+
+export 'src/connections/app_connection.dart' show AppConnection;
+export 'src/connections/debug_connection.dart' show DebugConnection;
+
+typedef LogWriter = void Function(Level, String);
+typedef ConnectionProvider = Future<ChromeConnection> Function();
+enum ReloadConfiguration { none, hotReload, hotRestart, liveReload }
+
+/// The Dart Web Debug Service.
+class Dwds {
+  final Handler handler;
+  final DevTools _devTools;
+  final DevHandler _devHandler;
+
+  Dwds._(this.handler, this._devTools, this._devHandler);
+
+  Stream<AppConnection> get connectedApps => _devHandler.connectedApps;
+
+  Future<void> stop() async {
+    await _devTools?.close();
+    await _devHandler.close();
+  }
+
+  Future<DebugConnection> debugConnection(AppConnection appConnection) async {
+    var appDebugServices = await _devHandler.loadAppServices(
+        appConnection.request.appId, appConnection.request.instanceId);
+    return DebugConnection(appDebugServices);
+  }
+
+  static Future<Dwds> start({
+    @required String hostname,
+    @required int applicationPort,
+    @required int assetServerPort,
+    @required String applicationTarget,
+    @required ReloadConfiguration reloadConfiguration,
+    @required Stream<BuildResult> buildResults,
+    @required ConnectionProvider chromeConnection,
+    @required bool serveDevTools,
+    @required LogWriter logWriter,
+    @required bool verbose,
+  }) async {
+    var assetHandler = AssetHandler(
+      assetServerPort,
+      applicationTarget,
+      hostname,
+      applicationPort,
+    );
+    var cascade = Cascade();
+    var pipeline = const Pipeline();
+
+    pipeline =
+        pipeline.addMiddleware(createInjectedHandler(reloadConfiguration));
+
+    DevTools devTools;
+    if (serveDevTools) {
+      devTools = await DevTools.start(hostname);
+      logWriter(Level.INFO,
+          'Serving DevTools at http://${devTools.hostname}:${devTools.port}\n');
+    }
+    var devHandler = DevHandler(
+      chromeConnection,
+      buildResults,
+      devTools,
+      assetHandler,
+      hostname,
+      verbose,
+      logWriter,
+    );
+    cascade = cascade.add(devHandler.handler).add(assetHandler.handler);
+
+    return Dwds._(pipeline.addHandler(cascade.handler), devTools, devHandler);
+  }
+}

dwds/lib/src/connections/app_connection.dart

@@ -0,0 +1,28 @@
+// Copyright (c) 2019, 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 'dart:convert';
+
+import 'package:sse/server/sse_handler.dart';
+
+import '../../data/connect_request.dart';
+import '../../data/run_request.dart';
+import '../../data/serializers.dart';
+
+/// A connection between the application loaded in the browser and DWDS.
+class AppConnection {
+  /// The initial connection request sent from the application in the browser.
+  final ConnectRequest request;
+
+  final SseConnection _connection;
+  var _isStarted = false;
+
+  AppConnection(this.request, this._connection);
+
+  void runMain() {
+    if (_isStarted) throw StateError('Main has already started.');
+    _connection.sink.add(jsonEncode(serializers.serialize(RunRequest())));
+    _isStarted = true;
+  }
+}

dwds/lib/src/connections/debug_connection.dart

@@ -0,0 +1,41 @@
+// Copyright (c) 2019, 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 'dart:async';
+
+import 'package:vm_service_lib/vm_service_lib.dart';
+
+import '../services/app_debug_services.dart';
+
+/// A debug connection between the application in the browser and DWDS.
+///
+/// Supports debugging your running application through the Dart VM Service
+/// Protocol.
+class DebugConnection {
+  final AppDebugServices _appDebugServices;
+  final _onDoneCompleter = Completer();
+
+  DebugConnection(this._appDebugServices) {
+    _appDebugServices.chromeProxyService.tabConnection.onClose.first.then((_) {
+      close();
+    });
+  }
+
+  /// The port of the host Dart VM Service.
+  int get port => _appDebugServices.debugService.port;
+
+  /// The websocket endpoint of the Dart VM Service.
+  String get wsUri => _appDebugServices.debugService.wsUri;
+
+  /// A client of the Dart VM Service with DWDS specific extensions.
+  VmService get vmService => _appDebugServices.dwdsVmClient.client;
+
+  Future<void> close() async {
+    if (!_onDoneCompleter.isCompleted) _onDoneCompleter.complete();
+    await _appDebugServices.chromeProxyService.tabConnection.close();
+    await _appDebugServices.close();
+  }
+
+  Future<void> get onDone => _onDoneCompleter.future;
+}

dwds/lib/src/debugger.dart

@@ -7,11 +7,11 @@ import 'dart:async';
 import 'package:vm_service_lib/vm_service_lib.dart';
 import 'package:webkit_inspection_protocol/webkit_inspection_protocol.dart';
 
-import 'chrome_proxy_service.dart';
 import 'dart_uri.dart';
 import 'domain.dart';
 import 'location.dart';
 import 'objects.dart';
+import 'services/chrome_proxy_service.dart';
 import 'sources.dart';
 
 /// Converts from ExceptionPauseMode strings to [PauseState] enums.

dwds/lib/src/domain.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 'dart:async';
 
-import 'package:dwds/src/chrome_proxy_service.dart';
 import 'package:vm_service_lib/vm_service_lib.dart';
 
 import 'inspector.dart';
+import 'services/chrome_proxy_service.dart';
 
 /// A common superclass to allow implementations of different parts of the
 /// protocol to get access to the inspector and utility functions.

dwds/lib/src/dwds_vm_client.dart

@@ -5,10 +5,10 @@
 import 'dart:async';
 import 'dart:convert';
 
-import 'package:dwds/service.dart';
 import 'package:vm_service_lib/vm_service_lib.dart';
 
-import 'chrome_proxy_service.dart' show ChromeProxyService;
+import 'services/chrome_proxy_service.dart' show ChromeProxyService;
+import 'services/debug_service.dart';
 
 // A client of the vm service that registers some custom extensions like
 // hotRestart.

dwds/lib/src/handlers/asset_handler.dart

@@ -11,18 +11,18 @@ import 'package:shelf_proxy/shelf_proxy.dart';
 ///
 /// Proxies requests to the build daemon asset server.
 class AssetHandler {
-  final int _daemonPort;
+  final int _assetServerPort;
   final String _target;
   final int _applicationPort;
   final String _applicationHost;
 
   Handler _handler;
 
-  AssetHandler(this._daemonPort, this._target, this._applicationHost,
+  AssetHandler(this._assetServerPort, this._target, this._applicationHost,
       this._applicationPort);
 
   Handler get handler =>
-      _handler ??= proxyHandler('http://localhost:$_daemonPort/$_target/');
+      _handler ??= proxyHandler('http://localhost:$_assetServerPort/$_target/');
 
   /// Returns the asset from a relative [path].
   ///

dwds/lib/src/handlers/dev_handler.dart

@@ -6,7 +6,7 @@ import 'dart:async';
 import 'dart:convert';
 
 import 'package:build_daemon/data/build_status.dart';
-import 'package:build_daemon/data/serializers.dart';
+import 'package:build_daemon/data/serializers.dart' as build_daemon;
 import 'package:logging/logging.dart';
 import 'package:pedantic/pedantic.dart';
 import 'package:shelf/shelf.dart';
@@ -16,13 +16,13 @@ import 'package:webkit_inspection_protocol/webkit_inspection_protocol.dart';
 import '../../data/connect_request.dart';
 import '../../data/devtools_request.dart';
 import '../../data/isolate_events.dart';
-import '../../data/run_request.dart';
-import '../../data/serializers.dart' as dwds;
-import '../../service.dart';
-import '../app_debug_services.dart';
+import '../../data/serializers.dart';
+import '../connections/app_connection.dart';
 import '../devtools.dart';
 import '../dwds_vm_client.dart';
 import '../handlers/asset_handler.dart';
+import '../services/app_debug_services.dart';
+import '../services/debug_service.dart';
 
 /// SSE handler to enable development features like hot reload and
 /// opening DevTools.
@@ -33,14 +33,14 @@ class DevHandler {
   final DevTools _devTools;
   final AssetHandler _assetHandler;
   final String _hostname;
-  final _connectedApps = StreamController<DevConnection>.broadcast();
+  final _connectedApps = StreamController<AppConnection>.broadcast();
   final _servicesByAppId = <String, Future<AppDebugServices>>{};
   final Stream<BuildResult> buildResults;
   final bool _verbose;
   final void Function(Level, String) _logWriter;
   final Future<ChromeConnection> Function() _chromeConnection;
 
-  Stream<DevConnection> get connectedApps => _connectedApps.stream;
+  Stream<AppConnection> get connectedApps => _connectedApps.stream;
 
   DevHandler(
     this._chromeConnection,
@@ -73,7 +73,8 @@ class DevHandler {
   void _emitBuildResults(BuildResult result) {
     if (result.status != BuildStatus.succeeded) return;
     for (var connection in _connections) {
-      connection.sink.add(jsonEncode(serializers.serialize(result)));
+      connection.sink
+          .add(jsonEncode(build_daemon.serializers.serialize(result)));
     }
   }
 
@@ -104,20 +105,21 @@ class DevHandler {
     _connections.add(connection);
     String appId;
     connection.stream.listen((data) async {
-      var message = dwds.serializers.deserialize(jsonDecode(data));
+      var message = serializers.deserialize(jsonDecode(data));
       if (message is DevToolsRequest) {
         if (_devTools == null) {
-          connection.sink.add(jsonEncode(dwds.serializers.serialize(
-              DevToolsResponse((b) => b
+          connection.sink
+              .add(jsonEncode(serializers.serialize(DevToolsResponse((b) => b
                 ..success = false
-                ..error =
-                    'Debugging is not enabled, please pass the --debug flag '
-                        'when starting webdev.'))));
+                ..error = 'Debugging is not enabled.\n\n'
+                    'If you are using webdev please pass the --debug flag.\n'
+                    'Otherwise check the docs for the tool you are using.'))));
           return;
         }
+
         if (appId != message.appId) {
-          connection.sink.add(jsonEncode(dwds.serializers.serialize(
-              DevToolsResponse((b) => b
+          connection.sink.add(jsonEncode(serializers.serialize(DevToolsResponse(
+              (b) => b
                 ..success = false
                 ..error =
                     'App ID has changed since the connection was established. '
@@ -131,22 +133,22 @@ class DevHandler {
           appServices =
               await loadAppServices(message.appId, message.instanceId);
         } catch (_) {
-          connection.sink.add(
-              jsonEncode(dwds.serializers.serialize(DevToolsResponse((b) => b
+          connection.sink
+              .add(jsonEncode(serializers.serialize(DevToolsResponse((b) => b
                 ..success = false
-                ..error = 'Webdev was unable to connect debug services to your '
+                ..error = 'Unable to connect debug services to your '
                     'application. Most likely this means you are trying to '
                     'load in a different Chrome window than was launched by '
-                    'webdev.'))));
+                    'your development tool.'))));
           return;
         }
 
         // Check if we are already running debug services for a different
         // instance of this app.
         if (appServices.connectedInstanceId != null &&
             appServices.connectedInstanceId != message.instanceId) {
-          connection.sink.add(jsonEncode(dwds.serializers.serialize(
-              DevToolsResponse((b) => b
+          connection.sink.add(jsonEncode(serializers.serialize(DevToolsResponse(
+              (b) => b
                 ..success = false
                 ..error =
                     'This app is already being debugged in a different tab. '
@@ -164,8 +166,8 @@ class DevHandler {
               await loadAppServices(message.appId, message.instanceId);
         }
 
-        connection.sink.add(jsonEncode(dwds.serializers
-            .serialize(DevToolsResponse((b) => b..success = true))));
+        connection.sink.add(jsonEncode(
+            serializers.serialize(DevToolsResponse((b) => b..success = true))));
 
         appServices.connectedInstanceId = message.instanceId;
         await appServices.chromeProxyService.tabConnection
@@ -195,7 +197,7 @@ class DevHandler {
           }
         }
 
-        _connectedApps.add(DevConnection(message, connection));
+        _connectedApps.add(AppConnection(message, connection));
       } else if (message is IsolateExit) {
         (await loadAppServices(message.appId, message.instanceId))
             ?.chromeProxyService
@@ -257,18 +259,3 @@ Future<bool> _isCorrectTab(
       await tabConnection.runtime.evaluate(r'window["$dartAppInstanceId"];');
   return result.value == instanceId;
 }
-
-class DevConnection {
-  final ConnectRequest request;
-  final SseConnection _connection;
-  var _isStarted = false;
-  DevConnection(this.request, this._connection);
-
-  void runMain() {
-    if (!_isStarted) {
-      _connection.sink
-          .add(jsonEncode(dwds.serializers.serialize(RunRequest())));
-    }
-    _isStarted = true;
-  }
-}

dwds/lib/src/handlers/injected_handler.dart

@@ -9,7 +9,7 @@ import 'dart:isolate';
 import 'package:crypto/crypto.dart';
 import 'package:shelf/shelf.dart';
 
-import '../injected/configuration.dart';
+import '../../dwds.dart';
 
 /// File extension that build_web_compilers will place the
 /// [entrypointExtensionMarker] in.