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

package/README.md

@@ -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

@@ -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/dialects.js

@@ -17,8 +17,6 @@
  * 若不指定 dialect 或指定不认识的值，所有方言方法必须由 db 自行实现，否则报错。
  */
 
-import { getInfraSchemaSQL, getTriggersSQL, dropTriggersSQL } from './sync-protocol.js';
-
 // ═══════════════════════════════════════════════════
 //  SQLite
 // ═══════════════════════════════════════════════════
@@ -34,9 +32,101 @@ const SQLITE = {
         return `INSERT OR REPLACE INTO ${table} (${cols}) VALUES (${ph})`;
     },
 
-    infraSchemaSQL: getInfraSchemaSQL,
-    triggersSQL: getTriggersSQL,
-    dropTriggersSQL,
+    infraSchemaSQL() {
+        return [
+            `CREATE TABLE IF NOT EXISTS _sync_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    table_name TEXT NOT NULL,
+    operation TEXT NOT NULL CHECK (operation IN ('INSERT', 'UPDATE', 'DELETE')),
+    row_key TEXT NOT NULL,
+    row_data TEXT,
+    _hlc TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+)`,
+            `CREATE INDEX IF NOT EXISTS idx_sync_log_id ON _sync_log (id)`,
+            `CREATE TABLE IF NOT EXISTS _sync_peers (
+    peer_key TEXT NOT NULL,
+    last_sync_id INTEGER NOT NULL DEFAULT 0,
+    last_sync_at TEXT,
+    PRIMARY KEY (peer_key)
+)`,
+            `CREATE TABLE IF NOT EXISTS _tombstones (
+    table_name TEXT NOT NULL,
+    row_key TEXT NOT NULL,
+    _hlc TEXT NOT NULL,
+    PRIMARY KEY (table_name, row_key)
+)`,
+        ];
+    },
+
+    triggersSQL(tableName, def) {
+        const blobSet = new Set(def.blobColumns || []);
+
+        const keyExpr = (ref) => {
+            const parts = def.keyColumns.map((col) => `'${col}', ${ref}.${col}`);
+            return `json_object(${parts.join(', ')})`;
+        };
+
+        const dataExpr = (ref) => {
+            const parts = def.dataColumns.map((col) => {
+                if (blobSet.has(col)) return `'${col}', hex(${ref}.${col})`;
+                return `'${col}', ${ref}.${col}`;
+            });
+            return `json_object(${parts.join(', ')})`;
+        };
+
+        return [
+            // BEFORE INSERT：强制要求 _hlc 非空且非默认值 '0'
+            `
+CREATE TRIGGER IF NOT EXISTS _sync_trg_${tableName}_hlc_insert
+BEFORE INSERT ON ${tableName}
+BEGIN
+    SELECT RAISE(ABORT, 'sync-lib: _hlc is required for INSERT on ${tableName}')
+    WHERE NEW._hlc IS NULL OR NEW._hlc = '' OR NEW._hlc = '0';
+END`,
+            // BEFORE UPDATE：强制要求 _hlc 非空且非默认值 '0'，且必须严格大于旧值（防止时钟回退）
+            `
+CREATE TRIGGER IF NOT EXISTS _sync_trg_${tableName}_hlc_update
+BEFORE UPDATE ON ${tableName}
+BEGIN
+    SELECT RAISE(ABORT, 'sync-lib: _hlc is required for UPDATE on ${tableName}')
+    WHERE NEW._hlc IS NULL OR NEW._hlc = '' OR NEW._hlc = '0';
+    SELECT RAISE(ABORT, 'sync-lib: _hlc must advance on UPDATE on ${tableName}')
+    WHERE NEW._hlc <= OLD._hlc;
+END`,
+            `
+CREATE TRIGGER IF NOT EXISTS _sync_trg_${tableName}_insert
+AFTER INSERT ON ${tableName}
+BEGIN
+    INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+    VALUES ('${tableName}', 'INSERT', ${keyExpr('NEW')}, ${dataExpr('NEW')}, NEW._hlc);
+END`,
+            `
+CREATE TRIGGER IF NOT EXISTS _sync_trg_${tableName}_update
+AFTER UPDATE ON ${tableName}
+BEGIN
+    INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+    VALUES ('${tableName}', 'UPDATE', ${keyExpr('NEW')}, ${dataExpr('NEW')}, NEW._hlc);
+END`,
+            `
+CREATE TRIGGER IF NOT EXISTS _sync_trg_${tableName}_delete
+AFTER DELETE ON ${tableName}
+BEGIN
+    INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+    VALUES ('${tableName}', 'DELETE', ${keyExpr('OLD')}, NULL, OLD._hlc);
+END`,
+        ];
+    },
+
+    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`,
+        ];
+    },
 };
 
 // ═══════════════════════════════════════════════════
@@ -98,6 +188,22 @@ const POSTGRESQL = {
         }).join(', ');
 
         return [
+            // HLC 校验函数：INSERT/UPDATE 时强制要求 _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()`,
+            // 变更记录函数：写入 _sync_log
             `CREATE OR REPLACE FUNCTION _sync_trg_${tableName}_fn() RETURNS TRIGGER AS $$
 BEGIN
     IF TG_OP = 'DELETE' THEN
@@ -119,6 +225,8 @@ FOR EACH ROW EXECUTE FUNCTION _sync_trg_${tableName}_fn()`,
 
     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`,
         ];
@@ -180,6 +288,26 @@ const MYSQL = {
         }).join(', ');
 
         return [
+            // HLC 校验触发器：INSERT 时强制要求 _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`,
+            // HLC 校验触发器：UPDATE 时强制要求 _hlc 有效且单调递增
+            `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)
@@ -197,6 +325,8 @@ VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${keyExpr('OLD')}), 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`,

