Clarification needed regarding the http/net Server `keepAlive` options

[dominykas]

Affected URL(s)

No response

Description of the problem

Docs for net.createServer and http.createServer say:

keepAlive If set to true, it enables keep-alive functionality on the socket immediately after a new incoming connection is received, similarly on what is done in socket.setKeepAlive(). Default: false.

This is somewhat misleading, because it does not say what happens for the default false - it could be interpreted as "false disables keep-alive functionality" - which, if I understand things correctly, it does not - this flag changes when keep-alive becomes enabled, not if? But I have not figured out what the answer to the "when" is - would be nice if it was documented.

---

Additionally, the docs for http's server.keepAliveTimeout say:

A value of 0 will disable the keep-alive timeout behavior on incoming connections. A value of 0 makes the HTTP server behave similarly to Node.js versions prior to 8.0.0, which did not have a keep-alive timeout.

This is somewhat presumptuous on people knowing what the behavior was 8 years ago, whereby some of the people reading it might not have even known Node.js exists at that point (or they maybe just got old and can't remember anymore...), so describing that behavior explicitly would be nice.

But that aside, the phrasing can probably improved, because without reading it carefully (e.g. by reading it through an LLM lens, don't ask me how I know 😁), one might misinterpret that 0 means that it will disable the "keep-alive" rather than the "timeout". Perhaps it needs to be rephrased along the lines of "A value of 0 will allow keep-alive connections to persist forever." A note on the implications (memory usage? file handle usage?) would also be useful.

Now, I'll admit this is not the area I'm very familiar with, so maybe I'm misreading this entirely?

Happy to work on the improvements with someone guiding with providing details.

---

On a completely unrelated note - 😍 #59203