@onebots/core 0.5.0 → 1.0.4

package/lib/lifecycle.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 生命周期管理
+ * 提供资源管理和优雅关闭机制
+ */
+import { EventEmitter } from 'events';
+import type { Dispose } from './types.js';
+export interface LifecycleHook {
+    /** 初始化钩子 */
+    onInit?(): void | Promise<void>;
+    /** 启动钩子 */
+    onStart?(): void | Promise<void>;
+    /** 停止钩子 */
+    onStop?(): void | Promise<void>;
+    /** 清理钩子 */
+    onCleanup?(): void | Promise<void>;
+}
+/**
+ * 生命周期管理器
+ */
+export declare class LifecycleManager extends EventEmitter {
+    private resources;
+    private hooks;
+    private isShuttingDown;
+    private shutdownTimeout;
+    /**
+     * 注册资源
+     */
+    register(name: string, dispose: Dispose): void;
+    /**
+     * 注销资源
+     */
+    unregister(name: string): boolean;
+    /**
+     * 注册生命周期钩子
+     */
+    addHook(hook: LifecycleHook): void;
+    /**
+     * 移除生命周期钩子
+     */
+    removeHook(hook: LifecycleHook): void;
+    /**
+     * 初始化所有钩子
+     */
+    init(): Promise<void>;
+    /**
+     * 启动所有钩子
+     */
+    start(): Promise<void>;
+    /**
+     * 停止所有钩子
+     */
+    stop(): Promise<void>;
+    /**
+     * 清理所有资源
+     */
+    cleanup(): Promise<void>;
+    /**
+     * 优雅关闭
+     */
+    gracefulShutdown(signal?: string, options?: {
+        exitOnTimeout?: boolean;
+    }): Promise<void>;
+    /**
+     * 设置关闭超时时间
+     */
+    setShutdownTimeout(timeout: number): void;
+    /**
+     * 获取资源数量
+     */
+    getResourceCount(): number;
+    /**
+     * 获取所有资源名称
+     */
+    getResourceNames(): string[];
+}

package/lib/lifecycle.js

@@ -0,0 +1,175 @@
+/**
+ * 生命周期管理
+ * 提供资源管理和优雅关闭机制
+ */
+import { EventEmitter } from 'events';
+import { ResourceError } from './errors.js';
+/**
+ * 生命周期管理器
+ */
+export class LifecycleManager extends EventEmitter {
+    resources = new Map();
+    hooks = [];
+    isShuttingDown = false;
+    shutdownTimeout = 30000; // 30秒超时
+    /**
+     * 注册资源
+     */
+    register(name, dispose) {
+        if (this.resources.has(name)) {
+            throw new ResourceError(`Resource ${name} already registered`);
+        }
+        this.resources.set(name, dispose);
+    }
+    /**
+     * 注销资源
+     */
+    unregister(name) {
+        return this.resources.delete(name);
+    }
+    /**
+     * 注册生命周期钩子
+     */
+    addHook(hook) {
+        this.hooks.push(hook);
+    }
+    /**
+     * 移除生命周期钩子
+     */
+    removeHook(hook) {
+        const index = this.hooks.indexOf(hook);
+        if (index !== -1) {
+            this.hooks.splice(index, 1);
+        }
+    }
+    /**
+     * 初始化所有钩子
+     */
+    async init() {
+        this.emit('beforeInit');
+        for (const hook of this.hooks) {
+            if (hook.onInit) {
+                await hook.onInit();
+            }
+        }
+        this.emit('afterInit');
+    }
+    /**
+     * 启动所有钩子
+     */
+    async start() {
+        this.emit('beforeStart');
+        for (const hook of this.hooks) {
+            if (hook.onStart) {
+                await hook.onStart();
+            }
+        }
+        this.emit('afterStart');
+    }
+    /**
+     * 停止所有钩子
+     */
+    async stop() {
+        this.emit('beforeStop');
+        for (const hook of this.hooks) {
+            if (hook.onStop) {
+                await hook.onStop();
+            }
+        }
+        this.emit('afterStop');
+    }
+    /**
+     * 清理所有资源
+     */
+    async cleanup() {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.isShuttingDown = true;
+        this.emit('beforeCleanup');
+        // 执行清理钩子
+        for (const hook of this.hooks) {
+            if (hook.onCleanup) {
+                try {
+                    await hook.onCleanup();
+                }
+                catch (error) {
+                    this.emit('cleanupError', { hook: 'onCleanup', error });
+                    // 继续执行，不抛出错误
+                }
+            }
+        }
+        // 清理所有资源
+        const cleanupPromises = [];
+        for (const [name, dispose] of this.resources.entries()) {
+            cleanupPromises.push((async () => {
+                try {
+                    const result = dispose();
+                    if (result instanceof Promise) {
+                        await result;
+                    }
+                }
+                catch (error) {
+                    this.emit('cleanupError', { name, error });
+                    // 继续执行，不抛出错误
+                }
+            })());
+        }
+        await Promise.all(cleanupPromises);
+        this.resources.clear();
+        this.hooks = [];
+        this.emit('afterCleanup');
+    }
+    /**
+     * 优雅关闭
+     */
+    async gracefulShutdown(signal, options) {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.emit('shutdown', signal);
+        // 设置超时
+        let timeout = null;
+        if (this.shutdownTimeout > 0) {
+            timeout = setTimeout(() => {
+                this.emit('shutdownTimeout');
+                if (options?.exitOnTimeout !== false) {
+                    process.exit(1);
+                }
+            }, this.shutdownTimeout);
+        }
+        try {
+            await this.stop();
+            await this.cleanup();
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            this.emit('shutdownComplete');
+        }
+        catch (error) {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            this.emit('shutdownError', error);
+            throw error;
+        }
+    }
+    /**
+     * 设置关闭超时时间
+     */
+    setShutdownTimeout(timeout) {
+        this.shutdownTimeout = timeout;
+    }
+    /**
+     * 获取资源数量
+     */
+    getResourceCount() {
+        return this.resources.size;
+    }
+    /**
+     * 获取所有资源名称
+     */
+    getResourceNames() {
+        return Array.from(this.resources.keys());
+    }
+}

