inspector: add initial support for network inspection

PR-URL: #53593
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Stephen Belanger <[email protected]>
Reviewed-By: Joyee Cheung <[email protected]>
Reviewed-By: Chengzhong Wu <[email protected]>
Reviewed-By: Paolo Insogna <[email protected]>

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');
 
 class Session extends EventEmitter {
@@ -188,11 +189,26 @@ function inspectorWaitForDebugger() {
  throw new ERR_INSPECTOR_NOT_ACTIVE();
 }
 
+function broadcastToFrontend(eventName, params) {
+ validateString(eventName, 'eventName');
+ if (params) {
+ validateObject(params, 'params');
+ }
+ emitProtocolEvent(eventName, JSONStringify(params ?? {}));
+}
+
+const Network = {
+ 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;
+
+let dc;
+let Network;
+
+let requestId = 0;
+const getNextRequestId = () => `node-network-event-${++requestId}`;
+
+function onClientRequestStart({ request }) {
+ const url = `${request.protocol}//${request.host}${request.path}`;
+ const wallTime = DateNow();
+ const timestamp = wallTime / 1000;
+ request._inspectorRequestId = getNextRequestId();
+ Network.requestWillBeSent({
+ requestId: request._inspectorRequestId,
+ timestamp,
+ wallTime,
+ request: {
+ url,
+ method: request.method,
+ },
+ });
+}
+
+function onClientResponseFinish({ request }) {
+ if (typeof request._inspectorRequestId !== 'string') {
+ return;
+ }
+ const timestamp = DateNow() / 1000;
+ Network.responseReceived({
+ requestId: request._inspectorRequestId,
+ timestamp,
+ });
+ Network.loadingFinished({
+ requestId: request._inspectorRequestId,
+ timestamp,
+ });
+}
+
+function enable() {
+ 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);
+}
+
+function disable() {
+ 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) {
  const mainEntry = patchProcessObject(expandArgv1);
  setupTraceCategoryState();
  setupInspectorHooks();
+ setupNetworkInspection();
  setupNavigator();
  setupWarningHandler();
  setupUndici();
@@ -513,6 +514,16 @@ function setupInspectorHooks() {
  }
 }
 
+function setupNetworkInspection() {
+ 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"
+
+namespace node {
+namespace inspector {
+namespace protocol {
+
+std::unique_ptr<Network::Request> Request(const String& url,
+ const String& method) {
+ return Network::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;
+}
+
+void NetworkAgent::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));
+ }
+}
+
+void NetworkAgent::Wire(UberDispatcher* dispatcher) {
+ frontend_ = std::make_unique<Network::Frontend>(dispatcher->channel());
+ Network::Dispatcher::wire(dispatcher, this);
+}
+
+DispatchResponse NetworkAgent::enable() {
+ inspector_->Enable();
+ return DispatchResponse::OK();
+}
+
+DispatchResponse NetworkAgent::disable() {
+ inspector_->Disable();
+ return DispatchResponse::OK();
+}
+
+void NetworkAgent::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);
+}
+
+void NetworkAgent::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);
+}
+
+void NetworkAgent::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_
+#define SRC_INSPECTOR_NETWORK_AGENT_H_
+
+#include "node/inspector/protocol/Network.h"
+
+#include <unordered_map>
+
+namespace node {
+
+namespace inspector {
+class NetworkInspector;
+
+namespace protocol {
+
+std::unique_ptr<Network::Request> Request(const String& url,
+ const String& method);
+
+class NetworkAgent : public Network::Backend {
+ public:
+ explicit NetworkAgent(NetworkInspector* inspector);
+
+ void Wire(UberDispatcher* dispatcher);
+
+ DispatchResponse enable() override;
+
+ DispatchResponse disable() override;
+
+ void emitNotification(const String& event,
+ std::unique_ptr<protocol::DictionaryValue> params);
+
+ void requestWillBeSent(std::unique_ptr<protocol::DictionaryValue> params);
+
+ void responseReceived(std::unique_ptr<protocol::DictionaryValue> params);
+
+ void loadingFinished(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_