monsqlize 1.0.0 → 1.0.2

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,58 @@ module.exports = class {
     /**
      * 导出工具函数：创建 Redis 缓存适配器
      * @static
+     * @param {import('ioredis').Redis | import('ioredis').Cluster} client - Redis客户端
+     * @param {Object} [options] - 配置选项
+     * @returns {import('./cache').CacheLike} Redis缓存适配器
      */
-    static createRedisCacheAdapter = createRedisCacheAdapter;
-}
+    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;
+    }
+};

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 };
+

package/lib/infrastructure/uri-parser.js

@@ -0,0 +1,35 @@
+/**
+ * 通用URI解析器
+ * 支持：mongodb://、postgresql://、mysql://、redis://
+ */
+
+/**
+ * 解析数据库连接URI
+ * @param {string} uri - 数据库连接URI
+ * @returns {{protocol: string, auth: string|null, host: string, port: number}} 解析结果
+ */
+function parseUri(uri) {
+    const patterns = {
+        mongodb: /mongodb:\/\/([^@]*@)?([^:/]+):(\d+)/,
+        postgresql: /postgresql:\/\/([^@]*@)?([^:/]+):(\d+)/,
+        mysql: /mysql:\/\/([^@]*@)?([^:/]+):(\d+)/,
+        redis: /redis:\/\/([^@]*@)?([^:/]+):(\d+)/
+    };
+
+    for (const [protocol, pattern] of Object.entries(patterns)) {
+        const match = uri.match(pattern);
+        if (match) {
+            return {
+                protocol,
+                auth: match[1] ? match[1].slice(0, -1) : null,  // 去掉末尾的@
+                host: match[2],
+                port: parseInt(match[3], 10)
+            };
+        }
+    }
+
+    throw new Error(`Unsupported URI format: ${uri}`);
+}
+
+module.exports = { parseUri };
+

package/lib/lock/Lock.js

@@ -0,0 +1,66 @@
+/**
+ * 业务锁对象
+ * 表示一个已获取的锁，提供释放和续期方法
+ */
+class Lock {
+    /**
+     * @param {string} key - 锁的标识
+     * @param {string} lockId - 锁的唯一ID
+     * @param {Object} manager - 锁管理器实例
+     * @param {number} ttl - 锁的过期时间（毫秒）
+     */
+    constructor(key, lockId, manager, ttl) {
+        this.key = key;
+        this.lockId = lockId;
+        this.manager = manager;
+        this.ttl = ttl;
+        this.released = false;
+        this.acquiredAt = Date.now();
+    }
+
+    /**
+     * 释放锁
+     * @returns {Promise<boolean>}
+     */
+    async release() {
+        if (this.released) {
+            return false;
+        }
+
+        const result = await this.manager.releaseLock(this.key, this.lockId);
+        this.released = true;
+        return result;
+    }
+
+    /**
+     * 续期（延长锁的过期时间）
+     * @param {number} [ttl] - 新的过期时间，默认使用原TTL
+     * @returns {Promise<boolean>}
+     */
+    async renew(ttl) {
+        if (this.released) {
+            return false;
+        }
+
+        return this.manager.renewLock(this.key, this.lockId, ttl || this.ttl);
+    }
+
+    /**
+     * 检查锁是否仍被持有
+     * @returns {boolean}
+     */
+    isHeld() {
+        return !this.released;
+    }
+
+    /**
+     * 获取锁持有时间
+     * @returns {number} 毫秒
+     */
+    getHoldTime() {
+        return Date.now() - this.acquiredAt;
+    }
+}
+
+module.exports = Lock;
+

package/lib/lock/errors.js

@@ -0,0 +1,27 @@
+/**
+ * 锁获取失败错误
+ */
+class LockAcquireError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LockAcquireError';
+        this.code = 'LOCK_ACQUIRE_FAILED';
+    }
+}
+
+/**
+ * 锁超时错误
+ */
+class LockTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LockTimeoutError';
+        this.code = 'LOCK_TIMEOUT';
+    }
+}
+
+module.exports = {
+    LockAcquireError,
+    LockTimeoutError
+};
+

package/lib/lock/index.js

@@ -0,0 +1,12 @@
+/**
+ * 业务锁模块导出
+ */
+const Lock = require('./Lock');
+const { LockAcquireError, LockTimeoutError } = require('./errors');
+
+module.exports = {
+    Lock,
+    LockAcquireError,
+    LockTimeoutError
+};
+

package/lib/logger.js

@@ -220,5 +220,5 @@ module.exports = class Logger {
     static generateTraceId() {
         return generateTraceId();
     }
-}
+};
 

package/lib/model/examples/test.js

@@ -15,7 +15,7 @@ module.exports = {
             password: sc.string().pattern(/^[a-zA-Z0-9]{6,30}$/).required(),
             age: sc.number().integer().min(0).default(18),   // 默认值
             role: sc.string().valid('admin', 'user').default('user'),
-        }
+        };
     },
 
     // 自定义方法
@@ -36,7 +36,7 @@ module.exports = {
                     return this.find({ username: name });
                 }
             }
-        }
+        };
     },
 
     // 支持操作前、后处理
@@ -63,7 +63,7 @@ module.exports = {
                 before:(ctx,options)=>{},
                 after:(ctx,result)=>{},
             }
-        }
+        };
     },
 
     // 创建索引
@@ -111,4 +111,4 @@ module.exports = {
 
     // 自动索引 / 慢查询统计 → 全局 ORM 层统一管理
     // 恢复软删除 → 全局方法注入到每个启用 softDelete 的模型
-}
+};

package/lib/mongodb/common/accessor-helpers.js

@@ -8,6 +8,7 @@ const crypto = require('crypto');
 const CacheFactory = require('../../cache');
 const { buildCommonLogExtra } = require('../../common/shape-builders');
 const { shapeQuery, shapeProjection, shapeSort } = require('./shape');
+const { normalizeForCache } = require('../../utils/objectid-converter');
 
 /**
  * Mongo 专属：慢日志去敏形状构造器
@@ -26,18 +27,31 @@ function mongoSlowLogShaper(options) {
  * Mongo 专属：缓存键构造器
  * 仅在 findPage 时：对 pipeline 做稳定串行化并 sha256 → pipelineHash；
  * 同时从参与键的 options 中去除原始 pipeline，避免键过长与不稳定。
+ *
+ * ✅ v1.3.0 新增：标准化 ObjectId
+ * - 将所有 ObjectId 实例转换为字符串
+ * - 确保 ObjectId('xxx') 和 'xxx' 生成相同的缓存键
+ * - 避免缓存失效和重复查询
+ *
  * @param {string} op
  * @param {object} options
  * @returns {object} 用于参与缓存键构造的 options 视图
  */
 function mongoKeyBuilder(op, options) {
     const opts = options || {};
-    if (op !== 'findPage') return opts;
+
+    // ✅ 标准化 options 中的 ObjectId（转为字符串）
+    // 确保查询缓存键一致性
+    const normalizedOpts = normalizeForCache(opts);
+
+    if (op !== 'findPage') return normalizedOpts;
+
+    // findPage 特殊处理：pipeline 转 hash
     const pipelineHash = crypto
         .createHash('sha256')
-        .update(CacheFactory.stableStringify(opts.pipeline || []))
+        .update(CacheFactory.stableStringify(normalizedOpts.pipeline || []))
         .digest('hex');
-    const { pipeline, ...rest } = opts;
+    const { pipeline, ...rest } = normalizedOpts;
     return { ...rest, pipelineHash };
 }