feat: Sentinel preferredSlaves option (#370)

* Support for “preferredSlave” when connecting to a Sentinel group for
local reads in a distributed environment. Value can be an array of
objects with required properties “ip” and “port” and option property of
“prio” indicating the priority, defaults to 1, lower numbers preferred
first. If the value is a function the available slaves are passed into
it, expecting a single slave as the response. If no preferred slave is
found a random one is returned from those available.

Updated tests to return bad values in SENTINEL slaves command but still
select the correct one based on the preferredSlave result.

* Update README with details on the `preferredSlaves` option.

Author: doublesharp

README.md

@@ -608,10 +608,46 @@ The arguments passed to the constructor are different from the ones you use to c
 
 * `name` identifies a group of Redis instances composed of a master and one or more slaves (`mymaster` in the example);
 * `sentinels` are a list of sentinels to connect to. The list does not need to enumerate all your sentinel instances, but a few so that if one is down the client will try the next one.
+* `role` (optional) with a value of `slave` will return a random slave from the Sentinel group.
+* `preferredSlaves` (optional) can be used to prefer a particular slave or set of slaves based on priority. It accepts a function or array.
 
 ioredis **guarantees** that the node you connected to is always a master even after a failover. When a failover happens, instead of trying to reconnect to the failed node (which will be demoted to slave when it's available again), ioredis will ask sentinels for the new master node and connect to it. All commands sent during the failover are queued and will be executed when the new connection is established so that none of the commands will be lost.
 
-It's possible to connect to a slave instead of a master by specifying the option `role` with the value of `slave`, and ioredis will try to connect to a random slave of the specified master, with the guarantee that the connected node is always a slave. If the current node is promoted to master due to a failover, ioredis will disconnect from it and ask the sentinels for another slave node to connect to.
+It's possible to connect to a slave instead of a master by specifying the option `role` with the value of `slave` and ioredis will try to connect to a random slave of the specified master, with the guarantee that the connected node is always a slave. If the current node is promoted to master due to a failover, ioredis will disconnect from it and ask the sentinels for another slave node to connect to. 
+
+If you specify the option `preferredSlaves` along with `role: 'slave'` ioredis will attempt to use this value when selecting the slave from the pool of available slaves. The value of `preferredSlaves` should either be a function that accepts an array of avaiable slaves and returns a single result, or an array of slave values priorities by the lowest `prio` value first with a default value of `1`.
+
+```javascript
+// available slaves format
+var availableSlaves = [{ ip: '127.0.0.1', port: '31231', flags: 'slave' }];
+
+// preferredSlaves array format
+var preferredSlaves = [
+  { ip: '127.0.0.1', port: '31231', prio: 1 },
+  { ip: '127.0.0.1', port: '31232', prio: 2 }
+];
+
+// preferredSlaves function format
+preferredSlaves = function(availableSlaves) {
+  for (var i = 0; i < availableSlaves.length; i++) {
+    var slave = availableSlaves[i];
+    if (slave.ip === '127.0.0.1') {
+      if (slave.port === '31234') {
+        return slave;
+      }
+    }
+  }
+  // if no preferred slaves are available a random one is used
+  return false;
+};
+
+var redis = new Redis({
+  sentinels: [{ host: '127.0.0.1', port: 26379 }, { host: '127.0.0.1', port: 26380 }],
+  name: 'mymaster',
+  role: 'slave',
+  preferredSlaves: preferredSlaves
+});
+```
 
 Besides the `retryStrategy` option, there's also a `sentinelRetryStrategy` in Sentinel mode which will be invoked when all the sentinel nodes are unreachable during connecting. If `sentinelRetryStrategy` returns a valid delay time, ioredis will try to reconnect from scratch. The default value of `sentinelRetryStrategy` is:
 

lib/connectors/sentinel_connector.js

@@ -11,7 +11,7 @@ var Redis;
 function SentinelConnector(options) {
   Connector.call(this, options);
   if (this.options.sentinels.length === 0) {
-    throw new Error('Requires at least on sentinel to connect to.');
+    throw new Error('Requires at least one sentinel to connect to.');
   }
   if (!this.options.name) {
     throw new Error('Requires the name of master.');
@@ -131,6 +131,7 @@ SentinelConnector.prototype.resolveMaster = function (client, callback) {
 };
 
 SentinelConnector.prototype.resolveSlave = function (client, callback) {
+  var _this = this;
   client.sentinel('slaves', this.options.name, function (err, result) {
     client.disconnect();
     if (err) {
@@ -145,7 +146,60 @@ SentinelConnector.prototype.resolveSlave = function (client, callback) {
           availableSlaves.push(slave);
         }
       }
-      selectedSlave = _.sample(availableSlaves);
+      // allow the options to prefer particular slave(s)
+      if (_this.options.preferredSlaves) {
+        var preferredSlaves = _this.options.preferredSlaves;
+        switch (typeof preferredSlaves) {
+        case 'function':
+          // use function from options to filter preferred slave
+          selectedSlave = _this.options.preferredSlaves(availableSlaves);
+          break;
+        case 'object':
+          if (!Array.isArray(preferredSlaves)) {
+            preferredSlaves = [preferredSlaves];
+          } else {
+            // sort by priority
+            preferredSlaves.sort(function (a, b) {
+              // default the priority to 1
+              if (!a.prio) {
+                a.prio = 1;
+              }
+              if (!b.prio) {
+                b.prio = 1;
+              }
+
+              // lowest priority first
+              if (a.prio < b.prio) {
+                return -1;
+              }
+              if (a.prio > b.prio) {
+                return 1;
+              }
+              return 0;
+            });
+          }
+          // loop over preferred slaves and return the first match
+          for (var p = 0; p < preferredSlaves.length; p++) {
+            for (var a = 0; a < availableSlaves.length; a++) {
+              if (availableSlaves[a].ip === preferredSlaves[p].ip) {
+                if (availableSlaves[a].port === preferredSlaves[p].port) {
+                  selectedSlave = availableSlaves[a];
+                  break;
+                }
+              }
+            }
+            if (selectedSlave) {
+              break;
+            }
+          }
+          // if none of the preferred slaves are available, a random available slave is returned
+          break;
+        }
+      }
+      if (!selectedSlave) {
+        // get a random available slave
+        selectedSlave = _.sample(availableSlaves);
+      }
     }
     callback(null, selectedSlave ? { host: selectedSlave.ip, port: selectedSlave.port } : null);
   });

test/functional/sentinel.js

@@ -231,7 +231,76 @@ describe('sentinel', function () {
           { host: '127.0.0.1', port: '27379' }
         ],
         name: 'master',
-        role: 'slave'
+        role: 'slave',
+        preferredSlaves: [{ ip: '127.0.0.1', port: '17381', prio: 10 }]
+      });
+    });
+
+    it('should connect to the slave successfully based on preferred slave priority', function (done) {
+      var sentinel = new MockServer(27379, function (argv) {
+        if (argv[0] === 'sentinel' && argv[1] === 'slaves' && argv[2] === 'master') {
+          return [
+            ['ip', '127.0.0.1', 'port', '44444', 'flags', 'slave'],
+            ['ip', '127.0.0.1', 'port', '17381', 'flags', 'slave'],
+            ['ip', '127.0.0.1', 'port', '55555', 'flags', 'slave']
+          ];
+        }
+      });
+      var slave = new MockServer(17381);
+      slave.on('connect', function () {
+        redis.disconnect();
+        sentinel.disconnect(function () {
+          slave.disconnect(done);
+        });
+      });
+
+      var redis = new Redis({
+        sentinels: [
+          { host: '127.0.0.1', port: '27379' }
+        ],
+        name: 'master',
+        role: 'slave',
+        // for code coverage (sorting, etc), use multiple valid values that resolve to prio 1
+        preferredSlaves: [,
+          { ip: '127.0.0.1', port: '11111', prio: 100 },
+          { ip: '127.0.0.1', port: '17381', prio: 1 },
+          { ip: '127.0.0.1', port: '22222', prio: 100 },
+          { ip: '127.0.0.1', port: '17381' },
+          { ip: '127.0.0.1', port: '17381' }
+        ]
+      });
+    });
+
+    it('should connect to the slave successfully based on preferred slave filter function', function (done) {
+      var sentinel = new MockServer(27379, function (argv) {
+        if (argv[0] === 'sentinel' && argv[1] === 'slaves' && argv[2] === 'master') {
+          return [['ip', '127.0.0.1', 'port', '17381', 'flags', 'slave']];
+        }
+      });
+      // only one running slave, which we will prefer
+      var slave = new MockServer(17381);
+      slave.on('connect', function () {
+        redis.disconnect();
+        sentinel.disconnect(function () {
+          slave.disconnect(done);
+        });
+      });
+
+      var redis = new Redis({
+        sentinels: [
+          { host: '127.0.0.1', port: '27379' }
+        ],
+        name: 'master',
+        role: 'slave',
+        preferredSlaves: function(slaves){
+          for (var i = 0; i < slaves.length; i++){
+            var slave = slaves[i];
+            if (slave.ip == '127.0.0.1' && slave.port =='17381'){
+              return slave;
+            }
+          }
+          return false;
+        }
       });
     });