gamejolt / node-redlock

A node.js redlock implementation for distributed redis locks

Redlock

This is a node.js implementation of the redlock algorithm for distributed redis locks. It provides strong guarantees in both single-redis and multi-redis environments, and provides fault tolerance through use of multiple independent redis instances or clusters.

###High-Availability Recommendations

• Use at least 3 independent servers or clusters
• Use an odd number of independent redis servers for most installations
• Use an odd number of independent redis clusters for massive installations
• When possible, distribute redis nodes across different physical machines

Installation

npm install --save redlock

Configuration

Redlock can use node redis, ioredis or any other compatible redis library to keep its client connections.

A redlock object is instantiated with an array of at least one redis client and an optional options object. Properties of the Redlock object should NOT be changed after it is firstused, as doing so could have unintended consequences for live locks.

var client1 = require('redis').createClient(6379, 'redis1.example.com');
var client2 = require('redis').createClient(6379, 'redis2.example.com');
var client3 = require('redis').createClient(6379, 'redis3.example.com');
var Redlock = require('redlock');

var redlock = new Redlock(
	// you should have one client for each redis node
	// in your cluster
	[client1, client2, client3],
	{
		// the expected clock drift; for more details
		// see http://redis.io/topics/distlock
		driftFactor: 0.01,

		// the max number of times Redlock will attempt
		// to lock a resource before erroring
		retryCount:  3,

		// the time in ms between attempts
		retryDelay:  200
	}
);

Error Handling

Because redlock is designed for high availability, it does not care if a minority of redis instances/clusters fail at an operation. If you want to write logs or take another action when a redis client fails, you can listen for the clientError event:

// ...

redlock.on('clientError', function(err) {
	console.error('A redis error has occurred:', err);
});

// ...

Usage (promise style)

###Locking & Unocking

// the string identifier for the resource you want to lock
var resource = 'locks:account:322456';

// the maximum amount of time you want the resource locked,
// keeping in mind that you can extend the lock up until
// the point when it expires
var ttl = 1000;

redlock.lock(resource, ttl).then(function(lock) {

	// ...do something here...

	// unlock your resource when you are done
	return lock.unlock();
});

###Locking and Extending

redlock.lock('locks:account:322456', 1000).then(function(lock) {

	// ...do something here...

	// if you need more time, you can continue to extend
	// the lock as long as you never let it expire
	return lock.extend(1000).then(function(lock){

		// ...do something here...

		// unlock your resource when you are done
		return lock.unlock();
	});
});

Usage (disposer style)

###Locking & Unocking

var using = require('bluebird').using;

// the string identifier for the resource you want to lock
var resource = 'locks:account:322456';

// the maximum amount of time you want the resource locked,
// keeping in mind that you can extend the lock up until
// the point when it expires
var ttl = 1000;

using(redlock.disposer(resource, ttl), function(lock) {

	// ...do something here...

}); // <-- unlock is automatically handled by bluebird

###Locking and Extending

using(redlock.disposer('locks:account:322456', 1000), function(lock) {

	// ...do something here...

	// if you need more time, you can continue to extend
	// the lock until it expires
	return lock.extend(1000).then(function(extended){

		// Note that redlock modifies the original lock,
		// so the vars `lock` and `extended` point to the
		// exact same object

		// ...do something here...

	});
}); // <-- unlock is automatically handled by bluebird

Usage (callback style)

###Locking & Unocking

// the string identifier for the resource you want to lock
var resource = 'locks:account:322456';

// the maximum amount of time you want the resource locked,
// keeping in mind that you can extend the lock up until
// the point when it expires
var ttl = 1000;

redlock.lock(resource, ttl, function(err, lock) {

	// we failed to lock the resource
	if(err) {
		// ...
	}

	// we have the lock
	else {


		// ...do something here...


		// unlock your resource when you are done
		lock.unlock();
	}
});

###Locking and Extending

redlock.lock('locks:account:322456', 1000, function(err, lock) {

	// we failed to lock the resource
	if(err) {
		// ...
	}

	// we have the lock
	else {


		// ...do something here...


		// if you need more time, you can continue to extend
		// the lock until it expires
		lock.extend(1000, function(err, lock){

			// we failed to extend the lock on the resource
			if(err) {
				// ...
			}


			// ...do something here...


			// unlock your resource when you are done
			lock.unlock();
		}
	}
});

API Docs

###Redlock.lock(resource, ttl, callback)

• resource (string) resource to be locked
• ttl (number) time in ms until the lock expires
• callback (function) callback returning:
  • err (Error)
  • lock (Lock)

###Redlock.unlock(lock, callback)

• lock (Lock) lock to be released
• callback (function) callback with no returning arguments

###Redlock.extend(lock, ttl, callback)

• lock (Lock) lock to be extended
• ttl (number) time in ms to extend the lock's expiration
• callback (function) callback returning:
  • err (Error)
  • lock (Lock)

###Lock.unlock(callback)

• callback (function) callback with no returning arguments

###Lock.extend(ttl, callback)

• ttl (number) time in ms to extend the lock's expiration
• callback (function) callback returning:
  • err (Error)
  • lock (Lock)