Ac-redislock NPM

AC RedisLock

This tool can be used to lock operations (e.g. make sure workers will fetch a job only once)

Breaking changes version 4

Version 4 no longer supports callbacks! Please use async/await instead.

Breaking changes version 2

RedisLock will now be only initialized once - if parameters redis, logger, logLevel, suppressMismatch are already set (by first init call) they are re-used and no longer overwritten.

If you want the old behaviour, init again with parameter reInit=true.

Requirements

Requires an existing Redis connection.

Usage

Init function requires a valid redis instance.

redis - INSTANCE required Redis instance
logger - OPTIONAL INSTANCE logger instance (e.g. Winston)
logLevel - OPTIONAL STRING logLevel for the Redis operation
suppressMismatch - OPTIONAL BOOL - if true, release mismatches are not logged
reInit - OPTIONAL BOOL - if true, you can re-init ac-redisLock, otherwise existing values (from first init) will be used (the latter is the default behaviour)

Those options will init ac-redislock once. Calling it again will not have any effect as long as you do not use reInit=true.

await redisLock.lockKey(params)

LockKey has the following parameters

redisKey - STRING required name for the key
expires - OPTIONAL INT seconds after the lock is released, defaults to 10 seconds
value - OPTIONAL STRING value for this redisKey. Use it to compare/secure lock values

Lock key throws an error 423 (if lock is already active) or otherwise returns the lock value, which can be used in releaseLock function.

await redisLock.releaseLock(params)

ReleaseKey has the following parameters

redisKey - STRING required name for the key
value - if set will be compared with the redisKey value before releasing. If not matching, the function will return an error message
suppressMismatch - if true, no warning will be logged if the value does not match the stored one (see "multiple processes" section)

Examples

const redisLock = require('ac-redislock')

// create a Redis instance (using io-redis)
const app.redisInstance = new Redis(options)

await redisLock.init({
  redis: app.redisInstance 
})

const params = {
  redisKey: 'someMeaningfulKey',
}
try {
   // value for this lock -> set as params.value for releaseLock
  const value = await redisLock.lockKey(params)
}
catch(err) {
  // err can be 423 -> key is locked
}

// redisKey is deleted and lock released
await redisLock.releaseKey(params)

Multiple Processes

If you use this package on multiple instances and want to make sure only of those instances processes a job we recommend to set suppressMismatch in order to avoid error messages if a process tries to release a key even though it did not lock it.