@onebots/core 0.5.0 → 1.0.4

package/lib/circuit-breaker.js

@@ -0,0 +1,206 @@
+/**
+ * 熔断器模式实现
+ * 防止级联故障，提高系统稳定性
+ */
+import { createLogger } from './logger.js';
+const logger = createLogger('CircuitBreaker');
+export var CircuitState;
+(function (CircuitState) {
+    /** 关闭状态：正常处理请求 */
+    CircuitState["CLOSED"] = "CLOSED";
+    /** 开启状态：拒绝所有请求 */
+    CircuitState["OPEN"] = "OPEN";
+    /** 半开状态：尝试恢复，允许部分请求通过 */
+    CircuitState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitState || (CircuitState = {}));
+const DEFAULT_OPTIONS = {
+    failureThreshold: 5,
+    successThreshold: 2,
+    timeout: 60000, // 1 分钟
+    monitoringPeriod: 60000, // 1 分钟
+    minimumRequests: 10,
+    errorRateThreshold: 0.5, // 50%
+};
+/**
+ * 熔断器类
+ */
+export class CircuitBreaker {
+    state = CircuitState.CLOSED;
+    failureCount = 0;
+    successCount = 0;
+    lastFailureTime = null;
+    records = [];
+    options;
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * 执行函数，带熔断保护
+     */
+    async execute(fn) {
+        // 检查状态
+        if (this.state === CircuitState.OPEN) {
+            // 检查是否可以进入半开状态
+            if (this.lastFailureTime && Date.now() - this.lastFailureTime >= this.options.timeout) {
+                this.state = CircuitState.HALF_OPEN;
+                this.successCount = 0;
+                logger.info('Circuit breaker entering HALF_OPEN state');
+            }
+            else {
+                throw new CircuitBreakerOpenError('Circuit breaker is OPEN');
+            }
+        }
+        // 执行函数
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * 成功回调
+     */
+    onSuccess() {
+        const now = Date.now();
+        this.records.push({ timestamp: now, success: true });
+        this.cleanupOldRecords(now);
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.successCount++;
+            if (this.successCount >= this.options.successThreshold) {
+                this.state = CircuitState.CLOSED;
+                this.failureCount = 0;
+                this.successCount = 0;
+                logger.info('Circuit breaker CLOSED: recovery successful');
+            }
+        }
+        else if (this.state === CircuitState.CLOSED) {
+            // 重置失败计数
+            this.failureCount = 0;
+        }
+    }
+    /**
+     * 失败回调
+     */
+    onFailure() {
+        const now = Date.now();
+        this.records.push({ timestamp: now, success: false });
+        this.cleanupOldRecords(now);
+        if (this.state === CircuitState.HALF_OPEN) {
+            // 半开状态下失败，立即开启
+            this.state = CircuitState.OPEN;
+            this.lastFailureTime = now;
+            this.successCount = 0;
+            logger.warn('Circuit breaker OPEN: failed in HALF_OPEN state');
+        }
+        else if (this.state === CircuitState.CLOSED) {
+            this.failureCount++;
+            this.lastFailureTime = now;
+            // 检查是否应该开启熔断
+            const shouldOpen = this.shouldOpen(now);
+            if (shouldOpen) {
+                this.state = CircuitState.OPEN;
+                logger.warn('Circuit breaker OPEN: threshold exceeded', {
+                    failureCount: this.failureCount,
+                    errorRate: this.getErrorRate(now),
+                });
+            }
+        }
+    }
+    /**
+     * 判断是否应该开启熔断
+     */
+    shouldOpen(now) {
+        // 检查连续失败次数
+        if (this.failureCount >= this.options.failureThreshold) {
+            return true;
+        }
+        // 检查错误率
+        const errorRate = this.getErrorRate(now);
+        if (errorRate >= this.options.errorRateThreshold) {
+            const recentRequests = this.getRecentRequests(now);
+            if (recentRequests.length >= this.options.minimumRequests) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * 获取错误率
+     */
+    getErrorRate(now) {
+        const recentRequests = this.getRecentRequests(now);
+        if (recentRequests.length === 0) {
+            return 0;
+        }
+        const failures = recentRequests.filter(r => !r.success).length;
+        return failures / recentRequests.length;
+    }
+    /**
+     * 获取最近的请求记录
+     */
+    getRecentRequests(now) {
+        const cutoff = now - this.options.monitoringPeriod;
+        return this.records.filter(r => r.timestamp >= cutoff);
+    }
+    /**
+     * 清理过期记录
+     */
+    cleanupOldRecords(now) {
+        const cutoff = now - this.options.monitoringPeriod * 2;
+        this.records = this.records.filter(r => r.timestamp >= cutoff);
+    }
+    /**
+     * 获取当前状态
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * 获取统计信息
+     */
+    getStats() {
+        const now = Date.now();
+        const recentRequests = this.getRecentRequests(now);
+        const failures = recentRequests.filter(r => !r.success).length;
+        const errorRate = recentRequests.length > 0 ? failures / recentRequests.length : 0;
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            successCount: this.successCount,
+            errorRate,
+            totalRequests: recentRequests.length,
+        };
+    }
+    /**
+     * 手动重置熔断器
+     */
+    reset() {
+        this.state = CircuitState.CLOSED;
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.lastFailureTime = null;
+        this.records = [];
+        logger.info('Circuit breaker manually reset');
+    }
+}
+/**
+ * 熔断器开启错误
+ */
+export class CircuitBreakerOpenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircuitBreakerOpenError';
+    }
+}
+/**
+ * 创建带熔断器的函数包装器
+ */
+export function withCircuitBreaker(fn, breaker) {
+    return ((...args) => {
+        return breaker.execute(() => fn(...args));
+    });
+}

