@raft-hlc-sync-protocol/raft-sync-lib 1.0.5 → 1.0.6

package/README.md

@@ -168,35 +168,22 @@ setInterval(() => engine.tickCleanup(), 3600_000);   // Cleanup old logs every 1
 
 ### Step 5: Write data
 
-With `dialect` set and `initTriggers()` called, all databases work the same way — triggers automatically log changes:
+> **Important:** All writes (INSERT/UPDATE/DELETE) to registered tables **must** go through `engine.write()` or be manually wrapped with `engine.beginManualTransaction()` / `commitManualTransaction()`. Do NOT write directly via `db.run(...)` outside of these wrappers — the engine needs to manage transactions and 2PC coordination to ensure data is correctly synced across nodes.
 
-```js
-const ts = engine.hlc.tick();
-db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)',
-    ['u1', 'Alice', ts]);
-engine.notifyLocalWrite();  // pushes to peers
-```
+**Recommended: `engine.write()` (high-level API)**
 
-**Without triggers** (manual logChange fallback):
+The engine handles the entire lifecycle automatically: BEGIN → execute → trigger logs → 2PC prepare/ack → COMMIT → broadcast commit → notify peers.
 
 ```js
-import { logChange } from 'sync-lib';
-
-const ts = engine.hlc.tick();
-db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)',
-    ['u1', 'Alice', ts]);
-logChange(db, 'users', 'INSERT',
-    JSON.stringify({ user_id: 'u1' }),
-    JSON.stringify({ user_id: 'u1', name: 'Alice', _hlc: ts }),
-    ts);
-engine.notifyLocalWrite();
+const result = await engine.write(async (db) => {
+    const ts = engine.hlc.tick();
+    db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)',
+        ['u1', 'Alice', ts]);
+    return { userId: 'u1' };  // return value is passed through
+}, userId);  // shardKey for routing
 ```
 
----
-
-## 2PC: Strong Consistency Writes
-
-When you need atomic multi-node writes:
+**Low-level API (for fine-grained control)**
 
 ```js
 const writeId = crypto.randomUUID();
@@ -479,13 +466,14 @@ VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${delKeyExpr}), NULL, OLD._hlc)`,
 | `tickPull()` | Pull changes from all peers |
 | `tickHeartbeat()` | Check timeouts, send pings |
 | `tickCleanup()` | Clean old sync_log and tombstones |
-| `beginManualTransaction(id)` | Start 2PC transaction |
-| `getManualTransactionEntries(id)` | Read sync_log entries from current txn |
-| `commitManualTransaction(id)` | Commit 2PC transaction |
-| `rollbackManualTransaction(id)` | Rollback 2PC transaction |
-| `waitForPrepareAck(writeId, entries, term, shardId)` | 2PC: broadcast prepare, wait for acks |
-| `broadcastCommit(writeId)` | 2PC: broadcast commit |
-| `broadcastAbort(writeId, reason)` | 2PC: broadcast abort |
+| `write(fn, shardKey?)` | **High-level 2PC API**: execute fn in a 2PC transaction, engine handles everything automatically |
+| `beginManualTransaction(id)` | Low-level: start 2PC transaction |
+| `getManualTransactionEntries(id)` | Low-level: read sync_log entries from current txn |
+| `commitManualTransaction(id)` | Low-level: commit 2PC transaction |
+| `rollbackManualTransaction(id)` | Low-level: rollback 2PC transaction |
+| `waitForPrepareAck(writeId, entries, term, shardId)` | Low-level 2PC: broadcast prepare, wait for acks |
+| `broadcastCommit(writeId)` | Low-level 2PC: broadcast commit |
+| `broadcastAbort(writeId, reason)` | Low-level 2PC: broadcast abort |
 | `proxyRequest(key, payload)` | Forward write request to leader |
 | `getShardId(key)` | Get shard ID for a key |
 | `isLeaderForShard(shardId)` | Check if local node is leader for shard |

package/README.zh-CN.md

@@ -168,35 +168,24 @@ setInterval(() => engine.tickCleanup(), 3600_000);   // 每 1 小时清理旧日
 
 ### 第 5 步：写入数据
 
-指定了 `dialect` 并调用 `initTriggers()` 后，所有数据库的写入方式完全一致 — 触发器自动记录变更：
+> **重要：** 对已注册表的所有写操作（INSERT/UPDATE/DELETE）**必须**通过 `engine.write()` 或手动使用 `engine.beginManualTransaction()` / `commitManualTransaction()` 包裹。**不要**在这些包裹之外直接调用 `db.run(...)` 写入——引擎需要管理事务和 2PC 协调，以确保数据正确同步到其他节点。
 
-```js
-const ts = engine.hlc.tick();
-db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)',
-    ['u1', 'Alice', ts]);
-engine.notifyLocalWrite();  // 推送到对等节点
-```
+**推荐：`engine.write()`（高阶 API）**
 
