http docs should refer to stream.Duplex instead of net.Socket

[tniessen]

In many places in the documentation (example: 'socket' event), socket is not necessarily a net.Socket, but always a stream.Duplex (which net.Socket inherits from). We should at least mention that if we don't want to replace all references.

[jeffinnes]

I would be interested in working on this.

Would the preference be to replace the references to net.Socket with a reference to stream.Duplex?

[tniessen]

Personally, I would prefer that, but let's see what other folks think. @nodejs/http @nodejs/streams

[mcollina]

There are some data about the connection itself available on a net.Socket and the other implementations that can be passed in there. IMHO we should mention that it is a stream.Duplex subclass, and put some sort of table somewhere.

[jessekoconnor]

@mcollina and @tniessen - I have a few silly questions for you on this issue.

I agree that the docs for net.Socket documentation state pretty clearly that it extends stream.Duplex, but I am still not quite sure what the solution is that you are guys are suggestion.

Are you suggesting that we modify the description of methods and events in doc/api/http.md like I have done for the http.ClientRequest event socket like in the following draft pr? This would make sense; It also requires more code changes, which is always a bad thing. This is the solution I was thinking is most fitting.

Or are you simply suggesting that you want the docs for net.Socket documentation to be more explicate in saying that it extends stream.Duplex? This solution makes less sense to me because this class is not responsible for parameters passed into arbitrary events and method calls; but this solution would require less code changes, again not always a good thing.

Finally, you mentioned adding a table somewhere and id like to confirm that I have the right idea for it. Were you thinking that it should be a table documenting which methods and events in doc/api/http.md actually fire with a net.Socket param versus the methods/events that fire with a stream.Duplex param? This option makes sense to me but may be a duplication of work from above; or were you thinking about using a table to document the differences between net.Socket and stream.Duplex?

Any feedback is warmly welcomed, I am a first time open source contributor but long time node user searching for a way to give back to the community.

Thanks in advance :D

[addaleax]

Are you suggesting that we modify the description of methods and events in doc/api/http.md like I have done for the http.ClientRequest event socket like in the following draft pr? This would make sense; It also requires more code changes, which is always a bad thing. This is the solution I was thinking is most fitting.

The issue I see with that PR is that it doesn’t actually change the reference to net.Socket to be stream.Duplex? The text can remain the same, imo, although you could mention that the argument typically is a net.Socket.

But yeah, that generally seems to go in the right direction to me. 👍

[jessekoconnor]

Excellent. Thanks for the prompt feedback @addaleax. I updated the PR based on your comment so that the current solution can now be summarized as follows:

• update stream arg to duplex arg
• mention that a stream will sometimes be passed in
• also mention that a stream is an extension of duplex

I'll begin scoping out all of the places that I need to update in this file (and possibly other files). In the meantime I welcome reviews/feedback of the following PR #30155 (same pr as above) from @addaleax, @tniessen, @mcollina, @devnexen and any others.