npm - @raft-hlc-sync-protocol/raft-sync-lib - Versions diffs - 1.0.4 → 1.0.5 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -118,6 +118,12 @@ const engine = new SyncEngine({
         console.log(`Shard ${shardId}: leader=${leaderId} local=${isLocal}`);
     },
+    // Required: any node can be elected as Leader and must handle proxied write requests
+    onExecuteProxyRequest: async (payload) => {
+        // Execute the write request locally and return the result
+        return await yourBusinessLogic(payload);
+    },
     // Optional callbacks
     onWriteCompleted: () => engine.notifyLocalWrite(),
     onError: (ctx, err) => console.error(`[sync] ${ctx}:`, err.message),
@@ -126,6 +132,7 @@ const engine = new SyncEngine({
 engine.registerTable('users', {
     keyColumns:  ['user_id'],
     dataColumns: ['user_id', 'name', 'email', '_hlc'],   // must include _hlc
+    // registerTable validates: keyColumns non-empty, dataColumns non-empty, '_hlc' in dataColumns
     validator:   (row) => { if (!row.user_id) throw new Error('missing user_id'); },
 });
@@ -296,19 +303,39 @@ const db = {
     },
     // Optional: inject PG triggers so initTriggers() works
+    // Note: must include HLC validation (same as built-in dialect)
     triggersSQL(tableName, def) {
-        const keyExpr = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const keyExprNew = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const keyExprOld = def.keyColumns.map(c => `'${c}', OLD.${c}`).join(', ');
         const dataExpr = def.dataColumns.map(c => `'${c}', NEW.${c}`).join(', ');
         return [
+            // HLC validation: enforce valid, monotonically increasing _hlc
+            `CREATE OR REPLACE FUNCTION _sync_trg_${tableName}_hlc_fn() RETURNS TRIGGER AS $$
+             BEGIN
+                 IF NEW._hlc IS NULL OR NEW._hlc = '' OR NEW._hlc = '0' THEN
+                     RAISE EXCEPTION 'sync-lib: _hlc is required for % on ${tableName}', TG_OP;
+                 END IF;
+                 IF TG_OP = 'UPDATE' AND NEW._hlc <= OLD._hlc THEN
+                     RAISE EXCEPTION 'sync-lib: _hlc must advance on UPDATE on ${tableName}';
+                 END IF;
+                 RETURN NEW;
+             END; $$ LANGUAGE plpgsql`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_hlc ON ${tableName}`,
+            `CREATE TRIGGER _sync_trg_${tableName}_hlc
+             BEFORE INSERT OR UPDATE ON ${tableName}
+             FOR EACH ROW EXECUTE FUNCTION _sync_trg_${tableName}_hlc_fn()`,
+            // Change logging
             `CREATE OR REPLACE FUNCTION _sync_trg_${tableName}_fn() RETURNS TRIGGER AS $$
              BEGIN
-                 INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-                 VALUES ('${tableName}', TG_OP,
-                         json_build_object(${keyExpr})::text,
-                         CASE WHEN TG_OP = 'DELETE' THEN NULL
-                              ELSE json_build_object(${dataExpr})::text END,
-                         COALESCE(NEW._hlc, OLD._hlc));
-                 RETURN COALESCE(NEW, OLD);
+                 IF TG_OP = 'DELETE' THEN
+                     INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+                     VALUES ('${tableName}', 'DELETE', json_build_object(${keyExprOld})::text, NULL, OLD._hlc);
+                     RETURN OLD;
+                 ELSE
+                     INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+                     VALUES ('${tableName}', TG_OP, json_build_object(${keyExprNew})::text, json_build_object(${dataExpr})::text, NEW._hlc);
+                     RETURN NEW;
+                 END IF;
              END; $$ LANGUAGE plpgsql`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
             `CREATE TRIGGER _sync_trg_${tableName}
@@ -318,6 +345,8 @@ const db = {
     },
     dropTriggersSQL(tableName) {
         return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_hlc ON ${tableName}`,
+            `DROP FUNCTION IF EXISTS _sync_trg_${tableName}_hlc_fn`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
             `DROP FUNCTION IF EXISTS _sync_trg_${tableName}_fn`,
         ];
@@ -380,27 +409,49 @@ const db = {
     },
     // Optional: inject MySQL triggers so initTriggers() works
+    // Note: must include HLC validation (same as built-in dialect)
     triggersSQL(tableName, def) {
         const keyExpr = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
         const dataExpr = def.dataColumns.map(c => `'${c}', NEW.${c}`).join(', ');
         const delKeyExpr = def.keyColumns.map(c => `'${c}', OLD.${c}`).join(', ');
         return [
+            // HLC validation: enforce valid, monotonically increasing _hlc
+            `CREATE TRIGGER _sync_trg_${tableName}_hlc_insert
+BEFORE INSERT ON ${tableName} FOR EACH ROW
+BEGIN
+    IF NEW._hlc IS NULL OR NEW._hlc = '' OR NEW._hlc = '0' THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'sync-lib: _hlc is required for INSERT on ${tableName}';
+    END IF;
+END`,
+            `CREATE TRIGGER _sync_trg_${tableName}_hlc_update
+BEFORE UPDATE ON ${tableName} FOR EACH ROW
+BEGIN
+    IF NEW._hlc IS NULL OR NEW._hlc = '' OR NEW._hlc = '0' THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'sync-lib: _hlc is required for UPDATE on ${tableName}';
+    END IF;
+    IF NEW._hlc <= OLD._hlc THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'sync-lib: _hlc must advance on UPDATE on ${tableName}';
+    END IF;
+END`,
+            // Change logging
             `CREATE TRIGGER _sync_trg_${tableName}_insert
-             AFTER INSERT ON ${tableName} FOR EACH ROW
-             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-             VALUES ('${tableName}', 'INSERT', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
+AFTER INSERT ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'INSERT', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
             `CREATE TRIGGER _sync_trg_${tableName}_update
-             AFTER UPDATE ON ${tableName} FOR EACH ROW
-             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-             VALUES ('${tableName}', 'UPDATE', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
+AFTER UPDATE ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'UPDATE', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
             `CREATE TRIGGER _sync_trg_${tableName}_delete
-             AFTER DELETE ON ${tableName} FOR EACH ROW
-             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-             VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${delKeyExpr}), NULL, OLD._hlc)`,
+AFTER DELETE ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${delKeyExpr}), NULL, OLD._hlc)`,
         ];
     },
     dropTriggersSQL(tableName) {
         return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_hlc_insert`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_hlc_update`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_insert`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_update`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_delete`,
@@ -419,7 +470,7 @@ const db = {
 |--------|-------------|
 | `registerTable(name, def)` | Register a business table for sync |
 | `initSchema()` | Create infrastructure tables (`_sync_log`, `_sync_peers`, `_tombstones`) |
-| `initTriggers()` | Create SQLite triggers (skip for other DBs) |
+| `initTriggers()` | Create auto-logging triggers (dialect-aware; works for SQLite, PG, MySQL) |
 | `start()` / `stop()` | Start/stop leader election |
 | `peerConnected(id, opts)` | Notify: new peer connected |
 | `receiveMessage(id, raw)` | Notify: message received from peer |
@@ -444,19 +495,17 @@ const db = {
 ### Standalone utilities
 ```js
-import { HLC, DIALECTS, applyDialect, logChange, getInfraSchemaSQL, getTriggersSQL } from 'sync-lib';
+import { HLC, DIALECTS, applyDialect, logChange, applyEntries } from 'sync-lib';
 ```
 | Export | Description |
 |--------|-------------|
 | `HLC` | Hybrid Logical Clock class |
 | `LeaderElection` | Leader election state machine |
-| `DIALECTS` | Built-in dialect definitions (sqlite, postgresql, mysql) |
+| `DIALECTS` | Built-in dialect definitions (sqlite, postgresql, mysql). Each dialect provides `infraSchemaSQL`, `upsertSQL`, `triggersSQL`, `dropTriggersSQL` |
 | `applyDialect(db, name)` | Apply a dialect's methods to a db adapter |
 | `validateDialectMethods(db)` | Validate all required dialect methods exist |
 | `logChange(db, table, op, key, data, hlc)` | Manually log a change (alternative to triggers) |
-| `getInfraSchemaSQL()` | Built-in SQLite DDL for infrastructure tables |
-| `getTriggersSQL(table, def)` | Generate SQLite sync triggers |
 | `applyEntries(db, entries, hlc, registry)` | Apply remote entries idempotently |
 ---

package/README.zh-CN.md CHANGED Viewed

@@ -118,6 +118,12 @@ const engine = new SyncEngine({
         console.log(`分片 ${shardId}: leader=${leaderId} local=${isLocal}`);
     },
+    // 必需：任何节点都可能当选 Leader，必须能处理 Follower 转发来的写请求
+    onExecuteProxyRequest: async (payload) => {
+        // 在本地执行写请求并返回结果
+        return await yourBusinessLogic(payload);
+    },
     // 可选回调
     onWriteCompleted: () => engine.notifyLocalWrite(),
     onError: (ctx, err) => console.error(`[sync] ${ctx}:`, err.message),
@@ -126,6 +132,7 @@ const engine = new SyncEngine({
 engine.registerTable('users', {
     keyColumns:  ['user_id'],
     dataColumns: ['user_id', 'name', 'email', '_hlc'],   // 必须包含 _hlc
+    // registerTable 会校验：keyColumns 非空、dataColumns 非空、dataColumns 包含 '_hlc'
     validator:   (row) => { if (!row.user_id) throw new Error('缺少 user_id'); },
 });
@@ -296,19 +303,39 @@ const db = {
     },
     // 可选：注入 PG 触发器，使 initTriggers() 自动创建
+    // 注意：必须包含 HLC 校验逻辑（与内置方言一致）
     triggersSQL(tableName, def) {
-        const keyExpr = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const keyExprNew = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const keyExprOld = def.keyColumns.map(c => `'${c}', OLD.${c}`).join(', ');
         const dataExpr = def.dataColumns.map(c => `'${c}', NEW.${c}`).join(', ');
         return [
+            // HLC 校验：强制要求 _hlc 有效且单调递增
+            `CREATE OR REPLACE FUNCTION _sync_trg_${tableName}_hlc_fn() RETURNS TRIGGER AS $$
+             BEGIN
+                 IF NEW._hlc IS NULL OR NEW._hlc = '' OR NEW._hlc = '0' THEN
+                     RAISE EXCEPTION 'sync-lib: _hlc is required for % on ${tableName}', TG_OP;
+                 END IF;
+                 IF TG_OP = 'UPDATE' AND NEW._hlc <= OLD._hlc THEN
+                     RAISE EXCEPTION 'sync-lib: _hlc must advance on UPDATE on ${tableName}';
+                 END IF;
+                 RETURN NEW;
+             END; $$ LANGUAGE plpgsql`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_hlc ON ${tableName}`,
+            `CREATE TRIGGER _sync_trg_${tableName}_hlc
+             BEFORE INSERT OR UPDATE ON ${tableName}
+             FOR EACH ROW EXECUTE FUNCTION _sync_trg_${tableName}_hlc_fn()`,
+            // 变更记录
             `CREATE OR REPLACE FUNCTION _sync_trg_${tableName}_fn() RETURNS TRIGGER AS $$
              BEGIN
-                 INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-                 VALUES ('${tableName}', TG_OP,
-                         json_build_object(${keyExpr})::text,
-                         CASE WHEN TG_OP = 'DELETE' THEN NULL
-                              ELSE json_build_object(${dataExpr})::text END,
-                         COALESCE(NEW._hlc, OLD._hlc));
-                 RETURN COALESCE(NEW, OLD);
+                 IF TG_OP = 'DELETE' THEN
+                     INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+                     VALUES ('${tableName}', 'DELETE', json_build_object(${keyExprOld})::text, NULL, OLD._hlc);
+                     RETURN OLD;
+                 ELSE
+                     INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+                     VALUES ('${tableName}', TG_OP, json_build_object(${keyExprNew})::text, json_build_object(${dataExpr})::text, NEW._hlc);
+                     RETURN NEW;
+                 END IF;
              END; $$ LANGUAGE plpgsql`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
             `CREATE TRIGGER _sync_trg_${tableName}
@@ -318,6 +345,8 @@ const db = {
     },
     dropTriggersSQL(tableName) {
         return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_hlc ON ${tableName}`,
+            `DROP FUNCTION IF EXISTS _sync_trg_${tableName}_hlc_fn`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
             `DROP FUNCTION IF EXISTS _sync_trg_${tableName}_fn`,
         ];
@@ -380,27 +409,49 @@ const db = {
     },
     // 可选：注入 MySQL 触发器，使 initTriggers() 自动创建
+    // 注意：必须包含 HLC 校验逻辑（与内置方言一致）
     triggersSQL(tableName, def) {
         const keyExpr = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
         const dataExpr = def.dataColumns.map(c => `'${c}', NEW.${c}`).join(', ');
         const delKeyExpr = def.keyColumns.map(c => `'${c}', OLD.${c}`).join(', ');
         return [
+            // HLC 校验：强制要求 _hlc 有效且单调递增
+            `CREATE TRIGGER _sync_trg_${tableName}_hlc_insert
+BEFORE INSERT ON ${tableName} FOR EACH ROW
+BEGIN
+    IF NEW._hlc IS NULL OR NEW._hlc = '' OR NEW._hlc = '0' THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'sync-lib: _hlc is required for INSERT on ${tableName}';
+    END IF;
+END`,
+            `CREATE TRIGGER _sync_trg_${tableName}_hlc_update
+BEFORE UPDATE ON ${tableName} FOR EACH ROW
+BEGIN
+    IF NEW._hlc IS NULL OR NEW._hlc = '' OR NEW._hlc = '0' THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'sync-lib: _hlc is required for UPDATE on ${tableName}';
+    END IF;
+    IF NEW._hlc <= OLD._hlc THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'sync-lib: _hlc must advance on UPDATE on ${tableName}';
+    END IF;
+END`,
+            // 变更记录
             `CREATE TRIGGER _sync_trg_${tableName}_insert
-             AFTER INSERT ON ${tableName} FOR EACH ROW
-             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-             VALUES ('${tableName}', 'INSERT', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
+AFTER INSERT ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'INSERT', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
             `CREATE TRIGGER _sync_trg_${tableName}_update
-             AFTER UPDATE ON ${tableName} FOR EACH ROW
-             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-             VALUES ('${tableName}', 'UPDATE', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
+AFTER UPDATE ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'UPDATE', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
             `CREATE TRIGGER _sync_trg_${tableName}_delete
-             AFTER DELETE ON ${tableName} FOR EACH ROW
-             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-             VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${delKeyExpr}), NULL, OLD._hlc)`,
+AFTER DELETE ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${delKeyExpr}), NULL, OLD._hlc)`,
         ];
     },
     dropTriggersSQL(tableName) {
         return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_hlc_insert`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_hlc_update`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_insert`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_update`,
             `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_delete`,
@@ -419,7 +470,7 @@ const db = {
 |------|------|
 | `registerTable(name, def)` | 注册业务表用于同步 |
 | `initSchema()` | 创建基础设施表（`_sync_log`、`_sync_peers`、`_tombstones`） |
-| `initTriggers()` | 创建 SQLite 触发器（其他数据库跳过） |
+| `initTriggers()` | 创建同步触发器（方言感知，支持 SQLite、PG、MySQL） |
 | `start()` / `stop()` | 启动/停止 Leader 选举 |
 | `peerConnected(id, opts)` | 通知：新的对等节点已连接 |
 | `receiveMessage(id, raw)` | 通知：收到对等节点消息 |
@@ -444,19 +495,17 @@ const db = {
 ### 独立工具函数
 ```js
-import { HLC, DIALECTS, applyDialect, logChange, getInfraSchemaSQL, getTriggersSQL } from 'sync-lib';
+import { HLC, DIALECTS, applyDialect, logChange, applyEntries } from 'sync-lib';
 ```
 | 导出 | 说明 |
 |------|------|
 | `HLC` | 混合逻辑时钟类 |
 | `LeaderElection` | Leader 选举状态机 |
-| `DIALECTS` | 内置方言定义（sqlite、postgresql、mysql） |
+| `DIALECTS` | 内置方言定义（sqlite、postgresql、mysql）。每种方言提供 `infraSchemaSQL`、`upsertSQL`、`triggersSQL`、`dropTriggersSQL` |
 | `applyDialect(db, name)` | 将方言方法应用到 db 适配器 |
 | `validateDialectMethods(db)` | 校验 db 是否具备所有必需的方言方法 |
 | `logChange(db, table, op, key, data, hlc)` | 手动记录变更（触发器的替代方案） |
-| `getInfraSchemaSQL()` | 内置 SQLite DDL（基础设施表） |
-| `getTriggersSQL(table, def)` | 生成 SQLite 同步触发器 |
 | `applyEntries(db, entries, hlc, registry)` | 幂等地应用远程条目 |
 ---

package/index.js CHANGED Viewed

@@ -39,11 +39,12 @@
  *      onSendToPeer:   (peerId, msg) => transport.send(peerId, msg),
  *      onClosePeer:    (peerId, reason) => transport.close(peerId),
  *      onLeaderChanged: (shardId, leaderId, isLocal) => { ... },
+ *      onExecuteProxyRequest: async (payload) => handleRequest(payload),
+ *        // ⚠️ 必须注册：任何节点都可能当选 Leader，必须能处理 Follower 转发的写请求
  *
  *      // ── 可选回调 ──
  *      onWriteCompleted:       () => engine.notifyLocalWrite(),
  *      onError:                (ctx, err) => logger.error(ctx, err),
- *      onExecuteProxyRequest:  (payload) => handleRequest(payload),
  *
  *      // ── 可选配置（全部有默认值）──
  *      numShards:          16,

package/package.json CHANGED Viewed

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

package/sync-engine.js CHANGED Viewed

@@ -62,9 +62,12 @@
  *  │    错误通知。context 是出错的位置字符串。                     │
  *  │                                                            │
  *  │  onExecuteProxyRequest(payload) → Promise<object>          │
- *  │    Leader 收到代理请求后的执行回调。                          │
+ *  │    Leader 收到 Follower 转发的写请求后的执行回调。            │
  *  │    payload / response 格式由外部业务自行定义，对模块透明。    │
  *  │                                                            │
+ *  │    ⚠️  多节点部署时必须注册：节点无法控制自己是否当选 Leader，  │
+ *  │    若当选后未注册此回调，Follower 转发来的请求将返回错误。     │
+ *  │                                                            │
  *  └────────────────────────────────────────────────────────────┘
  *
  * ═══════════════════════════════════════════════════════════════
@@ -179,7 +182,12 @@ export class SyncEngine {
      * ── 可选回调 ──
      * @param {function(): void} [options.onWriteCompleted] - 同步数据写入完成通知
      * @param {function(string, Error): void} [options.onError] - 错误通知
-     * @param {function(object): Promise<object>} [options.onExecuteProxyRequest] - 代理请求执行
+     *
+     * ── 必须回调 ──
+     * @param {function(object): Promise<object>} options.onExecuteProxyRequest - 代理请求执行
+     *   Leader 收到 Follower 转发的写请求后的执行回调。
+     *   节点无法控制自己是否当选 Leader，因此此回调始终必须注册。
+     *   payload / response 格式由外部业务自行定义，对模块透明。
      *
      * ── 方言 ──
      * @param {string} [options.dialect] - 数据库方言：'sqlite' | 'postgresql' | 'mysql'
@@ -217,7 +225,16 @@ export class SyncEngine {
         // ===== 可选回调 =====
         this._onWriteCompleted = options.onWriteCompleted || (() => {});
         this._onError = options.onError || (() => {});
-        this._onExecuteProxyRequest = options.onExecuteProxyRequest || null;
+        // ===== 必须回调：onExecuteProxyRequest =====
+        // 节点无法控制自己是否当选 Leader，因此此回调始终必须注册。
+        if (typeof options.onExecuteProxyRequest !== 'function') {
+            throw new Error(
+                'SyncEngine: onExecuteProxyRequest is required. ' +
+                'Any node can be elected as Leader and must be able to handle proxied write requests from Followers.'
+            );
+        }
+        this._onExecuteProxyRequest = options.onExecuteProxyRequest;
         // ===== 外部配置 =====
         this._numShards = options.numShards ?? 16;
@@ -278,12 +295,21 @@ export class SyncEngine {
      * @param {string} name - 表名
      * @param {object} def
      * @param {string[]} def.keyColumns     - 主键列名数组
-     * @param {string[]} def.dataColumns    - 全部列名数组（含 _hlc）
+     * @param {string[]} def.dataColumns    - 全部列名数组（必须包含 '_hlc'）
      * @param {string[]} [def.blobColumns]  - BLOB 列名（触发器中用 hex 序列化）
      * @param {function(object): void} [def.validator]      - 数据验证，不合法时抛异常
      * @param {function(object): object} [def.deserializer] - 反序列化（如 hex→Buffer）
      */
     registerTable(name, def) {
+        if (!def.keyColumns || def.keyColumns.length === 0) {
+            throw new Error(`registerTable('${name}'): keyColumns is required and must be non-empty`);
+        }
+        if (!def.dataColumns || def.dataColumns.length === 0) {
+            throw new Error(`registerTable('${name}'): dataColumns is required and must be non-empty`);
+        }
+        if (!def.dataColumns.includes('_hlc')) {
+            throw new Error(`registerTable('${name}'): dataColumns must include '_hlc' column`);
+        }
         this._tableRegistry.set(name, {
             keyColumns: def.keyColumns,
             dataColumns: def.dataColumns,
@@ -643,7 +669,12 @@ export class SyncEngine {
         }
         if (leaderNodeId === this.nodeId) {
-            if (!this._onExecuteProxyRequest) throw new Error('onExecuteProxyRequest not registered');
+            if (!this._onExecuteProxyRequest) {
+                throw new Error(
+                    'onExecuteProxyRequest is not registered on this node, but it is the Leader. ' +
+                    'In a multi-node deployment, all nodes must register onExecuteProxyRequest.'
+                );
+            }
             return this._onExecuteProxyRequest(payload);
         }
@@ -843,7 +874,15 @@ export class SyncEngine {
         const { requestId, payload } = msg;
         try {
             if (!this._onExecuteProxyRequest) {
-                this._sendToPeer(peerId, makeProxyRes(requestId, { error: 'proxy not supported' }));
+                // onExecuteProxyRequest 未注册：当前节点是 Leader 但无法处理代理请求。
+                // 这通常意味着多节点部署时忘记注册此回调。
+                const err = new Error(
+                    'onExecuteProxyRequest is not registered on this node, but it was elected as Leader. ' +
+                    'In a multi-node deployment, all nodes must register onExecuteProxyRequest ' +
+                    'because any node can become Leader.'
+                );
+                this._onError('proxy_exec', err);
+                this._sendToPeer(peerId, makeProxyRes(requestId, { error: err.message }));
                 return;
             }
             const result = await this._onExecuteProxyRequest(payload);

package/sync-protocol.js CHANGED Viewed

@@ -407,7 +407,7 @@ export function cleanTombstones(db, retentionDays = 7) {
 /**
  * 手动记录一条数据变更到 _sync_log
- * 适用于不支持触发器或不使用 SQLite 的数据库。
+ * 适用于不支持触发器的数据库。
  * 外部业务代码在每次写操作后调用此方法。
  *
  * @param {DatabaseAdapter} db