A network lock service and client library. Port of apokalyptik/glockd to Node.js.
Exclusive locks are... exclusive. They can only be held by one connection at a time.
Upon disconnection of a client all of that client's exclusive locks are considered to be "orphaned" and are automatically released. The intended purpose of this functionality is to help avoid the complicated gymnastics generally used in distributed locking (timeouts, heartbeating, etc). This way, a single process can maintain a lock simply by its continued presence, and can release its lock by its absence. A side effect of this methodology is that stale locks simply cannot exist in this environment. If the connection goes away then its locks are released. Any lock still extant, therefore, is still validly held by a process that is still literally running somewhere.
Shared locks are... not exclusive. They can be obtained by any number of clients at the same time.
One interesting feature of shared locks is that they are counted. That is if 4 clients have a lock, and another goes to lock the same thing then when it does it will be told that it is the 5th client to obtain that lock. This makes shared locks good for things like rate limiting, throttling, etc.: the client can have logic built in so that after 5 active locks are obtained it waits, defers, or otherwise avoids doing the work for which the shared lock was requested.
Upon disconnection of a client all of that client's shared locks are considered to be "orphaned" and are automatically released. This behavior works just like the exclusive lock orphaning feature. Counts on shared locks are appropriately updated when locks are orphaned.
To connect to a running lockd server:
npm install lockd
var lockd = require('lockd');
var client = lockd.connect({
tcp : 'host:port',
// Extra options, if needed:
timeout : /* connection timeout in ms */
readTimeout : /* socket read timeout in ms */
});
To run a lockd server from the command line:
sudo npm install -g lockd
lockd --help
When running the server from the command line, it will listen on TCP/IP port 9999 by default.
To start a lockd server as part of a Node.js program:
npm install lockd
var lockd = require('lockd');
var server = lockd.listen({
tcp : 'host:port',
features : {
// Enable or disable features (default enabled)
dump : true/false,
registry : true/false
}
});
When you're done with the server, call server.close() (will wait for all
clients to disconnect) or server.destroy() (will forcibly disconnect all
clients).
The following methods are available on lockd client objects created with
lockd.connect as described above.
All client operations are serialized: a client will perform requests to the server in series so that at most one operation is in progress at once. Clients will also queue operations until connected to the server, so requests can be made immediately upon creating a client.
Many server responses contain a leading number that is 0 on failure or >= 1
on success, and then a text description (see the
protocol documentation for more information). When a
method has a callback with parameters count/ok and msg, they will contain
the number and the message from the server response (unless the server response
indicates an error condition like failure to acquire an exclusive lock).
Clients will emit the following events:
connect - when connected to the server, if applicable. You shouldn't have
to worry about this event since client operations are serialized.close - when disconnected from the server, if applicable. You shouldn't
have to worry about this event - use the disconnect method
instead.error - on failure to connect to the server.Attempts to acquire the exclusive lock lockName. The callback cb is called
with parameters (err, count, msg).
If the lock is acquired, err will be null and count will be 1. If the
lock is not acquired (because it is held by another client), err will be an
Error object and the other arguments will be missing.
Attempts to release the exclusive lock lockName. The callback cb is called
with parameters (err, ok, msg).
If the lock is released, err will be null and ok will be 1. If the
lock is not released (because it is not held by this client), err will be an
Error object and the other arguments will be missing.
Returns whether the exclusive lock lockName is currently held by a client.
The callback cb is called with parameters (err, count, msg).
count will be 1 if the lock is held by a client and 0 if it is free.
Returns information about the exclusive lock lockName (or all exclusive
locks). The callback cb is called with parameters (err, lockInfo), where
lockInfo is defined as follows:
lockName is given, then lockInfo is the address of the client holding
the exclusive lock lockName, or null if it is not held.lockName is not given, then lockInfo is a hash representing all
exclusive locks currently held, where keys are lock names and values are
client addresses.If the dump feature is disabled on the lockd server, then err will be set
accordingly.
Acquires the shared lock lockName. The callback cb is called with
parameters (err, count, msg).
The lock will be acquired and count will be the number of clients that are
holding the requested lock, including the current client.
Attempts to release the shared lock lockName. The callback cb is called
with parameters (err, ok, msg).
If the lock is released, err will be null and ok will be 1. If the
lock is not released (because it is not held by this client), err will be an
Error object and the other arguments will be missing.
Returns the number of clients currently holding the shared lock lockName.
The callback cb is called with parameters (err, count, msg).
count will be >= 1 if the lock is held by one or more clients and 0 if it
is free.
Returns information about the shared lock lockName (or all shared
locks). The callback cb is called with parameters (err, lockInfo), where
lockInfo is defined as follows:
lockName is given, then lockInfo is an array of the addresses of the
clients holding the shared lock lockName, or [] if it is not held.lockName is not given, then lockInfo is a hash representing all
shared locks currently held, where keys are lock names and values are arrays
of client addresses.If the dump feature is disabled on the lockd server, then err will be set
accordingly.
Returns the name registered to the current client. The callback cb is called
with parameters (err, addr, name) where:
addr is the client socket's address:port.name is the friendly name registered to the client (or the same as addr
if none has been registered).If the registry feature is disabled on the lockd server, then name will
always equal addr.
Sets the name of the current client. The callback cb is called with
parameters (err, ok, msg).
To reset the name of the current client to the default (its address:port),
pass '' as the name parameter.
If the registry feature is disabled on the lockd server, then err will be
set accordingly.
Returns information about the client with registered name clientName (or all
clients with registered names). The callback cb is called with parameters
(err, clientInfo), where clientInfo is defined as follows:
clientName is given, then clientInfo is the address:port of the
client with that name, or null if there is no such client.clientName is not given, then clientInfo is a hash representing all
clients with registered names, where keys are client names and values are
client address:port strings.If the registry feature is disabled on the lockd server, then err will be
set accordingly.
Returns statistics about the operation of the server. The callback cb is
called with parameters (err, stats).
stats is an object with properties like command_X representing the number
of times command X has been executed, and a few other pieces of information.
For details about the available statistics, see the
Stats API section
of the protocol documentation.
Closes the connection to the lockd server (if any). This will also cause any
locks held by the client to be released.
lockd uses a simple line-based protocol over TCP sockets. See
docs/protocol.md for more information.
FAQs
A network lock service and client library.
The npm package lockd receives a total of 16 weekly downloads. As such, lockd popularity was classified as not popular.
We found that lockd demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer 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
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.