inspector: initial support websocket inspection

Refs: #53946

Author: islandryu

doc/api/inspector.md

@@ -602,6 +602,48 @@ This feature is only available with the `--experimental-network-inspection` flag
 Broadcasts the `Network.loadingFailed` event to connected frontends. This event indicates that
 HTTP request has failed to load.
 
+### `inspector.Network.webSocketCreated([params])`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+* `params` {Object}
+
+This feature is only available with the `--experimental-network-inspection` flag enabled.
+
+Broadcasts the `Network.webSocketCreated` event to connected frontends. This event indicates that
+a WebSocket connection has been initiated.
+
+### `inspector.Network.webSocketHandshakeResponseReceived([params])`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+* `params` {Object}
+
+This feature is only available with the `--experimental-network-inspection` flag enabled.
+
+Broadcasts the `Network.webSocketHandshakeResponseReceived` event to connected frontends.
+This event indicates that the WebSocket handshake response has been received.
+
+### `inspector.Network.webSocketClosed([params])`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+* `params` {Object}
+
+This feature is only available with the `--experimental-network-inspection` flag enabled.
+
+Broadcasts the `Network.webSocketClosed` event to connected frontends.
+This event indicates that a WebSocket connection has been closed.
+
 ### `inspector.NetworkResources.put`
 
 <!-- YAML

lib/inspector.js

@@ -219,6 +219,10 @@ const Network = {
   loadingFailed: (params) => broadcastToFrontend('Network.loadingFailed', params),
   dataSent: (params) => broadcastToFrontend('Network.dataSent', params),
   dataReceived: (params) => broadcastToFrontend('Network.dataReceived', params),
+  webSocketCreated: (params) => broadcastToFrontend('Network.webSocketCreated', params),
+  webSocketClosed: (params) => broadcastToFrontend('Network.webSocketClosed', params),
+  webSocketHandshakeResponseReceived:
+    (params) => broadcastToFrontend('Network.webSocketHandshakeResponseReceived', params),
 };
 
 const NetworkResources = {

lib/internal/inspector/network_undici.js

@@ -2,6 +2,7 @@
 
 const {
   DateNow,
+  NumberMAX_SAFE_INTEGER,
   StringPrototypeToLowerCase,
 } = primordials;
 
@@ -206,6 +207,43 @@ function onClientResponseFinish({ request }) {
   });
 }
 
