README
clusterix
Node module for cluster node management
Introduction
Inspired by metroplex, this module is meant to be used standalone in order to detect nodes entering and leaving a cluster. This is useful, for example, if you are running socket.io in a cluster, and you want to be able to detect a node failure and be able to clean up after it.
Install
$ npm install --save clusterix
Usage
Run this basic setup in 3 different node processes, for i=1,2,3
:
import Clusterix from 'clusterix';
import Redis from 'ioredis'
const ioredis = new Redis({ keyPrefix: 'myapp:clusterix' });
const cluster = new Clusterix(ioredis);
cluster.initializeNode(`node${i}`);
cluster.on('node down', async node => {
console.log(`${node} is down, ${await cluster.nodes} are still up`);
});
After you kill one on the processes, for instance, node3
, either node1
or node2
will output node3 is down, node1,node2 are still up
.
API
class Clusterix extends EventEmitter
new Clusterix(redis, { id, nodeId, heartbeatInterval, pollInterval, timeout })
redis
Type: object
Instance of ioredis used to store heartbeats. Should have an open connection to the redis server when calling initializeNode
. Lua scripting features of ioredis
are used to define a command polls redis for each node's heartbeat, under the name __clusterix__poll
.
node_redis is not supported. This is because of the lack of built in Promise support on redis commands, and ease of lua commands usage with ioredis
.
id
Type: string
, optional, default: ''
The identifier for the cluster, can remain empty if using only one cluster (usually that's the case).
nodeId
Type: string
, default: ${os.hostname()}:${process.env.PORT}
The id of the node that initialized the instance of clusterix. Has to be unique across the cluster.
heartbeatInterval
Type: integer
, default: 500
Determines how often we send a heartbeat to redis. Has to be smaller than the timeout
passed to the constructor.
pollInterval
Type: integer
, default: 500
How often we poll the server for dead nodes in milliseconds.
timeout
Type: integer
, default: 1000
The number of milliseconds before a node is considered down.
initializeNode()
Type: Promise<undefined | Error>
Starts polling for dead nodes and sending heartbeats to redis.
If another node is sending heartbeats under the same nodeId
, it gets rejected with an Error
.
If heartbeats are found on redis for this same node, but no other node is sending heartbeats, a node down
event is emitted.
dispose()
Type: void
Clears all open handles (interval timeouts).
nodes
Type: Promise<Array<string>>
Returns the ids of all the nodes currently in the cluster
Tests
npm test
TODO
- Extend API
- More tests
- Examples
License
See the LICENSE file for license rights and limitations (MIT).