mongo-dlock

distributed lock on top of mongodb for node.js. It provides an implementation of a distributed lock using mongodb

Features

• behind-the scenes lock retry or one-shot lock try
• locks can be refreshed (ie, extended). An auro refresh mode also exists
• uses mongodb ttl index to safeguard deletion of stray locks
• locks can have a data payload, and it can be updated on each refesh

BREAKING CHANGE

• Starting on v2.0.0, the features related to propagation of lock/unlock events over pubsub (a mongodb capped collection), and then marshalled to EventEmitter, has been dropped.

  All funcionalities work the same, anyway: the DLock.wait_lock() operation remains uncionally unchanged, but it releis solely on polling

Quickstart

const MDL = require ('mongo-dlock');
const opts = {...};

MDL (opts, (err, Locks) => {
  if (err) {
    // manage error
  }

  var l1 = Locks.dlock ('some-task');

  l1.wait_lock (err => {
    // do whatever the task is...

    l1.unlock (err => {
      ...
      // and close
      Locks.close (err => {...})
    })
  });

API

MDL (opts, (err, MongoDLock) => {})

Initializes the Distributed Lock subsystem. Receives an object with options:

• url: mongodb url of the backend DB. Defaults to 'mongodb://localhost:27017'
• db: mongodb database to be used as Backend DB. Defaults to 'dlocks'
• coll: mongodb collection to store the Distributed Locks. Defaults to 'dlocks'
• grace: grace period (in seconds) added to the lock expiration to set the ttl index t mongodb. Defaults to 60
• exp_delta: expiration of lock, in milliseconds. Unless autorefreshed, an acquired lock will be valid only for this amount of time. Defaults to 15000;
• autorefresh: if set to true, the lock will set an internal loop to autorefresh (that is, renew the expiration). Defaults to undefined
• wait_lock_period: period in milliseconds to wait between tries on wait_lock() operations. Defaults to 5000

Upon completion, calls the cb argument as cb (err, MongoDLock). MongoDLock is basically a DLock factory: all actual distributed locks are created using this object

DLock <- MongoDLock.dlock (opts)

Creates and returns a Distributed Lock. Receives an object with options; those not defined will take its default from the opts passed upon MDL initialization:

• exp_delta: expiration of lock, in milliseconds. Unless autorefreshed, an acquired lock will be valid only for this amount of time. Defaults to 5000;

• autorefresh: if set to true, the lock will set an internal loop to autorefresh (that is, renew the expiration). Defaults to undefined

• id: string identifier for the lock. Locks of equal id refer to the same logical lock. If not provided, a new uuid v4 is assigned;

• wait_lock_period: period in milliseconds to wait between tries on wait_lock() operations. Defaults to 5000

• upd: extra update passed to mongodb on creation (upsert) and refresh (update). Must follow the format of mongodb updateOne()

  It can be an object, or a function returning an object. In the latter case, teh function is called on each lock/refresh method call

Alternatively, opts can be just an string, in which case it is taken as the id parameter

MongoDLock.is_locked (id, (err, res) => {})

checks whether the lock on id is acquired. The callback's res will be true if locked, false otherwise

id can be a regex: this can be used to check, for example, all the locks on a given set of IDs. Especially useful if a convention to add hierarchy is applied to the id, such as channel-000:subchannel-17:entry-000: one can check what is locked under channel 000 with MongoDLock.active_locks (/^channel-000:/, (err, res) => {...})

MongoDLock.active_locks (id, (err, res) => {})

gets the list of locks on id. The callback's res will be an array of lock objects

id can be a string or a regex; if a string, the array can only ocntain 0 or 1 element; if a regex, it can return zero or more lock objects. This can be used to check, for example, all the locks on a given set of IDs. Especially useful if a convention to add hierarchy is applied to the id, such as channel-000:subchannel-17:entry-000: one can check what is locked under channel 000 with MongoDLock.active_locks (/^channel-000:/, (err, res) => {...})

MongoDLock.close (err => {})

Closes the MongoDLock factory. After the cb is invoked the factory is no longer usable. It DOES NOT unlock any of the locks created by it

DLock.lock ((err, res) => {})

Attempts a lock. If the lock is acquired already (and therefore the call failed to acquire it) res will be false. If the lock is acquired correctly, res will be true

DLock.wait_lock ((err, res) => {})

Attempts a lock, but waits and retries internally if the lock is acquired someqhre else. wait_lock_period controls how often to retry If an error occurs in any retry the operation ends and the callback is called with the error For coherency, the callback is also called with a second res parameter as true when the lock is finally acquired

DLock.unlock ((err, res) => {})

releases a lock (which was previously held). Callback is called upon error or upon completion, where res is true if the lock was released, false if it was not released (but no actual error was seen)

DLock.is_locked((err, res) => {})

checks whether the lock is acquired (by this or any other lock instance). The callback's res will be true if locked, false otherwise