{"_id":"bull-redlock","_rev":"4529400","name":"bull-redlock","description":"A node.js redlock implementation for distributed redis locks","dist-tags":{"latest":"2.2.1"},"maintainers":[{"name":"manast","email":""}],"time":{"modified":"2026-04-09T13:33:11.000Z","created":"2017-03-07T23:26:48.434Z","2.2.1":"2017-03-07T23:34:52.095Z","2.2.0":"2017-03-07T23:26:48.434Z"},"users":{},"author":{"name":"Mike Marcacci"},"repository":{"type":"git","url":"git+https://github.com/mike-marcacci/node-redlock.git"},"versions":{"2.2.1":{"name":"bull-redlock","version":"2.2.1","description":"A node.js redlock implementation for distributed redis locks","main":"redlock.js","scripts":{"test":"istanbul cover mocha","test-ci":"istanbul cover _mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | coveralls"},"repository":{"type":"git","url":"git+https://github.com/mike-marcacci/node-redlock.git"},"keywords":["nodejs","iojs","redlock","distributed","lock","redis"],"author":{"name":"Mike Marcacci"},"license":"MIT","bugs":{"url":"https://github.com/mike-marcacci/node-redlock/issues"},"homepage":"https://github.com/mike-marcacci/node-redlock","devDependencies":{"chai":"^3.5.0","coveralls":"^2.11.8","ioredis":"^1.15.1","istanbul":"^0.4.2","mocha":"^2.4.5","redis":"^2.4.2"},"dependencies":{"bluebird":"^3.3.3"},"config":{"blanket":{"pattern":["redlock.js"]}},"gitHead":"20492e1c3cc72425c03b6e412958f2623bb7d4c8","_id":"bull-redlock@2.2.1","_shasum":"98aa093d2d069cc54039526c8756a864b8785be9","_from":".","_npmVersion":"2.15.9","_nodeVersion":"4.6.0","_npmUser":{"name":"manast","email":"manuel@optimalbits.com"},"maintainers":[{"name":"manast","email":""}],"dist":{"shasum":"98aa093d2d069cc54039526c8756a864b8785be9","size":9187,"noattachment":false,"key":"/bull-redlock/-/bull-redlock-2.2.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/bull-redlock/download/bull-redlock-2.2.1.tgz"},"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/bull-redlock-2.2.1.tgz_1488929689828_0.4766295636072755"},"directories":{},"publish_time":1488929692095,"_hasShrinkwrap":false,"_cnpm_publish_time":1488929692095,"_cnpmcore_publish_time":"2021-12-19T01:30:55.391Z"},"2.2.0":{"name":"bull-redlock","version":"2.2.0","description":"A node.js redlock implementation for distributed redis locks","main":"redlock.js","scripts":{"test":"istanbul cover mocha","test-ci":"istanbul cover _mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | coveralls"},"repository":{"type":"git","url":"git+https://github.com/mike-marcacci/node-redlock.git"},"keywords":["nodejs","iojs","redlock","distributed","lock","redis"],"author":{"name":"Mike Marcacci"},"license":"MIT","bugs":{"url":"https://github.com/mike-marcacci/node-redlock/issues"},"homepage":"https://github.com/mike-marcacci/node-redlock","devDependencies":{"chai":"^3.5.0","coveralls":"^2.11.8","ioredis":"^1.15.1","istanbul":"^0.4.2","mocha":"^2.4.5","redis":"^2.4.2"},"dependencies":{"bluebird":"^3.3.3"},"config":{"blanket":{"pattern":["redlock.js"]}},"gitHead":"886e96595190620ca63f4e7cea6b8867815e718d","_id":"bull-redlock@2.2.0","_shasum":"8ebb3b5105a0a5ce6be1ee860e6e57347e1af11e","_from":".","_npmVersion":"2.15.9","_nodeVersion":"4.6.0","_npmUser":{"name":"manast","email":"manuel@optimalbits.com"},"maintainers":[{"name":"manast","email":""}],"dist":{"shasum":"8ebb3b5105a0a5ce6be1ee860e6e57347e1af11e","size":9218,"noattachment":false,"key":"/bull-redlock/-/bull-redlock-2.2.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/bull-redlock/download/bull-redlock-2.2.0.tgz"},"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/bull-redlock-2.2.0.tgz_1488929206430_0.14352457667700946"},"directories":{},"publish_time":1488929208434,"_hasShrinkwrap":false,"_cnpm_publish_time":1488929208434,"_cnpmcore_publish_time":"2021-12-19T01:30:55.668Z"}},"readme":"[![npm version](https://badge.fury.io/js/redlock.svg)](https://www.npmjs.com/package/redlock)\n[![Build Status](https://travis-ci.org/mike-marcacci/node-redlock.svg)](https://travis-ci.org/mike-marcacci/node-redlock)\n[![Coverage Status](https://coveralls.io/repos/mike-marcacci/node-redlock/badge.svg)](https://coveralls.io/r/mike-marcacci/node-redlock)\n\nRedlock\n=======\nThis 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.\n\n- [Installation](#installation)\n- [Usage (Promise Style)](#usage-promise-style)\n- [Usage (Disposer Style)](#usage-disposer-style)\n- [Usage (Callback Style)](#usage-callback-style)\n- [API Docs](#api-docs)\n\n###High-Availability Recommendations\n- Use at least 3 independent servers or clusters\n- Use an odd number of independent redis ***servers*** for most installations\n- Use an odd number of independent redis ***clusters*** for massive installations\n- When possible, distribute redis nodes across different physical machines\n\n\n###Using Cluster/Sentinel\nIt is completely possible to use a *single* redis cluster or sentinal configuration by passing one preconfigured client to redlock. While you do gain high availability and vastly increased throughput under this scheme, the failure modes are a bit different, and it becomes theoretically possible that a lock is acquired twice:\n\nAssume you are using eventually-consistent redis replication, and you acquire a lock for a resource. Immediately after acquiring your lock, the redis master for that shard crashes. Redis does its thing and fails over to the slave which hasn't yet synced your lock. If another process attempts to acquire a lock for the same resource, it will succeed!\n\nThis is why redlock allows you to specify multiple independent nodes/clusters: by requiring consensus between them, we can safely take out or fail-over a minority of nodes without invalidating active locks.\n\nTo learn more about the the algorithm, check out the [redis distlock page](http://redis.io/topics/distlock).\n\n\n###How do I check if something is locked?\nRedlock cannot tell you *with certainty* if a resource is currently locked. For example, if you are on the smaller side of a network partition you will fail to acquire a lock, but you don't know if the lock exists on the other side; all you know is that you can't guarantee exclusivity on yours.\n\nThat said, for many tasks it's sufficient to attempt a lock with `retryCount=0`, and treat a failure as the resource being \"locked\" or (more correctly) \"unavailable\",\n\n\nInstallation\n------------\n```bash\nnpm install --save redlock\n```\n\nConfiguration\n-------------\nRedlock 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.\n\nA 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.\n\n```js\nvar client1 = require('redis').createClient(6379, 'redis1.example.com');\nvar client2 = require('redis').createClient(6379, 'redis2.example.com');\nvar client3 = require('redis').createClient(6379, 'redis3.example.com');\nvar Redlock = require('redlock');\n\nvar redlock = new Redlock(\n\t// you should have one client for each redis node\n\t// in your cluster\n\t[client1, client2, client3],\n\t{\n\t\t// the expected clock drift; for more details\n\t\t// see http://redis.io/topics/distlock\n\t\tdriftFactor: 0.01, // time in ms\n\n\t\t// the max number of times Redlock will attempt\n\t\t// to lock a resource before erroring\n\t\tretryCount:  10,\n\n\t\t// the time in ms between attempts\n\t\tretryDelay:  400, // time in ms\n\n\t\t// the max time in ms randomly added to retries\n\t\t// to improve performance under high contention\n\t\t// see https://www.awsarchitectureblog.com/2015/03/backoff.html\n\t\tretryJitter:  400 // time in ms\n\t}\n);\n```\n\n\nError Handling\n--------------\n\nBecause 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:\n\n```js\n\n// ...\n\nredlock.on('clientError', function(err) {\n\tconsole.error('A redis error has occurred:', err);\n});\n\n// ...\n\n```\n\n\nUsage (promise style)\n---------------------\n\n\n###Locking & Unlocking\n\n```js\n\n// the string identifier for the resource you want to lock\nvar resource = 'locks:account:322456';\n\n// the maximum amount of time you want the resource locked,\n// keeping in mind that you can extend the lock up until\n// the point when it expires\nvar ttl = 1000;\n\nredlock.lock(resource, ttl).then(function(lock) {\n\n\t// ...do something here...\n\n\t// unlock your resource when you are done\n\treturn lock.unlock()\n\t.catch(function(err) {\n\t\t// we weren't able to reach redis; your lock will eventually\n\t\t// expire, but you probably want to log this error\n\t\tconsole.error(err);\n\t});\n});\n\n```\n\n\n###Locking and Extending\n\n```js\nredlock.lock('locks:account:322456', 1000).then(function(lock) {\n\n\t// ...do something here...\n\n\t// if you need more time, you can continue to extend\n\t// the lock as long as you never let it expire\n\treturn lock.extend(1000).then(function(lock){\n\n\t\t// ...do something here...\n\n\t\t// unlock your resource when you are done\n\t\treturn lock.unlock()\n\t\t.catch(function(err) {\n\t\t\t// we weren't able to reach redis; your lock will eventually\n\t\t\t// expire, but you probably want to log this error\n\t\t\tconsole.error(err);\n\t\t});\n\t});\n});\n\n```\n\n\nUsage (disposer style)\n----------------------\n\n\n###Locking & Unlocking\n\n```js\nvar using = require('bluebird').using;\n\n// the string identifier for the resource you want to lock\nvar resource = 'locks:account:322456';\n\n// the maximum amount of time you want the resource locked,\n// keeping in mind that you can extend the lock up until\n// the point when it expires\nvar ttl = 1000;\n\n// if we weren't able to reach redis, your lock will eventually\n// expire, but you probably want to do something like log that\n// an error occurred; if you don't pass a handler, this error\n// will be ignored\nfunction unlockErrorHandler(err) {\n\tconsole.error(err);\n}\n\nusing(redlock.disposer(resource, ttl, unlockErrorHandler), function(lock) {\n\n\t// ...do something here...\n\n}); // <-- unlock is automatically handled by bluebird\n\n```\n\n\n###Locking and Extending\n\n```js\nusing(redlock.disposer('locks:account:322456', 1000, unlockErrorHandler), function(lock) {\n\n\t// ...do something here...\n\n\t// if you need more time, you can continue to extend\n\t// the lock until it expires\n\treturn lock.extend(1000).then(function(extended){\n\n\t\t// Note that redlock modifies the original lock,\n\t\t// so the vars `lock` and `extended` point to the\n\t\t// exact same object\n\n\t\t// ...do something here...\n\n\t});\n}); // <-- unlock is automatically handled by bluebird\n\n```\n\n\nUsage (callback style)\n----------------------\n\n\n###Locking & Unlocking\n\n```js\n\n// the string identifier for the resource you want to lock\nvar resource = 'locks:account:322456';\n\n// the maximum amount of time you want the resource locked,\n// keeping in mind that you can extend the lock up until\n// the point when it expires\nvar ttl = 1000;\n\nredlock.lock(resource, ttl, function(err, lock) {\n\n\t// we failed to lock the resource\n\tif(err) {\n\t\t// ...\n\t}\n\n\t// we have the lock\n\telse {\n\n\n\t\t// ...do something here...\n\n\n\t\t// unlock your resource when you are done\n\t\tlock.unlock(function(err) {\n\t\t\t// we weren't able to reach redis; your lock will eventually\n\t\t\t// expire, but you probably want to log this error\n\t\t\tconsole.error(err);\n\t\t});\n\t}\n});\n\n```\n\n\n###Locking and Extending\n\n```js\nredlock.lock('locks:account:322456', 1000, function(err, lock) {\n\n\t// we failed to lock the resource\n\tif(err) {\n\t\t// ...\n\t}\n\n\t// we have the lock\n\telse {\n\n\n\t\t// ...do something here...\n\n\n\t\t// if you need more time, you can continue to extend\n\t\t// the lock until it expires\n\t\tlock.extend(1000, function(err, lock){\n\n\t\t\t// we failed to extend the lock on the resource\n\t\t\tif(err) {\n\t\t\t\t// ...\n\t\t\t}\n\n\n\t\t\t// ...do something here...\n\n\n\t\t\t// unlock your resource when you are done\n\t\t\tlock.unlock();\n\t\t}\n\t}\n});\n\n```\n\nAPI Docs\n--------\n\n###`Redlock.lock(resource, ttl, ?callback)`\n- `resource (string)` resource to be locked\n- `ttl (number)` time in ms until the lock expires\n- `callback (function)` callback returning:\n\t- `err (Error)`\n\t- `lock (Lock)`\n\n\n###`Redlock.unlock(lock, ?callback)`\n- `lock (Lock)` lock to be released\n- `callback (function)` callback returning:\n\t- `err (Error)`\n\n\n###`Redlock.extend(lock, ttl, ?callback)`\n- `lock (Lock)` lock to be extended\n- `ttl (number)` time in ms to extend the lock's expiration\n- `callback (function)` callback returning:\n\t- `err (Error)`\n\t- `lock (Lock)`\n\n\n###`Redlock.disposer(resource, ttl, ?unlockErrorHandler)`\n- `resource (string)` resource to be locked\n- `ttl (number)` time in ms to extend the lock's expiration\n- `callback (function)` error handler called with:\n\t- `err (Error)`\n\n\n###`Lock.unlock(?callback)`\n- `callback (function)` callback returning:\n\t- `err (Error)`\n\n\n###`Lock.extend(ttl, ?callback)`\n- `ttl (number)` time in ms to extend the lock's expiration\n- `callback (function)` callback returning:\n\t- `err (Error)`\n\t- `lock (Lock)`\n\n","_attachments":{},"homepage":"https://github.com/mike-marcacci/node-redlock","bugs":{"url":"https://github.com/mike-marcacci/node-redlock/issues"},"license":"MIT"}