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

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,6 +23,18 @@
  *      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),
@@ -106,6 +118,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 +164,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.4",
   "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

@@ -139,9 +139,6 @@ import {
     cleanTombstones,
     getPeerLastSyncId,
     updatePeerSyncId,
-    getInfraSchemaSQL,
-    getTriggersSQL,
-    dropTriggersSQL,
 } from './sync-protocol.js';
 
 // ========== 工具函数 ==========

package/sync-protocol.js

@@ -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`,
-    ];
-}