-**不使用触发器时**（手动 logChange 备选方案）：
+引擎自动处理完整生命周期：BEGIN → 执行 → 触发器记录 → 2PC prepare/ack → COMMIT → 广播 commit → 通知对等节点。
 
 ```js
-import { logChange } from 'sync-lib';
-
-const ts = engine.hlc.tick();
-db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)',
-    ['u1', 'Alice', ts]);
-logChange(db, 'users', 'INSERT',
-    JSON.stringify({ user_id: 'u1' }),
-    JSON.stringify({ user_id: 'u1', name: 'Alice', _hlc: ts }),
-    ts);
-engine.notifyLocalWrite();
+const result = await engine.write(async (db) => {
+    const ts = engine.hlc.tick();
+    db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)',
+        ['u1', 'Alice', ts]);
+    return { userId: 'u1' };  // 返回值透传给调用方
+}, userId);  // shardKey 用于路由
 ```
 
----
-
-## 2PC：强一致性写入
+**低阶 API（需要精细控制时）**
 
-需要原子性多节点写入时：
+如果需要更精细的控制（如在 prepare 前读取 entries），可使用低阶 API：
 
 ```js
 const writeId = crypto.randomUUID();
@@ -479,13 +468,14 @@ VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${delKeyExpr}), NULL, OLD._hlc)`,
 | `tickPull()` | 从所有对等节点拉取变更 |
 | `tickHeartbeat()` | 检查超时，发送心跳 |
 | `tickCleanup()` | 清理旧的 sync_log 和墓碑记录 |
-| `beginManualTransaction(id)` | 开始 2PC 事务 |
-| `getManualTransactionEntries(id)` | 读取当前事务的 sync_log 条目 |
-| `commitManualTransaction(id)` | 提交 2PC 事务 |
-| `rollbackManualTransaction(id)` | 回滚 2PC 事务 |
-| `waitForPrepareAck(writeId, entries, term, shardId)` | 2PC：广播 prepare，等待确认 |
-| `broadcastCommit(writeId)` | 2PC：广播 commit |
-| `broadcastAbort(writeId, reason)` | 2PC：广播 abort |
+| `write(fn, shardKey?)` | **高阶 2PC API**：在 2PC 事务中执行 fn，引擎自动处理全部流程 |
+| `beginManualTransaction(id)` | 低阶：开始 2PC 事务 |
+| `getManualTransactionEntries(id)` | 低阶：读取当前事务的 sync_log 条目 |
+| `commitManualTransaction(id)` | 低阶：提交 2PC 事务 |
+| `rollbackManualTransaction(id)` | 低阶：回滚 2PC 事务 |
+| `waitForPrepareAck(writeId, entries, term, shardId)` | 低阶 2PC：广播 prepare，等待确认 |
+| `broadcastCommit(writeId)` | 低阶 2PC：广播 commit |
+| `broadcastAbort(writeId, reason)` | 低阶 2PC：广播 abort |
 | `proxyRequest(key, payload)` | 将写请求转发给 Leader |
 | `getShardId(key)` | 获取 key 对应的分片 ID |
 | `isLeaderForShard(shardId)` | 检查本节点是否为该分片的 Leader |

package/index.js

@@ -81,19 +81,26 @@
  *  setInterval(() => engine.tickCleanup(), 3600_000);
  *  setInterval(() => engine.tickHeartbeat(), 15_000);
  *
- *  // 7. 业务写操作后通知推送
- *  db.run('INSERT INTO users ...');
- *  engine.notifyLocalWrite();
- *
- *  // 8. 未使用触发器时的备选方案：手动记录变更
- *  db.run('INSERT INTO users ...');
- *  engine.logChange('users', 'INSERT', { user_id: 'u1' }, { user_id: 'u1', name: 'Alice', ... });
- *  engine.notifyLocalWrite();
+ *  // 7. 写操作：已注册表的所有增删改必须通过 engine.write() 或手动事务包裹
+ *  //    ⚠️ 不要直接 db.run('INSERT ...') — 引擎需要管理事务和 2PC 同步
+ *  const result = await engine.write(async (db) => {
+ *      const ts = engine.hlc.tick();
+ *      db.run('INSERT INTO users ...', [ts, ...]);
+ *      return { userId: 'u1' };
+ *  }, userId);
  *
  * ═══════════════════════════════════════════════════════════════════
  *  2PC 写操作流程（多节点强一致）
  * ═══════════════════════════════════════════════════════════════════
  *
