Expose AllowListPolicy and deprecate WhiteListPolicy

Author: jorgebay

doc/features/tuning-policies/README.md

@@ -20,8 +20,8 @@ hosts in the remote data centers, but those are always tried after the local nod
 - `RoundRobinPolicy`: a policy that yields nodes in a round-robin fashion.
 - `TokenAwarePolicy`: a policy that yields replica nodes for a given partition key and keyspace. The token-aware policy
 uses a child policy to retrieve the next nodes in case the replicas for a partition key are not available.
-- `WhiteListPolicy`: a policy that wraps the provided child policy but only "allow" hosts from the provided
-whilelist. Keep in mind however that this policy defeats somewhat the host auto-detection of the driver. As such, this 
+- `AllowListPolicy`: a policy that wraps the provided child policy but only "allow" hosts from the provided
+list. Keep in mind however that this policy defeats somewhat the host auto-detection of the driver. As such, this 
 policy is only useful in a few special cases or for testing, but is not optimal in general.
 
 ### Default load-balancing policy

lib/policies/index.d.ts

@@ -63,8 +63,11 @@ export namespace policies {
       constructor(childPolicy: LoadBalancingPolicy);
     }
 
-    class WhiteListPolicy extends LoadBalancingPolicy {
-      constructor(childPolicy: LoadBalancingPolicy, whiteList: string[]);
+    class AllowListPolicy extends LoadBalancingPolicy {
+      constructor(childPolicy: LoadBalancingPolicy, allowList: string[]);
+    }
+
+    class WhiteListPolicy extends AllowListPolicy {
     }
 
     class RoundRobinPolicy extends LoadBalancingPolicy {

lib/policies/load-balancing.js

@@ -366,15 +366,15 @@ TokenAwarePolicy.prototype.getOptions = function () {
 
 /**
  * Create a new policy that wraps the provided child policy but only "allow" hosts
- * from the provided while list.
+ * from the provided list.
  * @class
  * @classdesc
  * A load balancing policy wrapper that ensure that only hosts from a provided
- * white list will ever be returned.
+ * allow list will ever be returned.
  * <p>
  * This policy wraps another load balancing policy and will delegate the choice
  * of hosts to the wrapped policy with the exception that only hosts contained
- * in the white list provided when constructing this policy will ever be
+ * in the allow list provided when constructing this policy will ever be
  * returned. Any host not in the while list will be considered ignored
  * and thus will not be connected to.
  * <p>
@@ -386,39 +386,36 @@ TokenAwarePolicy.prototype.getOptions = function () {
  * data-center then you should use DCAwareRoundRobinPolicy and *not* this policy
  * in particular.
  * @param {LoadBalancingPolicy} childPolicy the wrapped policy.
- * @param {Array.<string>}  whiteList the white listed hosts address in the format ipAddress:port.
+ * @param {Array.<string>}  allowList The hosts address in the format ipAddress:port.
  * Only hosts from this list may get connected
  * to (whether they will get connected to or not depends on the child policy).
  * @extends LoadBalancingPolicy
  * @constructor
  */
-function WhiteListPolicy (childPolicy, whiteList) {
+function AllowListPolicy (childPolicy, allowList) {
   if (!childPolicy) {
     throw new Error("You must specify a child load balancing policy");
   }
-  if (!Array.isArray(whiteList)) {
-    throw new Error("You must provide the white list of host addresses");
+  if (!Array.isArray(allowList)) {
+    throw new Error("You must provide the list of allowed host addresses");
   }
+
   this.childPolicy = childPolicy;
-  const map = {};
-  whiteList.forEach(function (address) {
-    map[address] = true;
-  });
-  this.whiteList = map;
+  this.allowList = new Map(allowList.map(address => [ address, true ]));
 }
 
-util.inherits(WhiteListPolicy, LoadBalancingPolicy);
+util.inherits(AllowListPolicy, LoadBalancingPolicy);
 
-WhiteListPolicy.prototype.init = function (client, hosts, callback) {
+AllowListPolicy.prototype.init = function (client, hosts, callback) {
   this.childPolicy.init(client, hosts, callback);
 };
 
 /**
- * Uses the child policy to return the distance to the host if included in the white list.
+ * Uses the child policy to return the distance to the host if included in the allow list.
  * Any host not in the while list will be considered ignored.
  * @param host
  */
-WhiteListPolicy.prototype.getDistance = function (host) {
+AllowListPolicy.prototype.getDistance = function (host) {
   if (!this._contains(host)) {
     return types.distance.ignored;
   }
@@ -430,14 +427,14 @@ WhiteListPolicy.prototype.getDistance = function (host) {
  * @returns {boolean}
  * @private
  */
-WhiteListPolicy.prototype._contains = function (host) {
-  return !!this.whiteList[host.address];
+AllowListPolicy.prototype._contains = function (host) {
+  return !!this.allowList.get(host.address);
 };
 
 /**
- * Returns the hosts to use for a new query filtered by the white list.
+ * Returns the hosts to use for a new query filtered by the allow list.
  */
-WhiteListPolicy.prototype.newQueryPlan = function (keyspace, info, callback) {
+AllowListPolicy.prototype.newQueryPlan = function (keyspace, info, callback) {
   const self = this;
   this.childPolicy.newQueryPlan(keyspace, info, function (err, iterator) {
     if (err) {
@@ -447,7 +444,7 @@ WhiteListPolicy.prototype.newQueryPlan = function (keyspace, info, callback) {
   });
 };
 
-WhiteListPolicy.prototype._filter = function (childIterator) {
+AllowListPolicy.prototype._filter = function (childIterator) {
   const self = this;
   return {
     next: function () {
@@ -463,13 +460,31 @@ WhiteListPolicy.prototype._filter = function (childIterator) {
 /**
  * Gets an associative array containing the policy options.
  */
-WhiteListPolicy.prototype.getOptions = function () {
+AllowListPolicy.prototype.getOptions = function () {
   return new Map([
     ['childPolicy', this.childPolicy.constructor !== undefined ? this.childPolicy.constructor.name : null ],
-    ['whitelist', Object.keys(this.whiteList)]
+    ['allowList', Array.from(this.allowList.keys())]
   ]);
 };
 
+/**
+ * Creates a new instance of the policy.
+ * @classdesc
+ * Exposed for backward-compatibility only, it's recommended that you use {@link AllowListPolicy} instead.
+ * @param {LoadBalancingPolicy} childPolicy the wrapped policy.
+ * @param {Array.<string>} allowList The hosts address in the format ipAddress:port.
+ * Only hosts from this list may get connected to (whether they will get connected to or not depends on the child
+ * policy).
+ * @extends AllowListPolicy
+ * @deprecated Use allow-list instead. It will be removed in future major versions.
+ * @constructor
+ */
+function WhiteListPolicy(childPolicy, allowList) {
+  AllowListPolicy.call(this, childPolicy, allowList);
+}
+
+util.inherits(WhiteListPolicy, AllowListPolicy);
+
 /**
  * A load-balancing policy implementation that attempts to fairly distribute the load based on the amount of in-flight
  * request per hosts. The local replicas are initially shuffled and
@@ -856,9 +871,13 @@ function getDataCenters(hosts) {
   return new Set(hosts.values().map(h => h.datacenter));
 }
 
-exports.DCAwareRoundRobinPolicy = DCAwareRoundRobinPolicy;
-exports.DefaultLoadBalancingPolicy = DefaultLoadBalancingPolicy;
-exports.LoadBalancingPolicy = LoadBalancingPolicy;
-exports.RoundRobinPolicy = RoundRobinPolicy;
-exports.TokenAwarePolicy = TokenAwarePolicy;
-exports.WhiteListPolicy = WhiteListPolicy;
+module.exports = {
+  AllowListPolicy,
+  DCAwareRoundRobinPolicy,
+  DefaultLoadBalancingPolicy,
+  LoadBalancingPolicy,
+  RoundRobinPolicy,
+  TokenAwarePolicy,
+  // Deprecated: for backward compatibility only.
+  WhiteListPolicy
+};

test/integration/short/client-execute-simulator-tests.js

@@ -25,8 +25,7 @@ const errors = require('../../../lib/errors');
 
 const { responseErrorCodes } = require('../../../lib/types');
 const Client = require('../../../lib/client');
-const DCAwareRoundRobinPolicy = require('../../../lib/policies').loadBalancing.DCAwareRoundRobinPolicy;
-const WhiteListPolicy = require('../../../lib/policies').loadBalancing.WhiteListPolicy;
+const { AllowListPolicy, DCAwareRoundRobinPolicy } = require('../../../lib/policies').loadBalancing;
 
 const query = "select * from data";
 const clusterSize = 3;
@@ -46,7 +45,7 @@ describe('Client', function() {
         localDataCenter: 'dc1',
         policies: {
           // define an LBP that includes all nodes except node 3
-          loadBalancing: new WhiteListPolicy(new DCAwareRoundRobinPolicy(), [
+          loadBalancing: new AllowListPolicy(new DCAwareRoundRobinPolicy(), [
             cluster.node(0).address,
             cluster.node(1).address,
             cluster.node(2).address

test/integration/short/execution-profile-tests.js

@@ -13,18 +13,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 'use strict';
+
 const assert = require('assert');
 
-const helper = require('../../test-helper.js');
-const Client = require('../../../lib/client.js');
+const helper = require('../../test-helper');
+const Client = require('../../../lib/client');
 const types = require('../../../lib/types');
-const utils = require('../../../lib/utils.js');
+const utils = require('../../../lib/utils');
 const simulacron = require('../simulacron');
-const loadBalancing = require('../../../lib/policies/load-balancing.js');
-const DCAwareRoundRobinPolicy = loadBalancing.DCAwareRoundRobinPolicy;
-const WhiteListPolicy = loadBalancing.WhiteListPolicy;
-const ExecutionProfile = require('../../../lib/execution-profile.js').ExecutionProfile;
+const { AllowListPolicy, DCAwareRoundRobinPolicy } = require('../../../lib/policies/load-balancing');
+const { ExecutionProfile } = require('../../../lib/execution-profile');
 
 describe('ProfileManager', function() {
   this.timeout(40000);
@@ -69,8 +69,8 @@ describe('ProfileManager', function() {
       loadBalancing: decorateInitWithCounter(new DCAwareRoundRobinPolicy('dc1'))
     });
     // A profile that targets 127.0.0.4 specifically.
-    const wlProfile = new ExecutionProfile('whitelist', {
-      loadBalancing: decorateInitWithCounter(new WhiteListPolicy(new DCAwareRoundRobinPolicy('dc2'), [ node4 ]))
+    const wlProfile = new ExecutionProfile('allowlist', {
+      loadBalancing: decorateInitWithCounter(new AllowListPolicy(new DCAwareRoundRobinPolicy('dc2'), [ node4 ]))
     });
     // A profile with no defined lbp, it should fallback on the default profile's lbp.
     const emptyProfile = new ExecutionProfile('empty');
@@ -143,7 +143,7 @@ describe('ProfileManager', function() {
         hosts.forEach(function(h) {
           const distance = client.profileManager.getDistance(h);
           // all hosts except 3 should be at a distance of local since a profile exists for all DCs
-          // with DC2 white listing host 4.  While host 5 is ignored in whitelist profile, it is remote in others
+          // with DC2 allow-listing host 4.  While host 5 is ignored in allowlist profile, it is remote in others
           // so it should be considered remote.
           const expectedDistance = h.address === node3 ? types.distance.ignored : types.distance.local;
           assert.strictEqual(distance, expectedDistance, "Expected distance of " + expectedDistance + " for host " + h.address);
@@ -157,7 +157,7 @@ describe('ProfileManager', function() {
   it('should only use hosts from the load balancing policy in the default profile', ensureOnlyHostsUsed([0, 1]));
   it('should only use hosts from the load balancing policy in the default profile when profile doesn\'t have policy', ensureOnlyHostsUsed([0, 1], 'empty'));
   it('should only use hosts from the load balancing policy in the default profile when specified', ensureOnlyHostsUsed([0, 1], 'default'));
-  it('should only use hosts from the load balancing policy in whitelist profile', ensureOnlyHostsUsed([3], 'whitelist'));
+  it('should only use hosts from the load balancing policy in allowlist profile', ensureOnlyHostsUsed([3], 'allowlist'));
   it('should fallback on client load balancing policy when default profile has no lbp', function (done) {
     const policy = new DCAwareRoundRobinPolicy('dc2');
     const profiles = [new ExecutionProfile('default'), new ExecutionProfile('empty')];

test/integration/short/load-balancing-tests.js

@@ -21,10 +21,7 @@ const helper = require('../../test-helper');
 const Client = require('../../../lib/client');
 const utils = require('../../../lib/utils');
 const types = require('../../../lib/types');
-const loadBalancing = require('../../../lib/policies/load-balancing');
-const RoundRobinPolicy = loadBalancing.RoundRobinPolicy;
-const TokenAwarePolicy = loadBalancing.TokenAwarePolicy;
-const WhiteListPolicy = loadBalancing.WhiteListPolicy;
+const { RoundRobinPolicy, AllowListPolicy, TokenAwarePolicy} = require('../../../lib/policies/load-balancing');
 const vdescribe = helper.vdescribe;
 
 const maxInFlightRequests = 16;
@@ -112,9 +109,9 @@ context('with a reusable 3 node cluster', function () {
       'ALTER KEYSPACE system_traces WITH replication = {\'class\': \'SimpleStrategy\', \'replication_factor\': \'1\'}'
     ]
   });
-  vdescribe('2.0', 'WhiteListPolicy', function () {
-    it('should use the hosts in the white list only', function (done) {
-      const policy = new WhiteListPolicy(new RoundRobinPolicy(), ['127.0.0.1:9042', '127.0.0.2:9042']);
+  vdescribe('2.0', 'AllowListPolicy', function () {
+    it('should use the hosts in the allow list only', function (done) {
+      const policy = new AllowListPolicy(new RoundRobinPolicy(), ['127.0.0.1:9042', '127.0.0.2:9042']);
       const client = newInstance(policy);
       utils.timesLimit(100, maxInFlightRequests, function (n, next) {
         client.execute(helper.queries.basic, function (err, result) {

test/integration/short/metadata-tests.js

@@ -325,7 +325,7 @@ describe('metadata @SERVER_API', function () {
     describe('#getTrace()', function () {
       it('should retrieve the trace immediately after', function (done) {
         // use a single node
-        const lbp = new helper.WhiteListPolicy(['1']);
+        const lbp = new helper.AllowListPolicy(['1']);
         const client = newInstance({policies: {loadBalancing: lbp}});
         let traceId;
         utils.series([
@@ -363,7 +363,7 @@ describe('metadata @SERVER_API', function () {
       });
       it('should retrieve the trace a few seconds after', function (done) {
         // use a single node
-        const lbp = new helper.WhiteListPolicy(['2']);
+        const lbp = new helper.AllowListPolicy(['2']);
         const client = newInstance({policies: {loadBalancing: lbp}});
         let traceId;
         utils.series([

test/test-helper.js

@@ -580,7 +580,7 @@ const helper = {
   },
   Map: MapPolyFill,
   Set: SetPolyFill,
-  WhiteListPolicy: WhiteListPolicy,
+  AllowListPolicy: AllowListPolicy,
   FallthroughRetryPolicy: FallthroughRetryPolicy,
   /**
    * Determines if test tracing is enabled
@@ -1601,18 +1601,18 @@ RetryMultipleTimes.prototype.onWriteTimeout = function (requestInfo) {
  * @param [childPolicy]
  * @constructor
  */
-function WhiteListPolicy(list, childPolicy) {
+function AllowListPolicy(list, childPolicy) {
   this.list = list;
   this.childPolicy = childPolicy || new policies.loadBalancing.RoundRobinPolicy();
 }
 
-util.inherits(WhiteListPolicy, policies.loadBalancing.LoadBalancingPolicy);
+util.inherits(AllowListPolicy, policies.loadBalancing.LoadBalancingPolicy);
 
-WhiteListPolicy.prototype.init = function (client, hosts, callback) {
+AllowListPolicy.prototype.init = function (client, hosts, callback) {
   this.childPolicy.init(client, hosts, callback);
 };
 
-WhiteListPolicy.prototype.newQueryPlan = function (keyspace, info, callback) {
+AllowListPolicy.prototype.newQueryPlan = function (keyspace, info, callback) {
   const list = this.list;
   this.childPolicy.newQueryPlan(keyspace, info, function (err, iterator) {
     callback(err, {

test/unit/api-tests.js

@@ -104,6 +104,9 @@ describe('API', function () {
     assert.ok(api.errors);
     assert.ok(api.policies);
     assert.ok(api.policies.loadBalancing);
+    checkConstructor(api.policies.loadBalancing, 'AllowListPolicy');
+    // For backward compatibility only
+    checkConstructor(api.policies.loadBalancing, 'WhiteListPolicy');
     assert.ok(api.policies.retry);
     assert.ok(api.policies.reconnection);
     assert.ok(api.metadata);

test/unit/load-balancing-tests.js

@@ -19,18 +19,13 @@ const assert = require('assert');
 const helper = require('../test-helper.js');
 const errors = require('../../lib/errors');
 const Client = require('../../lib/client.js');
-const clientOptions = require('../../lib/client-options.js');
-const Host = require('../../lib/host.js').Host;
-const HostMap = require('../../lib/host.js').HostMap;
+const clientOptions = require('../../lib/client-options');
+const { Host, HostMap } = require('../../lib/host');
 const types = require('../../lib/types');
-const utils = require('../../lib/utils.js');
-const loadBalancing = require('../../lib/policies/load-balancing.js');
-const ExecutionOptions = require('../../lib/execution-options').ExecutionOptions;
-const LoadBalancingPolicy = loadBalancing.LoadBalancingPolicy;
-const TokenAwarePolicy = loadBalancing.TokenAwarePolicy;
-const RoundRobinPolicy = loadBalancing.RoundRobinPolicy;
-const DCAwareRoundRobinPolicy = loadBalancing.DCAwareRoundRobinPolicy;
-const WhiteListPolicy = loadBalancing.WhiteListPolicy;
+const utils = require('../../lib/utils');
+const { ExecutionOptions } = require('../../lib/execution-options');
+const { AllowListPolicy, LoadBalancingPolicy, TokenAwarePolicy, RoundRobinPolicy, DCAwareRoundRobinPolicy } =
+  require('../../lib/policies/load-balancing');
 
 describe('RoundRobinPolicy', function () {
   it('should yield an error when the hosts are not set', function(done) {
@@ -447,7 +442,7 @@ describe('TokenAwarePolicy', function () {
     });
   });
 });
-describe('WhiteListPolicy', function () {
+describe('AllowListPolicy', function () {
   it('should use the childPolicy to determine the distance', function () {
     let getDistanceCalled = 0;
     const childPolicy = {
@@ -456,7 +451,7 @@ describe('WhiteListPolicy', function () {
         return types.distance.local;
       }
     };
-    const policy = new WhiteListPolicy(childPolicy, ['h1:9042', 'h2:9042']);
+    const policy = new AllowListPolicy(childPolicy, ['h1:9042', 'h2:9042']);
     assert.strictEqual(policy.getDistance({ address: 'h1:9042'}), types.distance.local);
     assert.strictEqual(getDistanceCalled, 1);
     assert.strictEqual(policy.getDistance({ address: 'h2:9042'}), types.distance.local);
@@ -471,7 +466,7 @@ describe('WhiteListPolicy', function () {
         cb(null, utils.arrayIterator([{ address: '1.1.1.1:9042'}, { address: '1.1.1.2:9042'}, { address: '1.1.1.3:9042'}]));
       }
     };
-    const policy = new WhiteListPolicy(childPolicy, ['1.1.1.3:9042', '1.1.1.1:9042']);
+    const policy = new AllowListPolicy(childPolicy, ['1.1.1.3:9042', '1.1.1.1:9042']);
     policy.newQueryPlan('ks1', {}, function (err, iterator) {
       assert.ifError(err);
       const hosts = helper.iteratorToArray(iterator);
@@ -484,8 +479,8 @@ describe('WhiteListPolicy', function () {
 
   describe('#getOptions()', () => {
     it('should return a Map with the child policy name', () => {
-      helper.assertMapEqual(new WhiteListPolicy(new RoundRobinPolicy(), ['a', 'b']).getOptions(),
-        new Map([['childPolicy', 'RoundRobinPolicy'], ['whitelist', ['a', 'b']]]));
+      helper.assertMapEqual(new AllowListPolicy(new RoundRobinPolicy(), ['a', 'b']).getOptions(),
+        new Map([['childPolicy', 'RoundRobinPolicy'], ['allowList', ['a', 'b']]]));
     });
   });
 });