Integrate with DevTools. (#20)

Author: polina-c

lib/leak_analysis.dart renamed to lib/devtools_integration.dart

@@ -5,6 +5,9 @@
 /// The library should be used by DevTools to analyse the collected leaks.
 ///
 /// Should not be used in the application itself.
-library leak_analysis;
+library devtools_integration;
 
-export 'src/leak_analysis_model.dart';
+export 'src/devtools_integration/delivery.dart';
+export 'src/devtools_integration/messages.dart';
+export 'src/devtools_integration/primitives.dart';
+export 'src/model.dart';

lib/leak_tracker.dart

@@ -4,3 +4,4 @@
 
 export 'src/leak_tracker.dart';
 export 'src/leak_tracker_model.dart';
+export 'src/model.dart';

lib/src/_leak_checker.dart

@@ -3,10 +3,10 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'dart:async';
-import 'dart:developer';
 
-import 'leak_analysis_model.dart';
+import 'devtools_integration/delivery.dart';
 import 'leak_tracker_model.dart';
+import 'model.dart';
 
 class LeakChecker {
   LeakChecker({
@@ -23,7 +23,7 @@ class LeakChecker {
 
   late final Timer? _timer;
 
-  LeakSummary _previousResult = const LeakSummary({});
+  LeakSummary _previousResult = LeakSummary({});
 
   /// Period to check for leaks.
   ///
@@ -32,11 +32,11 @@ class LeakChecker {
 
   // If not null, then the leak summary will be printed here, when
   // leak totals change.
-  final StdoutSink? stdoutSink;
+  final StdoutSummarySink? stdoutSink;
 
   // If not null, the leak summary will be sent here, when
   // leak totals change.
-  final DevToolsSink? devToolsSink;
+  final DevToolsSummarySink? devToolsSink;
 
   /// Listener for leaks.
   ///
@@ -50,8 +50,8 @@ class LeakChecker {
     if (summary.matches(_previousResult)) return;
 
     leakListener?.call(summary);
-    stdoutSink?.print(summary.toMessage());
-    devToolsSink?.send(summary.toJson());
+    stdoutSink?.send(summary);
+    devToolsSink?.send(summary);
 
     _previousResult = summary;
   }
@@ -61,11 +61,10 @@ class LeakChecker {
   }
 }
 
-class StdoutSink {
-  void print(String content) => print(content);
+class StdoutSummarySink {
+  void send(LeakSummary summary) => print(summary.toMessage());
 }
 
-class DevToolsSink {
-  void send(Map<String, dynamic> content) =>
-      postEvent(EventNames.memoryLeaksSummary, content);
+class DevToolsSummarySink {
+  void send(LeakSummary summary) => EventFromApp(summary).post();
 }

lib/src/_object_record.dart

@@ -4,7 +4,7 @@
 
 import '_gc_counter.dart';
 import '_primitives.dart';
-import 'leak_analysis_model.dart';
+import 'model.dart';
 
 /// Object collections to track leaks.
 ///

lib/src/_object_tracker.dart

@@ -7,7 +7,7 @@ import 'package:clock/clock.dart';
 import '_gc_counter.dart';
 import '_object_record.dart';
 import '_primitives.dart';
-import 'leak_analysis_model.dart';
+import 'model.dart';
 
 class ObjectTracker implements LeakProvider {
   /// The optional parameters are injected for testing purposes.
@@ -167,6 +167,7 @@ class ObjectTracker implements LeakProvider {
     return result;
   }
 
+  @override
   Leaks collectLeaks() {
     throwIfDisposed();
     _checkForNewNotGCedLeaks();

lib/src/_primitives.dart

@@ -20,3 +20,8 @@ String fullClassName({
   required String shortClassName,
 }) =>
     '$library/$shortClassName';
+
+class ObjectRef<T> {
+  ObjectRef(this.value);
+  T value;
+}

lib/src/_util.dart

@@ -23,3 +23,11 @@ bool mapEquals<T, U>(Map<T, U>? a, Map<T, U>? b) {
   }
   return true;
 }
+
+/// This function is better than `as`, because `as` does not provide callstack on failure.
+T cast<T>(value) {
+  if (value is T) return value;
+  throw ArgumentError(
+    '$value is of type ${value.runtimeType} that is not subtype of $T',
+  );
+}

lib/src/devtools_integration/_protocol.dart

@@ -0,0 +1,170 @@
+// Copyright 2022 The Chromium Authors. 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:meta/meta.dart';
+
+import '../model.dart';
+import 'messages.dart';
+
+/// Generic parameter is not used for encoder, because the message type cannot be detected in runtime.
+typedef AppMessageEncoder = Map<String, dynamic> Function(dynamic message);
+
+typedef AppMessageDecoder<T> = T Function(Map<String, dynamic> message);
+
+enum Channel {
+  requestToApp,
+  eventFromApp,
+  responseFromApp,
+}
+
+/// Codes to identify event types in interaction between appliocation and DevTools.
+///
+/// When application starts real tracking, it sends [started]. As soon as it
+/// catch new leaks, it sends [summary] information about collected leaks.
+///
+/// When user wants to get more about the collected leaks, they request details in
+/// DevTools, devtools sends [detailsRequest] to the app, and the app responds with
+/// [leakDetails].
+@visibleForTesting
+enum Codes {
+  // Events from app.
+  started,
+  summary,
+
+  // Requests to app.
+  detailsRequest,
+
+  // Successfull responses from app.
+  leakDetails,
+
+  // Error responses from app.
+  leakTrackingTurnedOffError,
+  unexpectedError,
+  unexpectedRequestTypeError,
+  ;
+
+  static Codes byName(String name) =>
+      Codes.values.where((e) => e.name == name).single;
+}
+
+class _JsonFields {
+  static const envelopeCode = 'code';
+  static const content = 'content';
+}
+
+/// Serializes an object so that it's type can be reconstructed.
+Map<String, dynamic> sealEnvelope(Object message, Channel channel) {
+  final theEnvelope = envelopeByType(message.runtimeType);
+  assert(theEnvelope.channel == channel);
+  return {
+    _JsonFields.envelopeCode: theEnvelope.code.name,
+    _JsonFields.content: theEnvelope.encode(message),
+  };
+}
+
+/// Deserialize [message] into an opbejct of a right type.
+Object openEnvelope(
+  Map<String, dynamic> message,
+  Channel channel,
+) {
+  final envelope = envelopeByCode(message[_JsonFields.envelopeCode] as String);
+  assert(envelope.channel == channel);
+  return envelope.decode(message[_JsonFields.content]);
+}
+
+/// Information necessary to serialize and deserialize an instance of type [T],
+/// so that the message type can be auto-detected.
+class _Envelope<T> {
+  const _Envelope(this.code, this.channel, this.decode, this.encode);
+
+  /// Serialization code, that corresponts to [T].
+  final Codes code;
+
+  /// Communication channel, that should be used for messages of type [T].
+  final Channel channel;
+
+  /// Decoder for the message.
+  final AppMessageDecoder<T> decode;
+
+  /// Encoder for the message.
+  final AppMessageEncoder encode;
+
+  Type get type => T;
+}
+
+/// Envelopes should be unique by message type.
+@visibleForTesting
+final envelopes = [
+  // Events from app.
+
+  _Envelope<LeakTrackingStarted>(
+    Codes.started,
+    Channel.eventFromApp,
+    (Map<String, dynamic> json) => LeakTrackingStarted.fromJson(json),
+    (message) => (message as LeakTrackingStarted).toJson(),
+  ),
+  _Envelope<LeakSummary>(
+    Codes.summary,
+    Channel.eventFromApp,
+    (Map<String, dynamic> json) => LeakSummary.fromJson(json),
+    (message) => (message as LeakSummary).toJson(),
+  ),
+
+  // Requests to app.
+
+  _Envelope<RequestForLeakDetails>(
+    Codes.detailsRequest,
+    Channel.requestToApp,
+    (Map<String, dynamic> json) => RequestForLeakDetails(),
+    (message) => {},
+  ),
+
+  // Responses from app.
+
+  _Envelope<Leaks>(
+    Codes.leakDetails,
+    Channel.responseFromApp,
+    (Map<String, dynamic> json) => Leaks.fromJson(json),
+    (message) => (message as Leaks).toJson(),
+  ),
+
+  _Envelope<LeakTrackingTurnedOffError>(
+    Codes.leakTrackingTurnedOffError,
+    Channel.responseFromApp,
+    (Map<String, dynamic> json) => LeakTrackingTurnedOffError(),
+    (message) => {},
+  ),
+
+  _Envelope<UnexpectedRequestTypeError>(
+    Codes.unexpectedRequestTypeError,
+    Channel.responseFromApp,
+    (Map<String, dynamic> json) => UnexpectedRequestTypeError.fromJson(json),
+    (message) => (message as UnexpectedRequestTypeError).toJson(),
+  ),
+
+  _Envelope<UnexpectedError>(
+    Codes.unexpectedError,
+    Channel.responseFromApp,
+    (Map<String, dynamic> json) => UnexpectedError.fromJson(json),
+    (message) => (message as UnexpectedError).toJson(),
+  ),
+];
+
+_Envelope<T> envelopeByCode<T>(String codeString) {
+  return _envelopesByCode[codeString]! as _Envelope<T>;
+}
+
+_Envelope envelopeByType(Type type) => _envelopesByType[type]!;
+
+late final _envelopesByCode = Map<String, _Envelope>.fromIterable(
+  envelopes,
+  key: (e) => (e as _Envelope).code.name,
+  value: (e) => e,
+);
+
+late final _envelopesByType = Map<Type, _Envelope>.fromIterable(
+  envelopes,
+  key: (e) => e.type,
+  value: (e) => e,
+);

lib/src/devtools_integration/_registration.dart

@@ -0,0 +1,93 @@
+// Copyright 2022 The Chromium Authors. 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 'dart:developer';
+
+import '../_primitives.dart';
+import '../model.dart';
+import 'delivery.dart';
+import 'messages.dart';
+import 'primitives.dart';
+
+bool _extentsionRegistered = false;
+
+/// Registers service extension to signal that leak tracking is
+/// already enabled and other leak tracking systems
+/// (for example, the one built into Flutter framework)
+/// should not be activated.
+///
+/// If the extension is already registered, returns false.
+bool registerLeakTrackingServiceExtension() => _registerServiceExtension(
+      (p0, p1) async => ServiceExtensionResponse.result(jsonEncode({})),
+    );
+
+/// Registers service extension for DevTools integration.
+///
+/// If the extension is already registered, returns false.
+bool setupDevToolsIntegration(
+  ObjectRef<LeakProvider?> leakProvider,
+) {
+  final handler = (String method, Map<String, String> parameters) async {
+    try {
+      assert(method == memoryLeakTrackingExtensionName);
+
+      final theLeakProvider = leakProvider.value;
+
+      if (theLeakProvider == null) {
+        return ResponseFromApp(LeakTrackingTurnedOffError())
+            .toServiceResponse();
+      }
+
+      final request = RequestToApp.fromRequestParameters(parameters).message;
+
+      if (request is RequestForLeakDetails) {
+        return ResponseFromApp(theLeakProvider.collectLeaks())
+            .toServiceResponse();
+      }
+
+      return ResponseFromApp(
+        UnexpectedRequestTypeError(request.runtimeType),
+      ).toServiceResponse();
+    } catch (error, stack) {
+      print(
+        'Error handling leak tracking request from DevTools to application.',
+      );
+      print(error);
+      print(stack);
+
+      return ResponseFromApp(UnexpectedError(error, stack)).toServiceResponse();
+    }
+  };
+
+  final result = _registerServiceExtension(handler);
+
+  EventFromApp(LeakTrackingStarted(appLeakTrackerProtocolVersion)).post();
+
+  return result;
+}
+
+bool _registerServiceExtension(
+  Future<ServiceExtensionResponse> Function(String, Map<String, String>)
+      handler,
+) {
+  if (_extentsionRegistered) return false;
+  try {
+    registerExtension(
+      memoryLeakTrackingExtensionName,
+      handler,
+    );
+    _extentsionRegistered = true;
+
+    return true;
+  } on ArgumentError catch (ex) {
+    // Return false if extension is already registered.
+    final bool isAlreadyRegisteredError = ex.toString().contains('registered');
+    if (isAlreadyRegisteredError) {
+      return false;
+    } else {
+      rethrow;
+    }
+  }
+}