inspector: add initial support for network inspection

PR-URL: #53593
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>

Author: cola119

doc/api/cli.md

@@ -1028,6 +1028,17 @@ added:
 
 Enable experimental support for the `https:` protocol in `import` specifiers.
 
+### `--experimental-network-inspection`
+
+<!-- YAML
+added:
+ - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Enable experimental support for the network inspection with Chrome DevTools.
+
 ### `--experimental-permission`
 
 <!-- YAML

doc/api/inspector.md

@@ -488,6 +488,75 @@ Blocks until a client (existing or connected later) has sent
 
 An exception will be thrown if there is no active inspector.
 
+## Integration with DevTools
+
+The `node:inspector` module provides an API for integrating with devtools that support Chrome DevTools Protocol.
+DevTools frontends connected to a running Node.js instance can capture protocol events emitted from the instance
+and display them accordingly to facilitate debugging.
+The following methods broadcast a protocol event to all connected frontends.
+The `params` passed to the methods can be optional, depending on the protocol.
+
+```js
+// The `Network.requestWillBeSent` event will be fired.
+inspector.Network.requestWillBeSent({
+ requestId:'request-id-1',
+ timestamp:Date.now() /1000,
+ wallTime:Date.now(),
+ request: {
+ url:'https://nodejs.org/en',
+ method:'GET',
+ }
+});
+```
+
+### `inspector.Network.requestWillBeSent([params])`
+
+<!-- YAML
+added:
+ - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+*`params` {Object}
+
+This feature is only available with the `--experimental-network-inspection` flag enabled.
+
+Broadcasts the `Network.requestWillBeSent` event to connected frontends. This event indicates that
+the application is about to send an HTTP request.
+
+### `inspector.Network.responseReceived([params])`
+
+<!-- YAML
+added:
+ - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+*`params` {Object}
+
+This feature is only available with the `--experimental-network-inspection` flag enabled.
+
+Broadcasts the `Network.responseReceived` event to connected frontends. This event indicates that
+HTTP response is available.
+
+### `inspector.Network.loadingFinished([params])`
+
+<!-- YAML
+added:
+ - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+*`params` {Object}
+
+This feature is only available with the `--experimental-network-inspection` flag enabled.
+
+Broadcasts the `Network.loadingFinished` event to connected frontends. This event indicates that
+HTTP request has finished loading.
+
 ## Support of breakpoints
 
 The Chrome DevTools Protocol [`Debugger` domain][] allows an

lib/inspector.js

