From 9b8c5326dfab7c5577f665b845e053e944e88531 Mon Sep 17 00:00:00 2001
From: islandryu <shimaryuhei@gmail.com>
Date: Thu, 7 Aug 2025 22:49:18 +0900
Subject: [PATCH 1/4] inspector: initial support websocket inspection

Refs: https://github.com/nodejs/node/issues/53946
---
 doc/api/inspector.md                          |  42 +++++++
 lib/inspector.js                              |   4 +
 lib/internal/inspector/network_undici.js      |  33 +++++
 src/inspector/network_agent.cc                |  87 ++++++++++++++
 src/inspector/network_agent.h                 |   7 ++
 src/inspector/node_protocol.pdl               |  35 ++++++
 test/common/websocket-server.js               | 113 ++++++++++++++++++
 .../test-inspector-emit-protocol-event.js     |  30 ++++-
 .../test-inspector-network-websocket.js       |  63 ++++++++++
 9 files changed, 413 insertions(+), 1 deletion(-)
 create mode 100644 test/common/websocket-server.js
 create mode 100644 test/parallel/test-inspector-network-websocket.js

diff --git a/doc/api/inspector.md b/doc/api/inspector.md
index 95ddad0e9363a9..939351ec383161 100644
--- a/doc/api/inspector.md
+++ b/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
diff --git a/lib/inspector.js b/lib/inspector.js
index 4bf3ef7b61e99f..a6b835bbc7d529 100644
--- a/lib/inspector.js
+++ b/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 = {
diff --git a/lib/internal/inspector/network_undici.js b/lib/internal/inspector/network_undici.js
index 95be848910f3da..676cb1e5573052 100644
--- a/lib/internal/inspector/network_undici.js
+++ b/lib/internal/inspector/network_undici.js
@@ -206,6 +206,35 @@ function onClientResponseFinish({ request }) {
   });
 }
 
+function onWebSocketOpen({ websocket }) {
+  websocket[kInspectorRequestId] = getNextRequestId();
+  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 +243,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 +255,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 = {
diff --git a/src/inspector/network_agent.cc b/src/inspector/network_agent.cc
index 3b5d9615021101..d136b72e598d07 100644
--- a/src/inspector/network_agent.cc
+++ b/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,
diff --git a/src/inspector/network_agent.h b/src/inspector/network_agent.h
index f814c7f5cf6662..487c7d02680d3d 100644
--- a/src/inspector/network_agent.h
+++ b/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_;
diff --git a/src/inspector/node_protocol.pdl b/src/inspector/node_protocol.pdl
index 46631bc20ad081..33a88335cdacdb 100644
--- a/src/inspector/node_protocol.pdl
+++ b/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
diff --git a/test/common/websocket-server.js b/test/common/websocket-server.js
new file mode 100644
index 00000000000000..5920a23a5ef2d6
--- /dev/null
+++ b/test/common/websocket-server.js
@@ -0,0 +1,113 @@
+'use strict';
+const common = require('./index');
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+const http = require('http');
+const crypto = require('crypto');
+
+class WebSocketServer {
+  constructor({
+    port = 0,
+    responseError = false,
+  }) {
+    this.port = port;
+    this.server = http.createServer();
+    this.clients = new Set();
+    this.responseError = responseError;
+
+    this.server.on('upgrade', this.handleUpgrade.bind(this));
+  }
+
+  start() {
+    return new Promise((resolve) => {
+      this.server.listen(this.port, () => {
+        this.port = this.server.address().port;
+        resolve();
+      });
+    }).catch((err) => {
+      console.error('Failed to start WebSocket server:', err);
+    });
+  }
+
+  handleUpgrade(req, socket, head) {
+    const key = req.headers['sec-websocket-key'];
+    const acceptKey = this.generateAcceptValue(key);
+    const responseHeaders = [
+      'HTTP/1.1 101 Switching Protocols',
+      'Upgrade: websocket',
+      'Connection: Upgrade',
+      `Sec-WebSocket-Accept: ${acceptKey}`,
+    ];
+
+    socket.write(responseHeaders.join('\r\n') + '\r\n\r\n');
+    this.clients.add(socket);
+
+    socket.on('data', (buffer) => {
+      const opcode = buffer[0] & 0x0f;
+
+      if (opcode === 0x8) {
+        socket.end();
+        this.clients.delete(socket);
+        return;
+      }
+
+      if (this.responseError) {
+        socket.write(Buffer.from([0x88, 0x00])); // close frame
+        socket.end();
+        this.clients.delete(socket);
+        return;
+      }
+      socket.write(this.encodeMessage('Hello from server!'));
+    });
+
+    socket.on('close', () => {
+      this.clients.delete(socket);
+    });
+
+    socket.on('error', (err) => {
+      console.error('Socket error:', err);
+      this.clients.delete(socket);
+    });
+  }
+
+  generateAcceptValue(secWebSocketKey) {
+    return crypto
+      .createHash('sha1')
+      .update(secWebSocketKey + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11', 'binary')
+      .digest('base64');
+  }
+
+  decodeMessage(buffer) {
+    const secondByte = buffer[1];
+    const length = secondByte & 127;
+    const maskStart = 2;
+    const dataStart = maskStart + 4;
+    const masks = buffer.slice(maskStart, dataStart);
+    const data = buffer.slice(dataStart, dataStart + length);
+    const result = Buffer.alloc(length);
+
+    for (let i = 0; i < length; i++) {
+      result[i] = data[i] ^ masks[i % 4];
+    }
+
+    return result.toString();
+  }
+
+  encodeMessage(message) {
+    const msgBuffer = Buffer.from(message);
+    const length = msgBuffer.length;
+    const frame = [0x81];
+
+    if (length < 126) {
+      frame.push(length);
+    } else if (length < 65536) {
+      frame.push(126, (length >> 8) & 0xff, length & 0xff);
+    } else {
+      throw new Error('Message too long');
+    }
+
+    return Buffer.concat([Buffer.from(frame), msgBuffer]);
+  }
+}
+
+module.exports = WebSocketServer;
diff --git a/test/parallel/test-inspector-emit-protocol-event.js b/test/parallel/test-inspector-emit-protocol-event.js
index 5a90b258cd6e1a..5c9fb580edecfb 100644
--- a/test/parallel/test-inspector-emit-protocol-event.js
+++ b/test/parallel/test-inspector-emit-protocol-event.js
@@ -87,6 +87,34 @@ const EXPECTED_EVENTS = {
         errorText: 'Failed to load resource'
       }
     },
+    {
+      name: 'webSocketCreated',
+      params: {
+        requestId: 'websocket-id-1',
+        url: 'ws://example.com:8080',
+      }
+
+    },
+    {
+      name: 'webSocketHandshakeResponseReceived',
+      params: {
+        requestId: 'websocket-id-1',
+        response: {
+          status: 101,
+          statusText: 'Switching Protocols',
+          headers: {},
+        },
+        timestamp: 1000,
+      }
+    },
+    {
+      name: 'webSocketClosed',
+      params: {
+        requestId: 'websocket-id-1',
+        timestamp: 1000,
+
+      }
+    },
   ]
 };
 
