Initial package:dtd implementation.

This initial implementation has been taken from the design docs, and modified slightly to make the linter happy.

Lots of TODOs are being added since the actual implementation still needs to be done.

Relates to: https://b.corp.google.com/issues/312968807

Change-Id: Iae80b30fa2ca0f41e1a1ae7bbdd19100f67bdc13
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/337885
Commit-Queue: Dan Chevalier <danchevalier@google.com>
Reviewed-by: Ben Konyi <bkonyi@google.com>
Reviewed-by: Devon Carew <devoncarew@google.com>

pkg/dtd/.gitignore

@@ -0,0 +1,7 @@
+# https://dart.dev/guides/libraries/private-files
+# Created by `dart pub`
+.dart_tool/
+
+# Avoid committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock

pkg/dtd/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+- Initial version.

pkg/dtd/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2023, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkg/dtd/README.md

@@ -0,0 +1,7 @@
+A package for communicating with the Dart Tooling Daemon.
+
+Use `DartToolingDaemon.connect(uri)` to connect to a running Dart Tooling
+Daemon.
+
+<!-- TODO(@danchevalier) Add more documentation about specific functionality when
+it gets added -->

pkg/dtd/analysis_options.yaml

@@ -0,0 +1,6 @@
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+linter:
+  rules:
+    - avoid_void_async
+    - unawaited_futures

pkg/dtd/example/dtd_example.dart

@@ -0,0 +1,10 @@
+// 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:dtd/dtd.dart';
+
+void main() {
+  // TODO(@danchevalier): make this example meaningful
+  DartToolingDaemon.connect(Uri.parse('wss://127.0.0.1:12345'));
+}

pkg/dtd/lib/dtd.dart

@@ -0,0 +1,9 @@
+// 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.
+
+/// Support for communicating with the Dart Tooling Daemon.
+library;
+
+export 'src/dart_tooling_daemon.dart';
+export 'src/dtd_connection.dart';

pkg/dtd/lib/src/dart_tooling_daemon.dart

@@ -0,0 +1,16 @@
+// 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 'dart:async';
+import 'package:web_socket_channel/web_socket_channel.dart';
+
+import 'dtd_connection.dart';
+
+abstract class DartToolingDaemon {
+  // TODO(@danchevalier)
+  static Future<DTDConnection> connect(Uri uri) async {
+    final channel = WebSocketChannel.connect(uri);
+    return DTDConnection(channel);
+  }
+}

pkg/dtd/lib/src/dtd_connection.dart

@@ -0,0 +1,106 @@
+// 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:stream_channel/stream_channel.dart';
+
+class DTDConnection {
+  DTDConnection(this._connectionChannel) {
+    // TODO(@danchevalier);
+  }
+
+  /// Terminates the connection with the Dart Tooling Daemon.
+  Future<void> close() async {
+    // TODO(@danchevalier)
+    return;
+  }
+
+  // TODO(@danchevalier)
+  /// A `Future` that completes when the connection with the Dart Tooling Daemon
+  /// is terminated.
+  Future<void> get done async => Future.value();
+
+  /// Returns the current list of services available.
+  Future<List<String>> getRegisteredServices() async {
+    // TODO(@danchevalier)
+    return Future.value([]);
+  }
+
+  /// Returns the current list of streams with active subscribers.
+  Future<List<String>> getRegisteredStreams() async {
+    // TODO(@danchevalier)
+    return Future.value([]);
+  }
+
+  /// Subscribes this client to events posted on [streamId].
+  ///
+  /// If this client is already subscribed to [streamId], an exception will be
+  /// thrown.
+  Future<void> streamListen(String streamId) async {
+    // TODO(@danchevalier)
+    return;
+  }
+
+  /// Cancel the subscription to [streamId].
+  ///
+  /// Once called, this connection will no longer receive events posted on
+  /// [streamId].
+  ///
+  /// If this client was not subscribed to [streamId], an exception will be
+  /// thrown.
+  Future<void> streamCancel(Stream streamId) async {
+    // TODO(@danchevalier)
+    return;
+  }
+
+  /// Creates a `Stream` for events received on [streamId].
+  ///
+  /// This method should be called before calling [streamListen] to ensure
+  /// events aren't dropped. [streamListen(streamId)] must be called before any
+  /// events will appear on the returned stream.
+  Stream<DTDEvent> onEvent(String streamId) {
+    // TODO(@danchevalier)
+    return const Stream.empty();
+  }
+
+  /// Posts an [DTDEvent] with [eventData] to [streamId].
+  ///
+  /// If no clients are subscribed to [streamId], the event will be dropped.
+  void postEvent(String streamId, Map<String, Object?> eventData) {
+    // TODO(@danchevalier)
+  }
+
+  /// Invokes a service with the name `serviceName.methodName`.
+  ///
+  /// If provided, [params] will be sent as the set of parameters used when
+  /// invoking the service.
+  ///
+  /// If `serviceName.methodName` is not a valid service, an exception will be
+  /// thrown.
+  ///
+  /// If the parameters included in [params] are invalid, an exception will be
+  /// thrown.
+  Future<T> call<T extends DTDResponse>(
+    String serviceName,
+    String methodName, {
+    Map<String, Object>? params,
+  }) async {
+    // TODO(@danchevalier)
+    // ignore: null_argument_to_non_null_type
+    return Future.value();
+  }
+
+  // ignore: unused_field
+  final StreamChannel _connectionChannel;
+}
+
+abstract class DTDResponse {
+  String get id;
+
+  String get type;
+
+  Map<String, Object?> get json;
+}
+
+// TODO(@danchevalier): is this how event should be done?
+abstract class DTDEvent {}

pkg/dtd/pubspec.yaml

@@ -0,0 +1,19 @@
+name: dtd
+description: A package for communicating with the Dart Tooling Daemon.
+version: 0.0.1
+repository: https://github.com/dart-lang/sdk/tree/main/pkg/dtd
+
+environment:
+  sdk: ">=3.0.0 <4.0.0"
+
+dependencies:
+  stream_channel: ^2.1.2
+  web_socket_channel: ^2.4.0
+
+# We use 'any' version constraints here as we get our package versions from
+# the dart-lang/sdk repo's DEPS file. Note that this is a special case; the
+# best practice for packages is to specify their compatible version ranges.
+# See also https://dart.dev/tools/pub/dependencies.
+dev_dependencies:
+  dart_flutter_team_lints: any
+  lints: any

pkg/dtd/test/dtd_connect.dart

@@ -0,0 +1,10 @@
+import 'package:dtd/dtd.dart';
+
+void main() {
+  // ignore: unused_local_variable
+  final dtdConnection = DartToolingDaemon.connect(
+    Uri.parse(
+      'wss://127.0.0.1:51906',
+    ),
+  );
+}