Security News
The Push to Ban Ransom Payments Is Gaining Momentum
Ransomware costs victims an estimated $30 billion per year and has gotten so out of control that global support for banning payments is gaining momentum.
proper-lockfile
Advanced tools
Readme
An inter-process and inter-machine lockfile utility that works on a local or network file system.
$ npm install proper-lockfile
There are various ways to achieve file locking.
This library utilizes the mkdir
strategy which works atomically on any kind of file system, even network based ones.
The lockfile path is based on the file path you are trying to lock by suffixing it with .lock
.
When a lock is successfully acquired, the lockfile's mtime
(modified time) is periodically updated to prevent staleness. This allows to effectively check if a lock is stale by checking its mtime
against a stale threshold. If the update of the mtime fails several times, the lock might be compromised. The mtime
is supported in almost every filesystem
.
This library is similar to lockfile but the later has some drawbacks:
open
with O_EXCL
flag which has problems in network file systems. proper-lockfile
uses mkdir
which doesn't have this issue.O_EXCL is broken on NFS file systems; programs which rely on it for performing locking tasks will contain a race condition.
The lockfile staleness check is done via ctime
(creation time) which is unsuitable for long running processes. proper-lockfile
constantly updates lockfiles mtime
to do proper staleness check.
It does not check if the lockfile was compromised which can led to undesirable situations. proper-lockfile
checks the lockfile when updating the mtime
.
proper-lockfile
does not detect cases in which:
lockfile
is manually removed and someone else acquires the lock right afterstale
/update
values are being used for the same file, possibly causing two locks to be acquired on the same fileproper-lockfile
detects cases in which:
lockfile
failAs you see, the first two are a consequence of bad usage. Technically, it was possible to detect the first two but it would introduce complexity and eventual race conditions.
Tries to acquire a lock on file
.
If the lock succeeds, a release
function is provided that should be called when you want to release the lock.
Available options:
stale
: Duration in milliseconds in which the lock is considered stale, defaults to 10000
(minimum value is 5000
)update
: The interval in milliseconds in which the lockfile's mtime
will be updated, defaults to stale/2
(minimum value is 1000
, maximum value is stale/2
)retries
: The number of retries or a retry options object, defaults to 0
realpath
: Resolve symlinks using realpath, defaults to true
(note that if true
, the file
must exist previously)fs
: A custom fs to use, defaults to graceful-fs
onCompromised
: Called if the lock gets compromised, defaults to a function that simply throws the error which will probably cause the process to dieconst lockfile = require('proper-lockfile');
lockfile.lock('some/file')
.then((release) => {
// Do something while the file is locked
// Call the provided release function when you're done,
// which will also return a promise
return release();
});
// Alternatively, you may use lockfile('some/file') directly.
Releases a previously acquired lock on file
.
Whenever possible you should use the release
function instead (as exemplified above). Still there are cases in which its hard to keep a reference to it around code. In those cases unlock()
might be handy.
Available options:
realpath
: Resolve symlinks using realpath, defaults to true
(note that if true
, the file
must exist previously)fs
: A custom fs to use, defaults to graceful-fs
const lockfile = require('proper-lockfile');
lockfile.lock('some/file')
.then(() => {
// Do something while the file is locked
// Later..
return lockfile.unlock('some/file');
});
Check if the file is locked and its lockfile is not stale.
Available options:
stale
: Duration in milliseconds in which the lock is considered stale, defaults to 10000
(minimum value is 5000
)realpath
: Resolve symlinks using realpath, defaults to true
(note that if true
, the file
must exist previously)fs
: A custom fs to use, defaults to graceful-fs
const lockfile = require('proper-lockfile');
lockfile.check('some/file')
.then((isLocked) => {
// isLocked will be true if 'some/file' is locked, false otherwise
});
Sync version of .lock()
.
Returns the release
function or throws on error.
Sync version of .unlock()
.
Throws on error.
Sync version of .check()
.
Returns a boolean or throws on error.
proper-lockfile
automatically remove locks if the process exists. Though, SIGINT
and SIGTERM
signals
are handled differently by nodejs
in the sense that they do not fire a exit
event on the process
.
To avoid this common issue that CLI
developers have, please do the following:
// Map SIGINT & SIGTERM to process exit
// so that lockfile removes the lockfile automatically
process
.once('SIGINT', () => process.exit(1))
.once('SIGTERM', () => process.exit(1));
$ npm test
$ npm test -- --watch
during development
The test suite is very extensive. There's even a stress test to guarantee exclusiveness of locks.
Released under the MIT License.
FAQs
A inter-process and inter-machine lockfile utility that works on a local or network file system
We found that proper-lockfile demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware costs victims an estimated $30 billion per year and has gotten so out of control that global support for banning payments is gaining momentum.
Application Security
New SEC disclosure rules aim to enforce timely cyber incident reporting, but fear of job loss and inadequate resources lead to significant underreporting.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).