tls: doc-only deprecate new TLSSocket constructor

Fixes: nodejs#10555
Refs: nodejs#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 <[email protected]>

doc/api/deprecations.md

@@ -881,7 +881,7 @@ changes:
 Type: End-of-Life
 
 The [`tls.CryptoStream`][] class was removed. Please use
-[`tls.TLSSocket`][] instead.
+[`tls.connect()`][] instead.
 
 ### DEP0043: `tls.SecurePair`
 <!-- YAML
@@ -908,7 +908,7 @@ changes:
 Type: Documentation-only
 
 The [`tls.SecurePair`][] class is deprecated. Please use
-[`tls.TLSSocket`][] instead.
+[`tls.connect()`][] instead.
 
 ### DEP0044: `util.isArray()`
 <!-- YAML
@@ -2699,6 +2699,18 @@ resolutions not in `node_modules`. This means there will not be deprecation
 warnings for `"exports"` in dependencies. With `--pending-deprecation`, a
 runtime warning results no matter where the `"exports"` usage occurs.
 
+### DEP0XXX: `new tls.TLSSocket(socket[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+Type: Documentation-only
+
+The preferred method for creating [`tls.TLSSocket`][] instances is to use the
+[`tls.connect()`][] API. While using `new tls.TLSSocket()` will create the
+socket, the various mechanisms for managing the lifetime of the underlying
+socket and for validating the peer certificate and identity are not configured.
+
 [Legacy URL API]: url.md#url_legacy_url_api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -2787,6 +2799,7 @@ runtime warning results no matter where the `"exports"` usage occurs.
 [`tls.SecurePair`]: tls.md#tls_class_tls_securepair
 [`tls.TLSSocket`]: tls.md#tls_class_tls_tlssocket
 [`tls.checkServerIdentity()`]: tls.md#tls_tls_checkserveridentity_hostname_cert
+[`tls.connect()`]: tls.md#tls_tls_connect_options_callback
 [`tls.createSecureContext()`]: tls.md#tls_tls_createsecurecontext_options
 [`url.format()`]: url.md#url_url_format_urlobject
 [`url.parse()`]: url.md#url_url_parse_urlstring_parsequerystring_slashesdenotehost

doc/api/tls.md

@@ -376,7 +376,7 @@ added: v0.3.4
 deprecated: v0.11.3
 -->
 
-> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
+> Stability: 0 - Deprecated: Use [`tls.connect()`][] instead.
 
 The `tls.CryptoStream` class represents a stream of encrypted data. This class
 is deprecated and should no longer be used.
@@ -397,7 +397,7 @@ added: v0.3.2
 deprecated: v0.11.3
 -->
 
-> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
+> Stability: 0 - Deprecated: Use [`tls.connect()`][] instead.
 
 Returned by [`tls.createSecurePair()`][].
 
@@ -714,6 +714,10 @@ connection is open.
 <!-- YAML
 added: v0.11.4
 changes:
+  - version: REPLACEME
+    pr-url: REPLACEME
+    description: The new tls.TLSSocket() constructor is deprecated
+                 in docs only.
   - version: v12.2.0
     pr-url: https://github.com/nodejs/node/pull/27497
     description: The `enableTrace` option is now supported.
@@ -722,6 +726,8 @@ changes:
     description: ALPN options are supported now.
 -->
 
+> Stability: 0 - Deprecated: Use [`tls.connect()`][] instead.
+
 * `socket` {net.Socket|stream.Duplex}
   On the server side, any `Duplex` stream. On the client side, any
   instance of [`net.Socket`][] (for generic `Duplex` stream support
@@ -1736,7 +1742,7 @@ changes:
     description: ALPN options are supported now.
 -->
 
-> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
+> Stability: 0 - Deprecated: Use [`tls.connect()`][] instead.
 
 * `context` {Object} A secure context object as returned by
   `tls.createSecureContext()`
@@ -1784,7 +1790,7 @@ socket.pipe(pair.encrypted);
 can be replaced by:
 
 ```js
-secureSocket = tls.TLSSocket(socket, options);
+secureSocket = tls.connect({ socket, ...options });
 ```
 
 where `secureSocket` has the same API as `pair.cleartext`.