imean-service-engine 2.0.0 → 2.0.2

package/src/plugins/graceful-shutdown/graceful-shutdown-plugin.test.ts

@@ -1,401 +0,0 @@
-import { beforeEach, describe, expect, it, vi, afterEach } from "vitest";
-import { GracefulShutdownPlugin } from "./plugin";
-import { Testing } from "../../core/testing";
-import { Handler } from "../../core/decorators";
-import { ActionPlugin } from "../action";
-import { RoutePlugin } from "../route";
-import { Route } from "../route";
-
-describe("GracefulShutdownPlugin", () => {
-  let plugin: GracefulShutdownPlugin;
-  let originalExit: typeof process.exit;
-  let exitCode: number | null = null;
-
-  beforeEach(() => {
-    // 保存原始的 process.exit
-    originalExit = process.exit;
-    exitCode = null;
-    
-    // Mock process.exit
-    process.exit = vi.fn((code?: number) => {
-      exitCode = code ?? 0;
-      return undefined as never;
-    }) as typeof process.exit;
-
-    plugin = new GracefulShutdownPlugin({
-      shutdownTimeout: 1000, // 1秒超时，用于测试
-    });
-  });
-
-  afterEach(() => {
-    // 恢复原始的 process.exit
-    process.exit = originalExit;
-    
-    // 清理所有信号监听器
-    process.removeAllListeners("SIGINT");
-    process.removeAllListeners("SIGTERM");
-    process.removeAllListeners("SIGBREAK");
-  });
-
-  describe("插件初始化", () => {
-    it("应该正确初始化插件", () => {
-      expect(plugin.name).toBe("graceful-shutdown-plugin");
-      expect(plugin.getActiveHandlersCount()).toBe(0);
-      expect(plugin.isShuttingDownNow()).toBe(false);
-    });
-
-    it("应该支持自定义超时时间", () => {
-      const customPlugin = new GracefulShutdownPlugin({
-        shutdownTimeout: 5000,
-      });
-      expect(customPlugin).toBeDefined();
-    });
-
-    it("应该支持禁用插件", () => {
-      const disabledPlugin = new GracefulShutdownPlugin({
-        enabled: false,
-      });
-      expect(disabledPlugin).toBeDefined();
-    });
-  });
-
-  describe("处理器追踪", () => {
-    it("应该追踪 Action 处理器的执行", async () => {
-      const { engine, Module: TestModule } = Testing.createTestEngine({
-        plugins: [new ActionPlugin(), plugin],
-      });
-
-      @TestModule("test-module")
-      class TestService {
-        @Handler({
-          type: "action",
-          options: {
-            params: [],
-            returns: { type: "string" },
-          },
-        })
-        async testAction() {
-          await new Promise((resolve) => setTimeout(resolve, 200));
-          return "done";
-        }
-      }
-
-      await engine.start();
-      const port = engine.getPort();
-
-      // 发送请求
-      const promise = fetch(`http://127.0.0.1:${port}/test-module/testAction`, {
-        method: "POST",
-        headers: { "Content-Type": "application/ejson" },
-        body: JSON.stringify({}),
-      });
-
-      // 等待一小段时间，确保处理器开始执行
-      await new Promise((resolve) => setTimeout(resolve, 50));
-
-      // 检查活跃处理器计数
-      expect(plugin.getActiveHandlersCount()).toBeGreaterThan(0);
-
-      // 等待请求完成
-      await promise;
-      await new Promise((resolve) => setTimeout(resolve, 50));
-
-      // 检查活跃处理器计数应该为0
-      expect(plugin.getActiveHandlersCount()).toBe(0);
-
-      await engine.stop();
-    });
-
-    it("应该追踪 Route 处理器的执行", async () => {
-      const { engine, Module: TestModule } = Testing.createTestEngine({
-        plugins: [new RoutePlugin(), plugin],
-      });
-
-      @TestModule("test-module")
-      class TestService {
-        @Route({
-          method: "GET",
-          path: "/test",
-        })
-        async testRoute() {
-          await new Promise((resolve) => setTimeout(resolve, 200));
-          return { success: true };
-        }
-      }
-
-      await engine.start();
-      const port = engine.getPort();
-
-      // 发送请求
-      const promise = fetch(`http://127.0.0.1:${port}/test`);
-
-      // 等待一小段时间，确保处理器开始执行
-      await new Promise((resolve) => setTimeout(resolve, 50));
-
-      // 检查活跃处理器计数
-      expect(plugin.getActiveHandlersCount()).toBeGreaterThan(0);
-
-      // 等待请求完成
-      await promise;
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // 检查活跃处理器计数应该为0
-      expect(plugin.getActiveHandlersCount()).toBe(0);
-
-      await engine.stop();
-    });
-  });
-
-  describe("优雅停机", () => {
-    it("应该在收到 SIGINT 信号时启动优雅停机", async () => {
-      const { engine, Module: TestModule } = Testing.createTestEngine({
-        plugins: [new ActionPlugin(), plugin],
-      });
-
-      @TestModule("test-module")
-      class TestService {
-        @Handler({
-          type: "action",
-          options: {
-            params: [],
-            returns: { type: "string" },
-          },
-        })
-        async testAction() {
-          await new Promise((resolve) => setTimeout(resolve, 200));
-          return "done";
-        }
-      }
-
-      await engine.start();
-
-      // 发送一个请求
-      const requestPromise = fetch(
-        `http://127.0.0.1:${engine.getPort()}/test-module/testAction`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/ejson" },
-          body: JSON.stringify({}),
-        }
-      );
-
-      // 等待处理器开始执行
-      await new Promise((resolve) => setTimeout(resolve, 50));
-
-      // 模拟 SIGINT 信号
-      process.emit("SIGINT" as any, "SIGINT");
-
-      // 等待停机流程
-      await new Promise((resolve) => setTimeout(resolve, 300));
-
-      // 检查是否正在停机
-      expect(plugin.isShuttingDownNow()).toBe(true);
-
-      // 等待请求完成
-      await requestPromise;
-
-      // 等待停机完成
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // 检查是否调用了 process.exit
-      expect(exitCode).toBe(0);
-    });
-
-    it("应该在所有处理器完成后立即停机", async () => {
-      const { engine, Module: TestModule } = Testing.createTestEngine({
-        plugins: [new ActionPlugin(), plugin],
-      });
-
-      @TestModule("test-module")
-      class TestService {
-        @Handler({
-          type: "action",
-          options: {
-            params: [],
-            returns: { type: "string" },
-          },
-        })
-        async quickAction() {
-          return "done";
-        }
-      }
-
-      await engine.start();
-
-      // 发送一个快速完成的请求
-      await fetch(
-        `http://127.0.0.1:${engine.getPort()}/test-module/quickAction`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/ejson" },
-          body: JSON.stringify({}),
-        }
-      );
-
-      // 等待一小段时间确保请求完成
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // 确保没有活跃的处理器
-      expect(plugin.getActiveHandlersCount()).toBe(0);
-
-      // 模拟 SIGINT 信号（Windows 也支持）
-      process.emit("SIGINT" as any, "SIGINT");
-
-      // 等待停机流程（需要更长时间，因为需要等待引擎停止）
-      await new Promise((resolve) => setTimeout(resolve, 500));
-
-      // 检查是否调用了 process.exit
-      // 注意：在某些情况下，process.exit 可能不会立即调用
-      // 所以我们检查 exitCode 是否为 0 或 null（null 表示还没有调用）
-      expect(exitCode === 0 || exitCode === null).toBe(true);
-    });
-
-    it("应该在超时后强制停机", async () => {
-      const fastTimeoutPlugin = new GracefulShutdownPlugin({
-        shutdownTimeout: 100, // 100ms 超时
-      });
-
-      const { engine, Module: TestModule } = Testing.createTestEngine({
-        plugins: [new ActionPlugin(), fastTimeoutPlugin],
-      });
-
-      @TestModule("test-module")
-      class TestService {
-        @Handler({
-          type: "action",
-          options: {
-            params: [],
-            returns: { type: "string" },
-          },
-        })
-        async slowAction() {
-          await new Promise((resolve) => setTimeout(resolve, 500));
-          return "done";
-        }
-      }
-
-      await engine.start();
-
-      // 发送一个慢请求
-      const requestPromise = fetch(
-        `http://127.0.0.1:${engine.getPort()}/test-module/slowAction`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/ejson" },
-          body: JSON.stringify({}),
-        }
-      );
-
-      // 等待处理器开始执行
-      await new Promise((resolve) => setTimeout(resolve, 50));
-
-      // 模拟 SIGINT 信号
-      process.emit("SIGINT" as any, "SIGINT");
-
-      // 等待超时
-      await new Promise((resolve) => setTimeout(resolve, 200));
-
-      // 检查是否调用了 process.exit（应该因为超时而退出）
-      expect(exitCode).toBe(0);
-
-      // 清理
-      try {
-        await requestPromise;
-      } catch {
-        // 忽略错误，因为服务器可能已经关闭
-      }
-    });
-
-    it("应该在停机期间拒绝新的请求", async () => {
-      const { engine, Module: TestModule } = Testing.createTestEngine({
-        plugins: [new ActionPlugin(), plugin],
-      });
-
-      @TestModule("test-module")
-      class TestService {
-        @Handler({
-          type: "action",
-          options: {
-            params: [],
-            returns: { type: "string" },
-          },
-        })
-        async testAction() {
-          return "done";
-        }
-      }
-
-      await engine.start();
-
-      // 模拟 SIGINT 信号
-      process.emit("SIGINT" as any, "SIGINT");
-
-      // 等待停机流程启动
-      await new Promise((resolve) => setTimeout(resolve, 50));
-
-      // 尝试发送新请求（应该被拒绝）
-      try {
-        await fetch(
-          `http://127.0.0.1:${engine.getPort()}/test-module/testAction`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/ejson" },
-            body: JSON.stringify({}),
-          }
-        );
-        // 如果请求成功，测试失败
-        expect.fail("Request should be rejected during shutdown");
-      } catch (error) {
-        // 请求应该被拒绝或失败
-        expect(error).toBeDefined();
-      }
-    });
-  });
-
-  describe("错误处理", () => {
-    it("应该正确处理处理器执行错误", async () => {
-      const { engine, Module: TestModule } = Testing.createTestEngine({
-        plugins: [new ActionPlugin(), plugin],
-      });
-
-      @TestModule("test-module")
-      class TestService {
-        @Handler({
-          type: "action",
-          options: {
-            params: [],
-            returns: { type: "string" },
-          },
-        })
-        async failingAction() {
-          throw new Error("Test error");
-        }
-      }
-
-      await engine.start();
-
-      // 发送一个会失败的请求
-      try {
-        await fetch(
-          `http://127.0.0.1:${engine.getPort()}/test-module/failingAction`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/ejson" },
-            body: JSON.stringify({}),
-          }
-        );
-      } catch {
-        // 忽略错误
-      }
-
-      // 等待一小段时间
-      await new Promise((resolve) => setTimeout(resolve, 50));
-
-      // 检查活跃处理器计数应该为0（即使出错也应该减少计数）
-      expect(plugin.getActiveHandlersCount()).toBe(0);
-
-      await engine.stop();
-    });
-  });
-});
-

