monsqlize 1.0.1 → 1.0.5

package/lib/cache.js

@@ -13,7 +13,7 @@ class Cache {
             enableStats: options.enableStats !== false, // 启用统计信息
             ...options
         };
-        
+
         // 统计信息
         this.stats = {
             hits: 0,
@@ -141,13 +141,13 @@ class Cache {
     async delPattern(pattern) {
         const regex = this._patternToRegex(pattern);
         const keysToDelete = [];
-        
+
         for (const key of this.cache.keys()) {
             if (regex.test(key)) {
                 keysToDelete.push(key);
             }
         }
-        
+
 
         return await this.delMany(keysToDelete);
     }
@@ -231,7 +231,7 @@ class Cache {
     _estimateSize(key, value) {
         const keySize = typeof key === 'string' ? key.length * 2 : 8;
         let valueSize = 8; // 默认值
-        
+
         if (typeof value === 'string') {
             valueSize = value.length * 2;
         } else if (typeof value === 'object' && value !== null) {
@@ -241,7 +241,7 @@ class Cache {
                 valueSize = 100; // 估算值
             }
         }
-        
+
         return keySize + valueSize;
     }
 
@@ -471,7 +471,7 @@ module.exports = class CacheFactory {
         return (op, base = {}, fetcher) => {
             // 检查是否在事务中
             const inTransaction = base.session && base.session.__monSQLizeTransaction;
-            
+
             // 事务内默认不缓存（除非显式指定 cache）
             let ttl = 0;
             if (inTransaction) {
@@ -481,11 +481,11 @@ module.exports = class CacheFactory {
                 // 非事务：正常处理 cache 参数
                 ttl = base.cache ? Number(base.cache) : 0;
             }
-            
+
             // 使用浅拷贝构建用于键的对象，避免修改调用方入参
             const { cache: _cacheTTL, maxTimeMS: _maxTimeMS, session: _session, ...keyBase } = base || {};
             const key = this.buildCacheKey({ ...ctx, op, base: keyBase });
             return this.readThrough(cache, ttl, key, fetcher);
         };
     }
-}
+};

package/lib/common/validation.js

@@ -46,4 +46,67 @@ function assertCursorSortCompatible(currentSort, cursorSort) {
     }
 }
 
-module.exports = { validateLimitAfterBefore, assertCursorSortCompatible };
+/**
+ * 验证数值范围
+ * @param {number} value - 要验证的数值
+ * @param {number} min - 最小值（包含）
+ * @param {number} max - 最大值（包含）
+ * @param {string} name - 参数名称（用于错误消息）
+ * @returns {number} 验证通过后的值
+ * @throws {Error} 当值不在有效范围内时抛出 INVALID_ARGUMENT 错误
+ */
+function validateRange(value, min, max, name) {
+    const { ErrorCodes, createError } = require('../errors');
+
+    // 检查是否为有效数字
+    if (typeof value !== 'number' || isNaN(value)) {
+        throw createError(
+            ErrorCodes.INVALID_ARGUMENT,
+            `${name} 必须是一个有效的数字`
+        );
+    }
+
+    // 检查是否为有限数（排除 Infinity）
+    if (!isFinite(value)) {
+        throw createError(
+            ErrorCodes.INVALID_ARGUMENT,
+            `${name} 必须是有限数字`
+        );
+    }
+
+    // 检查范围
+    if (value < min || value > max) {
+        throw createError(
+            ErrorCodes.INVALID_ARGUMENT,
+            `${name} 必须在 ${min} 到 ${max} 之间，当前值: ${value}`
+        );
+    }
+
+    return value;
+}
+
+/**
+ * 验证正整数
+ * @param {number} value - 要验证的数值
+ * @param {string} name - 参数名称（用于错误消息）
+ * @returns {number} 验证通过后的值
+ * @throws {Error} 当值不是正整数时抛出错误
+ */
+function validatePositiveInteger(value, name) {
+    const { ErrorCodes, createError } = require('../errors');
+
+    if (!Number.isInteger(value) || value <= 0) {
+        throw createError(
+            ErrorCodes.INVALID_ARGUMENT,
+            `${name} 必须是正整数，当前值: ${value}`
+        );
+    }
+    return value;
+}
+
+module.exports = {
+    validateLimitAfterBefore,
+    assertCursorSortCompatible,
+    validateRange,
+    validatePositiveInteger
+};

package/lib/connect.js

@@ -68,9 +68,9 @@ module.exports = class ConnectionManager {
         const db = (databaseName)=>{
             return {
                 collection:(collectionName)=>instance.collection(databaseName, collectionName)
-            }
-        }
+            };
+        };
 
         return { collection, db, instance };
     }
