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.