http,inspector: add WebSocket upgrade observability

Author: GrinZero

doc/api/diagnostics_channel.md

@@ -1590,6 +1590,18 @@ Emitted when an error occurs during a client request.
 
 Emitted when client receives a response.
 
+##### Event: `'http.client.request.upgrade'`
+
+* `request` {http.ClientRequest}
+* `response` {http.IncomingMessage}
+* `socket` {net.Socket}
+* `head` {Buffer}
+* `protocol` {string}
+
+Emitted when an HTTP/1.1 client request upgrades to WebSocket.
+The `head` value matches the `upgradeHead` argument emitted with the request's
+`'upgrade'` event.
+
 ##### Event: `'http.server.request.start'`
 
 * `request` {http.IncomingMessage}
@@ -1616,6 +1628,78 @@ The event is emitted before the response is sent.
 
 Emitted when server sends a response.
 
+##### Event: `'http.server.request.upgrade'`
+
+* `request` {http.IncomingMessage}
+* `socketOrStream` {net.Socket|stream.Duplex}
+* `head` {Buffer}
+* `protocol` {string}
+
+Emitted when an HTTP/1.1 server request upgrades to WebSocket.
+The `socketOrStream` value matches the upgraded object exposed to the server's
+`'upgrade'` event.
+
+#### WebSocket
+
+> Stability: 1 - Experimental
+
+The following WebSocket diagnostics channels currently observe HTTP/1.1
+WebSocket upgrades handled by the built-in `http` and `https` modules.
+
+##### Event: `'websocket.client.frameSent'`
+
+* `request` {http.ClientRequest}
+* `response` {http.IncomingMessage}
+* `socket` {net.Socket}
+* `opcode` {number}
+* `fin` {boolean}
+* `masked` {boolean}
+* `compressed` {boolean}
+* `payloadLength` {number}
+* `payload` {Buffer}
+
+Emitted when a complete WebSocket frame sent by the client has been observed.
+
+##### Event: `'websocket.client.frameReceived'`
+
+* `request` {http.ClientRequest}
+* `response` {http.IncomingMessage}
+* `socket` {net.Socket}
+* `opcode` {number}
+* `fin` {boolean}
+* `masked` {boolean}
+* `compressed` {boolean}
+* `payloadLength` {number}
+* `payload` {Buffer}
+
+Emitted when a complete WebSocket frame received by the client has been observed.
+
+##### Event: `'websocket.server.frameSent'`
+
+* `request` {http.IncomingMessage}
+* `socket` {net.Socket}
+* `opcode` {number}
+* `fin` {boolean}
+* `masked` {boolean}
+* `compressed` {boolean}
+* `payloadLength` {number}
+* `payload` {Buffer}
+
+Emitted when a complete WebSocket frame sent by the server has been observed.
+
+##### Event: `'websocket.server.frameReceived'`
+
+* `request` {http.IncomingMessage}
+* `socket` {net.Socket}
+* `opcode` {number}
+* `fin` {boolean}
+* `masked` {boolean}
+* `compressed` {boolean}
+* `payloadLength` {number}
+* `payload` {Buffer}
+
+Emitted when a complete WebSocket frame received by the server has been observed.
+
 #### HTTP/2
 
 > Stability: 1 - Experimental

lib/_http_client.js

@@ -99,6 +99,13 @@ const onClientRequestStartChannel = dc.channel('http.client.request.start');
 const onClientRequestErrorChannel = dc.channel('http.client.request.error');
 const onClientResponseFinishChannel = dc.channel('http.client.response.finish');
 
+let observeClientWebSocketUpgrade;
+function lazyObserveClientWebSocketUpgrade() {
+  observeClientWebSocketUpgrade ??=
+    require('internal/http_websocket_observer').observeClientWebSocketUpgrade;
+  return observeClientWebSocketUpgrade;
+}
+
 function emitErrorEvent(request, error) {
   if (onClientRequestErrorChannel.hasSubscribers) {
     onClientRequestErrorChannel.publish({
@@ -670,6 +677,10 @@ function socketOnData(d) {
       socket._httpMessage = null;
       socket.readableFlowing = null;
 
+      if (eventName === 'upgrade') {
+        lazyObserveClientWebSocketUpgrade()(req, res, socket, bodyHead);
+      }
+
       req.emit(eventName, res, socket, bodyHead);
       req.destroyed = true;
       req._closed = true;

lib/_http_server.js

@@ -107,6 +107,13 @@ const onRequestStartChannel = dc.channel('http.server.request.start');
 const onResponseCreatedChannel = dc.channel('http.server.response.created');
 const onResponseFinishChannel = dc.channel('http.server.response.finish');
 
+let observeServerWebSocketUpgrade;
+function lazyObserveServerWebSocketUpgrade() {
+  observeServerWebSocketUpgrade ??=
+    require('internal/http_websocket_observer').observeServerWebSocketUpgrade;
+  return observeServerWebSocketUpgrade;
+}
+
 const kServerResponse = Symbol('ServerResponse');
 const kServerResponseStatistics = Symbol('ServerResponseStatistics');
 const kUpgradeStream = Symbol('UpgradeStream');
@@ -1090,6 +1097,15 @@ function onParserExecuteCommon(server, socket, parser, state, ret, d) {
         socket[kUpgradeStream].requestBodyCompleted(bodyHead);
       } else {
         socket.readableFlowing = null;
+        if (eventName === 'upgrade') {
+          lazyObserveServerWebSocketUpgrade()(
+            req,
+            upgradeStream,
+            socket,
+            bodyHead,
+            req.complete,
+          );
+        }
         server.emit(eventName, req, upgradeStream, bodyHead);
       }
     } else {

lib/inspector.js

@@ -220,7 +220,11 @@ const Network = {
   dataSent: (params) => broadcastToFrontend('Network.dataSent', params),
   dataReceived: (params) => broadcastToFrontend('Network.dataReceived', params),
   webSocketCreated: (params) => broadcastToFrontend('Network.webSocketCreated', params),
+  webSocketWillSendHandshakeRequest:
+    (params) => broadcastToFrontend('Network.webSocketWillSendHandshakeRequest', params),
   webSocketClosed: (params) => broadcastToFrontend('Network.webSocketClosed', params),
+  webSocketFrameReceived: (params) => broadcastToFrontend('Network.webSocketFrameReceived', params),
+  webSocketFrameSent: (params) => broadcastToFrontend('Network.webSocketFrameSent', params),
   webSocketHandshakeResponseReceived:
     (params) => broadcastToFrontend('Network.webSocketHandshakeResponseReceived', params),
 };