@onebots/core 0.5.0 → 1.0.0

package/lib/__tests__/lifecycle.test.js

@@ -0,0 +1,163 @@
+/**
+ * 生命周期管理测试
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { LifecycleManager } from '../lifecycle.js';
+describe('Lifecycle Manager', () => {
+    let lifecycle;
+    beforeEach(() => {
+        lifecycle = new LifecycleManager();
+    });
+    describe('Resource Management', () => {
+        it('should register and cleanup resources', async () => {
+            let cleaned = false;
+            lifecycle.register('test-resource', () => {
+                cleaned = true;
+            });
+            expect(lifecycle.getResourceCount()).toBe(1);
+            expect(lifecycle.getResourceNames()).toContain('test-resource');
+            await lifecycle.cleanup();
+            expect(cleaned).toBe(true);
+            expect(lifecycle.getResourceCount()).toBe(0);
+        });
+        it('should handle multiple resources', async () => {
+            const cleaned = [];
+            lifecycle.register('resource1', () => {
+                cleaned.push('resource1');
+            });
+            lifecycle.register('resource2', () => {
+                cleaned.push('resource2');
+            });
+            await lifecycle.cleanup();
+            expect(cleaned).toContain('resource1');
+            expect(cleaned).toContain('resource2');
+        });
+        it('should handle resource cleanup errors', async () => {
+            const errorHandler = vi.fn();
+            lifecycle.on('cleanupError', errorHandler);
+            lifecycle.register('error-resource', () => {
+                throw new Error('Cleanup failed');
+            });
+            // 清理不应该抛出错误，应该触发事件
+            await expect(lifecycle.cleanup()).resolves.not.toThrow();
+            expect(errorHandler).toHaveBeenCalled();
+        });
+        it('should unregister resource', () => {
+            lifecycle.register('resource1', () => { });
+            lifecycle.register('resource2', () => { });
+            expect(lifecycle.unregister('resource1')).toBe(true);
+            expect(lifecycle.getResourceCount()).toBe(1);
+            expect(lifecycle.getResourceNames()).not.toContain('resource1');
+        });
+    });
+    describe('Lifecycle Hooks', () => {
+        it('should execute init hooks', async () => {
+            const initHook = vi.fn();
+            lifecycle.addHook({ onInit: initHook });
+            await lifecycle.init();
+            expect(initHook).toHaveBeenCalled();
+        });
+        it('should execute start hooks', async () => {
+            const startHook = vi.fn();
+            lifecycle.addHook({ onStart: startHook });
+            await lifecycle.start();
+            expect(startHook).toHaveBeenCalled();
+        });
+        it('should execute stop hooks', async () => {
+            const stopHook = vi.fn();
+            lifecycle.addHook({ onStop: stopHook });
+            await lifecycle.stop();
+            expect(stopHook).toHaveBeenCalled();
+        });
+        it('should execute cleanup hooks', async () => {
+            const cleanupHook = vi.fn();
+            lifecycle.addHook({ onCleanup: cleanupHook });
+            await lifecycle.cleanup();
+            expect(cleanupHook).toHaveBeenCalled();
+        });
+        it('should execute all hooks in order', async () => {
+            const order = [];
+            lifecycle.addHook({
+                onInit: () => {
+                    order.push('init');
+                },
+                onStart: () => {
+                    order.push('start');
+                },
+                onStop: () => {
+                    order.push('stop');
+                },
+                onCleanup: () => {
+                    order.push('cleanup');
+                },
+            });
+            await lifecycle.init();
+            await lifecycle.start();
+            await lifecycle.stop();
+            await lifecycle.cleanup();
+            expect(order).toEqual(['init', 'start', 'stop', 'cleanup']);
+        });
+    });
+    describe('Graceful Shutdown', () => {
+        it('should perform graceful shutdown', async () => {
+            const stopHook = vi.fn();
+            const cleanupHook = vi.fn();
+            lifecycle.addHook({
+                onStop: stopHook,
+                onCleanup: cleanupHook,
+            });
+            await lifecycle.gracefulShutdown('SIGTERM');
+            expect(stopHook).toHaveBeenCalled();
+            expect(cleanupHook).toHaveBeenCalled();
+        });
+        it('should emit shutdown events', async () => {
+            const shutdownHandler = vi.fn();
+            const shutdownCompleteHandler = vi.fn();
+            lifecycle.on('shutdown', shutdownHandler);
+            lifecycle.on('shutdownComplete', shutdownCompleteHandler);
+            await lifecycle.gracefulShutdown('SIGTERM');
+            expect(shutdownHandler).toHaveBeenCalledWith('SIGTERM');
+            expect(shutdownCompleteHandler).toHaveBeenCalled();
+        });
+        it('should handle shutdown timeout', async () => {
+            lifecycle.setShutdownTimeout(100);
+            const timeoutHandler = vi.fn();
+            lifecycle.on('shutdownTimeout', timeoutHandler);
+            // 添加一个永远不会完成的钩子
+            lifecycle.addHook({
+                onStop: () => new Promise(() => { }), // 永远pending
+            });
+            // 使用 vi.useFakeTimers 来测试超时
+            vi.useFakeTimers();
+            // 启动关闭流程
+            const shutdownPromise = lifecycle.gracefulShutdown(undefined, { exitOnTimeout: false });
+            // 等待超时事件触发
+            const timeoutPromise = new Promise((resolve) => {
+                lifecycle.once('shutdownTimeout', () => {
+                    timeoutHandler();
+                    resolve();
+                });
+            });
+            // 推进时间
+            vi.advanceTimersByTime(150);
+            // 等待超时事件
+            await timeoutPromise;
+            expect(timeoutHandler).toHaveBeenCalled();
+            // 清理
+            vi.useRealTimers();
+            // 取消关闭流程（避免测试挂起）
+            lifecycle.removeHook(lifecycle['hooks'][0]);
+        });
+    });
+    describe('Event Emission', () => {
+        it('should emit lifecycle events', async () => {
+            const beforeInit = vi.fn();
+            const afterInit = vi.fn();
+            lifecycle.on('beforeInit', beforeInit);
+            lifecycle.on('afterInit', afterInit);
+            await lifecycle.init();
+            expect(beforeInit).toHaveBeenCalled();
+            expect(afterInit).toHaveBeenCalled();
+        });
+    });
+});

package/lib/account.js

@@ -86,9 +86,10 @@ export class Account extends EventEmitter {
         return this.adapter.getFriendList(this.account_id);
     }
     async dispatch(commonEvent) {
-        this.logger.debug(`Dispatching event: ${commonEvent.type}`);
+        this.logger.debug(`Dispatching event: ${commonEvent.type} to ${this.protocols.length} protocol(s)`);
         // Each protocol instance formats the common event to its own standard
         for (const protocol of this.protocols) {
+            this.logger.debug(`Dispatching to protocol: ${protocol.name}/${protocol.version}`);
             protocol.dispatch(commonEvent);
         }
     }

package/lib/base-app.d.ts

@@ -6,12 +6,14 @@ import type { Logger } from "log4js";
 import { Server } from "http";
 import yaml from "js-yaml";
 declare const configure: typeof log4js.configure, connectLogger: typeof log4js.connectLogger;
-import { Router, WsServer } from "./router.js";
+import { Router } from "./router.js";
 import { LogLevel } from "./types.js";
 import { Adapter } from "./adapter.js";
 import { Protocol } from "./protocol.js";
 import { Account } from "./account.js";
 import { SqliteDB } from "./db.js";
+import { LifecycleManager } from "./lifecycle.js";
+import { Logger as EnhancedLogger } from "./logger.js";
 export { configure, yaml, connectLogger };
 export interface KoaOptions {
     env?: string;
@@ -26,12 +28,13 @@ export declare class BaseApp extends Koa {
     httpServer: Server;
     isStarted: boolean;
     logger: Logger;
+    enhancedLogger: EnhancedLogger;
+    lifecycle: LifecycleManager;
     static get configPath(): string;
     static get dataDir(): string;
     static get logFile(): string;
     db: SqliteDB;
     adapters: Map<keyof Adapter.Configs, Adapter>;
-    ws: WsServer;
     router: Router;
     get info(): {
         system_platform: NodeJS.Platform;
@@ -47,12 +50,20 @@ export declare class BaseApp extends Koa {
         process_cwd: string;
         process_use_memory: number;
         node_version: string;
-        sdk_version: any;
+        sdk_version: string;
         uptime: number;
     };
     constructor(config?: BaseApp.Config);
     init(): void;
     getLogger(patform: string): log4js.Logger;
+    /**
+     * 获取增强的 Logger 实例
+     */
+    getEnhancedLogger(name: string): EnhancedLogger;
+    /**
+     * 设置健康检查端点
+     */
+    private setupHealthEndpoints;
     get adapterConfigs(): Map<string, Account.Config[]>;
     private initAdapters;
     addAccount<P extends keyof Adapter.Configs>(config: Account.Config<P>): void;

