[protocol] Introduce CDPConnection interface

This CL proposes to introduce a new abstraction layer that will allow
us to utilize puppeteer connections in DevTools. At the moment we
have 2 layers:

  1) Raw transport: Sending and receiving strings.
     Current implementation: ConnectionTransport

  2) Message and session handling: Parsing strings into messages,
     correlating requests with their responses and dispatching
     them on the right session.
     Current implementation: SessionRouter

The new CDPConnection would be introduced inbetween: It uses
an existing transport and would only handle messages. That is,
serialization/deserializatrion and matching requests with their
responses.

A follow-up CL will add a concerete DevTools implementation that
moves the existing pieces out of SessionRouter.

As part of this refactoring, we also introduce an 'inspectable'
version of the connection: The protocol monitor and our test
harnesses require raw inspection of the CDP traffic. At the
moment, these are global functions ona global `test` object
that everyone can install, with the downside they can
overwrite each other. The proposed 'RawMessageObserver'
can handle both `test.dumpProtocol` as well as
`test.onMessageSent` and `test.onMessageReceived`.

Note: We use an observer pattern rather then the DevTools
event system for performance reasons: CDP is generally
rather talkative. Using an `ObjectWrapper` with an
`CDP_EVENT_RECEIVED` event would mean we have to do a Map
lookup to get the list of listeners for each CDP event.
With an observer, we can at least avoid the map lookup.

[email protected], [email protected]

Bug: 453469270
Change-Id: Ia226c2137274a73752b586e1fc924f6b91413f6a
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/7075672
Reviewed-by: Alex Rudenko <[email protected]>
Commit-Queue: Simon Zünd <[email protected]>
Reviewed-by: Philip Pfaffe <[email protected]>

Author: szuend

config/gni/devtools_grd_files.gni

@@ -895,6 +895,7 @@ grd_files_unbundled_sources = [
   "front_end/core/platform/TypescriptUtilities.js",
   "front_end/core/platform/UIString.js",
   "front_end/core/platform/UserVisibleError.js",
+  "front_end/core/protocol_client/CDPConnection.js",
   "front_end/core/protocol_client/ConnectionTransport.js",
   "front_end/core/protocol_client/InspectorBackend.js",
   "front_end/core/protocol_client/NodeURL.js",

front_end/core/protocol_client/BUILD.gn

@@ -8,6 +8,7 @@ import("../../../scripts/build/typescript/typescript.gni")
 
 devtools_module("protocol_client") {
   sources = [
+    "CDPConnection.ts",
     "ConnectionTransport.ts",
     "InspectorBackend.ts",
     "NodeURL.ts",

front_end/core/protocol_client/CDPConnection.ts

@@ -0,0 +1,39 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import type {ProtocolMapping} from '../../generated/protocol-mapping.js';
+
+/**
+ * Allows the sending and receiving of CDP commands and the notification of CDP events to observers.
+ *
+ * An instance of a CDPConnection "owns" the full transport channel and no other CDP traffic must
+ * be proxied over it. This is because each implementation needs to manage "message IDs", which
+ * would conflict with any other shared traffic.
+ */
+export interface CDPConnection {
+  send<T extends keyof ProtocolMapping.Commands>(
+      method: T, params: ProtocolMapping.Commands[T]['paramsType'][0],
+      sessionId: string|undefined): Promise<ProtocolMapping.Commands[T]['returnType']|{getError(): string}>;
+
+  observe(observer: CDPConnectionObserver): void;
+  unobserve(observer: CDPConnectionObserver): void;
+}
+
+export interface CDPConnectionObserver {
+  onEvent<T extends keyof ProtocolMapping.Events>(event: ProtocolMapping.Events[T]): void;
+  onDisconnect(reason: string): void;
+}
+
+/**
+ * The protocol monitor and test harness require inspection of raw CDP message traffic.
+ */
+export interface DebuggableCDPConnection extends CDPConnection {
+  observeMessages(observer: RawMessageObserver): void;
+  unobserveMessages(observer: RawMessageObserver): void;
+}
+
+export interface RawMessageObserver {
+  onMessageReceived(message: unknown): void;
+  onMessageSent(message: unknown): void;
+}