http,inspector: add WebSocket upgrade observability

[GrinZero]

Summary

This patch adds observability for HTTP client WebSocket upgrades through both diagnostics_channel and the inspector Network domain.

Today, regular HTTP client requests are surfaced through the existing http.client.* lifecycle, but upgrade-based WebSocket traffic is not represented cleanly:

• the HTTP upgrade handshake is not exposed as a first-class lifecycle
• WebSocket frames after the upgrade are not emitted through inspector network events

This change fills that gap.

Changes

• Add a shared internal WebSocket upgrade observer.
• Emit diagnostics channel events for HTTP client upgrade handshakes.
• Emit inspector Network.webSocket* events for:
  • socket creation
  • handshake request
  • handshake response
  • sent frames
  • received frames
  • socket close
• Prevent upgraded WebSocket requests from being double-reported as normal HTTP request/response traffic.
• Document the new diagnostics channel hooks.
• Add parallel test coverage for both diagnostics channel and inspector behavior.

Why This Approach

This is implemented at the HTTP upgrade / inspector plumbing layer rather than in a specific WebSocket client API.

That keeps the change aligned with where the underlying lifecycle actually occurs:

1. the initial HTTP upgrade request
2. the handshake response
3. the frame traffic that follows on the upgraded socket

It also avoids coupling the observability model to any single user-facing API, making the behavior reusable for clients built on the same upgrade path.

Scope

This PR does not add special handling or declarations for the built-in WebSocket or WebSocketStream APIs directly.

Those APIs are a separate surface-area discussion. The goal here is narrower: add transport-level observability for WebSocket upgrades and frame traffic first, so higher-level clients can benefit from the same underlying inspector and diagnostics hooks without expanding this PR beyond that scope.

Testing

Automated

python3 tools/test.py \
  test/parallel/test-diagnostics-channel-http-server-upgrade-websocket.js \
  test/parallel/test-diagnostics-channel-http-upgrade-websocket.js \
  test/parallel/test-inspector-emit-protocol-event-errors.js \
  test/parallel/test-inspector-emit-protocol-event.js \
  test/parallel/test-inspector-network-http-upgrade-websocket.js

Manual e2e

Used a small local Koa app with a /ws route:

• /ws opens an outbound ws connection to wss://echo.websocket.org/
• the route sends an initial message after connection
• follow-up frames are sent through /ws?message=...
• verified that the inspector surfaces the full WebSocket lifecycle end to end:
  • socket creation
  • handshake request
  • handshake response
  • frame send
  • frame receive
  • socket close

Refs

• Tracking issue: Stabilizing network inspection in Node.js #53946

[nodejs-github-bot]

Review requested:

• @nodejs/http
• @nodejs/inspector
• @nodejs/net

[GrinZero]

E2E

const Koa = require('koa')
const Router = require('koa-router')
const WebSocket = require('ws')

const app = new Koa()
const router = new Router()

let ws
let opened

function ensureWebSocket() {
  if (ws && ws.readyState === WebSocket.OPEN) return
  Promise.resolve()

  ws = new WebSocket('wss://echo.websocket.org/')
  opened = new Promise((resolve) => ws.once('open', resolve))

  ws.on('message', (data) => {
    console.log('WebSocket message:', data.toString())
  })

  ws.on('close', () => {
    console.log('WebSocket connection closed')
    ws = null
    opened = null
  })

  return opened
}

router.get('/ws', async (ctx) => {
  await ensureWebSocket()
  ws.send(ctx.query.message || 'Hello from Koa')
  ctx.body = 'WebSocket: Send'
})

app.use(router.routes())
app.listen(3000, () => {
  console.log('GET http://127.0.0.1:3000/ws?message=ping')
})

[GrinZero]

A slight push, hoping someone will notice.

[legendecas]

I think we should focus on improving the built-in WebSocket API inspection at the moment, as in

node/lib/internal/inspector/network_undici.js

Lines 244 to 245 in f67cf47

	['undici:websocket:open', onWebSocketOpen],
	['undici:websocket:close', onWebSocketClose],

.

[GrinZero]

I think we should focus on improving the built-in WebSocket API inspection at the moment, as in

node/lib/internal/inspector/network_undici.js

Lines 244 to 245 in f67cf47

	['undici:websocket:open', onWebSocketOpen],
	['undici:websocket:close', onWebSocketClose],

.

😂Haha, you found it. Not without a plan, I actually have three PRs waiting to be implemented: native sse, fetch-based sse, and native webso.

[GrinZero]

I wrote the manual analysis of the websocket protocol first because the new version is not yet widely circulated, and many low-level libraries still use the old version.

[mcollina]

lgtm

[GrinZero]

Thanks, the Lint issue has been fixed. I've documented this type of rule to my local tool to make sure that the PR has as few of the same issues as possible.

[GrinZero]

I've noticed other CI errors, mainly because the http.client.response.bodyChunkReceived event is present in adc events to reduce conflicts.I suggest waiting. #62915 First, merge and complete DC events to reduce conflicts.