Skip to content

Commit

Permalink
feat: Sentinel preferredSlaves option (#370)
Browse files Browse the repository at this point in the history 
* 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.
  • Loading branch information
@doublesharp @luin
doublesharp authored and luin committed Sep 24, 2016
1 parent 8718567 commit 6ddcc99
Show file tree
Hide file tree
Showing 3 changed files with 163 additions and 4 deletions.
38 changes: 37 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
58 changes: 56 additions & 2 deletions lib/connectors/sentinel_connector.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.');
Expand Down Expand Up @@ -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) {
Expand All @@ -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);
});
Expand Down
71 changes: 70 additions & 1 deletion test/functional/sentinel.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
});
});

Expand Down

0 comments on commit 6ddcc99

Please sign in to comment.