mongo-leader

mongo-leader is a Node.js package for leader election backed by MongoDB. It is inspired by the redis-leader library. The main class Leader extends the Node.js EventEmmiter class, allowing instances to emit events when they gain or lose leadership status. This makes it a powerful tool for managing distributed systems where only one instance should be in control at any given time.

Install

To install mongo-leader package with npm, you can use the following command:

npm install mongo-leader

Usage

const client = await MongoClient.connect(url)

const leader = new Leader(client.db('test'))
await leader.start() // Optional. If not called, a lazy start is initiated when isLeader is called for the first time.

setInterval(async () => {
  const isLeader = await leader.isLeader()
  console.log(`Am I leader? : ${isLeader}`)
}, 100)

Examples

For more detailed examples, check out the example/ directory which contains:

• minimal.js - Ultra-minimal polling example (12 lines)
• simple.js - Basic event-driven example with leader/follower events (20 lines)
• example.js - Production-ready example with comprehensive error handling and graceful shutdown

Configuration Changes

TTL Value Changes

Starting from version 1.5.0, mongo-leader gracefully handles TTL (time-to-live) configuration changes between application restarts. Previously, changing the ttl option would cause an IndexOptionsConflict error when MongoDB attempted to create a TTL index with different expiration settings.

Before (versions < 1.5.0):

// First run
const leader1 = new Leader(db, { ttl: 1000, wait: 100 })
await leader1.start() // Creates TTL index with 1 second expiration

// Second run (application restart with different TTL)
const leader2 = new Leader(db, { ttl: 5000, wait: 1000 })
await leader2.start() // Would throw IndexOptionsConflict error

After (versions >= 1.5.0):

// First run
const leader1 = new Leader(db, { ttl: 1000, wait: 100 })
await leader1.start() // Creates TTL index with 1 second expiration

// Second run (application restart with different TTL)
const leader2 = new Leader(db, { ttl: 5000, wait: 1000 })
await leader2.start() // ✅ Works! Automatically updates the TTL index

The library now automatically detects TTL changes and safely updates the MongoDB TTL index by:

1. Detecting the IndexOptionsConflict error
2. Comparing the existing TTL value with the requested TTL value
3. Dropping and recreating the index with the new TTL value if they differ
4. Gracefully handling any errors during this process

This enhancement allows for dynamic TTL adjustments in production environments without requiring manual database intervention.

Upgrade from a version earlier than 1.1.144

Breaking changes have been made when upgrading from a version earlier than 1.1.144. All asynchronous operations have been shifted from the constructor to a new method named start(), which needs to be called separately like in the example above.

API

new Leader(db, options)

Creates a new Leader instance.

Parameters

• db: A MongoClient object.
• options: An object with the following properties:
  • ttl: Lock time to live in milliseconds. The lock will be automatically released after this time. Default and minimum values are 1000. Must be at least 4 times the wait value to ensure reliable leader renewal.
  • wait: Time between tries getting elected in milliseconds. Default and minimum values are 100.
  • key: Unique identifier for the group of instances trying to be elected as leader. Default value is 'default'.

Important: The ttl value must be at least 4 times the wait value. This ensures that the leader renewal (which happens at ttl/2) has sufficient time to complete before the lock expires. For example, if wait is 500ms, then ttl must be at least 2000ms. The constructor will throw an error if this relationship is violated.

Validation Errors

The constructor performs validation on the options and will throw an error in the following cases:

• Invalid TTL/Wait Ratio: If ttl < wait * 4, an error will be thrown explaining the minimum required TTL value.

// This will throw an error
const leader = new Leader(db, { ttl: 2000, wait: 1000 })
// Error: TTL (2000ms) is too short relative to wait time (1000ms).
// TTL should be at least 4000ms (4x the wait time) to ensure reliable leader renewal.

// This is valid
const leader = new Leader(db, { ttl: 4000, wait: 1000 })

When the Leader constructor is invoked, it immediately initiates the election process to become the leader. This means that as soon as a Leader instance is created, it starts competing with other instances (if any) to gain the leadership role. This is done by attempting to acquire a lock in the MongoDB collection. If the lock is successfully acquired, the instance becomes the leader. The lock has a time-to-live (TTL) associated with it, after which it is automatically released. This allows for a continuous and dynamic leadership election process where leadership can change over time, especially in scenarios where the current leader instance becomes unavailable or is shut down.

start()

This method triggers the election process. It carries out the required setup in database and kick-starts the election procedure. The method is thread-safe and can be called multiple times concurrently - subsequent calls will wait for the first call to complete rather than running the initialization multiple times.

Note: If the instance is already initiated, this method returns immediately without performing any operations.

isLeader()

This method checks whether the current instance is the leader or not. It returns a Promise that resolves to a boolean value. If the returned value is true, it means the current instance is the leader. If the returned value is false, it means the current instance is not the leader. If the instance has not been initialized yet, a lazy start is performed.

pause()

This method is used to pause the leader election process. When called, the instance will stop trying to become a leader. This can be useful in scenarios where you want to manually control when your instance is trying to become a leader.

Note: The pause() method does not make the instance resign if it is currently a leader. It simply stops the instance from attempting to become a leader in the future.

resume()

This method is used to resume the leader election process. When called, the instance will start trying to become a leader again. This can be useful in scenarios where you have previously paused the leader election process and now want to allow your instance to become a leader again.

Note: The resume() method does not make the instance become a leader immediately. It simply allows the instance to start attempting to become a leader again.

stop()

This method is used to completely stop the leader election process and clean up resources. When called, the instance will be paused, all pending timeouts will be cleared, and all event listeners will be removed. This method should be called when the Leader instance is no longer needed to prevent memory leaks.

Note: After calling stop(), the instance should not be used again. Create a new Leader instance if needed.

Events

elected

The elected event is emitted when the instance successfully becomes a leader. This event can be listened to in order to perform actions that should only be done by the leader instance. For example, you might want to start certain tasks or services only when the instance has been elected as the leader.

revoked

The revoked event is emitted when the instance loses its leadership status. This event can be listened to in order to perform actions when the instance is no longer the leader. For example, you might want to stop certain tasks or services when the instance has been revoked from being the leader.

error

The error event is emitted when database operations fail during the election or renewal process. This includes MongoDB connection failures, timeout errors, or any other database-related issues. The leader election process will automatically retry after emitting this event, but applications should handle these errors appropriately.

leader.on('error', (error) => {
  console.error('Leader election error:', error.message)
  // Handle error (e.g., log, alert, etc.)
})

Note: During renewal failures, both error and revoked events will be emitted, as the instance assumes it has lost leadership and attempts to re-elect itself.

License

This project is licensed under the MIT License.

Releases

This project uses semantic-release for automated versioning and publishing. Releases are triggered automatically when commits are pushed to the master branch.

Commit Message Format

To trigger releases, use Conventional Commits format:

• feat: - New features (minor version bump)
• fix: - Bug fixes (patch version bump)
• BREAKING CHANGE: - Breaking changes (major version bump)
• chore:, docs:, style:, refactor:, test:, ci: - No version bump

Example commit messages:

feat: add new leader election algorithm
fix: resolve TTL index conflict issue
docs: update API documentation