redlock/README.md

[![npm version](https://badge.fury.io/js/redlock.svg)](https://www.npmjs.com/package/redlock)
[![Build Status](https://travis-ci.org/mike-marcacci/node-redlock.svg)](https://travis-ci.org/mike-marcacci/node-redlock)
[![Coverage Status](https://coveralls.io/repos/mike-marcacci/node-redlock/badge.svg)](https://coveralls.io/r/mike-marcacci/node-redlock)

Redlock
=======
This is a node.js implementation of the [redlock](http://redis.io/topics/distlock) 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
------------
```bash
npm install --save redlock
```

Configuration
-------------
Redlock can use [node redis](https://github.com/mranney/node_redis), [ioredis](https://github.com/luin/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.

```js
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:

```js

// ...

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

// ...

```


Usage (promise style)
---------------------


###Locking & Unocking

```js

// 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()
	.catch(function(err) {
		// we weren't able to reach redis; your lock will eventually
		// expire, but you probably want to log this error
		console.error(err);
	});
});

```


###Locking and Extending

```js
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()
		.catch(function(err) {
			// we weren't able to reach redis; your lock will eventually
			// expire, but you probably want to log this error
			console.error(err);
		});
	});
});

```


Usage (disposer style)
----------------------


###Locking & Unocking

```js
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;

// if we weren't able to reach redis, your lock will eventually
// expire, but you probably want to do something like log that
// an error occurred; if you don't pass a handler, this error
// will be ignored
function unlockErrorHandler(err) {
	console.error(err);
}

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

	// ...do something here...

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

```


###Locking and Extending

```js
using(redlock.disposer('locks:account:322456', 1000, unlockErrorHandler), 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

```js

// 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(function(err) {
			// we weren't able to reach redis; your lock will eventually
			// expire, but you probably want to log this error
			console.error(err);
		});
	}
});

```


###Locking and Extending

```js
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 returning:
	- `err (Error)`


###`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)`


###`Redlock.disposer(resource, ttl, ?unlockErrorHandler)`
- `resource (string)` resource to be locked
- `ttl (number)` time in ms to extend the lock's expiration
- `callback (function)` error handler called with:
	- `err (Error)`


###`Lock.unlock(?callback)`
- `callback (function)` callback returning:
	- `err (Error)`


###`Lock.extend(ttl, ?callback)`
- `ttl (number)` time in ms to extend the lock's expiration
- `callback (function)` callback returning:
	- `err (Error)`
	- `lock (Lock)`