package/index.js

@@ -10,7 +10,7 @@
  *
  *  import { SyncEngine } from './sync-lib/index.js';
  *
- *  // 1. 外部实现 DatabaseAdapter 接口
+ *  // 1. 外部实现 DatabaseAdapter 基础查询接口
  *  const db = {
  *      run(sql, params) { ... },  // → { changes: number }
  *      get(sql, params) { ... },  // → Object | null
@@ -23,15 +23,28 @@
  *      nodeId: 'node-1',
  *      db,
  *
+ *      // ── 方言（推荐）──
+ *      // 指定内置方言后，db 上缺失的 SQL 方法由 dialects.js 自动填充：
+ *      //   beginTransaction / commit / rollback
+ *      //   upsertSQL / infraSchemaSQL / triggersSQL / dropTriggersSQL
+ *      // 支持：'sqlite' | 'postgresql' | 'postgres' | 'pg' | 'mysql'
+ *      dialect: 'sqlite',
+ *
+ *      // ── 方言方法优先级 ──
+ *      // db 上已有的方法 > dialect 自动填充 > 报错（未指定 dialect 且方法缺失时）
+ *      // 即：用户在 db 上手动注入的方法始终优先于内置方言实现。
+ *      // 例如：db.upsertSQL = (table, cols, keys) => '...'  // 覆盖内置 SQLite upsert
+ *
  *      // ── 必须回调 ──
  *      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,
@@ -106,6 +119,7 @@
  *  ├── hlc.js              ← HLC 混合逻辑时钟（纯算法）
  *  ├── leader-election.js  ← Raft 简化版选举状态机（onXXX 回调）
  *  ├── sync-protocol.js    ← 消息编解码 + 幂等数据应用（DatabaseAdapter 接口）
+ *  ├── dialects.js         ← 内置 SQL 方言（SQLite/PostgreSQL/MySQL），所有 SQL 逻辑的唯一来源
  *  └── sync-engine.js      ← 主引擎（组合以上模块，对外统一入口）
  */
 
@@ -151,8 +165,4 @@ export {
     updatePeerSyncId,
     // 墓碑
     cleanTombstones,
-    // Schema / Trigger SQL 生成
-    getInfraSchemaSQL,
-    getTriggersSQL,
-    dropTriggersSQL,
 } from './sync-protocol.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raft-hlc-sync-protocol/raft-sync-lib",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "pure javascript raft and hlc sync protocol",
   "keywords": [
     "raft",
@@ -9,7 +9,7 @@
     "database",
     "sqlite",
     "mysql",
-    "postgreSQL"
+    "postgresql"
   ],
   "license": "MIT",
   "author": "xnet",

package/sync-engine.js

@@ -62,9 +62,12 @@
  *  │    错误通知。context 是出错的位置字符串。                     │
  *  │                                                            │
  *  │  onExecuteProxyRequest(payload) → Promise<object>          │
- *  │    Leader 收到代理请求后的执行回调。                          │
+ *  │    Leader 收到 Follower 转发的写请求后的执行回调。            │
  *  │    payload / response 格式由外部业务自行定义，对模块透明。    │
  *  │                                                            │
+ *  │    ⚠️  多节点部署时必须注册：节点无法控制自己是否当选 Leader，  │
+ *  │    若当选后未注册此回调，Follower 转发来的请求将返回错误。     │
+ *  │                                                            │
  *  └────────────────────────────────────────────────────────────┘
  *
  * ═══════════════════════════════════════════════════════════════
@@ -139,9 +142,6 @@ import {
     cleanTombstones,
     getPeerLastSyncId,
     updatePeerSyncId,
-    getInfraSchemaSQL,
-    getTriggersSQL,
-    dropTriggersSQL,
 } from './sync-protocol.js';
 
 // ========== 工具函数 ==========
@@ -182,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'
@@ -220,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;
@@ -281,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,
@@ -646,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);
         }
 
