tls: The TLS API is inconsistent with the TCP API

Add 'secureConnect' event to tls.CleartextStream.

Fixes #1467.

doc/api/tls.markdown

@@ -27,7 +27,7 @@ Alternatively you can send the CSR to a Certificate Authority for signing.
 `test/fixtures/keys/Makefile` in the Node source code)
 
 
-### s = tls.connect(port, [host], [options], callback)
+### s = tls.connect(port, [host], [options], secureConnectListener)
 
 Creates a new client connection to the given `port` and `host`. (If `host`
 defaults to `localhost`.) `options` should be an object which specifies
@@ -49,14 +49,10 @@ defaults to `localhost`.) `options` should be an object which specifies
 
   - `servername`: Servername for SNI (Server Name Indication) TLS extension.
 
-`tls.connect()` returns a [CleartextStream](#tls.CleartextStream) object.
+The `secureConnectListener` parameter will be added as a listener for the
+['secureConnect'](#event_secureConnect_) event.
 
-After the TLS/SSL handshake the `callback` is called. The `callback` will be
-called no matter if the server's certificate was authorized or not. It is up
-to the user to test `s.authorized` to see if the server certificate was signed
-by one of the specified CAs. If `s.authorized === false` then the error
-can be found in `s.authorizationError`. Also if NPN was used - you can check
-`s.npnProtocol` for negotiated protocol.
+`tls.connect()` returns a [CleartextStream](#tls.CleartextStream) object.
 
 
 ### STARTTLS
@@ -237,6 +233,18 @@ read/write an encrypted data as a cleartext data.
 This instance implements a duplex [Stream](streams.html#streams) interfaces.
 It has all the common stream methods and events.
 
+#### Event: 'secureConnect'
+
+`function () {}`
+
+This event is emitted after a new connection has been successfully handshaked. 
+The listener will be called no matter if the server's certificate was
+authorized or not. It is up to the user to test `cleartextStream.authorized`
+to see if the server certificate was signed by one of the specified CAs.
+If `cleartextStream.authorized === false` then the error can be found in
+`cleartextStream.authorizationError`. Also if NPN was used - you can check
+`cleartextStream.npnProtocol` for negotiated protocol.
+
 #### cleartextStream.authorized
 
 A boolean that is `true` if the peer certificate was signed by one of the
@@ -274,4 +282,3 @@ Example:
 
 If the peer does not provide a certificate, it returns `null` or an empty
 object.
-

lib/tls.js

@@ -981,6 +981,9 @@ exports.connect = function(port /* host, options, cb */) {
   }
 
   var cleartext = pipe(pair, socket);
+  if (cb) {
+    cleartext.on('secureConnect', cb);
+  }
 
   socket.connect(port, host);
 
@@ -996,7 +999,7 @@ exports.connect = function(port /* host, options, cb */) {
       cleartext.authorized = true;
     }
 
-    if (cb) cb();
+    cleartext.emit('secureConnect');
   });
 
   cleartext._controlReleased = true;

test/simple/test-tls-connect-simple.js

@@ -0,0 +1,57 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var common = require('../common');
+var assert = require('assert');
+var tls = require('tls');
+var fs = require('fs');
+
+var clientConnected = 0;
+var serverConnected = 0;
+
+var options = {
+  key: fs.readFileSync(common.fixturesDir + '/keys/agent1-key.pem'),
+  cert: fs.readFileSync(common.fixturesDir + '/keys/agent1-cert.pem')
+};
+
+var server = tls.Server(options, function(socket) {
+  if (++serverConnected === 2) {
+    server.close();
+  }
+});
+
+server.listen(common.PORT, function() {
+  var client1 = tls.connect(common.PORT, function() {
+    ++clientConnected;
+    client1.end();
+  });
+
+  var client2 = tls.connect(common.PORT);
+  client2.on('secureConnect', function() {
+    ++clientConnected;
+    client2.end();
+  });
+});
+
+process.on('exit', function() {
+  assert.equal(clientConnected, 2);
+  assert.equal(serverConnected, 2);
+});