-}
+};

package/lib/errors.js

@@ -43,6 +43,10 @@ const ErrorCodes = {
     DOCUMENTS_REQUIRED: 'DOCUMENTS_REQUIRED',
     DUPLICATE_KEY: 'DUPLICATE_KEY',
     WRITE_CONFLICT: 'WRITE_CONFLICT',
+
+    // 🆕 v1.4.0: 锁相关错误
+    LOCK_ACQUIRE_FAILED: 'LOCK_ACQUIRE_FAILED',
+    LOCK_TIMEOUT: 'LOCK_TIMEOUT',
 };
 
 /**
@@ -145,6 +149,9 @@ function createWriteError(operation, message, cause = null) {
     );
 }
 
+// 🆕 v1.4.0: 导入锁错误类
+const { LockAcquireError, LockTimeoutError } = require('./lock/errors');
+
 module.exports = {
     ErrorCodes,
     createError,
@@ -153,5 +160,8 @@ module.exports = {
     createConnectionError,
     createQueryTimeoutError,
     createWriteError,
+    // 🆕 v1.4.0: 锁错误类
+    LockAcquireError,
+    LockTimeoutError,
 };
 

package/lib/index.js

@@ -5,6 +5,7 @@ const { createRedisCacheAdapter } = require('./redis-cache-adapter');
 const TransactionManager = require('./transaction/TransactionManager');
 const CacheLockManager = require('./transaction/CacheLockManager');
 const DistributedCacheInvalidator = require('./distributed-cache-invalidator');
+const { validateRange } = require('./common/validation');
 
 module.exports = class {
 
@@ -28,6 +29,12 @@ module.exports = class {
         this.databaseName = databaseName;
         this.config = config;
 
+        // ✅ v1.3.0: 自动 ObjectId 转换配置
+        this.autoConvertConfig = this._initAutoConvertConfig(
+            options.autoConvertObjectId,
+            options.type
+        );
+
         // 🔧 修复：保存 distributed 配置到单独的变量
         this._cacheConfig = cache;
 
@@ -50,6 +57,20 @@ module.exports = class {
         // 使用 Logger 工具类创建日志记录器
         this.logger = Logger.create(logger);
 
+        // 🔒 参数验证：防止 DoS 攻击（允许null值用于显式禁用）
+        if (options.maxTimeMS !== undefined && options.maxTimeMS !== null) {
+            validateRange(options.maxTimeMS, 1, 300000, 'maxTimeMS');
+        }
+        if (options.findLimit !== undefined && options.findLimit !== null) {
+            validateRange(options.findLimit, 1, 10000, 'findLimit');
+        }
+        if (options.findPageMaxLimit !== undefined && options.findPageMaxLimit !== null) {
+            validateRange(options.findPageMaxLimit, 1, 10000, 'findPageMaxLimit');
+        }
+        if (options.slowQueryMs !== undefined && options.slowQueryMs !== null && options.slowQueryMs !== -1) {
+            validateRange(options.slowQueryMs, 0, 60000, 'slowQueryMs');
+        }
+
         // 集中默认配置（库内默认 + 用户覆盖）
         const DEFAULTS = {
             maxTimeMS: 2000,
@@ -83,6 +104,8 @@ module.exports = class {
             findPageMaxLimit: options.findPageMaxLimit,
             cursorSecret: options.cursorSecret,
             log: options.log,
+            // 🔴 v1.3.1: 慢查询日志持久化存储配置
+            slowQueryLog: options.slowQueryLog,
         });
         // 冻结默认配置，避免运行期被意外修改
         this.defaults = Object.freeze(this.defaults);
@@ -140,7 +163,7 @@ module.exports = class {
 
                         this._cacheInvalidator = new DistributedCacheInvalidator({
                             redisUrl: this._cacheConfig.distributed.redisUrl,
-                            redis: redis,
+                            redis,
                             channel: this._cacheConfig.distributed.channel,
                             instanceId: this._cacheConfig.distributed.instanceId,
                             cache: this.cache,
@@ -171,17 +194,17 @@ module.exports = class {
                 // 初始化事务管理器和缓存锁管理器
                 if (this.type === 'mongodb' && instance.client) {
                     // 检查是否配置了分布式事务锁
-                    const useDistributedLock = this.cache &&
-                        typeof this.cache.transaction === 'object' &&
-                        this.cache.transaction.distributedLock &&
-                        this.cache.transaction.distributedLock.redis;
+                    const useDistributedLock = this._cacheConfig &&
+                        typeof this._cacheConfig.transaction === 'object' &&
+                        this._cacheConfig.transaction.distributedLock &&
+                        this._cacheConfig.transaction.distributedLock.redis;
 
                     if (useDistributedLock) {
                         // 使用分布式缓存锁管理器
                         const DistributedCacheLockManager = require('./transaction/DistributedCacheLockManager');
                         this._lockManager = new DistributedCacheLockManager({
-                            redis: this.cache.transaction.distributedLock.redis,
-                            lockKeyPrefix: this.cache.transaction.distributedLock.keyPrefix || 'monsqlize:cache:lock:',
+                            redis: this._cacheConfig.transaction.distributedLock.redis,
+                            lockKeyPrefix: this._cacheConfig.transaction.distributedLock.keyPrefix || 'monsqlize:cache:lock:',
                             maxDuration: 300000,
                             logger: this.logger
                         });
@@ -215,6 +238,27 @@ module.exports = class {
                         hasLockManager: !!this._lockManager,
                         isDistributed: useDistributedLock
                     });
+
+                    // 🆕 v1.4.0: 挂载业务锁 API（仅在使用分布式锁时可用）
+                    if (this._lockManager && typeof this._lockManager.withLock === 'function') {
+                        this.dbInstance.withLock = (key, callback, opts) =>
+                            this._lockManager.withLock(key, callback, opts);
+                        this.dbInstance.acquireLock = (key, opts) =>
+                            this._lockManager.acquireLock(key, opts);
+                        this.dbInstance.tryAcquireLock = (key, opts) =>
+                            this._lockManager.tryAcquireLock(key, opts);
+                        this.dbInstance.getLockStats = () =>
+                            this._lockManager.getStats();
+
+                        this.logger.info('✅ Business lock API initialized', {
+                            isDistributed: useDistributedLock
+                        });
+                    } else {
+                        this.logger.warn('⚠️  Business lock API not available (Redis required)', {
+                            hasLockManager: !!this._lockManager,
+                            isDistributed: useDistributedLock
+                        });
+                    }
                 } else {
                     this.logger.warn('⚠️  Transaction manager not initialized', {
                         type: this.type,
@@ -293,6 +337,19 @@ module.exports = class {
         return { status: 'down', connected: false };
     }
 
+    /**
+     * 查询慢查询日志（v1.3.1+）
+     * @param {Object} filter - 查询条件 { db, collection, operation }
+     * @param {Object} options - 查询选项 { sort, limit, skip }
+     * @returns {Promise<Array>} 慢查询日志列表
+     */
+    async getSlowQueryLogs(filter, options) {
+        if (this._adapter && typeof this._adapter.getSlowQueryLogs === 'function') {
+            return this._adapter.getSlowQueryLogs(filter, options);
+        }
+        throw new Error('Slow query log feature is not enabled or not supported');
+    }
+
     /**
      * 事件订阅（适配器透传）
      * @param {'connected'|'closed'|'error'|'slow-query'} event
@@ -347,6 +404,113 @@ module.exports = class {
     /**
      * 导出工具函数：创建 Redis 缓存适配器
      * @static
+     * @param {import('ioredis').Redis | import('ioredis').Cluster} client - Redis客户端
+     * @param {Object} [options] - 配置选项
+     * @returns {import('./cache').CacheLike} Redis缓存适配器
+     */
+    static createRedisCacheAdapter(client, options) {
+        return createRedisCacheAdapter(client, options);
+    }
+
+    /**
+     * 初始化 ObjectId 自动转换配置
+     * @private
+     * @param {boolean|Object} config - 用户配置
+     * @param {string} dbType - 数据库类型
+     * @returns {Object} 配置对象
+     */
+    _initAutoConvertConfig(config, dbType) {
+        // 只在 MongoDB 类型下启用
+        if (dbType !== 'mongodb') {
+            return { enabled: false };
+        }
+
+        // 默认配置
+        const defaults = {
+            enabled: true,
+            excludeFields: [],
+            customFieldPatterns: [],
+            maxDepth: 10,
+            logLevel: 'warn'
+        };
+
+        // 用户禁用
+        if (config === false) {
+            return { enabled: false };
+        }
+
+        // 用户自定义配置
+        if (typeof config === 'object' && config !== null) {
+            return {
+                enabled: config.enabled !== false,
+                excludeFields: Array.isArray(config.excludeFields)
+                    ? config.excludeFields
+                    : defaults.excludeFields,
+                customFieldPatterns: Array.isArray(config.customFieldPatterns)
+                    ? config.customFieldPatterns
+                    : defaults.customFieldPatterns,
+                maxDepth: typeof config.maxDepth === 'number'
+                    ? config.maxDepth
+                    : defaults.maxDepth,
+                logLevel: config.logLevel || defaults.logLevel
+            };
+        }
+
+        return defaults;
+    }
+
+    /**
+     * 获取 Model 实例
+     *
+     * @param {string} collectionName - 集合名称
+     * @returns {ModelInstance} Model 实例
+     * @throws {Error} Model 未定义
+     * @throws {Error} 数据库未连接
+     *
+     * @example
+     * // 1. 定义 Model
+     * const { Model } = require('monsqlize');
+     * Model.define('users', {
+     *   schema: (dsl) => dsl({ username: 'string!' })
+     * });
+     *
+     * // 2. 连接数据库并获取 Model 实例
+     * const msq = new MonSQLize({ ... });
+     * await msq.connect();
+     * const User = msq.model('users');
+     *
+     * // 3. 使用 Model
+     * const result = await User.find({ status: 'active' });
      */