package/lib/config-validator.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 配置验证系统
+ * 提供配置schema验证和默认值处理
+ */
+import { ValidationError } from './errors.js';
+export { ValidationError };
+export interface ValidationRule<T = any> {
+    required?: boolean;
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+    enum?: any[];
+    validator?: (value: T) => boolean | string;
+    default?: T | (() => T);
+    transform?: (value: any) => T;
+    /** 用于表单展示的标签 */
+    label?: string;
+    /** 用于表单展示的说明 */
+    description?: string;
+    /** 用于表单展示的占位提示 */
+    placeholder?: string;
+}
+export interface Schema {
+    [key: string]: ValidationRule | Schema;
+}
+/**
+ * 配置验证器
+ */
+export declare class ConfigValidator {
+    /**
+     * 验证配置对象
+     */
+    static validate<T extends Record<string, any>>(config: T, schema: Schema, path?: string): T;
+    /**
+     * 检查类型
+     */
+    private static checkType;
+    /**
+     * 判断是否为嵌套schema
+     */
+    private static isSchema;
+    /**
+     * 验证并应用默认值
+     */
+    static validateWithDefaults<T extends Record<string, any>>(config: Partial<T>, schema: Schema): T;
+}
+/**
+ * BaseApp 配置 Schema
+ */
+export declare const BaseAppConfigSchema: Schema;

package/lib/config-validator.js