+let networkRequestId = 0;
+function getNextNetworkRequestId() {
+  if (networkRequestId === NumberMAX_SAFE_INTEGER) {
+    networkRequestId = 0;
+  }
+  return `node-network-event-${++networkRequestId}`;
+}
+
+function onWebSocketOpen({ websocket }) {
+  websocket[kInspectorRequestId] = getNextNetworkRequestId();
+  const url = websocket.url.toString();
+  Network.webSocketCreated({
+    requestId: websocket[kInspectorRequestId],
+    url,
+  });
+  // TODO: Use handshake response data from undici diagnostics when available.
+  Network.webSocketHandshakeResponseReceived({
+    requestId: websocket[kInspectorRequestId],
+    timestamp: getMonotonicTime(),
+    response: {
+      status: 101,
+      statusText: 'Switching Protocols',
+      headers: {},
+    },
+  });
+}
+
+function onWebSocketClose({ websocket }) {
+  if (typeof websocket[kInspectorRequestId] !== 'string') {
+    return;
+  }
+  Network.webSocketClosed({
+    requestId: websocket[kInspectorRequestId],
+    timestamp: getMonotonicTime(),
+  });
+}
+
 function enable() {
   dc.subscribe('undici:request:create', onClientRequestStart);
   dc.subscribe('undici:request:error', onClientRequestError);
@@ -214,6 +252,8 @@ function enable() {
   dc.subscribe('undici:request:bodyChunkSent', onClientRequestBodyChunkSent);
   dc.subscribe('undici:request:bodySent', onClientRequestBodySent);
   dc.subscribe('undici:request:bodyChunkReceived', onClientRequestBodyChunkReceived);
+  dc.subscribe('undici:websocket:open', onWebSocketOpen);
+  dc.subscribe('undici:websocket:close', onWebSocketClose);
 }
 
 function disable() {
@@ -224,6 +264,8 @@ function disable() {
   dc.unsubscribe('undici:request:bodyChunkSent', onClientRequestBodyChunkSent);
   dc.unsubscribe('undici:request:bodySent', onClientRequestBodySent);
   dc.unsubscribe('undici:request:bodyChunkReceived', onClientRequestBodyChunkReceived);
+  dc.unsubscribe('undici:websocket:open', onWebSocketOpen);
+  dc.unsubscribe('undici:websocket:close', onWebSocketClose);
 }
 
 module.exports = {

src/inspector/network_agent.cc

@@ -208,6 +208,35 @@ std::unique_ptr<protocol::Network::Response> createResponseFromObject(
       .build();
 }
 
+std::unique_ptr<protocol::Network::WebSocketResponse> createWebSocketResponse(
+    v8::Local<v8::Context> context, Local<Object> response) {
+  HandleScope handle_scope(context->GetIsolate());
+  int status;
+  if (!ObjectGetInt(context, response, "status").To(&status)) {
+    return {};
+  }
+  protocol::String statusText;
+  if (!ObjectGetProtocolString(context, response, "statusText")
+           .To(&statusText)) {
+    return {};
+  }
+  Local<Object> headers_obj;
+  if (!ObjectGetObject(context, response, "headers").ToLocal(&headers_obj)) {
+    return {};
+  }
+  std::unique_ptr<protocol::Network::Headers> headers =
+      createHeadersFromObject(context, headers_obj);
+  if (!headers) {
+    return {};
+  }
+
+  return protocol::Network::WebSocketResponse::create()
+      .setStatus(status)
+      .setStatusText(statusText)
+      .setHeaders(std::move(headers))
+      .build();
+}
+
 NetworkAgent::NetworkAgent(
     NetworkInspector* inspector,
     v8_inspector::V8Inspector* v8_inspector,
@@ -223,6 +252,64 @@ NetworkAgent::NetworkAgent(
   event_notifier_map_["loadingFinished"] = &NetworkAgent::loadingFinished;
   event_notifier_map_["dataSent"] = &NetworkAgent::dataSent;
   event_notifier_map_["dataReceived"] = &NetworkAgent::dataReceived;
+  event_notifier_map_["webSocketCreated"] = &NetworkAgent::webSocketCreated;
+  event_notifier_map_["webSocketClosed"] = &NetworkAgent::webSocketClosed;
+  event_notifier_map_["webSocketHandshakeResponseReceived"] =
+      &NetworkAgent::webSocketHandshakeResponseReceived;
+}
+
+void NetworkAgent::webSocketCreated(v8::Local<v8::Context> context,
+                                    v8::Local<v8::Object> params) {
+  protocol::String request_id;
+  if (!ObjectGetProtocolString(context, params, "requestId").To(&request_id)) {
+    return;
+  }
+  protocol::String url;
+  if (!ObjectGetProtocolString(context, params, "url").To(&url)) {
+    return;
+  }
+  std::unique_ptr<protocol::Network::Initiator> initiator =
+      protocol::Network::Initiator::create()
+          .setType(protocol::Network::Initiator::TypeEnum::Script)
+          .setStack(
+              v8_inspector_->captureStackTrace(true)->buildInspectorObject(0))
+          .build();
+  frontend_->webSocketCreated(request_id, url, std::move(initiator));
+}
+
+void NetworkAgent::webSocketClosed(v8::Local<v8::Context> context,
+                                   v8::Local<v8::Object> params) {
+  protocol::String request_id;
+  if (!ObjectGetProtocolString(context, params, "requestId").To(&request_id)) {
+    return;
+  }
+  double timestamp;
+  if (!ObjectGetDouble(context, params, "timestamp").To(&timestamp)) {
+    return;
+  }
+  frontend_->webSocketClosed(request_id, timestamp);
+}
+
+void NetworkAgent::webSocketHandshakeResponseReceived(
+    v8::Local<v8::Context> context, v8::Local<v8::Object> params) {
+  protocol::String request_id;
+  if (!ObjectGetProtocolString(context, params, "requestId").To(&request_id)) {
+    return;
+  }
+  double timestamp;
+  if (!ObjectGetDouble(context, params, "timestamp").To(&timestamp)) {
+    return;
+  }
+  Local<Object> response_obj;
+  if (!ObjectGetObject(context, params, "response").ToLocal(&response_obj)) {
+    return;
+  }
+  auto response = createWebSocketResponse(context, response_obj);
+  if (!response) {
+    return;
+  }
+  frontend_->webSocketHandshakeResponseReceived(
+      request_id, timestamp, std::move(response));
 }
 
 void NetworkAgent::emitNotification(v8::Local<v8::Context> context,

src/inspector/network_agent.h

@@ -93,6 +93,13 @@ class NetworkAgent : public protocol::Network::Backend {
   void dataReceived(v8::Local<v8::Context> context,
                     v8::Local<v8::Object> params);
 
+  void webSocketCreated(v8::Local<v8::Context> context,
+                        v8::Local<v8::Object> params);
+  void webSocketClosed(v8::Local<v8::Context> context,
+                       v8::Local<v8::Object> params);
+  void webSocketHandshakeResponseReceived(v8::Local<v8::Context> context,
+                                          v8::Local<v8::Object> params);
+
  private:
   NetworkInspector* inspector_;
   v8_inspector::V8Inspector* v8_inspector_;

src/inspector/node_protocol.pdl

@@ -185,6 +185,16 @@ experimental domain Network
       boolean success
       optional IO.StreamHandle stream
 
+  # WebSocket response data.
+  type WebSocketResponse extends object
+    properties
+      # HTTP response status code.
+      integer status
+      # HTTP response status text.
+      string statusText
+      # HTTP response headers.
+      Headers headers
+
   # Disables network tracking, prevents network events from being sent to the client.
   command disable
 
@@ -285,6 +295,31 @@ experimental domain Network
       integer encodedDataLength
       # Data that was received.
       experimental optional binary data
+  # Fired upon WebSocket creation.
+  event webSocketCreated
+    parameters
+      # Request identifier.
+      RequestId requestId
+      # WebSocket request URL.
+      string url
+      # Request initiator.
+      Initiator initiator
+  # Fired when WebSocket is closed.
+  event webSocketClosed
+    parameters
+      # Request identifier.
+      RequestId requestId
+      # Timestamp.
+      MonotonicTime timestamp
+    # Fired when WebSocket handshake response becomes available.
+  event webSocketHandshakeResponseReceived
+    parameters
+      # Request identifier.
+      RequestId requestId
+      # Timestamp.
+      MonotonicTime timestamp
+      # WebSocket response data.
+      WebSocketResponse response
 
 # Support for inspecting node process state.
 experimental domain NodeRuntime