{"id":16042529,"url":"https://github.com/nylen/lockd","last_synced_at":"2025-07-07T13:34:43.294Z","repository":{"id":24898356,"uuid":"28314798","full_name":"nylen/lockd","owner":"nylen","description":"A network lock service and client library.  Port of apokalyptik/glockd to Node.js.","archived":false,"fork":false,"pushed_at":"2015-01-20T20:17:05.000Z","size":286,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-26T21:18:45.906Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nylen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-21T22:02:21.000Z","updated_at":"2020-02-23T03:02:58.000Z","dependencies_parsed_at":"2022-08-22T20:11:10.576Z","dependency_job_id":null,"html_url":"https://github.com/nylen/lockd","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/nylen/lockd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylen%2Flockd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylen%2Flockd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylen%2Flockd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylen%2Flockd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nylen","download_url":"https://codeload.github.com/nylen/lockd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylen%2Flockd/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262412403,"owners_count":23306887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-09T00:02:30.984Z","updated_at":"2025-07-07T13:34:43.261Z","avatar_url":"https://github.com/nylen.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lockd [![Build status](https://img.shields.io/travis/nylen/lockd.svg?style=flat)](https://travis-ci.org/nylen/lockd) [![npm package](http://img.shields.io/npm/v/lockd.svg?style=flat)](https://www.npmjs.org/package/lockd)\n\nA network lock service and client library.  Port of\n[apokalyptik/glockd](https://github.com/apokalyptik/glockd) to Node.js.\n\n## Lock Types\n\n### Exclusive Locks\n\nExclusive locks are... exclusive. They can only be held by one connection at a\ntime.\n\nUpon disconnection of a client all of that client's exclusive locks are\nconsidered to be \"orphaned\" and are automatically released.  The intended\npurpose of this functionality is to help avoid the complicated gymnastics\ngenerally used in distributed locking (timeouts, heartbeating, etc).  This way,\na single process can maintain a lock simply by its continued presence, and can\nrelease its lock by its absence. A side effect of this methodology is that\nstale locks simply cannot exist in this environment.  If the connection goes\naway then its locks are released. Any lock still extant, therefore, is still\nvalidly held by a process that is still literally running somewhere.\n\n### Shared Locks\n\nShared locks are... not exclusive.  They can be obtained by any number of\nclients at the same time.\n\nOne interesting feature of shared locks is that they are counted. That is if 4\nclients have a lock, and another goes to lock the same thing then when it does\nit will be told that it is the 5th client to obtain that lock.  This makes\nshared locks good for things like rate limiting, throttling, etc.: the client\ncan have logic built in so that after 5 active locks are obtained it waits,\ndefers, or otherwise avoids doing the work for which the shared lock was\nrequested.\n\nUpon disconnection of a client all of that client's shared locks are considered\nto be \"orphaned\" and are automatically released.  This behavior works just like\nthe exclusive lock orphaning feature.  Counts on shared locks are appropriately\nupdated when locks are orphaned.\n\n## Installation\n\n### Client Installation\n\nTo connect to a running `lockd` server:\n\n```\nnpm install lockd\n```\n\n```js\nvar lockd = require('lockd');\n\nvar client = lockd.connect({\n    tcp : 'host:port',\n    // Extra options, if needed:\n    timeout     : /* connection timeout in ms */\n    readTimeout : /* socket read timeout in ms */\n});\n```\n\n### Server Installation\n\nTo run a `lockd` server from the command line:\n\n```\nsudo npm install -g lockd\nlockd --help\n```\n\nWhen running the server from the command line, it will listen on TCP/IP port\n9999 by default.\n\nTo start a `lockd` server as part of a Node.js program:\n\n```\nnpm install lockd\n```\n\n```js\nvar lockd = require('lockd');\n\nvar server = lockd.listen({\n    tcp      : 'host:port',\n    features : {\n        // Enable or disable features (default enabled)\n        dump     : true/false,\n        registry : true/false\n    }\n});\n```\n\nWhen you're done with the server, call `server.close()` (will wait for all\nclients to disconnect) or `server.destroy()` (will forcibly disconnect all\nclients).\n\n## Client Documentation\n\nThe following methods are available on `lockd` client objects created with\n`lockd.connect` as described above.\n\nAll client operations are serialized:  a client will perform requests to the\nserver in series so that at most one operation is in progress at once.  Clients\nwill also queue operations until connected to the server, so requests can be\nmade immediately upon creating a client.\n\nMany server responses contain a leading number that is `0` on failure or `\u003e= 1`\non success, and then a text description (see the\n[protocol documentation](docs/protocol.md) for more information).  When a\nmethod has a callback with parameters `count`/`ok` and `msg`, they will contain\nthe number and the message from the server response (unless the server response\nindicates an error condition like failure to acquire an exclusive lock).\n\n### Events\n\nClients will emit the following events:\n- `connect` - when connected to the server, if applicable.  You shouldn't have\n  to worry about this event since client operations are serialized.\n- `close` - when disconnected from the server, if applicable.  You shouldn't\n  have to worry about this event - use the [`disconnect`](#disconnectcb) method\n  instead.\n- `error` - on failure to connect to the server.\n\n### get(lockName, cb)\n\nAttempts to acquire the exclusive lock `lockName`.  The callback `cb` is called\nwith parameters (`err`, `count`, `msg`).\n\nIf the lock is acquired, `err` will be `null` and `count` will be `1`.  If the\nlock is not acquired (because it is held by another client), `err` will be an\n`Error` object and the other arguments will be missing.\n\n### release(lockName, cb)\n\nAttempts to release the exclusive lock `lockName`.  The callback `cb` is called\nwith parameters (`err`, `ok`, `msg`).\n\nIf the lock is released, `err` will be `null` and `ok` will be `1`.  If the\nlock is not released (because it is not held by this client), `err` will be an\n`Error` object and the other arguments will be missing.\n\n### inspect(lockName, cb)\n\nReturns whether the exclusive lock `lockName` is currently held by a client.\nThe callback `cb` is called with parameters (`err`, `count`, `msg`).\n\n`count` will be `1` if the lock is held by a client and `0` if it is free.\n\n### dump([lockName], cb)\n\nReturns information about the exclusive lock `lockName` (or all exclusive\nlocks).  The callback `cb` is called with parameters (`err`, `lockInfo`), where\n`lockInfo` is defined as follows:\n\n- If `lockName` is given, then `lockInfo` is the address of the client holding\n  the exclusive lock `lockName`, or `null` if it is not held.\n- If `lockName` is not given, then `lockInfo` is a hash representing all\n  exclusive locks currently held, where keys are lock names and values are\n  client addresses.\n\nIf the dump feature is disabled on the `lockd` server, then `err` will be set\naccordingly.\n\n### getShared(lockName, cb)\n\nAcquires the shared lock `lockName`.  The callback `cb` is called with\nparameters (`err`, `count`, `msg`).\n\nThe lock will be acquired and `count` will be the number of clients that are\nholding the requested lock, including the current client.\n\n### releaseShared(lockName, cb)\n\nAttempts to release the shared lock `lockName`.  The callback `cb` is called\nwith parameters (`err`, `ok`, `msg`).\n\nIf the lock is released, `err` will be `null` and `ok` will be `1`.  If the\nlock is not released (because it is not held by this client), `err` will be an\n`Error` object and the other arguments will be missing.\n\n### inspectShared(lockName, cb)\n\nReturns the number of clients currently holding the shared lock `lockName`.\nThe callback `cb` is called with parameters (`err`, `count`, `msg`).\n\n`count` will be `\u003e= 1` if the lock is held by one or more clients and `0` if it\nis free.\n\n### dumpShared([lockName], cb)\n\nReturns information about the shared lock `lockName` (or all shared\nlocks).  The callback `cb` is called with parameters (`err`, `lockInfo`), where\n`lockInfo` is defined as follows:\n\n- If `lockName` is given, then `lockInfo` is an array of the addresses of the\n  clients holding the shared lock `lockName`, or `[]` if it is not held.\n- If `lockName` is not given, then `lockInfo` is a hash representing all\n  shared locks currently held, where keys are lock names and values are arrays\n  of client addresses.\n\nIf the dump feature is disabled on the `lockd` server, then `err` will be set\naccordingly.\n\n### getName(cb)\n\nReturns the name registered to the current client.  The callback `cb` is called\nwith parameters (`err`, `addr`, `name`) where:\n\n- `addr` is the client socket's `address:port`.\n- `name` is the friendly name registered to the client (or the same as `addr`\n  if none has been registered).\n\nIf the registry feature is disabled on the `lockd` server, then `name` will\nalways equal `addr`.\n\n### setName(name, cb)\n\nSets the name of the current client.  The callback `cb` is called with\nparameters (`err`, `ok`, `msg`).\n\nTo reset the name of the current client to the default (its `address:port`),\npass `''` as the `name` parameter.\n\nIf the registry feature is disabled on the `lockd` server, then `err` will be\nset accordingly.\n\n### listClients([clientName], cb)\n\nReturns information about the client with registered name `clientName` (or all\nclients with registered names).  The callback `cb` is called with parameters\n(`err`, `clientInfo`), where `clientInfo` is defined as follows:\n\n- If `clientName` is given, then `clientInfo` is the `address:port` of the\n  client with that name, or `null` if there is no such client.\n- If `clientName` is not given, then `clientInfo` is a hash representing all\n  clients with registered names, where keys are client names and values are\n  client `address:port` strings.\n\nIf the registry feature is disabled on the `lockd` server, then `err` will be\nset accordingly.\n\n### getStats(cb)\n\nReturns statistics about the operation of the server.  The callback `cb` is\ncalled with parameters (`err`, `stats`).\n\n`stats` is an object with properties like `command_X` representing the number\nof times command `X` has been executed, and a few other pieces of information.\nFor details about the available statistics, see the\n[Stats API section](https://github.com/nylen/lockd/blob/master/docs/protocol.md#stats-api)\nof the protocol documentation.\n\n### disconnect(cb)\n\nCloses the connection to the `lockd` server (if any).  This will also cause any\nlocks held by the client to be released.\n\n## Other Client Implementations\n\n- PHP: http://code.svn.wordpress.org/lockd/lockd-client.php\n- Python: https://gist.github.com/mdawaffe/e53c86e5163b48d5fe3a\n- Go: https://github.com/apokalyptik/glockc\n\n## Protocol Documentation\n\n`lockd` uses a simple line-based protocol over TCP sockets.  See\n[docs/protocol.md](docs/protocol.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnylen%2Flockd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnylen%2Flockd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnylen%2Flockd/lists"}