tls: runtime deprecation for tls.createSecurePair()

Upgrade the deprecation for _tls_legacy (`tls.createSecurePair()`)
to a runtime deprecation.

PR-URL: #11349
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Fedor Indutny <fedor.indutny@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>

Author: jasnell

doc/api/deprecations.md

@@ -534,6 +534,14 @@ deprecated. Please use `ServerResponse.prototype.writeHead()` instead.
 *Note*: The `ServerResponse.prototype.writeHeader()` method was never documented
 as an officially supported API.
 
+<a id="DEP0064"></a>
+### DEP0064: tls.createSecurePair()
+
+Type: Runtime
+
+The `tls.createSecurePair()` API was deprecated in documentation in Node.js
+0.11.3. Users should use `tls.Socket` instead.
+
 [alloc]: buffer.html#buffer_class_method_buffer_alloc_size_fill_encoding
 [alloc_unsafe_size]: buffer.html#buffer_class_method_buffer_allocunsafe_size
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size

lib/_tls_legacy.js

@@ -3,15 +3,17 @@
 require('internal/util').assertCrypto();
 
 const assert = require('assert');
+const Buffer = require('buffer').Buffer;
+const common = require('_tls_common');
+const Connection = process.binding('crypto').Connection;
 const EventEmitter = require('events');
+const internalUtil = require('internal/util');
 const stream = require('stream');
+const Timer = process.binding('timer_wrap').Timer;
 const tls = require('tls');
 const util = require('util');
-const common = require('_tls_common');
+
 const debug = util.debuglog('tls-legacy');
-const Buffer = require('buffer').Buffer;
-const Timer = process.binding('timer_wrap').Timer;
-const Connection = process.binding('crypto').Connection;
 
 function SlabBuffer() {
   this.create();
@@ -787,18 +789,11 @@ function securePairNT(self, options) {
 }
 
 
-exports.createSecurePair = function(context,
-                                    isServer,
-                                    requestCert,
-                                    rejectUnauthorized,
-                                    options) {
-  var pair = new SecurePair(context,
-                            isServer,
-                            requestCert,
-                            rejectUnauthorized,
-                            options);
-  return pair;
-};
+function createSecurePair(context, isServer, requestCert,
+                          rejectUnauthorized, options) {
+  return new SecurePair(context, isServer, requestCert,
+                        rejectUnauthorized, options);
+}
 
 
 SecurePair.prototype.maybeInitFinished = function() {
@@ -868,7 +863,7 @@ SecurePair.prototype.error = function(returnOnly) {
 };
 
 
-exports.pipe = function pipe(pair, socket) {
+function pipe(pair, socket) {
   pair.encrypted.pipe(socket);
   socket.pipe(pair.encrypted);
 
@@ -918,7 +913,7 @@ exports.pipe = function pipe(pair, socket) {
   socket.on('timeout', ontimeout);
 
   return cleartext;
-};
+}
 
 
 function pipeCloseNT(pair, socket) {
@@ -927,3 +922,11 @@ function pipeCloseNT(pair, socket) {
   pair.encrypted.unpipe(socket);
   socket.destroySoon();
 }
+
+module.exports = {
+  createSecurePair:
+    internalUtil.deprecate(createSecurePair,
+                           'tls.createSecurePair() is deprecated. Please use ' +
+                           'tls.Socket instead.', 'DEP0064'),
+  pipe
+};

lib/tls.js

@@ -235,4 +235,6 @@ exports.TLSSocket = require('_tls_wrap').TLSSocket;
 exports.Server = require('_tls_wrap').Server;
 exports.createServer = require('_tls_wrap').createServer;
 exports.connect = require('_tls_wrap').connect;
+
+// Deprecated: DEP0064
 exports.createSecurePair = require('_tls_legacy').createSecurePair;

test/parallel/test-tls-legacy-deprecated.js

@@ -0,0 +1,12 @@
+// Flags: --no-warnings
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const tls = require('tls');
+
+common.expectWarning(
+  'DeprecationWarning',
+  'tls.createSecurePair() is deprecated. Please use tls.Socket instead.'
+);
+
+assert.doesNotThrow(() => tls.createSecurePair());