package/lib/logger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 增强的日志系统
+ * 提供结构化日志、错误追踪和上下文信息
+ */
+import { OneBotsError } from './errors.js';
+import type { LogLevel } from './types.js';
+export interface LogContext {
+    [key: string]: any;
+}
+export interface LogEntry {
+    level: string;
+    message: string;
+    context?: LogContext;
+    error?: OneBotsError;
+    timestamp: Date;
+}
+/**
+ * 增强的 Logger 类
+ */
+export declare class Logger {
+    private logger;
+    private context;
+    constructor(name: string, level?: LogLevel);
+    /**
+     * 设置日志级别
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * 添加上下文信息
+     */
+    withContext(context: LogContext): Logger;
+    /**
+     * Trace 级别日志
+     */
+    trace(message: string, context?: LogContext): void;
+    /**
+     * Debug 级别日志
+     */
+    debug(message: string, context?: LogContext): void;
+    /**
+     * Info 级别日志
+     */
+    info(message: string, context?: LogContext): void;
+    /**
+     * Warn 级别日志
+     */
+    warn(message: string, context?: LogContext): void;
+    /**
+     * Error 级别日志
+     */
+    error(message: string | Error | OneBotsError, context?: LogContext): void;
+    /**
+     * Fatal 级别日志
+     */
+    fatal(message: string | Error | OneBotsError, context?: LogContext): void;
+    /**
+     * Mark 级别日志
+     */
+    mark(message: string, context?: LogContext): void;
+    /**
+     * 记录性能指标
+     */
+    performance(operation: string, duration: number, context?: LogContext): void;
+    /**
+     * 记录操作开始
+     */
+    start(operation: string, context?: LogContext): () => void;
+    /**
+     * 内部日志方法
+     */
+    private log;
+}
+/**
+ * 创建 Logger 实例
+ */
+export declare function createLogger(name: string, level?: LogLevel): Logger;

package/lib/logger.js

