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
	}
);
```


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();
});

```


###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();
	});
});

```


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;

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

	// ...do something here...

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

```


###Locking and Extending

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

```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();
	}
});

```


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