From b835138a7613619c97ca0b2a4fac811a02deed30 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=A8=8B=E5=B9=BF?= <chengg@dacentsoft.com>
Date: Mon, 17 Nov 2025 15:50:15 +0800
Subject: [PATCH] =?UTF-8?q?```=20feat(tcp):=20=E6=B7=BB=E5=8A=A0=20TCPLock?=
 =?UTF-8?q?=20=E5=88=86=E5=B8=83=E5=BC=8F=E9=94=81=E6=9C=BA=E5=88=B6?=
 =?UTF-8?q?=E6=94=AF=E6=8C=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增基于 TCP 的分布式锁机制，用于跨多台机器的资源同步访问。该功能包含服务端和客户端实现，
支持读写锁模式，并提供详细的使用示例与 API 说明。
```
---
 README.md      | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++
 lock-client.js |  3 +++
 2 files changed, 72 insertions(+)

diff --git a/README.md b/README.md
index 24b919a..de8f18a 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@ A Node.js library providing asynchronous locking mechanisms including in-memory
 
 - **AsyncLock**: In-memory asynchronous lock for coordinating access to resources within a single process
 - **FileLock**: File-based lock for coordinating access to resources across multiple processes
+- **TCPLock**: TCP-based distributed lock for coordinating access to resources across multiple machines
 - Lightweight and easy to use
 - Promise-based API
 - Comprehensive test coverage
@@ -69,6 +70,53 @@ async function fileProtectedOperation() {
 }
 ```
 
+### TCPLock
+
+A TCP-based distributed lock for synchronizing operations across multiple machines:
+
+#### Server side
+
+```javascript
+const TCPLockServer = require('nlocks/lock.tcp');
+
+// Create and start a TCP lock server
+const server = new TCPLockServer({
+  host: '0.0.0.0',  // Listen host
+  port: 7301        // Listen port
+});
+
+server.start();
+```
+
+#### Client side
+
+```javascript
+const TcpRwLock = require('nlocks/lock-client.tcp');
+
+// Create a TCP lock client
+const lock = new TcpRwLock('resource-name', {
+  connect: {
+    host: 'localhost',  // Server host
+    port: 7301          // Server port
+  }
+});
+
+async function tcpProtectedOperation() {
+  await lock.connect();  // Connect to the lock server
+  try {
+    await lock.readLock();   // Acquire a read lock
+    // Or use await lock.writeLock(); for a write lock
+    
+    // Your critical section code here
+    console.log('Performing protected operation');
+    await someAsyncWork();
+  } finally {
+    await lock.unlock();     // Release the lock
+    await lock.close(); // Disconnect from server
+  }
+}
+```
+
 ## API
 
 ### AsyncLock
@@ -83,6 +131,27 @@ async function fileProtectedOperation() {
 - `acquire(filePath): Promise<void>` - Acquires a lock for the specified file path
 - `release(filePath): void` - Releases the lock for the specified file path
 
+### TCPLock
+
+#### Server
+
+- `new TCPLockServer(options)` - Creates a new TCP lock server instance
+  - `options.host`: Host to listen on (default: '0.0.0.0')
+  - `options.port`: Port to listen on (default: 7301)
+- `start(): void` - Starts the lock server
+- `stop(): void` - Stops the lock server
+
+#### Client
+
+- `new TcpRwLock(resource, options)` - Creates a new TCP lock client instance
+  - `resource`: Name of the resource to lock
+  - `options.connect.host`: Server hostname to connect to (default: 'localhost')
+  - `options.connect.port`: Server port to connect to (default: 7301)
+- `connect(): Promise<void>` - Connects to the lock server
+- `readLock(): Promise<void>` - Acquires a read lock
+- `writeLock(): Promise<void>` - Acquires a write lock
+- `unlock(): Promise<void>` - Releases the currently held lock
+
 ## Testing
 
 Run the test suite with:
diff --git a/lock-client.js b/lock-client.js
index fe4833c..645e020 100644
--- a/lock-client.js
+++ b/lock-client.js
@@ -135,6 +135,9 @@ class LockClient extends EventEmitter {
     this.cleanup();
     this._logger.debug(`Lock released for resource: ${this.resource}`);
   }
+  async release(){
+    await this.unlock();
+  }