@@ -0,0 +1,156 @@
+/**
+ * 增强的日志系统
+ * 提供结构化日志、错误追踪和上下文信息
+ */
+import log4js from 'log4js';
+import { ErrorHandler } from './errors.js';
+const { getLogger } = log4js;
+/**
+ * 增强的 Logger 类
+ */
+export class Logger {
+    logger;
+    context = {};
+    constructor(name, level) {
+        this.logger = getLogger(name);
+        if (level) {
+            this.logger.level = level;
+        }
+    }
+    /**
+     * 设置日志级别
+     */
+    setLevel(level) {
+        this.logger.level = level;
+    }
+    /**
+     * 添加上下文信息
+     */
+    withContext(context) {
+        const newLogger = new Logger(this.logger.category, this.logger.level);
+        newLogger.context = { ...this.context, ...context };
+        return newLogger;
+    }
+    /**
+     * Trace 级别日志
+     */
+    trace(message, context) {
+        this.log('trace', message, context);
+    }
+    /**
+     * Debug 级别日志
+     */
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    /**
+     * Info 级别日志
+     */
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    /**
+     * Warn 级别日志
+     */
+    warn(message, context) {
+        this.log('warn', message, context);
+    }
+    /**
+     * Error 级别日志
+     */
+    error(message, context) {
+        if (typeof message === 'object' && message !== null) {
+            if (message instanceof Error || message.category !== undefined) {
+                const error = ErrorHandler.wrap(message, context);
+                this.log('error', error.message, {
+                    ...context,
+                    error: error.toJSON(),
+                });
+                return;
+            }
+        }
+        this.log('error', message, context);
+    }
+    /**
+     * Fatal 级别日志
+     */
+    fatal(message, context) {
+        if (typeof message === 'object' && message !== null) {
+            if (message instanceof Error || message.category !== undefined) {
+                const error = ErrorHandler.wrap(message, context);
+                this.log('fatal', error.message, {
+                    ...context,
+                    error: error.toJSON(),
+                });
+                return;
+            }
+        }
+        this.log('fatal', message, context);
+    }
+    /**
+     * Mark 级别日志
+     */
+    mark(message, context) {
+        this.log('mark', message, context);
+    }
+    /**
+     * 记录性能指标
+     */
+    performance(operation, duration, context) {
+        this.info(`Performance: ${operation} took ${duration}ms`, {
+            ...context,
+            operation,
+            duration,
+            type: 'performance',
+        });
+    }
+    /**
+     * 记录操作开始
+     */
+    start(operation, context) {
+        const startTime = Date.now();
+        this.debug(`Starting: ${operation}`, context);
+        return () => {
+            const duration = Date.now() - startTime;
+            this.performance(operation, duration, context);
+        };
+    }
+    /**
+     * 内部日志方法
+     */
+    log(level, message, context) {
+        const mergedContext = { ...this.context, ...context };
+        const logMessage = mergedContext && Object.keys(mergedContext).length > 0
+            ? `${message} ${JSON.stringify(mergedContext)}`
+            : message;
+        switch (level) {
+            case 'trace':
+                this.logger.trace(logMessage);
+                break;
+            case 'debug':
+                this.logger.debug(logMessage);
+                break;
+            case 'info':
+                this.logger.info(logMessage);
+                break;
+            case 'warn':
+                this.logger.warn(logMessage);
+                break;
+            case 'error':
+                this.logger.error(logMessage);
+                break;
+            case 'fatal':
+                this.logger.fatal(logMessage);
+                break;
+            case 'mark':
+                this.logger.mark(logMessage);
+                break;
+        }
+    }
+}
+/**
+ * 创建 Logger 实例
+ */
+export function createLogger(name, level) {
+    return new Logger(name, level);
+}

package/lib/metrics.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 性能指标收集系统
+ * 收集请求数、响应时间、错误率等指标
+ */
+export interface MetricValue {
+    value: number;
+    timestamp: number;
+    labels?: Record<string, string>;
+}
+export interface Metric {
+    name: string;
+    type: 'counter' | 'gauge' | 'histogram';
+    help: string;
+    values: MetricValue[];
+    labels?: Record<string, string>;
+}
+/**
+ * 指标收集器
+ */
+export declare class MetricsCollector {
+    private metrics;
+    private readonly maxSamples;
+    /**
+     * 增加计数器
+     */
+    increment(name: string, value?: number, labels?: Record<string, string>): void;
+    /**
+     * 设置仪表值
+     */
+    set(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * 记录直方图值
+     */
+    observe(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * 获取或创建指标
+     */
+    private getOrCreateMetric;
+    /**
+     * 获取指标键
+     */
+    private getMetricKey;
+    /**
+     * 修剪样本数量
+     */
+    private trimSamples;
+    /**
+     * 获取指标
+     */
+    getMetric(name: string, labels?: Record<string, string>): Metric | undefined;
+    /**
+     * 获取所有指标
+     */
+    getAllMetrics(): Metric[];
+    /**
+     * 获取最新值
+     */
+    getLatestValue(name: string, labels?: Record<string, string>): number | undefined;
+    /**
+     * 计算平均值
+     */
+    getAverage(name: string, labels?: Record<string, string>, windowMs?: number): number | undefined;
+    /**
+     * 计算总和
+     */
+    getSum(name: string, labels?: Record<string, string>, windowMs?: number): number | undefined;
+    /**
+     * 导出为 Prometheus 格式
+     */
+    exportPrometheus(): string;
+    /**
+     * 清理过期数据
+     */
+    cleanup(maxAge?: number): void;
+    /**
+     * 重置所有指标
+     */
+    reset(): void;
+}
+export declare const metrics: MetricsCollector;