nodejs / nodejs/undici

Add WebSocket lifecycle, frame, and frame-error diagnostic events for DevTools Protocol support

Open
#4,673 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
JavaScript
Stars
7.7k
Forks
879
Avg merge
2d 16h
Merged PRs (30d)
68

Description

This would solve...

Node.js is currently developing WebSocket inspection support in DevTools, but at the moment it can only handle WebSocket open and close events.

Reference:
https://github.com/nodejs/node/pull/59404

I’d like to request further support for the data needed by the DevTools inspector.

The implementation should look like...

1. undici:websocket:created
{ websocket, url }

Required for Network.webSocketCreated.
undici:websocket:open fires after the handshake, so we need an event that fires when the WebSocket object is created.

Spec:
https://chromedevtools.github.io/devtools-protocol/tot/Network/#event-webSocketCreated

2. undici:websocket:handshakeRequest
{ websocket }

Required forNetwork.requestWillBeSent.

We need a hook for the moment when the HTTP upgrade request is sent.

Spec:
https://chromedevtools.github.io/devtools-protocol/tot/Network/#event-requestWillBeSent

3. undici:websocket:frameSent undici:websocket:frameRecieved
{ websocket, opcode, mask, payloadData }

Required for:

  • Network.webSocketFrameSent
  • Network.webSocketFrameReceived

Spec:
https://chromedevtools.github.io/devtools-protocol/tot/Network/#event-webSocketFrameSent
https://chromedevtools.github.io/devtools-protocol/tot/Network/#event-webSocketFrameReceived
https://chromedevtools.github.io/devtools-protocol/tot/Network/#type-WebSocketFrame

4. WebSocket frame error event

Required for Network.webSocketFrameError.

Undici currently has socket_error,
but it does not indicate which WebSocket instance the error belongs to—unlike other WebSocket events.

I have also considered...

Additional context

I understand that some of these events may require consideration, but I’d appreciate it if you could start by supporting the ones that are feasible.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files or tests are named. Start by locating the existing undici:websocket:open and undici:websocket:close diagnostic events, then compare their lifecycle points with the referenced DevTools Protocol events. Done means feasible lifecycle, handshake, frame sent/received, and frame-error events expose the requested data and associate errors with the correct WebSocket.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
backend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.