Repository: node
Issue: Tracking issue: Stabilizing network inspection in Node.js
Labels: inspector,diagnostics_channel

Related issue: https://github.com/nodejs/diagnostics/issues/75
Initial implementation: https://github.com/nodejs/node/pull/53593

This issue is for tracking the remaining work to make network inspection in Node.js stable and to provide a comprehensive debugging experience.

# Network inspection features

- ✅ - Implemented
- 🚫 - No plan to implement at the moment
- 🔍 - Need further investigation or discussion

## Basic information

| Feature | `http` | `https` | `http2` | `fetch` | `WebSocket` |
| --- | --- | --- | --- | --- | --- |
| type | ✅ #54156 | ✅ #54156 |  | ✅ #56488 |  |
| timestamp | ✅ #53593 | ✅ #53593 |  | ✅ #56488 |  |
| error | ✅ #54246 | ✅ #54246 |  | ✅ #56488 |  |

Related protocols:

- `Network.requestWillBeSent`
- `Network.responseReceived`
- `Network.loadingFinished`
- `Network.loadingFailed`
- `Network.webSocketCreated`
- `Network.webSocketClosed`
- `Network.webSocketFrameError`

## Request details

The details of the request, such as the request body, cookies, and query parameters. The [`Network.Request`](https://chromedevtools.github.io/devtools-protocol/tot/Network/#type-Request) object is used to represent the request. Some features such as `referrerPolicy` are only available in browser contexts.

| Feature | `http` | `https` | `http2` | `fetch` | `WebSocket` |
| --- | --- | --- | --- | --- | --- |
| url | ✅ #53593 | ✅ #53593 |  | ✅ #56488 |  |
| method | ✅ #53593 | ✅ #53593 |  | ✅ #56488 |  |
| headers | ✅ #54156 | ✅ #54156 |  | ✅ #56488 |  |
| postData | 🔍 | 🔍 |  |  |  |

Related protocols:

- `Network.requestWillBeSent`
- `Network.websocketFrameSent`
- `Network.webSocketWillSendHandshakeRequest`

## 🔍 Response details

The details of the response, such as the response body, and headers. The [`Network.Response`](https://chromedevtools.github.io/devtools-protocol/tot/Network/#type-Response) object is used to represent the response. Some features such as early hits are only available for browser contexts.

| Feature | `http` | `https` | `http2` | `fetch` | `WebSocket` |
| --- | --- | --- | --- | --- | --- |
| url | ✅ #54156 | ✅ #54156 |  | ✅ #56488 |  |
| status | ✅ #54156 | ✅ #54156 |  | ✅ #56488 |  |
| headers | ✅ #54156 | ✅ #54156 |  | ✅ #56488 |  |
| mimeType |  |  |  |  |  |

> [!CAUTION]
> We can't consume the response body within the `diagnostics_channel` hook. We need to investigate how to handle the response body. (ref. https://github.com/nodejs/node/pull/53593#discussion_r1658039637)

Related protocols:

- `Network.responseReceived`
- `Network.websocketFrameReceived`
- `Network.webSocketHandshakeResponseReceived`

## 🔍 Request initiator

The initiator of the request, such as the script URL, the line number, and the stack trace. The [`Network.Initiator`](https://chromedevtools.github.io/devtools-protocol/tot/Network/#type-Initiator) object is used to represent the initiator.

| Feature | `http` | `https` | `http2` | `fetch` | `WebSocket` |
| --- | --- | --- | --- | --- | --- |
| initiator |  |  |  |  |  |

Related protocols:

- `Network.requestWillBeSent`
- `Network.webSocketCreated`

## 🚫 Network conditions and throttling

The network conditions and throttling information of the request and response. The [`Network.emulateNetworkConditions`](https://chromedevtools.github.io/devtools-protocol/tot/Network/#method-emulateNetworkConditions) command is used to emulate network conditions.


## 🚫 Security and authentication information

The security and authentication information of the request and response. The [`SecurityDetails`](https://chromedevtools.github.io/devtools-protocol/tot/Network/#type-SecurityDetails) object is used to represent the security details.

## Others

If there are any other features that are not covered by the above categories, please let us know and we will add them to the list.

# Node.js specific features

These are network inspection features specific to Node.js applications, including:

- Monitoring incoming requests: Track and inspect incoming HTTP/HTTPS requests to the Node.js server, including headers, body, and timing information.
- Monitoring outgoing responses: Track and inspect outgoing HTTP/HTTPS responses from the Node.js server, including headers, body, and timing information.

These features are not available in the browser context. We plan to support these features in collaboration with the ChromeDevTools team. To move forward with the implementation, we will create a design doc for these features and discuss the specs with the ChromeDevTools team.

# Next steps

- [ ] Implement the remaining features ready for implementation in the table above
- [x] Investigate the support for WebSocket inspection in Node.js
- [ ] Investigate the support for fetch inspection in Node.js
- [ ] Investigate the support for HTTP/2 inspection in Node.js
- [x] Document the design doc for Node.js specific features to collaborate with the ChromeDevTools team.