mlock-server 0.1.10 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 脉冲云
+Copyright (c) 2020 Liang Xingchen https://github.com/liangxingchen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,218 @@
-# `mlock-server`
+# mlock-server
 
-## Usage
+Multi-resource distributed lock server
 
+## 功能特性
+
+- 原子性多资源锁支持
+- TCP 协议通信
+- 锁超时和续期
+- 队列等待机制
+- 断线重连支持
+- 实时状态查询
+
+## 安装
+
+```bash
+npm install mlock-server
+```
+
+## 快速开始
+
+### JavaScript
+
+```javascript
+const Server = require('mlock-server');
+
+const server = new Server({ port: 12340 });
+await server.listen();
+console.log('Server started on port 12340');
+```
+
+### TypeScript
+
+```typescript
+import Server from 'mlock-server';
+
+const server = new Server({ port: 12340, debug: true });
+await server.listen();
+```
+
+### CLI 命令
+
+```bash
+# 启动服务
+npx mlock-server --port 12340
+
+# 查看状态
+npx mlock-status
+```
+
+## 配置选项
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| port | number | 12340 | 监听端口 |
+| debug | boolean | false | 是否输出调试日志 |
+
+## API
+
+### constructor(options: ServerOptions)
+
+创建服务端实例。
+
+```javascript
+const server = new Server({
+  port: 12340,
+  debug: true
+});
+```
+
+### listen(): Promise<void>
+
+启动服务监听。
+
+```javascript
+await server.listen();
+```
+
+### close(): Promise<void>
+
+关闭服务，清理所有连接和锁。
+
+```javascript
+await server.close();
+```
+
+## 协议说明
+
+mlock-server 使用简单的文本协议，通过 TCP 通信。
+
+### 消息格式
+
+所有消息以空格分隔，由 `packet-wrapper` 处理数据包边界。
+
+### 命令列表
+
+#### CONNECT
+
+客户端连接认证。
+
+```
+connect <socketId> <apiVersion>
+```
+
+**响应：**
+```
+connected <version>
+```
+
+#### LOCK
+
+请求上锁。
+
+```
+lock <requestId> <resources> <ttl> <timeout> <tolerate>
 ```
-const mlockServer = require('mlock-server');
 
+- `requestId`: 请求 ID，用于响应匹配
+- `resources`: 资源列表，用 `|` 分隔
+- `ttl`: 锁生存时间（毫秒）
+- `timeout`: 上锁超时时间（毫秒），0 表示不超时
+- `tolerate`: 容忍队列长度，0 表示不限制
+
+**响应：**
+```
+result <requestId> success <lockId>
+result <requestId> failed <error>
+```
+
+#### EXTEND
+
+续期锁。
+
+```
+extend <requestId> <lockId> <ttl>
+```
+
+**响应：**
+```
+result <requestId> success <expiredAt>
+result <requestId> failed <error>
+```
+
+#### UNLOCK
+
+解锁。
+
+```
+unlock <requestId> <lockId>
+```
+
+**响应：**
+```
+result <requestId> success done
+result <requestId> failed <error>
+```
+
+#### PING
+
+心跳检测。
+
+```
+ping <requestId>
+```
+
+**响应：**
 ```
+result <requestId> success pong
+```
+
+#### STATUS
+
+查询服务器状态。
+
+```
+status <requestId>
+```
+
+**响应：**
+```
+result <requestId> success <statusJSON>
+```
+
+### 服务器推送消息
+
+服务器会主动推送以下消息：
+
+```
+connected <version>        # 连接成功
+error <message>            # 连接错误
+locked <lockId>            # 锁获取成功
+timeout <lockId>            # 锁超时
+expired <lockId>           # 锁过期
+```
+
+## 状态查询
+
+通过 Telnet 或 netcat 直接连接可获取状态：
+
+```bash
+nc localhost 12340
+status
+```
+
+返回文本格式的状态信息：
+
+```
+socketCount: 1
+currentLocks: 0
+liveTime: 12345
+lockCount: 5
+lockedCount: 5
+...
+```
+
+## 许可证
+
+MIT

package/index.d.ts

@@ -1,16 +1,42 @@
 import * as net from 'net';
 
+/**
+ * 服务端配置选项
+ */
 export interface ServerOptions {
+  /**
+   * 监听端口，默认 12340
+   */
   port?: number;
+  /**
+   * 是否开启调试模式，开启后会输出详细日志
+   */
   debug?: boolean;
 }
 
+/**
+ * 分布式锁服务端
+ *
+ * 提供 TCP 协议接口，支持资源的分布式锁管理
+ * 支持锁的超时、续期、队列等待等功能
+ */
 export default class Server {
   server: net.Server;
   options: ServerOptions;
 
+  /**
+   * 创建服务端实例
+   * @param options 服务端配置选项
+   */
   constructor(options: ServerOptions);
 
+  /**
+   * 启动服务监听
+   */
   listen(): Promise<void>;
+
+  /**
+   * 关闭服务，清理所有连接和锁
+   */
   close(): Promise<void>;
 }

package/lib/index.js

@@ -205,7 +205,7 @@ class Server {
         let args = [socket].concat(list.slice(1));
         let cmd = list[0].toLowerCase();
         if (!socket.id && cmd !== 'connect')
-            return this.sendError(socket, 'shoule connect first!');
+            return this.sendError(socket, 'should connect first!');
         switch (cmd) {
             case 'connect':
                 this.connect(...args);

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "mlock-server",
-  "version": "0.1.10",
-  "description": "Maichong lock server",
-  "author": "Liang <liang@maichong.it> (https://github.com/liangxingchen)",
-  "homepage": "https://github.com/maichong/mlock/tree/master/packages/mlock-server#readme",
+  "version": "0.2.0",
+  "description": "Multi-resource distributed lock server",
+  "author": {
+    "name": "Liang",
+    "email": "liang@miaomo.cn",
+    "url": "https://github.com/liangxingchen"
+  },
+  "homepage": "https://github.com/liangxingchen/mlock/tree/master/packages/mlock-server#readme",
   "license": "MIT",
   "bin": {
     "mlock-server": "bin/mlock-server",
@@ -17,19 +21,19 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/maichong/mlock.git"
+    "url": "git+https://github.com/liangxingchen/mlock.git"
   },
   "scripts": {
     "build": "tsc"
   },
   "bugs": {
-    "url": "https://github.com/maichong/mlock/issues"
+    "url": "https://github.com/liangxingchen/mlock/issues"
   },
   "dependencies": {
     "packet-wrapper": "^0.1.0"
   },
   "devDependencies": {
-    "typescript": "^4.1.3"
+    "typescript": "^5.9.3"
   },
-  "gitHead": "e736b7c2adeb6434628c89c1e32fc430c394ee6c"
+  "gitHead": "fc9fbe81475b3fbdc8a54aff9015f152aa6f4edb"
 }