+ *  // 高阶 API（推荐）：引擎自动处理 BEGIN/COMMIT/ROLLBACK 和 2PC 协调
+ *  const result = await engine.write(async (db) => {
+ *      const ts = engine.hlc.tick();
+ *      db.run('INSERT INTO users ...', [ts, ...]);
+ *      return { userId: 'u1' };  // 返回值透传
+ *  }, userId);  // shardKey 用于路由
+ *
+ *  // 低阶 API（需要精细控制时使用）
  *  const writeId = crypto.randomUUID();
  *  engine.beginManualTransaction(writeId);
  *  try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raft-hlc-sync-protocol/raft-sync-lib",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "pure javascript raft and hlc sync protocol",
   "keywords": [
     "raft",

package/sync-engine.js

@@ -11,9 +11,12 @@
  *    - 不依赖 Node.js 特有 API
  *    - 不持有任何定时器（setTimeout/setInterval）
  *
- *  所有外部能力通过构造函数注入回调接口：
- *    1. DatabaseAdapter  — 数据库操作
- *    2. onXXX 回调       — 向外部通知事件 / 请求外部执行动作
+ *  所有外部能力通过构造函数注入：
+ *    1. dialect           — 预定义 SQL 方言（'sqlite' | 'postgresql' | 'mysql'），
+ *                           自动填充 DatabaseAdapter 上的事务、upsert、schema、触发器方法。
+ *                           不指定时需手动在 db 上实现全部方言方法，否则报错。
+ *    2. DatabaseAdapter   — 数据库操作（基础查询：run/get/all/exec）
+ *    3. onXXX 回调        — 向外部通知事件 / 请求外部执行动作
  *
  *  所有周期性任务通过 tick*() 方法暴露，由外部调度：
  *    - tickPull()       — 从所有 peer 拉取数据（建议 10s 间隔）
@@ -107,10 +110,14 @@
  *  setInterval(() => engine.tickCleanup(), 3600_000);
  *  setInterval(() => engine.tickHeartbeat(), 15_000);
  *
- *  // 6. 业务写操作后通知推送
- *  app.post('/api/create', (req, res) => {
- *      db.run('INSERT INTO ...');
- *      engine.notifyLocalWrite();
+ *  // 6. 写操作：已注册表的所有增删改必须通过 engine.write() 或手动事务包裹
+ *  //    ⚠️ 不要直接 db.run('INSERT ...') — 引擎需要管理事务和 2PC 同步
+ *  app.post('/api/create', async (req, res) => {
+ *      const result = await engine.write(async (db) => {
+ *          const ts = engine.hlc.tick();
+ *          db.run('INSERT INTO users ...', [ts, ...]);
+ *          return { ok: true };
+ *      }, userId);
  *  });
  */
 
@@ -554,6 +561,71 @@ export class SyncEngine {
         }
     }
 
+    // ╔═══════════════════════════════════════╗
+    // ║    2PC 写操作高阶 API                  ║
+    // ╚═══════════════════════════════════════╝
+
+    /**
+     * 在 2PC 事务中执行写操作（高阶 API，自动处理事务开启/提交/回滚）
+     *
+     * 适用于多节点部署下需要强一致性的写操作。
+     * 引擎自动完成：BEGIN → 执行 fn → 广播 prepare → 等待 quorum ack → COMMIT → 广播 commit
+     *
+     * @param {function(db: DatabaseAdapter): any} fn - 写操作函数，在事务中执行
+     *   fn 接收 db 适配器，可直接调用 db.run/get/all 执行业务写操作。
+     *   fn 的返回值会作为 write() 的返回值透传。
+     * @param {string} [shardKey] - 分片键（如 userId），用于确定 term 和 shardId
+     * @returns {Promise<any>} fn 的返回值
+     *
+     * @example
+     * const result = await engine.write(async (db) => {
+     *     const ts = engine.hlc.tick();
+     *     db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)', ['u1', 'Alice', ts]);
+     *     return { userId: 'u1' };
+     * }, userId);
+     */
+    async write(fn, shardKey) {
+        const writeId = randomUUID();
+        const shardId = shardKey ? this.getShardId(shardKey) : 0;
+        const term = this._shardElections.get(shardId)?._currentTerm || 0;
+
+        this.beginManualTransaction(writeId);
+        let result;
+        let prepareSent = false;
+        let committed = false;
+        try {
+            result = await fn(this.db);
+
+            const entries = this.getManualTransactionEntries(writeId);
+            if (entries.length > 0 && this._getActivePeerIds().length > 0) {
+                prepareSent = true;
+                await this.waitForPrepareAck(writeId, entries, term, shardId);
+
+                // 验证 term 未变（防止 prepare 等待期间发生选举导致脑裂）
+                const termAfter = this._shardElections.get(shardId)?._currentTerm || 0;
+                if (termAfter !== term) {
+                    throw new Error('2PC prepare rejected: term changed during prepare (was ' + term + ', now ' + termAfter + ')');
+                }
+            }
+
+            this.commitManualTransaction(writeId);
+            committed = true;
+
+            if (entries && entries.length > 0) {
+                try { this.broadcastCommit(writeId); } catch (_) {}
+            }
+        } catch (err) {
+            if (!committed) {
+                this.rollbackManualTransaction(writeId);
+            }
+            if (prepareSent && !committed) {
+                try { this.broadcastAbort(writeId, err.message); } catch (_) {}
+            }
+            throw err;
+        }
+        return result;
+    }
+
     // ╔═══════════════════════════════════════╗
     // ║    手动事务管理（2PC Leader 侧）        ║
     // ╚═══════════════════════════════════════╝