@@ -123,7 +151,7 @@ const runAsyncTest = async () => {
         continue;
       }
       session.on(`${domain}.${event.name}`, common.mustCall(({ params }) => {
-        if (event.name === 'requestWillBeSent') {
+        if (event.name === 'requestWillBeSent' || event.name === 'webSocketCreated') {
           // Initiator is automatically captured and contains caller info.
           // No need to validate it.
           delete params.initiator;
diff --git a/test/parallel/test-inspector-network-websocket.js b/test/parallel/test-inspector-network-websocket.js
new file mode 100644
index 00000000000000..6f2613a4c27de2
--- /dev/null
+++ b/test/parallel/test-inspector-network-websocket.js
@@ -0,0 +1,63 @@
+// Flags: --inspect=0 --experimental-network-inspection
+'use strict';
+const common = require('../common');
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+common.skipIfInspectorDisabled();
+
+const assert = require('node:assert');
+const { once } = require('node:events');
+const WebSocketServer = require('../common/websocket-server');
+const inspector = require('node:inspector/promises');
+const dc = require('diagnostics_channel');
+
+const session = new inspector.Session();
+session.connect();
+
+dc.channel('undici:websocket:socket_error').subscribe((message) => {
+  console.error('WebSocket error:', message);
+});
+
+function findFrameInInitiator(scriptName, initiator) {
+  const frame = initiator.stack.callFrames.find((it) => {
+    return it.url === scriptName;
+  });
+  return frame;
+}
+
+async function test() {
+  await session.post('Network.enable');
+  const server = new WebSocketServer({
+    responseError: true,
+  });
+  await server.start();
+  const url = `ws://127.0.0.1:${server.port}/`;
+  let requestId;
+  once(session, 'Network.webSocketCreated').then(common.mustCall(([message]) => {
+    assert.strictEqual(message.method, 'Network.webSocketCreated');
+    assert.strictEqual(message.params.url, url);
+    assert.ok(message.params.requestId);
+    assert.strictEqual(typeof message.params.initiator, 'object');
+    assert.strictEqual(message.params.initiator.type, 'script');
+    assert.ok(findFrameInInitiator('node:internal/deps/undici/undici', message.params.initiator));
+    requestId = message.params.requestId;
+  }));
+
+  once(session, 'Network.webSocketHandshakeResponseReceived').then(common.mustCall(([message]) => {
+    assert.strictEqual(message.params.requestId, requestId);
+    assert.strictEqual(message.params.response.status, 101);
+    assert.strictEqual(message.params.response.statusText, 'Switching Protocols');
+    assert.strictEqual(typeof message.params.timestamp, 'number');
+    socket.close();
+  }));
+
+  const socket = new WebSocket(url);
+  once(session, 'Network.webSocketClosed').then(common.mustCall(([message]) => {
+    assert.strictEqual(message.method, 'Network.webSocketClosed');
+    assert.strictEqual(message.params.requestId, requestId);
+    session.disconnect();
+    server.server.close();
+  }));
+}
+
+test().then(common.mustCall());

From 530fb44de2ac1e90b764ad62033fff014646510c Mon Sep 17 00:00:00 2001
From: islandryu <shimaryuhei@gmail.com>
Date: Fri, 8 Aug 2025 22:52:49 +0900
Subject: [PATCH 2/4] Remove redundant code

---
 test/common/websocket-server.js | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/test/common/websocket-server.js b/test/common/websocket-server.js
index 5920a23a5ef2d6..a3b12ab8d30d49 100644
--- a/test/common/websocket-server.js
+++ b/test/common/websocket-server.js
@@ -8,12 +8,10 @@ const crypto = require('crypto');
 class WebSocketServer {
   constructor({
     port = 0,
-    responseError = false,
   }) {
     this.port = port;
     this.server = http.createServer();
     this.clients = new Set();
-    this.responseError = responseError;
 
     this.server.on('upgrade', this.handleUpgrade.bind(this));
   }
@@ -51,12 +49,6 @@ class WebSocketServer {
         return;
       }
 
-      if (this.responseError) {
-        socket.write(Buffer.from([0x88, 0x00])); // close frame
-        socket.end();
-        this.clients.delete(socket);
-        return;
-      }
       socket.write(this.encodeMessage('Hello from server!'));
     });
 

From 97800e9cc7b0b31408fefc97a703549be2bf3269 Mon Sep 17 00:00:00 2001
From: islandryu <shimaryuhei@gmail.com>
Date: Fri, 15 Aug 2025 21:14:34 +0900
Subject: [PATCH 3/4] fix TODO

---
 lib/internal/inspector/network_undici.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lib/internal/inspector/network_undici.js b/lib/internal/inspector/network_undici.js
index 676cb1e5573052..b4031eedcc88d1 100644
--- a/lib/internal/inspector/network_undici.js
+++ b/lib/internal/inspector/network_undici.js
@@ -206,6 +206,9 @@ function onClientResponseFinish({ request }) {
   });
 }
 
+// TODO: Move Network.webSocketCreated to the actual creation time of the WebSocket.
+// undici:websocket:open fires when the connection is established, but this results
+// in an inaccurate stack trace.
 function onWebSocketOpen({ websocket }) {
   websocket[kInspectorRequestId] = getNextRequestId();
   const url = websocket.url.toString();
@@ -214,6 +217,7 @@ function onWebSocketOpen({ websocket }) {
     url,
   });
   // TODO: Use handshake response data from undici diagnostics when available.
+  // https://github.com/nodejs/undici/pull/4396
   Network.webSocketHandshakeResponseReceived({
     requestId: websocket[kInspectorRequestId],
     timestamp: getMonotonicTime(),

From f13ec2ec937a9918438fb5152a62ab37c55ce8bb Mon Sep 17 00:00:00 2001
From: Shima Ryuhei <65934663+islandryu@users.noreply.github.com>
Date: Fri, 15 Aug 2025 21:43:10 +0900
Subject: [PATCH 4/4] Update src/inspector/node_protocol.pdl

Co-authored-by: Chengzhong Wu <legendecas@gmail.com>
---
 src/inspector/node_protocol.pdl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/inspector/node_protocol.pdl b/src/inspector/node_protocol.pdl
index 33a88335cdacdb..a79dd3595ce493 100644
--- a/src/inspector/node_protocol.pdl
+++ b/src/inspector/node_protocol.pdl
@@ -311,7 +311,7 @@ experimental domain Network
       RequestId requestId
       # Timestamp.
       MonotonicTime timestamp
-    # Fired when WebSocket handshake response becomes available.
+  # Fired when WebSocket handshake response becomes available.
   event webSocketHandshakeResponseReceived
     parameters
       # Request identifier.