dwds/debug_extension/web/cider_connection.dart

// 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.

@JS()
library;

import 'dart:convert';
// TODO: https://github.com/dart-lang/webdev/issues/2508
// ignore: deprecated_member_use
import 'dart:js_util';

// TODO: https://github.com/dart-lang/webdev/issues/2508
// ignore: deprecated_member_use
import 'package:js/js.dart';

import 'chrome_api.dart';
import 'debug_session.dart';
import 'logger.dart';
import 'storage.dart';
import 'utils.dart';

/// Used to identify messages passed to/from Cider.
///
/// This must match the key defined in the Cider extension.
const _ciderDartMessageKey = 'CIDER_DART';

/// Defines the message types that can be passed to/from Cider.
///
/// The types must match those defined by ChromeExtensionMessageType in the
/// Cider extension.
enum CiderMessageType {
  connected,
  error,
  inspectorUrlResponse,
  inspectorUrlRequest,
  ping,
  pong,
  startDebugResponse,
  startDebugRequest,
  stopDebugResponse,
  stopDebugRequest,
}

/// Defines the error types that can be sent to Cider.
///
/// The types must match those defined by ChromeExtensionErrorType in the
/// Cider extension.
enum CiderErrorType { internalError, invalidRequest, noAppId }

const _ciderPortName = 'cider';
Port? _ciderPort;

/// Handles a connect request from Cider.
///
/// The only site allowed to connect with this extension is Cider. The allowed
/// URIs for Cider are set in the externally_connectable field in the manifest.
void handleCiderConnectRequest(Port port) {
  if (port.name == _ciderPortName) {
    debugLog('Received connect request from Cider', verbose: true);
    _ciderPort = port;

    port.onMessage.addListener(allowInterop(_handleMessageFromCider));

    sendMessageToCider(messageType: CiderMessageType.connected);
  }
}

/// Sends a message to the Cider-connected port.
void sendMessageToCider({
  required CiderMessageType messageType,
  String? messageBody,
}) {
  if (_ciderPort == null) return;
  final message = jsonEncode({
    'messageType': messageType.name,
    'messageBody': messageBody,
  });
  _sendMessageToCider(message);
}

/// Sends an error message to the Cider-connected port.
void sendErrorMessageToCider({
  required CiderErrorType errorType,
  String? errorDetails,
}) {
  debugWarn('CiderError.${errorType.name} $errorDetails');
  if (_ciderPort == null) return;
  final message = jsonEncode({
    'messageType': CiderMessageType.error.name,
    'errorType': errorType.name,
    'messageBody': errorDetails,
  });
  _sendMessageToCider(message);
}

void _sendMessageToCider(String json) {
  final message = {'key': _ciderDartMessageKey, 'json': json};
  _ciderPort!.postMessage(jsify(message));
}

Future<void> _handleMessageFromCider(dynamic message, Port _) async {
  final key = getProperty(message, 'key');
  final json = getProperty(message, 'json');
  if (key != _ciderDartMessageKey || json is! String) {
    sendErrorMessageToCider(
      errorType: CiderErrorType.invalidRequest,
      errorDetails: 'Invalid message format: $message',
    );
    return;
  }

  final decoded = jsonDecode(json) as Map<String, dynamic>;
  final messageType = decoded['messageType'] as String?;
  final messageBody = decoded['messageBody'] as String?;

  if (messageType == CiderMessageType.startDebugRequest.name) {
    await _startDebugging(appId: messageBody);
  } else if (messageType == CiderMessageType.stopDebugRequest.name) {
    await _stopDebugging(appId: messageBody);
  } else if (messageType == CiderMessageType.inspectorUrlRequest.name) {
    await _sendInspectorUrl(appId: messageBody);
  } else if (messageType == CiderMessageType.ping.name) {
    sendMessageToCider(messageType: CiderMessageType.pong);
  }
}

Future<void> _startDebugging({String? appId}) async {
  if (appId == null) {
    _sendNoAppIdError();
    return;
  }
  final tabId = _tabId(appId);
  // TODO(https://github.com/dart-lang/webdev/issues/2198): When debugging
  // with Cider, disable debugging with DevTools.
  debugLog('Attach debugger to Cider', verbose: true);
  await attachDebugger(tabId, trigger: Trigger.cider);
}

Future<void> _stopDebugging({String? appId}) async {
  if (appId == null) {
    _sendNoAppIdError();
    return;
  }
  final tabId = _tabId(appId);

  final successfullyDetached = await detachDebugger(
    tabId,
    type: TabType.dartApp,
    reason: DetachReason.canceledByUser,
  );

  if (successfullyDetached) {
    sendMessageToCider(messageType: CiderMessageType.stopDebugResponse);
  } else {
    sendErrorMessageToCider(
      errorType: CiderErrorType.internalError,
      errorDetails: 'Unable to detach debugger.',
    );
  }
}

Future<void> _sendInspectorUrl({String? appId}) async {
  if (appId == null) {
    _sendNoAppIdError();
    return;
  }
  final tabId = _tabId(appId);
  final alreadyDebugging = isActiveDebugSession(tabId);
  if (!alreadyDebugging) {
    sendErrorMessageToCider(
      errorType: CiderErrorType.invalidRequest,
      errorDetails:
          'Cannot send the inspector URL before '
          'the debugger has been attached.',
    );
    return;
  }
  final devToolsUri = await fetchStorageObject<String>(
    type: StorageObject.devToolsUri,
    tabId: tabId,
  );
  if (devToolsUri == null) {
    sendErrorMessageToCider(
      errorType: CiderErrorType.internalError,
      errorDetails: 'Failed to fetch the DevTools URI for the inspector.',
    );
    return;
  }
  final inspectorUrl = addQueryParameters(
    devToolsUri,
    queryParameters: {'embed': 'true', 'page': 'inspector'},
  );
  sendMessageToCider(
    messageType: CiderMessageType.inspectorUrlResponse,
    messageBody: inspectorUrl,
  );
}

int _tabId(String appId) {
  // The suffix "-f" is used to tell Cider that this is a Flutter app.
  if (appId.endsWith('-f')) {
    appId = appId.substring(0, appId.length - 2);
  }
  final tabId = appId.split('-').last;
  return int.parse(tabId);
}

void _sendNoAppIdError() {
  sendErrorMessageToCider(
    errorType: CiderErrorType.noAppId,
    errorDetails: 'Cannot find a debuggable Dart tab without an app ID',
  );
}