feat(keepAlive): make keepAlive options consistent (#1612)

keepAlive options are now consistent with socket / node api.
keepAlive is a boolean that enables / disables keepAlive,
and keepAliveInitialDelay is the number of milliseconds to wait
before initiating keepAlive.

BREAKING CHANGE:
option `keepAlive` is now split into boolean `keepAlive` and
number `keepAliveInitialDelay`

Fixes NODE-998

Author: daprahamian

CHANGES_3.0.0.md

@@ -198,6 +198,10 @@ testCollection.updateOne({_id: 'test'}, {});
 // An error is returned: The update operation document must contain at least one atomic operator.
 ```
 
+### `keepAlive`
+
+Wherever it occurs, the option `keepAlive` has been changed. `keepAlive` is now a boolean that enables/disables `keepAlive`, while `keepAliveInitialDelay` specifies how long to wait before initiating keepAlive. This brings the API in line with [NodeJS's socket api](https://nodejs.org/dist/latest-v9.x/docs/api/all.html#net_socket_setkeepalive_enable_initialdelay)
+
 ### Tests
 
 We have updated all of the tests to use [Mocha](https://mochajs.org) and a new test runner, [`mongodb-test-runner`](https://github.com./mongodb-js/mongodb-test-runner), which

lib/topologies/mongos.js

@@ -58,6 +58,7 @@ var legalOptionNames = [
   'autoReconnect',
   'emitError',
   'keepAlive',
+  'keepAliveInitialDelay',
   'noDelay',
   'connectTimeoutMS',
   'socketTimeoutMS',
@@ -96,7 +97,8 @@ var legalOptionNames = [
  * @param {string} [options.servername=null] String containing the server name requested via TLS SNI.
  * @param {object} [options.socketOptions=null] Socket options
  * @param {boolean} [options.socketOptions.noDelay=true] TCP Socket NoDelay option.
- * @param {number} [options.socketOptions.keepAlive=0] TCP KeepAlive on the socket with a X ms delay before start.
+ * @param {boolean} [options.socketOptions.keepAlive=true] TCP Connection keep alive enabled
+ * @param {number} [options.socketOptions.keepAliveInitialDelay=30000] The number of milliseconds to wait before initiating keepAlive on the TCP socket
  * @param {number} [options.socketOptions.connectTimeoutMS=0] TCP Connection timeout setting
  * @param {number} [options.socketOptions.socketTimeoutMS=0] TCP Socket timeout setting
  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit.
@@ -175,10 +177,6 @@ class Mongos extends TopologyBase {
 
     // Translate all the options to the mongodb-core ones
     clonedOptions = translateOptions(clonedOptions, socketOptions);
-    if (typeof clonedOptions.keepAlive === 'number') {
-      clonedOptions.keepAliveInitialDelay = clonedOptions.keepAlive;
-      clonedOptions.keepAlive = clonedOptions.keepAlive > 0;
-    }
 
     // Build default client information
     clonedOptions.clientInfo = this.clientInfo;

lib/topologies/replset.js

@@ -61,6 +61,7 @@ var legalOptionNames = [
   'autoReconnect',
   'emitError',
   'keepAlive',
+  'keepAliveInitialDelay',
   'noDelay',
   'connectTimeoutMS',
   'socketTimeoutMS',
@@ -106,7 +107,8 @@ var legalOptionNames = [
  * @param {string} [options.servername=null] String containing the server name requested via TLS SNI.
  * @param {object} [options.socketOptions=null] Socket options
  * @param {boolean} [options.socketOptions.noDelay=true] TCP Socket NoDelay option.
- * @param {number} [options.socketOptions.keepAlive=0] TCP KeepAlive on the socket with a X ms delay before start.
+ * @param {boolean} [options.socketOptions.keepAlive=true] TCP Connection keep alive enabled
+ * @param {number} [options.socketOptions.keepAliveInitialDelay=30000] The number of milliseconds to wait before initiating keepAlive on the TCP socket
  * @param {number} [options.socketOptions.connectTimeoutMS=10000] TCP Connection timeout setting
  * @param {number} [options.socketOptions.socketTimeoutMS=0] TCP Socket timeout setting
  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit.
@@ -182,10 +184,6 @@ class ReplSet extends TopologyBase {
 
     // Translate all the options to the mongodb-core ones
     clonedOptions = translateOptions(clonedOptions, socketOptions);
-    if (typeof clonedOptions.keepAlive === 'number') {
-      clonedOptions.keepAliveInitialDelay = clonedOptions.keepAlive;
-      clonedOptions.keepAlive = clonedOptions.keepAlive > 0;
-    }
 
     // Build default client information
     clonedOptions.clientInfo = this.clientInfo;

lib/topologies/server.js

@@ -55,6 +55,7 @@ var legalOptionNames = [
   'autoReconnect',
   'emitError',
   'keepAlive',
+  'keepAliveInitialDelay',
   'noDelay',
   'connectTimeoutMS',
   'socketTimeoutMS',
@@ -96,7 +97,8 @@ var legalOptionNames = [
  * @param {object} [options.socketOptions=null] Socket options
  * @param {boolean} [options.socketOptions.autoReconnect=true] Reconnect on error.
  * @param {boolean} [options.socketOptions.noDelay=true] TCP Socket NoDelay option.
- * @param {number} [options.socketOptions.keepAlive=0] TCP KeepAlive on the socket with a X ms delay before start.
+ * @param {boolean} [options.socketOptions.keepAlive=true] TCP Connection keep alive enabled
+ * @param {number} [options.socketOptions.keepAliveInitialDelay=30000] The number of milliseconds to wait before initiating keepAlive on the TCP socket
  * @param {number} [options.socketOptions.connectTimeoutMS=0] TCP Connection timeout setting
  * @param {number} [options.socketOptions.socketTimeoutMS=0] TCP Socket timeout setting
  * @param {number} [options.reconnectTries=30] Server attempt to reconnect #times
@@ -173,10 +175,6 @@ class Server extends TopologyBase {
 
     // Translate all the options to the mongodb-core ones
     clonedOptions = translateOptions(clonedOptions, socketOptions);
-    if (typeof clonedOptions.keepAlive === 'number') {
-      clonedOptions.keepAliveInitialDelay = clonedOptions.keepAlive;
-      clonedOptions.keepAlive = clonedOptions.keepAlive > 0;
-    }
 
     // Build default client information
     clonedOptions.clientInfo = this.clientInfo;

test/functional/mongo_client_tests.js

@@ -181,7 +181,8 @@ describe('MongoClient', function() {
           poolSize: 10,
           autoReconnect: false,
           noDelay: false,
-          keepAlive: 100,
+          keepAlive: true,
+          keepAliveInitialDelay: 100,
           connectTimeoutMS: 444444,
           socketTimeoutMS: 555555
         },
@@ -226,7 +227,8 @@ describe('MongoClient', function() {
             poolSize: 1,
             socketOptions: {
               noDelay: false,
-              keepAlive: 100,
+              keepAlive: true,
+              keepAliveInitialDelay: 100,
               connectTimeoutMS: 444444,
               socketTimeoutMS: 555555
             }
@@ -275,7 +277,8 @@ describe('MongoClient', function() {
           poolSize: 1,
           socketOptions: {
             noDelay: false,
-            keepAlive: 100,
+            keepAlive: true,
+            keepAliveInitialDelay: 100,
             connectTimeoutMS: 444444,
             socketTimeoutMS: 555555
           }
@@ -500,7 +503,8 @@ describe('MongoClient', function() {
       MongoClient.connect(
         configuration.url(),
         {
-          keepAlive: 100
+          keepAlive: true,
+          keepAliveInitialDelay: 100
         },
         function(err, client) {
           test.equal(null, err);

test/functional/reconnect_tests.js

@@ -61,7 +61,7 @@ describe('Reconnect', function() {
           db: { native_parser: true, bufferMaxEntries: -1 },
           server: {
             poolSize: 20,
-            socketOptions: { autoReconnect: true, keepAlive: 50 },
+            socketOptions: { autoReconnect: true, keepAlive: true, keepAliveInitialDelay: 50 },
             reconnectTries: 1000,
             reconnectInterval: 1000
           }

test/functional/replset_connection_tests.js

@@ -201,7 +201,10 @@ describe('ReplSet (Connection)', function() {
           new Server(configuration.host, configuration.port + 1),
           new Server(configuration.host, configuration.port + 2)
         ],
-        { socketOptions: { keepAlive: 100 }, rs_name: configuration.replicasetName }
+        {
+          socketOptions: { keepAlive: true, keepAliveInitialDelay: 100 },
+          rs_name: configuration.replicasetName
+        }
       );
 
       var client = new MongoClient(replSet, { w: 0 });