package/src/plugins/graceful-shutdown/index.ts

@@ -1,3 +0,0 @@
-export { GracefulShutdownPlugin } from "./plugin";
-export type { GracefulShutdownPluginOptions } from "./types";
-

package/src/plugins/graceful-shutdown/plugin.ts

@@ -1,279 +0,0 @@
-import { Microservice } from "../../core/engine";
-import {
-  HandlerMetadata,
-  Plugin,
-  PluginPriority,
-} from "../../core/types";
-import logger from "../../core/logger";
-import { GracefulShutdownPluginOptions } from "./types";
-
-/**
- * 优雅停机插件
- * 
- * 功能：
- * 1. 追踪所有处理器的执行状态（包括 Action、Route、Schedule 等）
- * 2. 监听系统停机信号（SIGINT、SIGTERM 等）
- * 3. 收到信号后，等待所有正在执行的处理器完成
- * 4. 如果超时或所有处理完成，执行优雅停机
- * 
- * @example
- * ```typescript
- * // 使用默认配置（10分钟超时）
- * const gracefulShutdownPlugin = new GracefulShutdownPlugin();
- * 
- * // 自定义超时时间（5分钟）
- * const gracefulShutdownPlugin = new GracefulShutdownPlugin({
- *   shutdownTimeout: 5 * 60 * 1000, // 5分钟
- * });
- * ```
- */
-export class GracefulShutdownPlugin implements Plugin {
-  public readonly name = "graceful-shutdown-plugin";
-  public readonly priority = PluginPriority.SYSTEM; // 系统级插件，最高优先级
-
-  private engine: Microservice | null = null;
-  private options: Required<GracefulShutdownPluginOptions>;
-  
-  // 正在执行的处理器计数
-  private activeHandlers: number = 0;
-  
-  // 是否正在停机
-  private isShuttingDown: boolean = false;
-  
-  // 停机超时定时器
-  private shutdownTimer: NodeJS.Timeout | null = null;
-  
-  // 信号监听器（用于清理）
-  private signalListeners: Map<string, () => void> = new Map();
-
-  constructor(options?: GracefulShutdownPluginOptions) {
-    this.options = {
-      shutdownTimeout: options?.shutdownTimeout ?? 10 * 60 * 1000, // 默认10分钟
-      enabled: options?.enabled ?? true,
-    };
-  }
-
-  /**
-   * 引擎初始化钩子
-   */
-  onInit(engine: Microservice): void {
-    this.engine = engine;
-    logger.info("GracefulShutdownPlugin initialized");
-  }
-
-  /**
-   * Handler加载钩子：拦截所有处理器，追踪执行状态
-   */
-  onHandlerLoad(handlers: HandlerMetadata[]): void {
-    if (!this.options.enabled) {
-      return;
-    }
-
-    // 拦截所有处理器（包括 action、route、schedule 等）
-    for (const handler of handlers) {
-      handler.wrap(async (next, instance, ...args) => {
-        // 如果正在停机，拒绝新的请求
-        if (this.isShuttingDown) {
-          throw new Error("Service is shutting down, new requests are not accepted");
-        }
-
-        // 增加活跃处理器计数
-        this.incrementActiveHandlers();
-
-        try {
-          // 执行处理器
-          const result = await next();
-          return result;
-        } catch (error) {
-          // 即使出错也要减少计数
-          throw error;
-        } finally {
-          // 减少活跃处理器计数
-          this.decrementActiveHandlers();
-        }
-      });
-    }
-
-    logger.info(
-      `GracefulShutdownPlugin: Tracking ${handlers.length} handler(s)`
-    );
-  }
-
-  /**
-   * 引擎启动后钩子：注册系统信号监听器
-   */
-  async onAfterStart(engine: Microservice): Promise<void> {
-    if (!this.options.enabled) {
-      return;
-    }
-
-    this.engine = engine;
-    this.registerSignalHandlers();
-    logger.info(
-      `GracefulShutdownPlugin: Signal handlers registered, shutdown timeout: ${this.options.shutdownTimeout}ms`
-    );
-  }
-
-  /**
-   * 注册系统信号监听器
-   */
-  private registerSignalHandlers(): void {
-    // 支持的信号列表（兼容不同操作系统）
-    const signals: NodeJS.Signals[] = [
-      "SIGINT",   // Ctrl+C (Unix/Linux/Mac)
-      "SIGTERM",  // 终止信号 (Unix/Linux/Mac)
-      "SIGBREAK", // Ctrl+Break (Windows)
-    ];
-
-    for (const signal of signals) {
-      // 检查信号是否在当前平台支持
-      if (process.platform === "win32" && signal === "SIGTERM") {
-        // Windows 不支持 SIGTERM，跳过
-        continue;
-      }
-
-      const handler = () => {
-        logger.info(`GracefulShutdownPlugin: Received ${signal} signal`);
-        this.initiateShutdown();
-      };
-
-      // 注册信号监听器
-      process.on(signal, handler);
-      
-      // 保存监听器引用，用于清理
-      this.signalListeners.set(signal, handler);
-    }
-  }
-
-  /**
-   * 增加活跃处理器计数
-   */
-  private incrementActiveHandlers(): void {
-    this.activeHandlers++;
-    logger.debug(
-      `GracefulShutdownPlugin: Active handlers: ${this.activeHandlers}`
-    );
-  }
-
-  /**
-   * 减少活跃处理器计数
-   */
-  private decrementActiveHandlers(): void {
-    this.activeHandlers = Math.max(0, this.activeHandlers - 1);
-    logger.debug(
-      `GracefulShutdownPlugin: Active handlers: ${this.activeHandlers}`
-    );
-
-    // 如果正在停机且所有处理器已完成，立即执行停机
-    if (this.isShuttingDown && this.activeHandlers === 0) {
-      logger.info(
-        "GracefulShutdownPlugin: All handlers completed, proceeding with shutdown"
-      );
-      this.completeShutdown();
-    }
-  }
-
-  /**
-   * 启动优雅停机流程
-   */
-  private async initiateShutdown(): Promise<void> {
-    // 防止重复调用
-    if (this.isShuttingDown) {
-      return;
-    }
-
-    this.isShuttingDown = true;
-    logger.info(
-      `GracefulShutdownPlugin: Initiating graceful shutdown, waiting for ${this.activeHandlers} active handler(s) to complete`
-    );
-
-    // 如果当前没有活跃的处理器，立即停机
-    if (this.activeHandlers === 0) {
-      logger.info(
-        "GracefulShutdownPlugin: No active handlers, proceeding with shutdown immediately"
-      );
-      await this.completeShutdown();
-      return;
-    }
-
-    // 设置超时定时器
-    this.shutdownTimer = setTimeout(() => {
-      logger.warn(
-        `GracefulShutdownPlugin: Shutdown timeout (${this.options.shutdownTimeout}ms) reached, forcing shutdown`
-      );
-      this.completeShutdown();
-    }, this.options.shutdownTimeout);
-
-    // 等待所有处理器完成（通过 decrementActiveHandlers 触发）
-    // 如果超时，completeShutdown 会被定时器调用
-  }
-
-  /**
-   * 完成停机流程
-   */
-  private async completeShutdown(): Promise<void> {
-    // 清除超时定时器
-    if (this.shutdownTimer) {
-      clearTimeout(this.shutdownTimer);
-      this.shutdownTimer = null;
-    }
-
-    // 清理信号监听器
-    this.cleanupSignalHandlers();
-
-    // 停止引擎
-    if (this.engine) {
-      try {
-        await this.engine.stop();
-        logger.info("GracefulShutdownPlugin: Engine stopped successfully");
-      } catch (error) {
-        logger.error("GracefulShutdownPlugin: Failed to stop engine", error);
-      }
-    }
-
-    // 退出进程
-    logger.info("GracefulShutdownPlugin: Process exiting");
-    process.exit(0);
-  }
-
-  /**
-   * 清理信号监听器
-   */
-  private cleanupSignalHandlers(): void {
-    for (const [signal, handler] of this.signalListeners.entries()) {
-      process.removeListener(signal, handler);
-    }
-    this.signalListeners.clear();
-  }
-
-  /**
-   * 引擎销毁钩子：清理资源
-   */
-  async onDestroy(): Promise<void> {
-    // 清理信号监听器
-    this.cleanupSignalHandlers();
-
-    // 清除超时定时器
-    if (this.shutdownTimer) {
-      clearTimeout(this.shutdownTimer);
-      this.shutdownTimer = null;
-    }
-
-    logger.info("GracefulShutdownPlugin: Cleaned up");
-  }
-
-  /**
-   * 获取当前活跃处理器数量（用于测试和监控）
-   */
-  getActiveHandlersCount(): number {
-    return this.activeHandlers;
-  }
-
-  /**
-   * 检查是否正在停机（用于测试和监控）
-   */
-  isShuttingDownNow(): boolean {
-    return this.isShuttingDown;
-  }
-}
-

package/src/plugins/graceful-shutdown/types.ts

@@ -1,17 +0,0 @@
-/**
- * 优雅停机插件配置选项
- */
-export interface GracefulShutdownPluginOptions {
-  /**
-   * 停机超时时间（毫秒）
-   * 默认：10分钟（600000ms）
-   */
-  shutdownTimeout?: number;
-
-  /**
-   * 是否启用优雅停机
-   * 默认：true
-   */
-  enabled?: boolean;
-}
-