feat(ext/node): make Network.* CDP events fire under plain --inspect (#34270)

Network.* CDP events for fetch and WebSocket only fired when user code
imported node:inspector — the bridge that ext/fetch and ext/websocket
look up on internals.__inspectorNetwork was installed inside that
polyfill's module body. Attaching Chrome DevTools to a script that
didn't import node:inspector showed nothing in the Network tab.

Moves the bridge install into a small always-loaded script that runs at
runtime startup via the node:process bootstrap. Also wires the missing
WebSocket frame events (frameSent / frameReceived / frameError) and
instruments Deno.upgradeWebSocket so server-side sockets accepted via
Deno.serve show up alongside their clients in the inspector.

Author: bartlomieju

ext/http/02_websocket.ts

@@ -95,6 +95,7 @@ function upgradeWebSocket(request, options = { __proto__: null }) {
     _role,
     _serverHandleIdleTimeout,
     createWebSocketBranded,
+    installServerInspector,
     SERVER,
     WebSocket,
   } = loadWebSocket();
@@ -116,6 +117,7 @@ function upgradeWebSocket(request, options = { __proto__: null }) {
 
         socket[_rid] = wsRid;
         socket[_readyState] = WebSocket.OPEN;
+        installServerInspector(socket, request.url);
         const event = new Event("open");
         socket.dispatchEvent(event);
 
@@ -199,6 +201,7 @@ function upgradeWebSocket(request, options = { __proto__: null }) {
 
         socket[_rid] = wsRid;
         socket[_readyState] = WebSocket.OPEN;
+        installServerInspector(socket, request.url);
         socket.dispatchEvent(new Event("open"));
 
         socket[_eventLoop]();

ext/node/lib.rs

@@ -555,6 +555,7 @@ deno_core::extension!(deno_node,
     "http2.ts",
     "https.ts",
     "inspector.js",
+    "inspector_network_bridge.js",
     "inspector/promises.js",
     "internal/streams/duplex.js",
     "internal/streams/passthrough.js",

ext/node/polyfills/inspector.js

@@ -4,7 +4,7 @@
 // deno-lint-ignore-file prefer-primordials
 
 (function () {
-const { core, internals, primordials } = __bootstrap;
+const { core, primordials } = __bootstrap;
 const {
   op_base64_encode_from_buffer,
   op_get_extras_binding_object,
@@ -305,32 +305,6 @@ const Network = {
     broadcastToFrontend("Network.webSocketClosed", params),
 };
 
-// Bridge for other extensions (fetch, websocket, http) to emit Network.*
-// inspector events without depending on ext/node directly. Populated when
-// node:inspector is loaded; ext/fetch and friends look it up lazily on
-// `internals.__inspectorNetwork`.
-let networkRequestIdCounter = 0;
-internals.__inspectorNetwork = {
-  isEnabled: () => op_inspector_enabled(),
-  nextRequestId: () => `node-network-event-${++networkRequestIdCounter}`,
-  requestWillBeSent: Network.requestWillBeSent,
-  responseReceived: Network.responseReceived,
-  loadingFinished: Network.loadingFinished,
-  loadingFailed: Network.loadingFailed,
-  dataReceived: Network.dataReceived,
-  dataSent: Network.dataSent,
-  webSocketCreated: Network.webSocketCreated,
-  // Not exposed on `inspector.Network` (Node doesn't expose it either - see
-  // node_compat test-inspector-emit-protocol-event), but DevTools still
-  // needs the event to populate the request-side Headers panel, so we
-  // route it directly through `broadcastToFrontend`.
-  webSocketWillSendHandshakeRequest: (params) =>
-    broadcastToFrontend("Network.webSocketWillSendHandshakeRequest", params),
-  webSocketHandshakeResponseReceived:
-    Network.webSocketHandshakeResponseReceived,
-  webSocketClosed: Network.webSocketClosed,
-};
-
 const DOMStorage = {
   domStorageItemAdded: (params) =>
     broadcastToFrontend("DOMStorage.domStorageItemAdded", params),

ext/node/polyfills/inspector_network_bridge.js

@@ -0,0 +1,117 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+
+// deno-lint-ignore-file prefer-primordials
+
+// Installs `internals.__inspectorNetwork`, the bridge that other
+// extensions (ext/fetch, http, websocket) use to emit `Network.*` CDP
+// events without depending on ext/node directly. It needs to be
+// installed eagerly so that `deno run --inspect` alone is enough to
+// see fetch traffic in DevTools - previously the bridge lived in the
+// `node:inspector` polyfill and only appeared if user code imported
+// that module.
+
+(function () {
+const { core, internals, primordials } = __bootstrap;
+const {
+  op_base64_encode_from_buffer,
+  op_inspector_emit_protocol_event,
+  op_inspector_enabled,
+} = core.ops;
+const {
+  JSONStringify,
+  ObjectAssign,
+  TypedArrayPrototypeGetByteLength,
+  TypedArrayPrototypeGetSymbolToStringTag,
+  Uint8Array,
+} = primordials;
+
+function encodeNetworkData(data) {
+  if (data == null) return undefined;
+  if (typeof data === "string") {
+    const buf = core.encode(data);
+    return op_base64_encode_from_buffer(buf, 0, buf.byteLength);
+  }
+  if (TypedArrayPrototypeGetSymbolToStringTag(data) === "Uint8Array") {
+    return op_base64_encode_from_buffer(
+      data,
+      0,
+      TypedArrayPrototypeGetByteLength(data),
+    );
+  }
+  if (data instanceof ArrayBuffer) {
+    const view = new Uint8Array(data);
+    return op_base64_encode_from_buffer(view, 0, view.byteLength);
+  }
+  throw new TypeError(
+    "Expected data to be a string, Buffer, Uint8Array, or ArrayBuffer",
+  );
+}
+
+function emit(eventName, params) {
+  op_inspector_emit_protocol_event(eventName, JSONStringify(params ?? {}));
+}
+
+function emitWithData(eventName, params) {
+  if (params && params.data !== undefined) {
+    const encoded = encodeNetworkData(params.data);
+    if (encoded !== params.data) {
+      params = ObjectAssign({ __proto__: null }, params, { data: encoded });
+    }
+  }
+  emit(eventName, params);
+}
+
+// CDP's `webSocketFrameSent`/`webSocketFrameReceived` carry the payload
+// inside `params.response.payloadData`. Text frames go through as-is, binary
+// frames must be base64-encoded (DevTools uses `opcode` to decide how to
+// render the panel - 1=text, 2=binary).
+function emitFrame(eventName, params) {
+  const payload = params?.response?.payloadData;
+  if (payload != null && typeof payload !== "string") {
+    let view = null;
+    if (TypedArrayPrototypeGetSymbolToStringTag(payload) === "Uint8Array") {
+      view = payload;
+    } else if (payload instanceof ArrayBuffer) {
+      view = new Uint8Array(payload);
+    }
+    if (view !== null) {
+      const encoded = op_base64_encode_from_buffer(
+        view,
+        0,
+        TypedArrayPrototypeGetByteLength(view),
+      );
+      params = ObjectAssign({ __proto__: null }, params, {
+        response: ObjectAssign({ __proto__: null }, params.response, {
+          payloadData: encoded,
+        }),
+      });
+    }
+  }
+  emit(eventName, params);
+}
+
+let networkRequestIdCounter = 0;
+internals.__inspectorNetwork = {
+  isEnabled: () => op_inspector_enabled(),
+  nextRequestId: () => `node-network-event-${++networkRequestIdCounter}`,
+  requestWillBeSent: (p) => emit("Network.requestWillBeSent", p),
+  responseReceived: (p) => emit("Network.responseReceived", p),
+  loadingFinished: (p) => emit("Network.loadingFinished", p),
+  loadingFailed: (p) => emit("Network.loadingFailed", p),
+  dataReceived: (p) => emitWithData("Network.dataReceived", p),
+  dataSent: (p) => emitWithData("Network.dataSent", p),
+  webSocketCreated: (p) => emit("Network.webSocketCreated", p),
+  // Not part of the public `inspector.Network` surface (Node doesn't
+  // expose it either - see node_compat test-inspector-emit-protocol-event)
+  // but DevTools still needs the event to populate the request-side
+  // Headers panel for websocket connections.
+  webSocketWillSendHandshakeRequest: (p) =>
+    emit("Network.webSocketWillSendHandshakeRequest", p),
+  webSocketHandshakeResponseReceived: (p) =>
+    emit("Network.webSocketHandshakeResponseReceived", p),
+  webSocketClosed: (p) => emit("Network.webSocketClosed", p),
+  webSocketFrameSent: (p) => emitFrame("Network.webSocketFrameSent", p),
+  webSocketFrameReceived: (p) => emitFrame("Network.webSocketFrameReceived", p),
+  webSocketFrameError: (p) => emit("Network.webSocketFrameError", p),
+};
+})();

ext/node/polyfills/process.ts

@@ -5,6 +5,10 @@
 // deno-lint-ignore-file prefer-primordials
 
 import { core, internals, primordials } from "ext:core/mod.js";
+// Installs `internals.__inspectorNetwork` so ext/fetch (and other
+// extensions) can emit Network.* CDP events without requiring user code
+// to import `node:inspector`. Side-effect import; no exports.
+core.loadExtScript("ext:deno_node/inspector_network_bridge.js");
 const { initializeDebugEnv } = core.loadExtScript(
   "ext:deno_node/internal/util/debuglog.ts",
 );

ext/websocket/01_websocket.js

@@ -191,6 +191,62 @@ function emitWebSocketClosed(ws) {
   ws[_inspectorRequestId] = undefined;
 }
 
+// Opcodes per RFC 6455 / CDP `WebSocketFrame.opcode`:
+// 1 = text, 2 = binary. Per RFC 6455 client-to-server frames are masked,
+// server-to-client are not - so the `mask` flag depends on direction and
+// role: a CLIENT socket masks what it sends, a SERVER socket sees masked
+// frames coming in.
+function emitWebSocketFrame(ws, eventName, opcode, payloadData) {
+  const ins = getInspectorNetwork();
+  const requestId = ws[_inspectorRequestId];
+  if (ins === null || requestId === undefined) return;
+  const sent = eventName === "frameSent";
+  const mask = ws[_role] === SERVER ? !sent : sent;
+  try {
+    const params = {
+      requestId,
+      timestamp: DateNow() / 1000,
+      response: { opcode, mask, payloadData },
+    };
+    if (sent) ins.webSocketFrameSent(params);
+    else ins.webSocketFrameReceived(params);
+  } catch {
+    // never let inspector instrumentation break a real WebSocket
+  }
+}
+
+// Called by ext/http's `upgradeWebSocket` after a successful handshake, so
+// server-accepted sockets show up in the inspector's Network panel and
+// the frame emitters in `_eventLoop` / `send` start firing for them.
+// Handshake events (`willSendHandshakeRequest`, `handshakeResponseReceived`)
+// are intentionally skipped here - those are client-side concepts.
+function installServerInspector(ws, url) {
+  const ins = getInspectorNetwork();
+  if (ins === null) return;
+  const requestId = ins.nextRequestId();
+  ws[_inspectorRequestId] = requestId;
+  try {
+    ins.webSocketCreated({ requestId, url });
+  } catch {
+    // never let inspector instrumentation break a real WebSocket
+  }
+}
+
+function emitWebSocketFrameError(ws, errorMessage) {
+  const ins = getInspectorNetwork();
+  const requestId = ws[_inspectorRequestId];
+  if (ins === null || requestId === undefined) return;
+  try {
+    ins.webSocketFrameError({
+      requestId,
+      timestamp: DateNow() / 1000,
+      errorMessage,
+    });
+  } catch {
+    // never let inspector instrumentation break a real WebSocket
+  }
+}
+
 class WebSocket extends EventTarget {
   constructor(url, initOrProtocols) {
     super();
@@ -573,8 +629,10 @@ class WebSocket extends EventTarget {
       // data is being sent.
       if (ArrayBufferIsView(data)) {
         op_ws_send_binary(this[_rid], data);
+        emitWebSocketFrame(this, "frameSent", 2, data);
       } else if (isArrayBuffer(data)) {
         op_ws_send_binary_ab(this[_rid], data);
+        emitWebSocketFrame(this, "frameSent", 2, data);
       } else if (ObjectPrototypeIsPrototypeOf(BlobPrototype, data)) {
         this[_queueSend](data);
       } else {
@@ -583,6 +641,7 @@ class WebSocket extends EventTarget {
           this[_rid],
           string,
         );
+        emitWebSocketFrame(this, "frameSent", 1, string);
       }
     } else {
       // Slower path if the send queue is not empty, for example when sending
@@ -690,6 +749,7 @@ class WebSocket extends EventTarget {
           }
 
           this[_serverHandleIdleTimeout]();
+          emitWebSocketFrame(this, "frameReceived", 1, data);
           const event = new MessageEvent("message", {
             data,
             origin: this[_url],
@@ -708,6 +768,7 @@ class WebSocket extends EventTarget {
           this[_serverHandleIdleTimeout]();
           // deno-lint-ignore prefer-primordials
           const buffer = d.buffer;
+          emitWebSocketFrame(this, "frameReceived", 2, buffer);
           let data;
           if (this.binaryType === "blob") {
             data = new Blob([buffer]);
@@ -733,6 +794,7 @@ class WebSocket extends EventTarget {
           this[_readyState] = CLOSED;
 
           const message = op_ws_get_error(rid);
+          emitWebSocketFrameError(this, message);
           const error = new Error(message);
           const errorEv = new ErrorEvent("error", {
             error,
@@ -797,18 +859,22 @@ class WebSocket extends EventTarget {
       const data = queue[0];
       if (ArrayBufferIsView(data)) {
         op_ws_send_binary(this[_rid], data);
+        emitWebSocketFrame(this, "frameSent", 2, data);
       } else if (isArrayBuffer(data)) {
         op_ws_send_binary_ab(this[_rid], data);
+        emitWebSocketFrame(this, "frameSent", 2, data);
       } else if (ObjectPrototypeIsPrototypeOf(BlobPrototype, data)) {
         // deno-lint-ignore prefer-primordials
         const ab = await data.slice().arrayBuffer();
         op_ws_send_binary_ab(this[_rid], ab);
+        emitWebSocketFrame(this, "frameSent", 2, ab);
       } else {
         const string = String(data);
         op_ws_send_text(
           this[_rid],
           string,
         );
+        emitWebSocketFrame(this, "frameSent", 1, string);
       }
       ArrayPrototypeShift(queue);
     }
@@ -947,6 +1013,8 @@ export {
   _serverHandleIdleTimeout,
   CLIENT,
   createWebSocketBranded,
+  emitWebSocketClosed,
+  installServerInspector,
   SERVER,
   WebSocket,
 };