A node package for distributed locks using etcd. It required ES6 support, so node >=4.0.0 should be used.
Use the exported constructor to instantiate new locks. The constructor has the signature function Lock(etcd, key, id, ttl),
where etcd is a node-etcd client, key is the etcd key to use for locking, id is a unique node identifier and
ttl is the TTL of the lock in seconds.
var Lock = require("etcd-lock");
var Etcd = require("node-etcd");
var os = require("os");
var key = "/example/lock"
, id = os.hostname()
, ttl = 60 // seconds;
var lock = new Lock(new Etcd(), key, id, ttl);Each lock instance has the methods lock() and unlock(), both of which return a promise that will be fulfilled or rejected
when the action is complete
lock.lock()
.then(() => { // lock is now locked,
console.log("locked");
/* do stuff here */;
return lock.unlock();
})
.then(() => {
console.log("unlocked");
});Note that the example above has no error handling: lock() will return a rejected promise if, for example, the etcd cluster
is not reachable. The lock instance itself will also emit error events in case the lock is lost for whatever reason.
Ignoring the error events is a bad idea, as you have no idea what state the lock is in.
Calling lock() multiple times will simply refresh the lock: you only need to unlock() once. The lock will
automatically refresh itself at intervals of (lock.ttl*1000) / 2. To change the refresh interval or TTL after construction,
changelock.refreshInterval or lock.ttl before calling lock().
Calling unlock() when you don't hold the lock will return a rejected promise.
etcd-lock comes with a command line tool called etcdlocker (do e.g. npm install -g etcd-lock to get it in your path.)
etcdlocker [options] [--] [command]
Tries to acquire a distributed lock, and when successful, runs a command. The lock will be released when the command
exits. If you need to supply flags to the command, use --: etcdlocker -i bla -k der -- ls -lah
Options:
-h --help what you're looking at
-e --etcd [host:port] etcd address. Defaults to ETCD_LOCK_HOST or localhost:2379
-i --id [value] node ID. Defaults to env ETCD_LOCK_ID, or host name if no env variable is specified
-k --key [key] etcd key for lock. Will default to the env variable ETCD_LOCK_KEY if not specified
-n --node assume that the command is a Node.js module. This will start the child process with
child_process.fork() and send ping messages at the same rate as it refreshes the lock.
The sent ping is {ping: somevalue}, and the expected reply is {pong: somevalue}. Child
processes have at most TTL seconds to reply. Failures to reply or incorrect replies
will cause child process termination and a release of the lock
-r --refresh [seconds] lock refresh period in seconds. Defaults to TTL / 2. Can also be specified with ETCD_LOCK_REFRESH
-t --ttl [seconds] lock TTL in seconds. Can also be specified with ETCD_LOCK_TTL
-v --verbose output debug information to stderr
If etcdlocker loses the lock for whatever reason (e.g. key was changed "from the outside"), it will kill the child process and
exit.
Exit codes
Under normal circumstances, etcdlocker will exit with the exit code of the command. If either etcdlocker or the
command exit due to a signal, the exit code will be 128 + [signal number], e.g. 143 for SIGTERM. This exit
code mapping will use bash's kill -l whenever possible to get the code of the signal.
1: trying to acquire the lock failed, e.g. due to etcd being unavailable
2: the lock was lost
3: the child process couldn't either be spawned or killed
4: problem with IPC pings with Node.js child processes
Example
# Try to acquire lock /test/lock using host name as ID, run mycmd --some --args when lock acquired
ETCD_LOCK_HOST=etcd:6666 etcdlocker -k /test/lock -t 120 -- mycmd --some --args