monsqlize 1.0.0

package/lib/transaction/CacheLockManager.js

@@ -0,0 +1,161 @@
+/**
+ * 缓存锁管理器
+ * 用于在事务执行期间锁定缓存键，防止脏数据写入缓存
+ */
+
+class CacheLockManager {
+    constructor(options = {}) {
+        this.locks = new Map(); // key -> { sessionId, expiresAt }
+        this.maxDuration = options.maxDuration || 300000; // 5分钟默认
+        this.lockCleanupInterval = options.lockCleanupInterval || 10000; // 10秒清理一次
+        this.cleanupTimer = null;
+
+        // 启动自动清理
+        this._startCleanup();
+    }
+
+    /**
+     * 添加缓存锁
+     * @param {string} key - 缓存键（支持通配符 *）
+     * @param {Object} session - MongoDB session 对象
+     */
+    addLock(key, session) {
+        if (!session || !session.id) {
+            return;
+        }
+
+        const sessionId = session.id.toString();
+        const expiresAt = Date.now() + this.maxDuration;
+
+        this.locks.set(key, {
+            sessionId,
+            expiresAt,
+            lockedAt: Date.now()
+        });
+    }
+
+    /**
+     * 检查缓存键是否被锁定
+     * @param {string} key - 缓存键
+     * @returns {boolean}
+     */
+    isLocked(key) {
+        // 精确匹配
+        if (this.locks.has(key)) {
+            const lock = this.locks.get(key);
+            if (Date.now() < lock.expiresAt) {
+                return true;
+            }
+            // 过期自动删除
+            this.locks.delete(key);
+        }
+
+        // 通配符匹配
+        for (const [lockKey, lock] of this.locks.entries()) {
+            if (lockKey.includes('*')) {
+                const pattern = lockKey.replace(/\*/g, '.*');
+                const regex = new RegExp(`^${pattern}$`);
+                if (regex.test(key)) {
+                    if (Date.now() < lock.expiresAt) {
+                        return true;
+                    }
+                    // 过期自动删除
+                    this.locks.delete(lockKey);
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * 释放指定 session 的所有锁
+     * @param {Object} session - MongoDB session 对象
+     */
+    releaseLocks(session) {
+        if (!session || !session.id) {
+            return;
+        }
+
+        const sessionId = session.id.toString();
+        const keysToDelete = [];
+
+        for (const [key, lock] of this.locks.entries()) {
+            if (lock.sessionId === sessionId) {
+                keysToDelete.push(key);
+            }
+        }
+
+        keysToDelete.forEach(key => this.locks.delete(key));
+    }
+
+    /**
+     * 清理过期的锁
+     * @private
+     */
+    _cleanupExpiredLocks() {
+        const now = Date.now();
+        const keysToDelete = [];
+
+        for (const [key, lock] of this.locks.entries()) {
+            if (now >= lock.expiresAt) {
+                keysToDelete.push(key);
+            }
+        }
+
+        if (keysToDelete.length > 0) {
+            keysToDelete.forEach(key => this.locks.delete(key));
+        }
+    }
+
+    /**
+     * 启动自动清理定时器
+     * @private
+     */
+    _startCleanup() {
+        if (this.cleanupTimer) {
+            return;
+        }
+
+        this.cleanupTimer = setInterval(() => {
+            this._cleanupExpiredLocks();
+        }, this.lockCleanupInterval);
+
+        // 防止定时器阻止进程退出
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+
+    /**
+     * 停止自动清理
+     */
+    stop() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+
+    /**
+     * 获取当前锁的统计信息
+     */
+    getStats() {
+        return {
+            totalLocks: this.locks.size,
+            activeLocks: Array.from(this.locks.values()).filter(
+                lock => Date.now() < lock.expiresAt
+            ).length
+        };
+    }
+
+    /**
+     * 清除所有锁（用于测试）
+     */
+    clear() {
+        this.locks.clear();
+    }
+}
+
+module.exports = CacheLockManager;
+

package/lib/transaction/DistributedCacheLockManager.js

@@ -0,0 +1,239 @@
+/**
+ * 分布式缓存锁管理器
+ * 基于 Redis 实现跨实例的事务缓存锁，确保事务隔离性
+ *
+ * @example
+ * const lockManager = new DistributedCacheLockManager({
+ *   redis: redisInstance,
+ *   lockKeyPrefix: 'monsqlize:cache:lock:'
+ * });
+ *
+ * await lockManager.addLock('user:1', session);
+ * const isLocked = await lockManager.isLocked('user:1');
+ * await lockManager.releaseLocks(session);
+ */
+
+class DistributedCacheLockManager {
+    /**
+     * @param {Object} options
+     * @param {Object} options.redis - ioredis 实例
+     * @param {string} [options.lockKeyPrefix='monsqlize:cache:lock:'] - 锁键前缀
+     * @param {number} [options.maxDuration=300000] - 锁最大持续时间（毫秒）
+     * @param {Object} [options.logger] - 日志记录器
+     */
+    constructor(options = {}) {
+        if (!options.redis) {
+            throw new Error('DistributedCacheLockManager requires a Redis instance');
+        }
+
+        this.redis = options.redis;
+        this.lockKeyPrefix = options.lockKeyPrefix || 'monsqlize:cache:lock:';
+        this.maxDuration = options.maxDuration || 300000; // 5 分钟默认
+        this.logger = options.logger;
+
+        // 统计信息
+        this.stats = {
+            locksAcquired: 0,
+            locksReleased: 0,
+            lockChecks: 0,
+            errors: 0
+        };
+
+        // 错误处理
+        this.redis.on('error', (err) => {
+            this.stats.errors++;
+            if (this.logger) {
+                this.logger.error('[DistributedCacheLockManager] Redis error:', err.message);
+            }
+        });
+    }
+
+    /**
+     * 添加分布式缓存锁
+     * @param {string} key - 缓存键（支持通配符 *）
+     * @param {Object} session - MongoDB session 对象
+     * @returns {Promise<boolean>} 是否成功获取锁
+     */
+    async addLock(key, session) {
+        if (!session || !session.id) {
+            if (this.logger) {
+                this.logger.warn('[DistributedCacheLockManager] Invalid session, skip lock');
+            }
+            return false;
+        }
+
+        const lockKey = this.lockKeyPrefix + key;
+        const sessionId = session.id.toString();
+        const ttlSeconds = Math.ceil(this.maxDuration / 1000);
+
+        try {
+            // 使用 SET NX EX 原子操作获取锁
+            const result = await this.redis.set(lockKey, sessionId, 'EX', ttlSeconds, 'NX');
+
+            if (result === 'OK') {
+                this.stats.locksAcquired++;
+                if (this.logger) {
+                    this.logger.debug(`[DistributedCacheLockManager] Lock acquired: ${key}`);
+                }
+                return true;
+            }
+
+            return false;
+        } catch (error) {
+            this.stats.errors++;
+            if (this.logger) {
+                this.logger.error('[DistributedCacheLockManager] Add lock error:', error.message);
+            }
+            return false;
+        }
+    }
+
+    /**
+     * 检查缓存键是否被锁定
+     * @param {string} key - 缓存键
+     * @returns {Promise<boolean>}
+     */
+    async isLocked(key) {
+        this.stats.lockChecks++;
+
+        try {
+            // 1. 检查精确匹配
+            const lockKey = this.lockKeyPrefix + key;
+            const exists = await this.redis.exists(lockKey);
+            if (exists) {
+                return true;
+            }
+
+            // 2. 检查通配符匹配
+            // 注意：KEYS 命令在大数据量下性能较差，这里使用 SCAN 会更好
+            // 但为了简单起见，暂时使用 KEYS，生产环境建议优化
+            const pattern = this.lockKeyPrefix + '*';
+            const keys = await this.redis.keys(pattern);
+
+            for (const foundKey of keys) {
+                const lockPattern = foundKey.replace(this.lockKeyPrefix, '');
+
+                // 检查是否是通配符模式
+                if (lockPattern.includes('*')) {
+                    const regex = this._patternToRegex(lockPattern);
+                    if (regex.test(key)) {
+                        return true;
+                    }
+                }
+            }
+
+            return false;
+        } catch (error) {
+            this.stats.errors++;
+            if (this.logger) {
+                this.logger.error('[DistributedCacheLockManager] Is locked check error:', error.message);
+            }
+            // 发生错误时保守处理：假设没有锁（允许操作继续）
+            return false;
+        }
+    }
+
+    /**
+     * 释放指定 session 的所有锁
+     * @param {Object} session - MongoDB session 对象
+     * @returns {Promise<number>} 释放的锁数量
+     */
+    async releaseLocks(session) {
+        if (!session || !session.id) {
+            return 0;
+        }
+
+        const sessionId = session.id.toString();
+        const pattern = this.lockKeyPrefix + '*';
+
+        try {
+            const keys = await this.redis.keys(pattern);
+
+            if (keys.length === 0) {
+                return 0;
+            }
+
+            // 使用 Lua 脚本批量删除（原子操作）
+            // 只删除属于当前 session 的锁
+            const luaScript = `
+                local deletedCount = 0
+                for i, key in ipairs(KEYS) do
+                    local value = redis.call('GET', key)
+                    if value == ARGV[1] then
+                        redis.call('DEL', key)
+                        deletedCount = deletedCount + 1
+                    end
+                end
+                return deletedCount
+            `;
+
+            const deleted = await this.redis.eval(
+                luaScript,
+                keys.length,
+                ...keys,
+                sessionId
+            );
+
+            this.stats.locksReleased += deleted;
+
+            if (this.logger && deleted > 0) {
+                this.logger.debug(`[DistributedCacheLockManager] Released ${deleted} locks for session ${sessionId}`);
+            }
+
+            return deleted;
+        } catch (error) {
+            this.stats.errors++;
+            if (this.logger) {
+                this.logger.error('[DistributedCacheLockManager] Release locks error:', error.message);
+            }
+            return 0;
+        }
+    }
+
+    /**
+     * 清理所有过期锁（Redis TTL 会自动清理，此方法保留用于手动清理）
+     * @returns {Promise<void>}
+     */
+    async cleanup() {
+        // Redis TTL 会自动清理过期的键
+        // 这里可以添加额外的清理逻辑，比如强制清理超时的锁
+        if (this.logger) {
+            this.logger.debug('[DistributedCacheLockManager] Cleanup called (Redis handles TTL automatically)');
+        }
+    }
+
+    /**
+     * 获取统计信息
+     * @returns {Object}
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            lockKeyPrefix: this.lockKeyPrefix,
+            maxDuration: this.maxDuration
+        };
+    }
+
+    /**
+     * 将通配符模式转换为正则表达式
+     * @private
+     */
+    _patternToRegex(pattern) {
+        const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const wildcarded = escaped.replace(/\\\*/g, '.*');
+        return new RegExp(`^${wildcarded}$`);
+    }
+
+    /**
+     * 停止（清理资源）
+     * 注意：不关闭 Redis 连接，因为连接是外部传入的
+     */
+    stop() {
+        if (this.logger) {
+            this.logger.info('[DistributedCacheLockManager] Stopped');
+        }
+    }
+}
+
+module.exports = DistributedCacheLockManager;
+

package/lib/transaction/Transaction.js

@@ -0,0 +1,314 @@
+/**
+ * Transaction 类
+ * 表示一个 MongoDB 事务
+ */
+
+class Transaction {
+    constructor(session, options = {}) {
+        this.session = session;
+        this.id = `tx_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        this.state = 'pending';
+        this.cache = options.cache;
+        this.logger = options.logger;
+        this.timeout = options.timeout || 30000;
+        this.startTime = null;
+        this.timeoutTimer = null;
+
+        // 记录待失效的缓存（事务提交后才失效）
+        this.pendingInvalidations = new Set();
+
+        // 缓存锁管理器
+        this.lockManager = options.lockManager;
+        this.lockedKeys = new Set();
+
+        // ✨ 只读优化：追踪事务是否有写操作
+        this.hasWriteOperation = false;
+        this.operationCount = { read: 0, write: 0 };
+
+        // 关键：将 Transaction 实例存储到 session 的自定义属性
+        // 这样写操作可以通过 session.__monSQLizeTransaction 访问到 Transaction 实例
+        if (session) {
+            session.__monSQLizeTransaction = this;
+        }
+    }
+
+    /**
+     * 开始事务
+     */
+    async start() {
+        if (this.state !== 'pending') {
+            throw new Error(`Cannot start transaction in state: ${this.state}`);
+        }
+
+        this.session.startTransaction();
+        this.state = 'active';
+        this.startTime = Date.now();
+
+        // 设置超时自动中止
+        if (this.timeout > 0) {
+            this.timeoutTimer = setTimeout(() => {
+                if (this.state === 'active') {
+                    this.logger?.warn(`[Transaction] Timeout after ${this.timeout}ms, auto-aborting transaction ${this.id}`);
+                    this.abort().catch(() => {});
+                }
+            }, this.timeout);
+        }
+
+        this.logger?.debug(`[Transaction] Started transaction ${this.id}`);
+    }
+
+    /**
+     * 提交事务
+     * 注意：缓存已在 recordInvalidation() 中失效，这里只释放锁
+     */
+    async commit() {
+        if (this.state !== 'active') {
+            throw new Error(`Cannot commit transaction in ${this.state} state`);
+        }
+
+        try {
+            // 1. 提交事务
+            await this.session.commitTransaction();
+            this.state = 'committed';
+
+            // 2. 释放缓存锁（允许重新缓存）
+            // 注意：缓存已在写操作时失效，这里不再失效
+            this._releaseLocks();
+
+            this.logger?.debug(`[Transaction] Committed transaction ${this.id}`);
+        } finally {
+            this._clearTimeout();
+            this.pendingInvalidations.clear();
+        }
+    }
+
+    /**
+     * 回滚事务
+     * 注意：
+     * - 缓存已在写操作时失效
+     * - 但数据实际未改变（事务回滚）
+     * - 释放锁后，下次查询会从数据库读取并重新缓存（正确的旧值）
+     */
+    async abort() {
+        if (this.state !== 'active' && this.state !== 'pending') {
+            return; // 已经结束或中止
+        }
+
+        try {
+            await this.session.abortTransaction();
+            this.state = 'aborted';
+            this.logger?.debug(`[Transaction] Aborted transaction ${this.id}`);
+        } finally {
+            this._clearTimeout();
+            // 释放缓存锁（允许重新缓存）
+            // 注意：缓存已在写时失效，不在这里失效
+            this._releaseLocks();
+            this.pendingInvalidations.clear();
+        }
+    }
+
+    /**
+     * 结束会话
+     */
+    async end() {
+        await this.session.endSession();
+        this._clearTimeout();
+        this._releaseLocks();
+        this.logger?.debug(`[Transaction] Ended session for transaction ${this.id}`);
+    }
+
+    /**
+     * 记录待失效的缓存
+     * 写操作应该调用此方法，立即失效缓存并添加锁
+     * @param {string} cachePattern - 缓存键模式（支持通配符）
+     * @param {Object} metadata - 操作元数据
+     * @param {string} metadata.operation - 操作类型：'read' | 'write'
+     * @param {Object} metadata.query - 查询条件（用于文档级别锁）
+     * @param {string} metadata.collection - 集合名称
+     * @param {boolean} metadata.useDocumentLock - 是否启用文档级别锁（默认：true）
+     */
+    async recordInvalidation(cachePattern, metadata = {}) {
+        if (this.state === 'active') {
+            const {
+                operation = 'write',
+                query = {},
+                collection = '',
+                useDocumentLock = true
+            } = metadata;
+
+            // ✨ 追踪操作类型
+            if (operation === 'read') {
+                this.operationCount.read++;
+            } else {
+                this.operationCount.write++;
+                this.hasWriteOperation = true;
+            }
+
+            // ✨ 只读优化：只读操作不失效缓存
+            if (operation === 'read') {
+                // 只添加缓存锁，不失效缓存
+                if (this.lockManager) {
+                    this.lockManager.addLock(cachePattern, this.session);
+                    this.lockedKeys.add(cachePattern);
+                    this.logger?.debug(`[Transaction] Added cache lock (read-only): ${cachePattern}`);
+                }
+                this.pendingInvalidations.add(cachePattern);
+                return;
+            }
+
+            // 🚀 文档级别锁：尝试提取文档键
+            let lockPatterns = [cachePattern];
+            let usedDocumentLock = false;
+
+            if (useDocumentLock && collection && query) {
+                const docKeys = this._extractDocumentKeys(query);
+
+                // 如果成功提取文档键，且数量合理（<100个）
+                if (docKeys.length > 0 && docKeys.length < 100) {
+                    lockPatterns = docKeys.map(key =>
+                        this._buildDocumentLockPattern(collection, key)
+                    );
+                    usedDocumentLock = true;
+                    this.logger?.debug(`[Transaction] Using document-level locks for ${docKeys.length} documents`);
+                } else if (docKeys.length >= 100) {
+                    // 文档太多，回退到集合级别
+                    lockPatterns = [this._buildCollectionLockPattern(collection)];
+                    this.logger?.debug(`[Transaction] Too many documents (${docKeys.length}), falling back to collection-level lock`);
+                } else {
+                    // 无法提取文档键，使用传入的模式（通常是集合级别）
+                    this.logger?.debug(`[Transaction] Cannot extract document keys, using pattern: ${cachePattern}`);
+                }
+            }
+
+            // 步骤 1: 立即失效缓存（写时无效化）
+            if (this.cache) {
+                try {
+                    let totalDeleted = 0;
+                    for (const pattern of lockPatterns) {
+                        const deleted = await this.cache.delPattern(pattern);
+                        totalDeleted += deleted;
+                    }
+                    this.logger?.debug(`[Transaction] Immediately invalidated ${totalDeleted} cache keys (${usedDocumentLock ? 'document-level' : 'collection-level'})`);
+                } catch (err) {
+                    this.logger?.warn(`[Transaction] Failed to invalidate cache: ${err.message}`);
+                }
+            }
+
+            // 步骤 2: 添加缓存锁
+            if (this.lockManager) {
+                for (const pattern of lockPatterns) {
+                    this.lockManager.addLock(pattern, this.session);
+                    this.lockedKeys.add(pattern);
+                }
+                this.logger?.debug(`[Transaction] Added ${lockPatterns.length} cache lock(s)`);
+            }
+
+            // 步骤 3: 记录到待处理列表
+            lockPatterns.forEach(p => this.pendingInvalidations.add(p));
+        }
+    }
+
+    /**
+     * 释放所有缓存锁
+     * @private
+     */
+    _releaseLocks() {
+        if (this.lockManager && this.session) {
+            this.lockManager.releaseLocks(this.session);
+            this.lockedKeys.clear();
+            this.logger?.debug(`[Transaction] Released all cache locks`);
+        }
+    }
+
+    /**
+     * 清除超时定时器
+     * @private
+     */
+    _clearTimeout() {
+        if (this.timeoutTimer) {
+            clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = null;
+        }
+    }
+
+    /**
+     * 获取事务持续时间
+     */
+    getDuration() {
+        if (!this.startTime) return 0;
+        return Date.now() - this.startTime;
+    }
+
+    /**
+     * 🚀 文档级别锁：提取查询中的文档键
+     * @param {Object} query - MongoDB 查询条件
+     * @returns {Array} 文档键数组
+     * @private
+     */
+    _extractDocumentKeys(query) {
+        if (!query || typeof query !== 'object') {
+            return [];
+        }
+
+        const keys = [];
+
+        // 1. 简单的 _id 查询
+        if (query._id !== undefined && query._id !== null) {
+            if (Array.isArray(query._id)) {
+                // { _id: [1, 2, 3] }
+                keys.push(...query._id.map(id => String(id)));
+            } else if (query._id.$in && Array.isArray(query._id.$in)) {
+                // { _id: { $in: [1, 2, 3] } }
+                keys.push(...query._id.$in.map(id => String(id)));
+            } else if (typeof query._id === 'object' && query._id.constructor.name === 'ObjectId') {
+                // { _id: ObjectId("...") }
+                keys.push(String(query._id));
+            } else if (typeof query._id !== 'object' || query._id === null) {
+                // { _id: 1 } 或 { _id: "xxx" }
+                keys.push(String(query._id));
+            }
+        }
+
+        return keys;
+    }
+
+    /**
+     * 🚀 文档级别锁：构建文档级别的缓存模式
+     * @param {string} collection - 集合名称
+     * @param {string} docKey - 文档键
+     * @returns {string} 文档级别缓存模式
+     * @private
+     */
+    _buildDocumentLockPattern(collection, docKey) {
+        // 格式: *"collection":"collectionName"*"base":{"_id":"docKey"}*
+        return `*"collection":"${collection}"*"base":{"_id":"${docKey}"}*`;
+    }
+
+    /**
+     * 🚀 文档级别锁：构建集合级别的缓存模式（回退）
+     * @param {string} collection - 集合名称
+     * @returns {string} 集合级别缓存模式
+     * @private
+     */
+    _buildCollectionLockPattern(collection) {
+        // 格式: *"collection":"collectionName"*
+        return `*"collection":"${collection}"*`;
+    }
+
+    /**
+     * 🚀 获取事务统计信息
+     * @returns {Object} 统计信息
+     */
+    getStats() {
+        return {
+            id: this.id,
+            state: this.state,
+            duration: this.getDuration(),
+            hasWriteOperation: this.hasWriteOperation,
+            operationCount: { ...this.operationCount },
+            lockedKeysCount: this.lockedKeys.size
+        };
+    }
+}
+
+module.exports = Transaction;