https://github.com/pioardi/ring-election
A node js library with a distributed leader/follower algorithm ready to be used
https://github.com/pioardi/ring-election
algorithm cluster concurrency distributed-lock distributed-systems driver frequency hearth-beat javascript javascript-library leader leader-election leader-node monitoring nodejs partition partitioning ring ring-election scalability
Last synced: 6 days ago
JSON representation
A node js library with a distributed leader/follower algorithm ready to be used
- Host: GitHub
- URL: https://github.com/pioardi/ring-election
- Owner: pioardi
- License: mit
- Created: 2018-10-23T18:12:39.000Z (about 7 years ago)
- Default Branch: develop
- Last Pushed: 2023-01-23T21:55:33.000Z (almost 3 years ago)
- Last Synced: 2025-09-13T15:25:22.353Z (4 months ago)
- Topics: algorithm, cluster, concurrency, distributed-lock, distributed-systems, driver, frequency, hearth-beat, javascript, javascript-library, leader, leader-election, leader-node, monitoring, nodejs, partition, partitioning, ring, ring-election, scalability
- Language: JavaScript
- Homepage: https://medium.com/@alessandroardizio94/how-to-build-high-available-fault-tolerant-services-in-node-js-25a3785b2e46
- Size: 3.59 MB
- Stars: 117
- Watchers: 12
- Forks: 6
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Ring election :sparkles: :dizzy:
Is your dream to build a service like cassandra,kafka,zipkin,jaeger,redis,etc...? You are in the right place , join ring-election project !!!
[](https://coveralls.io/github/pioardi/ring-election?branch=master)
[](https://github.com/pioardi/ring-election/actions)
[](https://flat.badgen.net/dependabot/dependabot/dependabot-core/?icon=dependabot)
[](https://www.codacy.com/app/alessandroardizio94/ring-election?utm_source=github.com&utm_medium=referral&utm_content=pioardi/ring-election&utm_campaign=Badge_Grade)
[](https://gitter.im/ring-election)
[](https://github.com/standard/standard)
Contents
Getting started
·
Overview
·
Use cases
·
Config
·
Config
·
Monitoring
·
High level design
·
Contribute
·
Versioning
·
License
What the ring-election driver offers you ?
- A default partitioner that for an object returns the partition to which it is assigned.
- Mechanism of leader election
- Failure detection between nodes.
- Assignment and rebalancing of partitions between nodes
- Automatic re-election of the leader
- Listen for new assigned/revoked partitions
What problems can you solve with this driver ?
- Scalability
- High availability
- Concurrency between nodes in a cluster
- Automatic failover
Getting started
Install with npm !
```bash
npm i ring-election --save
```
Example
You do not need to choose a node as leader , just indicate all your nodes and start everyone as follower.
The first node to start will be the leader , the leader do not have assigned partitions so try to start 2 instances after your integration
How to integrate
```javascript
const ring = require('ring-election')
let follower = ring.follower
const {
BECOME_LEADER,
PARTITIONS_ASSIGNED,
PARTITIONS_REVOKED
} = ring.constants;
follower.createClient()
// if you want REST API as monitoring , invoke startMonitoring
follower.startMonitoring()
// to get ring info
ring.follower.ring()
// to get assigned partitions
let assignedPartitions = ring.follower.partitions()
// now let me assume that a follower will create some data
// and you want to partition this data
let partition = ring.follower.defaultPartitioner('KEY')
// save your data including the partition on a storage
// you will be the only one in the cluster working on the partitions assigned to you.
// If you want to handle partitions assigned
// ( use other constants to listen other events ) you can do in this way.
ring.follower.eventListener.on(PARTITIONS_ASSIGNED , (newAssignedPartitions) => {
// DO STUFF
})
```
Start your development cluster
You will find some helpful files into the dev folder , please see the following video
[Watch the video](https://www.youtube.com/embed/5keF_OVXGLM?controls=0)
Check assigned partitions to local:9000/status or change the port to 9001/9002
Try to stop and restart processes and observe the behaviour.
Overview and rationale
In modern systems it is often needed to distribute the application load to make the system scalable so that every data is processed by a single instance.
Ring-election is a driver that implements a distributed algorithm that assigns to each node the partitions to work on .
In a simple use case each node can obtain data that are part of the partitions of which it is owner and work on them.
The algorithm will assign to each node one or more partitions to work with.
A node will be removed if it does not send an heart beat for a while , this process is called heart check.
Each node in the ring will have an ID and a priority , if the leader node will die the node with lower priority will be elect as leader.
If a node is added or removed from the cluster, the allocated partitions will be rebalanced.
Use cases
This section introduce you on what you can build on top of ring-election using it as driver/library.
Distributed Scheduler
Each Scheduler instance will work on the assigned partitions .
A real implementation of this use case is available here https://github.com/pioardi/hurricane-scheduler
Distributed lock
Distributed cache
Distributed computing
Try it out !
```bash
docker image build -t ring-election .
docker-compose up
```
Configuration
PORT : The leader will start to listen on this port , default is 3000
TIME_TO_RECONNECT: The time to wait for a follower when he has to connect to a new leader in ms , default is 3000ms
HEART_BEAT_FREQUENCY: The frequency with which a heart beat is performed by a follower , default is 1000ms
HEART_BEAT_CHECK_FREQUENCY: The frequency with which an heart check is performed by a leader , default is 3000ms
LOG_LEVEL: Follow this https://www.npmjs.com/package/winston#logging-levels , default is info.
NUM_PARTITIONS: Number of partitions to distribute across the cluster , default is 10.
SEED_NODES : hostnames and ports of leader node comma separated, Ex . hostname1:port,hostname2:port
MONITORING_PORT : port to expose rest service for monitoring , default is 9000
Monitoring API
To monitor your cluster contact any node on the path /status (HTTP verb : GET) or contact a follower node on /partitions (HTTP verb : GET).
High Level Diagram
See wiki page.
How to contribute
See contributing guidelines [CONTRIBUTING](./CONTRIBUTING.md)
Versioning
We use (http://semver.org/) for versioning.
License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details