package/lib/base-app.js

@@ -1,26 +1,32 @@
 import Koa from "koa";
 import * as os from "os";
 import "reflect-metadata";
-import * as fs from "fs";
 import { writeFileSync } from "fs";
 import log4js from "log4js";
 import { createServer } from "http";
 import yaml from "js-yaml";
-import KoaBodyParser from "koa-bodyparser";
+import KoaBody from "koa-body";
 import basicAuth from "koa-basic-auth";
 const { configure, connectLogger, getLogger } = log4js;
-import { deepClone, deepMerge, readLine } from "./utils.js";
+import { deepClone, deepMerge } from "./utils.js";
 import { Router } from "./router.js";
 import * as path from "path";
 import process from "process";
 import { SqliteDB } from "./db.js";
-import { AdapterRegistry } from "./registry.js";
+import pkg from "../package.json" with { type: "json" };
+import { AdapterRegistry, ProtocolRegistry } from "./registry.js";
+import { ConfigValidator, BaseAppConfigSchema } from "./config-validator.js";
+import { LifecycleManager } from "./lifecycle.js";
+import { ErrorHandler, ConfigError } from "./errors.js";
+import { createLogger } from "./logger.js";
 export { configure, yaml, connectLogger };
 export class BaseApp extends Koa {
     config;
     httpServer;
     isStarted = false;
     logger;
+    enhancedLogger;
+    lifecycle;
     static get configPath() {
         return path.join(BaseApp.configDir, "config.yaml");
     }
@@ -32,10 +38,8 @@ export class BaseApp extends Koa {
     }
     db;
     adapters = new Map();
-    ws;
     router;
     get info() {
-        const pkg = require(path.resolve(__dirname, "../../package.json"));
         const free_memory = os.freemem();
         const total_memory = os.totalmem();
         return {
@@ -58,35 +62,176 @@ export class BaseApp extends Koa {
     }
     constructor(config = {}) {
         super(config);
-        this.config = deepMerge(deepClone(BaseApp.defaultConfig), config);
+        // 初始化生命周期管理器
+        this.lifecycle = new LifecycleManager();
+        // 合并配置并验证
+        const mergedConfig = deepMerge(deepClone(BaseApp.defaultConfig), config);
+        try {
+            this.config = ConfigValidator.validateWithDefaults(mergedConfig, BaseAppConfigSchema);
+        }
+        catch (error) {
+            const configError = ErrorHandler.wrap(error, { config: mergedConfig });
+            throw new ConfigError('Configuration validation failed', {
+                context: { originalError: configError.toJSON() },
+                cause: configError,
+            });
+        }
         this.init();
     }
     init() {
-        this.logger = getLogger("[OneBots]");
-        this.db = new SqliteDB(path.resolve(BaseApp.dataDir, this.config.database));
+        // 初始化传统日志（保持兼容性）
+        this.logger = getLogger("[onebots]");
         this.logger.level = this.config.log_level;
+        // 初始化增强日志
+        this.enhancedLogger = createLogger("[onebots]", this.config.log_level);
+        // 注册数据库资源到生命周期管理器
+        this.db = new SqliteDB(path.resolve(BaseApp.dataDir, this.config.database));
+        this.lifecycle.register('database', () => {
+            // 数据库清理逻辑（如果需要）
+        });
+        // 创建 HTTP 服务器
         this.httpServer = createServer(this.callback());
-        this.router = new Router(this.httpServer, { prefix: this.config.path });
-        this.use(KoaBodyParser({}))
-            .use(this.router.routes())
-            .use(this.router.allowedMethods())
+        this.router = new Router(this.httpServer);
+        // 注册路由清理
+        this.lifecycle.register('router', () => {
+            return this.router.cleanupAsync();
+        });
+        // 注册 HTTP 服务器清理
+        this.lifecycle.register('httpServer', () => {
+            return new Promise((resolve) => {
+                this.httpServer.close(() => resolve());
+            });
+        });
+        // 注册健康检查端点（无需认证）
+        this.setupHealthEndpoints();
+        this.use(KoaBody())
             .use(async (ctx, next) => {
-            const adapter = ctx.path?.slice(1)?.split("/")[0];
-            if (this.adapters.has(adapter))
+            // 健康检查端点跳过认证
+            if (ctx.path === '/health' || ctx.path === '/ready' || ctx.path === '/metrics') {
+                return next();
+            }
+            // 检查是否是协议路径格式: /{platform}/{accountId}/{protocol}/{version}/...
+            const pathParts = ctx.path?.split("/").filter(p => p) || [];
+            const [_platform, _accountId, protocol, version] = pathParts;
+            if (ProtocolRegistry.has(protocol, version)) {
                 return next();
-            return basicAuth({
+            }
+            return await basicAuth({
                 name: this.config.username,
                 pass: this.config.password,
             })(ctx, next);
+        })
+            .use(this.router.routes())
+            .use(this.router.allowedMethods());
+        this.enhancedLogger.info('Application initialized', {
+            username: this.config.username,
+            port: this.config.port,
         });
-        this.ws = this.router.ws("/");
         this.initAdapters();
     }
     getLogger(patform) {
-        const logger = getLogger(`[OneBots:${patform}]`);
+        const logger = getLogger(`[onebots:${patform}]`);
         logger.level = this.config.log_level;
         return logger;
     }
+    /**
+     * 获取增强的 Logger 实例
+     */
+    getEnhancedLogger(name) {
+        return createLogger(`[onebots:${name}]`, this.config.log_level);
+    }
+    /**
+     * 设置健康检查端点
+     */
+    setupHealthEndpoints() {
+        // /health - 基础健康检查（存活探针）
+        this.router.get('/health', (ctx) => {
+            ctx.body = {
+                status: 'ok',
+                timestamp: new Date().toISOString(),
+                uptime: process.uptime(),
+                version: pkg.version,
+            };
+        });
+        // /ready - 就绪检查（就绪探针）
+        this.router.get('/ready', (ctx) => {
+            const adaptersStatus = {};
+            let allReady = true;
+            let totalOnline = 0;
+            let totalAccounts = 0;
+            for (const [platform, adapter] of this.adapters) {
+                let online = 0;
+                let offline = 0;
+                for (const account of adapter.accounts.values()) {
+                    totalAccounts++;
+                    if (account.status === 'online') {
+                        online++;
+                        totalOnline++;
+                    }
+                    else {
+                        offline++;
+                    }
+                }
+                adaptersStatus[platform] = { online, offline, total: online + offline };
+                if (offline > 0)
+                    allReady = false;
+            }
+            ctx.status = allReady && this.isStarted ? 200 : 503;
+            ctx.body = {
+                ready: allReady && this.isStarted,
+                timestamp: new Date().toISOString(),
+                server: this.isStarted,
+                adapters: adaptersStatus,
+                summary: {
+                    total_adapters: this.adapters.size,
+                    total_accounts: totalAccounts,
+                    online_accounts: totalOnline,
+                },
+            };
+        });
+        // /metrics - 简单的 Prometheus 格式指标
+        this.router.get('/metrics', (ctx) => {
+            const metrics = [];
+            const now = Date.now();
+            // 基础指标
+            metrics.push(`# HELP onebots_info OneBots application info`);
+            metrics.push(`# TYPE onebots_info gauge`);
+            metrics.push(`onebots_info{version="${pkg.version}"} 1`);
+            metrics.push(`# HELP onebots_uptime_seconds Application uptime in seconds`);
+            metrics.push(`# TYPE onebots_uptime_seconds gauge`);
+            metrics.push(`onebots_uptime_seconds ${process.uptime()}`);
+            metrics.push(`# HELP onebots_started Whether the application is started`);
+            metrics.push(`# TYPE onebots_started gauge`);
+            metrics.push(`onebots_started ${this.isStarted ? 1 : 0}`);
+            // 内存使用
+            const memUsage = process.memoryUsage();
+            metrics.push(`# HELP onebots_memory_bytes Memory usage in bytes`);
+            metrics.push(`# TYPE onebots_memory_bytes gauge`);
+            metrics.push(`onebots_memory_bytes{type="rss"} ${memUsage.rss}`);
+            metrics.push(`onebots_memory_bytes{type="heapTotal"} ${memUsage.heapTotal}`);
+            metrics.push(`onebots_memory_bytes{type="heapUsed"} ${memUsage.heapUsed}`);
+            // 适配器和账号指标
+            metrics.push(`# HELP onebots_adapters_total Total number of adapters`);
+            metrics.push(`# TYPE onebots_adapters_total gauge`);
+            metrics.push(`onebots_adapters_total ${this.adapters.size}`);
+            metrics.push(`# HELP onebots_accounts_total Total accounts by platform and status`);
+            metrics.push(`# TYPE onebots_accounts_total gauge`);
+            for (const [platform, adapter] of this.adapters) {
+                let online = 0;
+                let offline = 0;
+                for (const account of adapter.accounts.values()) {
+                    if (account.status === 'online')
+                        online++;
+                    else
+                        offline++;
+                }
+                metrics.push(`onebots_accounts_total{platform="${platform}",status="online"} ${online}`);
+                metrics.push(`onebots_accounts_total{platform="${platform}",status="offline"} ${offline}`);
+            }
+            ctx.type = 'text/plain; charset=utf-8';
+            ctx.body = metrics.join('\n') + '\n';
+        });
+    }
     get adapterConfigs() {
         const map = new Map();
         Object.keys(this.config).forEach(key => {
@@ -169,124 +314,39 @@ export class BaseApp extends Koa {
         return adapter;
     }
     async start() {
-        this.httpServer.listen(this.config.port);
-        const fileListener = e => {
-            if (e === "change")
-                this.ws.clients.forEach(async (client) => {
-                    client.send(JSON.stringify({
-                        event: "system.log",
-                        data: await readLine(1, BaseApp.logFile),
-                    }));
+        const stopTimer = this.enhancedLogger.start('Application start');
+        try {
+            // 执行启动钩子
+            await this.lifecycle.start();
+            // 启动 HTTP 服务器
+            await new Promise((resolve, reject) => {
+                this.httpServer.once('error', reject);
+                this.httpServer.listen(this.config.port, () => {
+                    this.httpServer.removeListener('error', reject);
+                    resolve();
                 });
-        };
-        fs.watch(BaseApp.logFile, fileListener);
-        this.once("close", () => {
-            fs.unwatchFile(BaseApp.logFile, fileListener);
-        });
-        process.once("disconnect", () => {
-            fs.unwatchFile(BaseApp.logFile, fileListener);
-        });
-        this.ws.on("connection", async (client) => {
-            client.send(JSON.stringify({
-                event: "system.sync",
-                data: {
-                    config: fs.readFileSync(BaseApp.configPath, "utf8"),
-                    adapters: [...this.adapters.values()].map(adapter => {
-                        return adapter.info;
-                    }),
-                    app: this.info,
-                    logs: fs.existsSync(BaseApp.logFile) ? await readLine(100, BaseApp.logFile) : "",
-                },
-            }));
-            client.on("message", async (raw) => {
-                let payload = {};
+            });
+            this.enhancedLogger.mark(`Server listening at http://0.0.0.0:${this.config.port}/${this.config.path ? this.config.path : ""}`, { port: this.config.port, path: this.config.path });
+            // 启动所有适配器
+            for (const [platform, adapter] of this.adapters) {
                 try {
-                    payload = JSON.parse(raw.toString());
+                    await adapter.start();
+                    this.enhancedLogger.info(`Adapter started`, { platform });
                 }
-                catch {
-                    return;
+                catch (error) {
+                    const wrappedError = ErrorHandler.wrap(error, { platform });
+                    this.enhancedLogger.error(wrappedError, { platform });
+                    // 继续启动其他适配器
                 }
-                switch (payload.action) {
-                    case "system.input":
-                        // 将流的模式切换到“流动模式”
-                        process.stdin.resume();
-                        // 使用以下函数来模拟输入数据
-                        function simulateInput(data) {
-                            process.nextTick(() => {
-                                process.stdin.emit("data", data);
-                            });
-                        }
-                        simulateInput(Buffer.from(payload.data + "\n", "utf8"));
-                        // 模拟结束
-                        process.nextTick(() => {
-                            process.stdin.emit("end");
-                        });
-                        return true;
-                    case "system.saveConfig":
-                        return fs.writeFileSync(BaseApp.configPath, payload.data, "utf8");
-                    case "system.reload":
-                        const config = yaml.load(fs.readFileSync(BaseApp.configPath, "utf8"));
-                        return this.reload(config);
-                    case "bot.start": {
-                        const { platform, uin } = JSON.parse(payload.data);
-                        await this.adapters.get(platform)?.setOnline(uin);
-                        return client.send(JSON.stringify({
-                            event: "bot.change",
-                            data: this.adapters.get(platform).getAccount(uin).info,
-                        }));
-                    }
-                    case "bot.stop": {
-                        const { platform, uin } = JSON.parse(payload.data);
-                        await this.adapters.get(platform)?.setOffline(uin);
-                        return client.send(JSON.stringify({
-                            event: "bot.change",
-                            data: this.adapters.get(platform).getAccount(uin).info,
-                        }));
-                    }
-                }
-            });
-        });
-        this.router.get("/list", ctx => {
-            ctx.body = this.accounts.map(bot => {
-                return bot.info;
-            });
-        });
-        this.router.post("/add", (ctx, next) => {
-            const config = (ctx.request.body || {});
-            try {
-                this.addAccount(config);
-                ctx.body = `添加成功`;
-            }
-            catch (e) {
-                ctx.body = e.message;
-            }
-        });
-        this.router.post("/edit", (ctx, next) => {
-            const config = (ctx.request.body || {});
-            try {
-                this.updateAccount(config);
-                ctx.body = `修改成功`;
-            }
-            catch (e) {
-                ctx.body = e.message;
-            }
-        });
-        this.router.get("/remove", (ctx, next) => {
-            const { uin, platform, force } = ctx.request.query;
-            try {
-                this.removeAccount(String(platform), String(uin), Boolean(force));
-                ctx.body = `移除成功`;
-            }
-            catch (e) {
-                console.log(e);
-                ctx.body = e.message;
             }
-        });
-        this.logger.mark(`server listen at http://0.0.0.0:${this.config.port}/${this.config.path ? this.config.path : ""}`);
-        for (const [_, adapter] of this.adapters) {
-            await adapter.start();
+            this.isStarted = true;
+            stopTimer();
+        }
+        catch (error) {
+            const wrappedError = ErrorHandler.wrap(error);
+            this.enhancedLogger.fatal(wrappedError);
+            throw wrappedError;
         }
-        this.isStarted = true;
     }
     async reload(config) {
         await this.stop();
@@ -295,14 +355,32 @@ export class BaseApp extends Koa {
         await this.start();
     }
     async stop() {
-        for (const [_, adapter] of this.adapters) {
-            await adapter.stop();
+        const stopTimer = this.enhancedLogger.start('Application stop');
+        try {
+            // 执行停止钩子
+            await this.lifecycle.stop();
+            // 停止所有适配器
+            const stopPromises = [];
+            for (const [platform, adapter] of this.adapters) {
+                stopPromises.push(Promise.resolve(adapter.stop()).catch(error => {
+                    const wrappedError = ErrorHandler.wrap(error, { platform });
+                    this.enhancedLogger.error(wrappedError, { platform });
+                }));
+            }
+            await Promise.all(stopPromises);
+            this.adapters.clear();
+            // 清理资源
+            await this.lifecycle.cleanup();
+            this.emit("close");
+            this.isStarted = false;
+            stopTimer();
+            this.enhancedLogger.info('Application stopped');
+        }
+        catch (error) {
+            const wrappedError = ErrorHandler.wrap(error);
+            this.enhancedLogger.error(wrappedError);
+            throw wrappedError;
         }
-        this.adapters.clear();
-        // this.ws.close()
-        this.httpServer.close();
-        this.emit("close");
-        this.isStarted = false;
     }
 }
 (function (BaseApp) {