tls: doc-only deprecate new TLSSocket constructor

[jasnell]

Fixes: #10555
Refs: #10846

The new tls.TLSSocket() constructor does not set up all of the
necessary lifecycle management or event handlers necessary for
proper use. The tls.connect() method really should be the way
that all tls.TLSSocket() instances are created. This commit
begins the eventual phasing out of the new tls.TLSSocket()
constructor with a doc-only deprecation.

Signed-off-by: James M Snell jasnell@gmail.com

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[mscdex]

How are we supposed to create an unconnected socket then? Why can't the "lifecycle management or event handlers" be done once the socket's connect() has been called or similar?

[jasnell]

Well, this is only a doc only deprecation for now so the current way continues to work. What I would suggest is needed is an additional api or option to connect that allows creating the unconnected socket.

[jasnell]

Given the lack of attention it appears there's no support for this yet.

[mildsunrise]

Sorry, I've been pretty busy lately. Maybe I'm missing things, but I'm initially -1 on this since tls.connect() is only for creating client sockets. tls.connect() is too specialized / high level to generalize it into server sockets as well IMO, and asking users to create an unbound tls.Server and emit('connection') is inadequate as it doesn't expose the socket while the handshake takes place.