search

websockets / ws

Simple to use, blazing fast and thoroughly tested WebSocket client and server for Node.js
MIT License
21.34k stars 2.3k forks source link

doc: which events are proxied through `createWebSocketStream` #2228

Closed coolaj86 closed 6 days ago

coolaj86 commented 4 weeks ago

The documentation doesn't specify how the ws module stream maps to which type of Node Duplex Stream.

I assume that it behaves like a TCP Duplex Stream: https://nodejs.org/api/net.html#class-netsocket.

I also assume that the ping and pong and keepalive timeouts are proxied in a meaningful way.

lpinca commented 3 weeks ago

I assume that it behaves like a TCP Duplex Stream

Yes, a plain https://nodejs.org/api/stream.html#class-streamduplex specifically.

I also assume that the ping and pong and keepalive timeouts are proxied in a meaningful way.

You can't send and receive pings/pongs from the wrapper Duplex, but they are correctly handled by the wrapped WebSocket.

Is it necessary to list the events? They are the standard Duplex events and I would prefer to not keep them in sync in ws documentation. The 'timeout' event is not emitted, see https://github.com/websockets/ws/blob/b73b11828d166e9692a9bffe9c01a7e93bab04a8/lib/websocket.js#L233.

coolaj86 commented 1 week ago

Is it necessary to list the events? They are the standard Duplex events

I don't think that there are a standard set of events. I think it's all implementation specific - such as the use of 'end' vs 'close' and such. I think Duplexes are basically two-way EventEmitters, and can handle any arbitrary (hopefully documented) event.

If it's listed, it's clear what this implementation handles. If it's not listed, someone has to guess or read the code.

lpinca commented 1 week ago

I don't think that there are a standard set of events. I think it's all implementation specific - such as the use of 'end' vs 'close' and such. I think Duplexes are basically two-way EventEmitters, and can handle any arbitrary (hopefully documented) event.

Yes there is standard set of events. See https://nodejs.org/api/stream.html. For a Duplex the set is events of Readable ∪ events of Writable. 'end' and 'close' have different meanings and they are used accordingly. There are no implementation specific events or they would have already been documented.

If it's not listed, someone has to guess or read the code.

They just have to read Node.js documentation where the events are listed.

lpinca commented 6 days ago

I'm closing this as per https://github.com/websockets/ws/pull/2228#issuecomment-2161283387 and https://github.com/websockets/ws/pull/2228#issuecomment-2196964912. Thank you anyway.