@@ -0,0 +1,184 @@
+/**
+ * 配置验证系统
+ * 提供配置schema验证和默认值处理
+ */
+import { ValidationError } from './errors.js';
+export { ValidationError };
+/**
+ * 配置验证器
+ */
+export class ConfigValidator {
+    /**
+     * 验证配置对象
+     */
+    static validate(config, schema, path = '') {
+        const result = { ...config };
+        const errors = [];
+        for (const [key, rule] of Object.entries(schema)) {
+            const currentPath = path ? `${path}.${key}` : key;
+            const value = config[key];
+            // 如果是嵌套schema，递归验证
+            if (this.isSchema(rule)) {
+                if (value !== undefined) {
+                    result[key] = this.validate(value || {}, rule, currentPath);
+                }
+                continue;
+            }
+            const validationRule = rule;
+            // 检查必填字段
+            if (validationRule.required && (value === undefined || value === null)) {
+                if (validationRule.default !== undefined) {
+                    result[key] = typeof validationRule.default === 'function'
+                        ? validationRule.default()
+                        : validationRule.default;
+                    continue;
+                }
+                errors.push(`${currentPath} is required`);
+                continue;
+            }
+            // 如果值为undefined且有默认值，使用默认值
+            if (value === undefined && validationRule.default !== undefined) {
+                result[key] = typeof validationRule.default === 'function'
+                    ? validationRule.default()
+                    : validationRule.default;
+                continue;
+            }
+            // 如果值为undefined，跳过验证
+            if (value === undefined) {
+                continue;
+            }
+            // 类型转换
+            if (validationRule.transform) {
+                try {
+                    result[key] = validationRule.transform(value);
+                }
+                catch (error) {
+                    errors.push(`${currentPath} transform failed: ${error.message}`);
+                    continue;
+                }
+            }
+            const finalValue = result[key];
+            // transform 可能将空字符串等转为 undefined，视为可选字段未填，跳过后续类型与范围检查
+            if (finalValue === undefined) {
+                continue;
+            }
+            // 类型检查
+            if (validationRule.type) {
+                const typeError = this.checkType(finalValue, validationRule.type, currentPath);
+                if (typeError) {
+                    errors.push(typeError);
+                    continue;
+                }
+            }
+            // 数值范围检查
+            if (validationRule.type === 'number') {
+                if (validationRule.min !== undefined && finalValue < validationRule.min) {
+                    errors.push(`${currentPath} must be >= ${validationRule.min}`);
+                }
+                if (validationRule.max !== undefined && finalValue > validationRule.max) {
+                    errors.push(`${currentPath} must be <= ${validationRule.max}`);
+                }
+            }
+            // 字符串长度检查
+            if (validationRule.type === 'string') {
+                if (validationRule.min !== undefined && finalValue.length < validationRule.min) {
+                    errors.push(`${currentPath} length must be >= ${validationRule.min}`);
+                }
+                if (validationRule.max !== undefined && finalValue.length > validationRule.max) {
+                    errors.push(`${currentPath} length must be <= ${validationRule.max}`);
+                }
+                if (validationRule.pattern && !validationRule.pattern.test(finalValue)) {
+                    errors.push(`${currentPath} does not match pattern ${validationRule.pattern}`);
+                }
+            }
+            // 枚举检查
+            if (validationRule.enum && !validationRule.enum.includes(finalValue)) {
+                errors.push(`${currentPath} must be one of: ${validationRule.enum.join(', ')}`);
+            }
+            // 自定义验证器
+            if (validationRule.validator) {
+                const validationResult = validationRule.validator(finalValue);
+                if (validationResult !== true) {
+                    errors.push(`${currentPath}: ${validationResult || 'validation failed'}`);
+                }
+            }
+        }
+        if (errors.length > 0) {
+            throw new ValidationError('Configuration validation failed', {
+                context: {
+                    errors,
+                    path,
+                },
+            });
+        }
+        return result;
+    }
+    /**
+     * 检查类型
+     */
+    static checkType(value, expectedType, path) {
+        const actualType = Array.isArray(value) ? 'array' : typeof value;
+        if (actualType !== expectedType) {
+            return `${path} must be ${expectedType}, got ${actualType}`;
+        }
+        return null;
+    }
+    /**
+     * 判断是否为嵌套schema
+     */
+    static isSchema(rule) {
+        return !('required' in rule) && !('type' in rule) && typeof rule === 'object';
+    }
+    /**
+     * 验证并应用默认值
+     */
+    static validateWithDefaults(config, schema) {
+        return this.validate(config, schema);
+    }
+}
+/**
+ * BaseApp 配置 Schema
+ */
+export const BaseAppConfigSchema = {
+    port: {
+        type: 'number',
+        min: 1,
+        max: 65535,
+        default: 6727,
+    },
+    path: {
+        type: 'string',
+        default: '',
+    },
+    database: {
+        type: 'string',
+        default: 'onebots.db',
+    },
+    timeout: {
+        type: 'number',
+        min: 1,
+        default: 30,
+    },
+    username: {
+        type: 'string',
+        transform: (v) => (v != null && String(v).trim() !== '' ? String(v) : undefined),
+    },
+    password: {
+        type: 'string',
+        transform: (v) => (v != null && String(v).trim() !== '' ? String(v) : undefined),
+    },
+    access_token: {
+        type: 'string',
+        transform: (v) => (v != null && String(v).trim() !== '' ? String(v) : undefined),
+    },
+    log_level: {
+        type: 'string',
+        enum: ['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'mark', 'off'],
+        default: 'info',
+    },
+    /** 站点根静态文件目录（相对 BaseApp.configDir 或绝对路径），用于可信域名校验文件等 */
+    public_static_dir: {
+        type: 'string',
+        transform: (v) => (v != null && String(v).trim() !== '' ? String(v).trim() : undefined),
+    },
+};

package/lib/connection-pool.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 连接池和资源管理
+ * 管理 HTTP 连接、WebSocket 连接等资源
+ */
+import { EventEmitter } from 'events';
+export interface PoolConfig {
+    /** 最大连接数 */
+    maxConnections?: number;
+    /** 最小连接数 */
+    minConnections?: number;
+    /** 连接超时时间（毫秒） */
+    timeout?: number;
+    /** 空闲连接超时时间（毫秒） */
+    idleTimeout?: number;
+    /** 连接创建函数 */
+    create: () => Promise<any>;
+    /** 连接销毁函数 */
+    destroy: (connection: any) => Promise<void>;
+    /** 连接验证函数 */
+    validate?: (connection: any) => boolean | Promise<boolean>;
+}
+/**
+ * 连接池类
+ */
+export declare class ConnectionPool extends EventEmitter {
+    private pool;
+    private waiting;
+    private config;
+    private cleanupInterval?;
+    constructor(config: PoolConfig);
+    /**
+     * 获取连接
+     */
+    acquire(): Promise<any>;
+    /**
+     * 释放连接
+     */
+    release(connection: any): Promise<void>;
+    /**
+     * 销毁连接
+     */
+    destroy(connection: any): Promise<void>;
+    /**
+     * 启动清理任务
+     */
+    private startCleanup;
+    /**
+     * 清理空闲连接
+     */
+    private cleanup;
+    /**
+     * 获取池状态
+     */
+    getStatus(): {
+        total: number;
+        inUse: number;
+        idle: number;
+        waiting: number;
+    };
+    /**
+     * 清空连接池
+     */
+    clear(): Promise<void>;
+    /**
+     * 关闭连接池
+     */
+    close(): Promise<void>;
+}

package/lib/connection-pool.js

@@ -0,0 +1,202 @@
+/**
+ * 连接池和资源管理
+ * 管理 HTTP 连接、WebSocket 连接等资源
+ */
+import { createLogger } from './logger.js';
+import { EventEmitter } from 'events';
+const logger = createLogger('ConnectionPool');
+/**
+ * 连接池类
+ */
+export class ConnectionPool extends EventEmitter {
+    pool = [];
+    waiting = [];
+    config;
+    cleanupInterval;
+    constructor(config) {
+        super();
+        this.config = {
+            maxConnections: config.maxConnections || 10,
+            minConnections: config.minConnections || 0,
+            timeout: config.timeout || 30000,
+            idleTimeout: config.idleTimeout || 60000,
+            create: config.create,
+            destroy: config.destroy,
+            validate: config.validate || (() => true),
+        };
+        // 启动清理任务
+        this.startCleanup();
+    }
+    /**
+     * 获取连接
+     */
+    async acquire() {
+        // 尝试从池中获取可用连接
+        const available = this.pool.find(c => !c.inUse);
+        if (available) {
+            // 验证连接
+            const isValid = await this.config.validate(available.connection);
+            if (isValid) {
+                available.inUse = true;
+                available.lastUsedAt = Date.now();
+                return available.connection;
+            }
+            else {
+                // 连接无效，移除它
+                this.pool = this.pool.filter(c => c !== available);
+                await this.config.destroy(available.connection);
+            }
+        }
+        // 检查是否可以创建新连接
+        if (this.pool.length < this.config.maxConnections) {
+            try {
+                const connection = await this.config.create();
+                const pooled = {
+                    connection,
+                    createdAt: Date.now(),
+                    lastUsedAt: Date.now(),
+                    inUse: true,
+                };
+                this.pool.push(pooled);
+                this.emit('connection:created', connection);
+                return connection;
+            }
+            catch (error) {
+                logger.error('Failed to create connection', { error });
+                throw error;
+            }
+        }
+        // 等待可用连接
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                const index = this.waiting.findIndex(w => w.reject === reject);
+                if (index !== -1) {
+                    this.waiting.splice(index, 1);
+                }
+                reject(new Error('Connection acquisition timeout'));
+            }, this.config.timeout);
+            this.waiting.push({
+                resolve: (connection) => {
+                    clearTimeout(timeout);
+                    resolve(connection);
+                },
+                reject: (error) => {
+                    clearTimeout(timeout);
+                    reject(error);
+                },
+            });
+        });
+    }
+    /**
+     * 释放连接
+     */
+    async release(connection) {
+        const pooled = this.pool.find(c => c.connection === connection);
+        if (!pooled) {
+            logger.warn('Attempted to release connection not in pool');
+            return;
+        }
+        if (!pooled.inUse) {
+            logger.warn('Attempted to release connection that is not in use');
+            return;
+        }
+        pooled.inUse = false;
+        pooled.lastUsedAt = Date.now();
+        // 检查是否有等待的请求
+        if (this.waiting.length > 0) {
+            const waiter = this.waiting.shift();
+            waiter.resolve(connection);
+            pooled.inUse = true;
+            pooled.lastUsedAt = Date.now();
+        }
+    }
+    /**
+     * 销毁连接
+     */
+    async destroy(connection) {
+        const pooled = this.pool.find(c => c.connection === connection);
+        if (!pooled) {
+            return;
+        }
+        this.pool = this.pool.filter(c => c !== connection);
+        try {
+            await this.config.destroy(connection);
+            this.emit('connection:destroyed', connection);
+        }
+        catch (error) {
+            logger.error('Failed to destroy connection', { error });
+        }
+    }
+    /**
+     * 启动清理任务
+     */
+    startCleanup() {
+        this.cleanupInterval = setInterval(() => {
+            this.cleanup();
+        }, 60000); // 每分钟清理一次
+    }
+    /**
+     * 清理空闲连接
+     */
+    async cleanup() {
+        const now = Date.now();
+        const toRemove = [];
+        for (const pooled of this.pool) {
+            if (!pooled.inUse) {
+                const idleTime = now - pooled.lastUsedAt;
+                if (idleTime > this.config.idleTimeout) {
+                    // 检查是否超过最小连接数
+                    if (this.pool.length > this.config.minConnections) {
+                        toRemove.push(pooled);
+                    }
+                }
+            }
+        }
+        // 移除过期连接
+        for (const pooled of toRemove) {
+            await this.destroy(pooled.connection);
+        }
+        if (toRemove.length > 0) {
+            logger.debug(`Cleaned up ${toRemove.length} idle connections`);
+        }
+    }
+    /**
+     * 获取池状态
+     */
+    getStatus() {
+        return {
+            total: this.pool.length,
+            inUse: this.pool.filter(c => c.inUse).length,
+            idle: this.pool.filter(c => !c.inUse).length,
+            waiting: this.waiting.length,
+        };
+    }
+    /**
+     * 清空连接池
+     */
+    async clear() {
+        // 取消所有等待的请求
+        for (const waiter of this.waiting) {
+            waiter.reject(new Error('Pool cleared'));
+        }
+        this.waiting = [];
+        // 销毁所有连接
+        const connections = [...this.pool];
+        for (const pooled of connections) {
+            await this.destroy(pooled.connection);
+        }
+        this.pool = [];
+        logger.info('Connection pool cleared');
+    }
+    /**
+     * 关闭连接池
+     */
+    async close() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = undefined;
+        }
+        await this.clear();
+        this.emit('close');
+    }
+}