@@ -42,6 +42,7 @@ const {
  isEnabled,
  waitForDebugger,
  console,
+ emitProtocolEvent,
 }=internalBinding('inspector');
 
 classSessionextendsEventEmitter{
@@ -188,11 +189,26 @@ function inspectorWaitForDebugger() {
 thrownewERR_INSPECTOR_NOT_ACTIVE();
 }
 
+functionbroadcastToFrontend(eventName,params){
+validateString(eventName,'eventName');
+if(params){
+validateObject(params,'params');
+}
+emitProtocolEvent(eventName,JSONStringify(params??{}));
+}
+
+constNetwork={
+requestWillBeSent: (params)=>broadcastToFrontend('Network.requestWillBeSent',params),
+responseReceived: (params)=>broadcastToFrontend('Network.responseReceived',params),
+loadingFinished: (params)=>broadcastToFrontend('Network.loadingFinished',params),
+};
+
 module.exports={
 open: inspectorOpen,
 close: _debugEnd,
  url,
 waitForDebugger: inspectorWaitForDebugger,
  console,
  Session,
+ Network,
 };

lib/internal/inspector_network_tracking.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const{
+ DateNow,
+}=primordials;
+
+letdc;
+letNetwork;
+
+letrequestId=0;
+constgetNextRequestId=()=>`node-network-event-${++requestId}`;
+
+functiononClientRequestStart({ request }){
+consturl=`${request.protocol}//${request.host}${request.path}`;
+constwallTime=DateNow();
+consttimestamp=wallTime/1000;
+request._inspectorRequestId=getNextRequestId();
+Network.requestWillBeSent({
+requestId: request._inspectorRequestId,
+ timestamp,
+ wallTime,
+request: {
+ url,
+method: request.method,
+},
+});
+}
+
+functiononClientResponseFinish({ request }){
+if(typeofrequest._inspectorRequestId!=='string'){
+return;
+}
+consttimestamp=DateNow()/1000;
+Network.responseReceived({
+requestId: request._inspectorRequestId,
+ timestamp,
+});
+Network.loadingFinished({
+requestId: request._inspectorRequestId,
+ timestamp,
+});
+}
+
+functionenable(){
+if(!dc){
+dc=require('diagnostics_channel');
+}
+if(!Network){
+Network=require('inspector').Network;
+}
+dc.subscribe('http.client.request.start',onClientRequestStart);
+dc.subscribe('http.client.response.finish',onClientResponseFinish);
+}
+
+functiondisable(){
+dc.unsubscribe('http.client.request.start',onClientRequestStart);
+dc.unsubscribe('http.client.response.finish',onClientResponseFinish);
+}
+
+module.exports={
+ enable,
+ disable,
+};

lib/internal/process/pre_execution.js

@@ -106,6 +106,7 @@ function prepareExecution(options) {
 constmainEntry=patchProcessObject(expandArgv1);
 setupTraceCategoryState();
 setupInspectorHooks();
+setupNetworkInspection();
 setupNavigator();
 setupWarningHandler();
 setupUndici();
@@ -513,6 +514,16 @@ function setupInspectorHooks() {
 }
 }
 
+functionsetupNetworkInspection(){
+if(internalBinding('config').hasInspector&&getOptionValue('--experimental-network-inspection')){
+const{
+ enable,
+ disable,
+}=require('internal/inspector_network_tracking');
+internalBinding('inspector').setupNetworkTracking(enable,disable);
+}
+}
+
 // In general deprecations are initialized wherever the APIs are implemented,
 // this is used to deprecate APIs implemented in C++ where the deprecation
 // utilities are not easily accessible.

src/env_properties.h

@@ -448,7 +448,9 @@
  V(immediate_callback_function, v8::Function) \
  V(inspector_console_extension_installer, v8::Function) \
  V(inspector_disable_async_hooks, v8::Function) \
+ V(inspector_disable_network_tracking, v8::Function) \
  V(inspector_enable_async_hooks, v8::Function) \
+ V(inspector_enable_network_tracking, v8::Function) \
  V(maybe_cache_generated_source_map, v8::Function) \
  V(messaging_deserialize_create_object, v8::Function) \
  V(message_port, v8::Object) \

src/inspector/network_agent.cc

@@ -0,0 +1,84 @@
+#include"network_agent.h"
+#include"network_inspector.h"
+
+namespacenode {
+namespaceinspector {
+namespaceprotocol {
+
+std::unique_ptr<Network::Request> Request(const String& url,
+const String& method) {
+returnNetwork::Request::create().setUrl(url).setMethod(method).build();
+}
+
+NetworkAgent::NetworkAgent(NetworkInspector* inspector)
+ : inspector_(inspector) {
+ event_notifier_map_["requestWillBeSent"] = &NetworkAgent::requestWillBeSent;
+ event_notifier_map_["responseReceived"] = &NetworkAgent::responseReceived;
+ event_notifier_map_["loadingFinished"] = &NetworkAgent::loadingFinished;
+}
+
+voidNetworkAgent::emitNotification(
+const String& event, std::unique_ptr<protocol::DictionaryValue> params) {
+if (!inspector_->IsEnabled()) return;
+auto it = event_notifier_map_.find(event);
+if (it != event_notifier_map_.end()) {
+ (this->*(it->second))(std::move(params));
+ }
+}
+
+voidNetworkAgent::Wire(UberDispatcher* dispatcher) {
+ frontend_ = std::make_unique<Network::Frontend>(dispatcher->channel());
+Network::Dispatcher::wire(dispatcher, this);
+}
+
+DispatchResponse NetworkAgent::enable() {
+ inspector_->Enable();
+returnDispatchResponse::OK();
+}
+
+DispatchResponse NetworkAgent::disable() {
+ inspector_->Disable();
+returnDispatchResponse::OK();
+}
+
+voidNetworkAgent::requestWillBeSent(
+ std::unique_ptr<protocol::DictionaryValue> params) {
+ String request_id;
+ params->getString("requestId", &request_id);
+double timestamp;
+ params->getDouble("timestamp", &timestamp);
+double wall_time;
+ params->getDouble("wallTime", &wall_time);
+auto request = params->getObject("request");
+ String url;
+ request->getString("url", &url);
+ String method;
+ request->getString("method", &method);
+
+ frontend_->requestWillBeSent(
+ request_id, Request(url, method), timestamp, wall_time);
+}
+
+voidNetworkAgent::responseReceived(
+ std::unique_ptr<protocol::DictionaryValue> params) {
+ String request_id;
+ params->getString("requestId", &request_id);
+double timestamp;
+ params->getDouble("timestamp", &timestamp);
+
+ frontend_->responseReceived(request_id, timestamp);
+}
+
+voidNetworkAgent::loadingFinished(
+ std::unique_ptr<protocol::DictionaryValue> params) {
+ String request_id;
+ params->getString("requestId", &request_id);
+double timestamp;
+ params->getDouble("timestamp", &timestamp);
+
+ frontend_->loadingFinished(request_id, timestamp);
+}
+
+} // namespace protocol
+} // namespace inspector
+} // namespace node

src/inspector/network_agent.h

@@ -0,0 +1,49 @@
+#ifndef SRC_INSPECTOR_NETWORK_AGENT_H_
+#defineSRC_INSPECTOR_NETWORK_AGENT_H_
+
+#include"node/inspector/protocol/Network.h"
+
+#include<unordered_map>
+
+namespacenode {
+
+namespaceinspector {
+classNetworkInspector;
+
+namespaceprotocol {
+
+std::unique_ptr<Network::Request> Request(const String& url,
+const String& method);
+
+classNetworkAgent : publicNetwork::Backend {
+public:
+explicitNetworkAgent(NetworkInspector* inspector);
+
+voidWire(UberDispatcher* dispatcher);
+
+ DispatchResponse enable() override;
+
+ DispatchResponse disable() override;
+
+voidemitNotification(const String& event,
+ std::unique_ptr<protocol::DictionaryValue> params);
+
+voidrequestWillBeSent(std::unique_ptr<protocol::DictionaryValue> params);
+
+voidresponseReceived(std::unique_ptr<protocol::DictionaryValue> params);
+
+voidloadingFinished(std::unique_ptr<protocol::DictionaryValue> params);
+
+private:
+ NetworkInspector* inspector_;
+ std::shared_ptr<Network::Frontend> frontend_;
+using EventNotifier =
+void (NetworkAgent::*)(std::unique_ptr<protocol::DictionaryValue>);
+ std::unordered_map<String, EventNotifier> event_notifier_map_;
+};
+
+} // namespace protocol
+} // namespace inspector
+} // namespace node
+
+#endif// SRC_INSPECTOR_NETWORK_AGENT_H_