@@ -846,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

@@ -407,7 +407,7 @@ export function cleanTombstones(db, retentionDays = 7) {
 
 /**
  * 手动记录一条数据变更到 _sync_log
- * 适用于不支持触发器或不使用 SQLite 的数据库。
+ * 适用于不支持触发器的数据库。
  * 外部业务代码在每次写操作后调用此方法。
  *
  * @param {DatabaseAdapter} db
@@ -424,111 +424,3 @@ export function logChange(db, tableName, operation, rowKeyJson, rowDataJson, hlc
     );
 }
 
-// ╔═══════════════════════════════════════╗
-// ║       Schema / Trigger SQL 生成        ║
-// ╚═══════════════════════════════════════╝
-
-/**
- * 返回同步基础设施表的建表 SQL（SQLite 语法，作为默认降级实现）
- * 包含：_sync_log, _sync_peers, _tombstones
- *
- * 若需其他数据库方言，请在 DatabaseAdapter 上实现 infraSchemaSQL() 方法覆盖此默认值。
- * SyncEngine.initSchema() 优先调用 db.infraSchemaSQL()，不存在时才使用本函数。
- *
- * @returns {string[]} SQL 语句数组（SQLite 方言）
- */
-export function getInfraSchemaSQL() {
-    return [
-        `CREATE TABLE IF NOT EXISTS _sync_log (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    table_name TEXT NOT NULL,
-    operation TEXT NOT NULL CHECK (operation IN ('INSERT', 'UPDATE', 'DELETE')),
-    row_key TEXT NOT NULL,
-    row_data TEXT,
-    _hlc TEXT NOT NULL,
-    created_at TEXT NOT NULL DEFAULT (datetime('now'))
-)`,
-        `CREATE INDEX IF NOT EXISTS idx_sync_log_id ON _sync_log (id)`,
-
-        `CREATE TABLE IF NOT EXISTS _sync_peers (
-    peer_key TEXT NOT NULL,
-    last_sync_id INTEGER NOT NULL DEFAULT 0,
-    last_sync_at TEXT,
-    PRIMARY KEY (peer_key)
-)`,
-
-        `CREATE TABLE IF NOT EXISTS _tombstones (
-    table_name TEXT NOT NULL,
-    row_key TEXT NOT NULL,
-    _hlc TEXT NOT NULL,
-    PRIMARY KEY (table_name, row_key)
-)`,
-    ];
-}
-
-/**
- * 为指定表生成 SQLite 同步触发器 SQL
- * 触发器自动将 INSERT/UPDATE/DELETE 变更写入 _sync_log
- *
- * 注意：这是 SQLite 专用语法。其他数据库请使用 logChange() 手动记录。
- *
- * @param {string} tableName
- * @param {TableDef} def - 表定义
- * @returns {string[]} SQL 语句数组
- */
-export function getTriggersSQL(tableName, def) {
-    const sqls = [];
-
-    const keyExpr = (ref) => {
-        const parts = def.keyColumns.map((col) => `'${col}', ${ref}.${col}`);
-        return `json_object(${parts.join(', ')})`;
-    };
-
-    const dataExpr = (ref) => {
-        const blobSet = new Set(def.blobColumns || []);
-        const parts = def.dataColumns.map((col) => {
-            if (blobSet.has(col)) return `'${col}', hex(${ref}.${col})`;
-            return `'${col}', ${ref}.${col}`;
-        });
-        return `json_object(${parts.join(', ')})`;
-    };
-
-    sqls.push(`
-CREATE TRIGGER IF NOT EXISTS _sync_trg_${tableName}_insert
-AFTER INSERT ON ${tableName}
-BEGIN
-    INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-    VALUES ('${tableName}', 'INSERT', ${keyExpr('NEW')}, ${dataExpr('NEW')}, NEW._hlc);
-END`);
-
-    sqls.push(`
-CREATE TRIGGER IF NOT EXISTS _sync_trg_${tableName}_update
-AFTER UPDATE ON ${tableName}
-BEGIN
-    INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-    VALUES ('${tableName}', 'UPDATE', ${keyExpr('NEW')}, ${dataExpr('NEW')}, NEW._hlc);
-END`);
-
-    sqls.push(`
-CREATE TRIGGER IF NOT EXISTS _sync_trg_${tableName}_delete
-AFTER DELETE ON ${tableName}
-BEGIN
-    INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
-    VALUES ('${tableName}', 'DELETE', ${keyExpr('OLD')}, NULL, OLD._hlc);
-END`);
-
-    return sqls;
-}
-
-/**
- * 返回删除指定表同步触发器的 SQL
- * @param {string} tableName
- * @returns {string[]}
- */
-export function dropTriggersSQL(tableName) {
-    return [
-        `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_insert`,
-        `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_update`,
-        `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_delete`,
-    ];
-}