-    static createRedisCacheAdapter = createRedisCacheAdapter;
-}
+    model(collectionName) {
+        // 检查数据库是否已连接
+        if (!this.dbInstance) {
+            const err = new Error('Database is not connected. Call connect() before accessing models.');
+            err.code = 'NOT_CONNECTED';
+            throw err;
+        }
+
+        // 检查 Model 是否已定义
+        const Model = require('./model');
+        if (!Model.has(collectionName)) {
+            const err = new Error(`Model '${collectionName}' is not defined. Call Model.define() first.`);
+            err.code = 'MODEL_NOT_DEFINED';
+            throw err;
+        }
+
+        // 获取 Model 定义
+        const modelDef = Model.get(collectionName);
+
+        // 获取 collection 实例
+        const collection = this.dbInstance.collection(collectionName);
+
+        // 创建 ModelInstance
+        const ModelInstanceClass = require('./model').ModelInstance;
+        return new ModelInstanceClass(collection, modelDef.definition, this);
+    }
+};
+
+// ========== 导出 Model 类 ==========
+module.exports.Model = require('./model');
+
+

package/lib/infrastructure/ssh-tunnel-ssh2.js

@@ -0,0 +1,211 @@
+/**
+ * SSH隧道管理器 - ssh2实现
+ * 支持密码认证和私钥认证
+ */
+
+const { Client } = require('ssh2');
+const net = require('net');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * 基于ssh2的SSH隧道管理器
+ * 支持密码认证和私钥认证
+ */
+class SSHTunnelSSH2 {
+    /**
+     * @param {Object} sshConfig - SSH配置
+     * @param {string} sshConfig.host - SSH服务器地址
+     * @param {number} [sshConfig.port=22] - SSH端口
+     * @param {string} sshConfig.username - SSH用户名
+     * @param {string} [sshConfig.password] - SSH密码
+     * @param {string} [sshConfig.privateKey] - 私钥内容
+     * @param {string} [sshConfig.privateKeyPath] - 私钥路径
+     * @param {string} [sshConfig.passphrase] - 私钥密码
+     * @param {number} [sshConfig.localPort] - 本地监听端口（可选，默认随机）
+     * @param {number} [sshConfig.readyTimeout=20000] - 连接超时（毫秒）
+     * @param {number} [sshConfig.keepaliveInterval=30000] - 心跳间隔（毫秒）
+     * @param {string} remoteHost - 远程主机（数据库服务器地址）
+     * @param {number} remotePort - 远程端口（数据库端口）
+     * @param {Object} options - 可选配置
+     * @param {Object} options.logger - 日志记录器
+     * @param {string} options.name - 隧道名称（用于日志）
+     */
+    constructor(sshConfig, remoteHost, remotePort, options = {}) {
+        this.sshConfig = sshConfig;
+        this.remoteHost = remoteHost;
+        this.remotePort = remotePort;
+        this.logger = options.logger;
+        this.name = options.name || `${remoteHost}:${remotePort}`;
+
+        this.sshClient = null;
+        this.server = null;
+        this.localPort = null;
+        this.isConnected = false;
+    }
+
+    /**
+     * 建立SSH隧道
+     * @returns {Promise<number>} 本地监听端口
+     */
+    async connect() {
+        if (this.isConnected) {
+            this.logger?.warn?.(`SSH tunnel [${this.name}] already connected`);
+            return this.localPort;
+        }
+
+        return new Promise((resolve, reject) => {
+            this.sshClient = new Client();
+
+            this.sshClient.on('ready', () => {
+                this.logger?.info?.(`✅ SSH connection established [${this.name}]`);
+
+                // 创建本地TCP服务器（端口转发）
+                this.server = net.createServer((sock) => {
+                    this.sshClient.forwardOut(
+                        sock.remoteAddress,
+                        sock.remotePort,
+                        this.remoteHost,
+                        this.remotePort,
+                        (err, stream) => {
+                            if (err) {
+                                this.logger?.error?.(`SSH forward error [${this.name}]`, err);
+                                return sock.end();
+                            }
+                            sock.pipe(stream).pipe(sock);
+                        }
+                    );
+                });
+
+                // 监听本地端口（0 = 随机端口）
+                const port = this.sshConfig.localPort || 0;
+                this.server.listen(port, 'localhost', () => {
+                    this.localPort = this.server.address().port;
+                    this.isConnected = true;
+
+                    this.logger?.info?.(`✅ SSH tunnel ready [${this.name}]`, {
+                        localPort: this.localPort,
+                        remote: `${this.remoteHost}:${this.remotePort}`
+                    });
+
+                    resolve(this.localPort);
+                });
+
+                this.server.on('error', (err) => {
+                    this.logger?.error?.(`Local server error [${this.name}]`, err);
+                    reject(err);
+                });
+            });
+
+            this.sshClient.on('error', (err) => {
+                this.logger?.error?.(`SSH connection error [${this.name}]`, err);
+                reject(err);
+            });
+
+            this.sshClient.on('end', () => {
+                this.logger?.info?.(`SSH connection ended [${this.name}]`);
+                this.isConnected = false;
+            });
+
+            // 构建认证配置并连接
+            try {
+                const authConfig = this._buildAuthConfig();
+                this.sshClient.connect(authConfig);
+            } catch (err) {
+                reject(err);
+            }
+        });
+    }
+
+    /**
+     * 关闭SSH隧道
+     */
+    async close() {
+        if (this.server) {
+            this.server.close();
+            this.server = null;
+        }
+
+        if (this.sshClient) {
+            this.sshClient.end();
+            this.sshClient = null;
+        }
+
+        this.isConnected = false;
+        this.localPort = null;
+
+        this.logger?.info?.(`✅ SSH tunnel closed [${this.name}]`);
+    }
+
+    /**
+     * 获取隧道连接URI
+     * @param {string} protocol - 数据库协议（mongodb/postgresql/mysql/redis）
+     * @param {string} originalUri - 原始URI
+     * @returns {string} 替换后的本地URI
+     */
+    getTunnelUri(protocol, originalUri) {
+        if (!this.isConnected) {
+            throw new Error(`SSH tunnel [${this.name}] not connected`);
+        }
+
+        // 替换主机:端口为 localhost:本地端口
+        const pattern = new RegExp(`${protocol}://([^@]*@)?([^:/]+):(\\d+)`);
+        const replacement = `${protocol}://$1localhost:${this.localPort}`;
+
+        return originalUri.replace(pattern, replacement);
+    }
+
+    /**
+     * 获取本地连接地址
+     * @returns {string} localhost:端口
+     */
+    getLocalAddress() {
+        if (!this.isConnected) {
+            throw new Error(`SSH tunnel [${this.name}] not connected`);
+        }
+        return `localhost:${this.localPort}`;
+    }
+
+    /**
+     * 构建SSH认证配置
+     * @private
+     */
+    _buildAuthConfig() {
+        const { host, port, username, password, privateKey, privateKeyPath, passphrase } = this.sshConfig;
+
+        if (!host || !username) {
+            throw new Error('SSH config requires: host, username');
+        }
+
+        const config = {
+            host,
+            port: port || 22,
+            username,
+            readyTimeout: this.sshConfig.readyTimeout || 20000,
+            keepaliveInterval: this.sshConfig.keepaliveInterval || 30000,
+        };
+
+        // 优先使用私钥认证
+        if (privateKey) {
+            config.privateKey = privateKey;
+            if (passphrase) config.passphrase = passphrase;
+        } else if (privateKeyPath) {
+            const resolvedPath = privateKeyPath.startsWith('~')
+                ? path.join(os.homedir(), privateKeyPath.slice(1))
+                : privateKeyPath;
+            config.privateKey = fs.readFileSync(resolvedPath);
+            if (passphrase) config.passphrase = passphrase;
+        } else if (password) {
+            // 密码认证
+            config.password = password;
+        } else {
+            throw new Error('SSH authentication required: privateKey, privateKeyPath, or password');
+        }
+
+        return config;
+    }
+}
+
+module.exports = { SSHTunnelSSH2 };
+

package/lib/infrastructure/ssh-tunnel.js

@@ -0,0 +1,40 @@
+/**
+ * SSH隧道管理器 - 统一入口
+ * 使用ssh2库实现，支持密码认证和私钥认证
+ */
+
+const { SSHTunnelSSH2 } = require('./ssh-tunnel-ssh2');
+
+/**
+ * SSH隧道管理器
+ * 直接使用ssh2实现
+ */
+class SSHTunnelManager {
+    /**
+     * 创建SSH隧道实例
+     * @param {Object} sshConfig - SSH配置
+     * @param {string} remoteHost - 远程主机
+     * @param {number} remotePort - 远程端口
+     * @param {Object} options - 可选配置
+     * @returns {Object} SSH隧道实例
+     */
+    static create(sshConfig, remoteHost, remotePort, options = {}) {
+        return new SSHTunnelSSH2(sshConfig, remoteHost, remotePort, options);
+    }
+
+    /**
+     * 获取当前实现信息
+     * @returns {Object}
+     */
+    static getInfo() {
+        return {
+            implementation: 'ssh2',
+            supportsPassword: true,
+            supportsPrivateKey: true,
+            dependencies: ['ssh2']
+        };
+    }
+}
+
+module.exports = { SSHTunnelManager };
+