aetherframework-cluster 1.0.0

package/index.js

@@ -0,0 +1,288 @@
+// packages/cluster/index.js
+import ClusterManager from './src/core/ClusterManager.js';
+import WorkerManager from './src/core/WorkerManager.js';
+import HealthMonitor from './src/core/HealthMonitor.js';
+import LoadBalancer from './src/core/LoadBalancer.js';
+import { loadEnv } from './src/utils/env-loader.js';
+
+/**
+ * AetherJS Cluster Module
+ * High-performance cluster management for Node.js applications
+ */
+class ClusterModule {
+  constructor(config = {}) {
+    // 加载环境配置
+    this.env = loadEnv();
+    
+    // 合并配置
+    this.config = {
+      enabled: this.env.CLUSTER_ENABLED !== 'false',
+      workers: this.env.CLUSTER_WORKERS || 'auto',
+      port: parseInt(this.env.CLUSTER_PORT) || 3000,
+      gracefulShutdown: this.env.CLUSTER_GRACEFUL_SHUTDOWN !== 'false',
+      restartOnExit: this.env.CLUSTER_RESTART_ON_EXIT !== 'false',
+      restartDelay: parseInt(this.env.CLUSTER_RESTART_DELAY) || 1000,
+      healthCheck: {
+        enabled: this.env.CLUSTER_HEALTH_CHECK_ENABLED !== 'false',
+        interval: parseInt(this.env.CLUSTER_HEALTH_CHECK_INTERVAL) || 30000,
+        timeout: parseInt(this.env.CLUSTER_HEALTH_CHECK_TIMEOUT) || 5000
+      },
+      loadBalancing: {
+        enabled: this.env.CLUSTER_LOAD_BALANCING !== 'false',
+        type: this.env.CLUSTER_LOAD_BALANCER_TYPE || 'round-robin',
+        maxRequests: parseInt(this.env.CLUSTER_MAX_REQUESTS_PER_WORKER) || 1000
+      },
+      monitoring: {
+        enabled: this.env.CLUSTER_MONITORING_ENABLED !== 'false',
+        interval: parseInt(this.env.CLUSTER_MONITORING_INTERVAL) || 10000,
+        memoryThreshold: parseFloat(this.env.CLUSTER_MEMORY_THRESHOLD) || 0.8,
+        cpuThreshold: parseFloat(this.env.CLUSTER_CPU_THRESHOLD) || 0.7
+      },
+      ...config
+    };
+    
+    this.clusterManager = null;
+    this.workerManager = null;
+    this.healthMonitor = null;
+    this.loadBalancer = null;
+  }
+  
+  /**
+   * 初始化集群模块
+   * @param {Function} appFactory - 应用工厂函数
+   * @returns {Object|null} 应用实例或 null
+   */
+  initialize(appFactory) {
+    if (!this.config.enabled) {
+      console.log('🚫 Cluster module is disabled, running in single process mode');
+      return appFactory();
+    }
+    
+    console.log('🚀 Initializing AetherJS Cluster Module...');
+    
+    // 创建核心组件
+    this.clusterManager = new ClusterManager(this.config);
+    this.workerManager = new WorkerManager(this.config);
+    this.healthMonitor = new HealthMonitor(this.config.healthCheck);
+    this.loadBalancer = new LoadBalancer(this.config.loadBalancing);
+    
+    // 启动集群
+    return this.clusterManager.start(() => {
+      // 工作进程中的逻辑
+      const app = appFactory();
+      
+      // 设置工作进程应用
+      this.setupWorkerApp(app);
+      
+      return app;
+    });
+  }
+  
+  /**
+   * 设置工作进程应用
+   * @param {Object} app - 应用实例
+   */
+  setupWorkerApp(app) {
+    // 添加集群中间件
+    if (this.healthMonitor) {
+      app.use(this.healthMonitor.middleware());
+    }
+    
+    // 添加集群路由
+    this.setupClusterRoutes(app);
+    
+    // 设置进程间通信
+    this.setupIPC();
+    
+    // 启动监控
+    this.startMonitoring();
+  }
+  
+  /**
+   * 设置集群路由
+   * @param {Object} app - 应用实例
+   */
+  setupClusterRoutes(app) {
+    // 健康检查端点
+    app.get('/cluster/health', async (ctx) => {
+      const health = await this.healthMonitor.getHealthStatus();
+      ctx.body = health;
+    });
+    
+    // 集群统计端点
+    app.get('/cluster/stats', (ctx) => {
+      const stats = this.workerManager.getStats();
+      ctx.body = {
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        stats: {
+          ...stats,
+          pid: process.pid,
+          isWorker: !process.env.isPrimary,
+          workerId: process.env.workerId,
+          uptime: process.uptime(),
+          memory: process.memoryUsage(),
+          cpu: process.cpuUsage()
+        }
+      };
+    });
+    
+    // 工作进程管理端点
+    app.post('/cluster/workers/:pid/restart', (ctx) => {
+      const { pid } = ctx.params;
+      const success = this.clusterManager.restartWorker(parseInt(pid));
+      
+      ctx.body = {
+        status: success ? 'ok' : 'error',
+        message: success ? `Worker ${pid} restart initiated` : `Worker ${pid} not found`,
+        pid
+      };
+    });
+    
+    // 负载均衡信息
+    app.get('/cluster/load-balancer', (ctx) => {
+      const info = this.loadBalancer.getInfo();
+      ctx.body = info;
+    });
+  }
+  
+  /**
+   * 设置进程间通信
+   */
+  setupIPC() {
+    process.on('message', (message) => {
+      switch (message.type) {
+        case 'SHUTDOWN':
+          this.handleShutdown(message);
+          break;
+        case 'RESTART':
+          this.handleRestart(message);
+          break;
+        case 'STATS_REQUEST':
+          this.handleStatsRequest(message);
+          break;
+        case 'HEALTH_CHECK':
+          this.handleHealthCheck(message);
+          break;
+        default:
+          console.log(`Received unknown message type: ${message.type}`);
+      }
+    });
+  }
+  
+  /**
+   * 处理关闭信号
+   * @param {Object} message - IPC 消息
+   */
+  handleShutdown(message) {
+    console.log(`Worker ${process.pid} received shutdown signal`);
+    
+    if (this.config.gracefulShutdown) {
+      // 执行优雅关闭
+      setTimeout(() => {
+        process.exit(0);
+      }, this.config.shutdownTimeout || 5000);
+    } else {
+      process.exit(0);
+    }
+  }
+  
+  /**
+   * 处理重启信号
+   * @param {Object} message - IPC 消息
+   */
+  handleRestart(message) {
+    console.log(`Worker ${process.pid} received restart signal`);
+    process.exit(1); // 非0退出码会触发重启
+  }
+  
+  /**
+   * 处理统计请求
+   * @param {Object} message - IPC 消息
+   */
+  handleStatsRequest(message) {
+    const stats = {
+      pid: process.pid,
+      memory: process.memoryUsage(),
+      cpu: process.cpuUsage(),
+      uptime: process.uptime(),
+      requests: this.workerManager ? this.workerManager.getRequestCount() : 0
+    };
+    
+    process.send({
+      type: 'STATS_RESPONSE',
+      data: stats
+    });
+  }
+  
+  /**
+   * 处理健康检查
+   * @param {Object} message - IPC 消息
+   */
+  handleHealthCheck(message) {
+    const health = {
+      pid: process.pid,
+      status: 'healthy',
+      timestamp: new Date().toISOString()
+    };
+    
+    process.send({
+      type: 'HEALTH_RESPONSE',
+      data: health
+    });
+  }
+  
+  /**
+   * 启动监控
+   */
+  startMonitoring() {
+    if (this.config.monitoring.enabled) {
+      setInterval(() => {
+        this.healthMonitor.check();
+      }, this.config.monitoring.interval);
+    }
+  }
+  
+  /**
+   * 获取集群管理器
+   * @returns {ClusterManager} 集群管理器实例
+   */
+  getClusterManager() {
+    return this.clusterManager;
+  }
+  
+  /**
+   * 获取工作进程管理器
+   * @returns {WorkerManager} 工作进程管理器实例
+   */
+  getWorkerManager() {
+    return this.workerManager;
+  }
+  
+  /**
+   * 获取健康监控器
+   * @returns {HealthMonitor} 健康监控器实例
+   */
+  getHealthMonitor() {
+    return this.healthMonitor;
+  }
+  
+  /**
+   * 获取负载均衡器
+   * @returns {LoadBalancer} 负载均衡器实例
+   */
+  getLoadBalancer() {
+    return this.loadBalancer;
+  }
+  
+  /**
+   * 获取配置
+   * @returns {Object} 配置对象
+   */
+  getConfig() {
+    return this.config;
+  }
+}
+
+// 导出模块
+export default ClusterModule;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "aetherframework-cluster",
+  "version": "1.0.0",
+  "description": "Aether Framework - Cluster Management Module",
+  "main": "index.js",
+    "type": "module",
+    
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint .",
+    "coverage": "jest --coverage"
+  },
+  "keywords": [
+    "aether",
+    "framework",
+    "cluster",
+    "load-balancing",
+    "scalability"
+  ],
+  "author": "Aether Framework Team",
+  "license": "MIT",
+  "dependencies": {
+    "os": "^0.1.2"
+  },
+  "peerDependencies": {
+    "@aetherframework/core": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aetherjs/aetherframework-cluster.git",
+    "directory": "packages/cluster"
+  },
+  "bugs": {
+    "url": "https://github.com/aetherjs/aetherframework-cluster/issues"
+  },
+  "homepage": "https://github.com/aetherframework/aether-api#readme"
+}

package/src/core/ClusterManager.js

@@ -0,0 +1,109 @@
+// package/cluster/core/ClusterManager.js
+import cluster from 'cluster';
+import EventEmitter from 'events';
+
+export default class ClusterManager extends EventEmitter {
+  constructor(options = {}) {
+    super();
+      
+    // 从环境变量读取配置，提供默认值
+    const defaultWorkers = process.env.CLUSTER_WORKERS === 'auto' ? 
+      os.cpus().length - 1 : // 自动检测CPU核心数，保留1个给系统
+      parseInt(process.env.CLUSTER_WORKERS) || 7;
+    
+    const defaultPort = parseInt(process.env.CLUSTER_PORT) || 3000;
+    const defaultGracefulShutdown = process.env.CLUSTER_GRACEFUL_SHUTDOWN !== 'false';
+    const defaultRestartOnExit = process.env.CLUSTER_RESTART_ON_EXIT !== 'false';
+    const defaultWorkerReusePort = process.env.CLUSTER_WORKER_REUSE_PORT === 'true';
+    const defaultEnableIPC = process.env.CLUSTER_ENABLE_IPC !== 'false';
+    const defaultIpcTimeout = parseInt(process.env.CLUSTER_IPC_TIMEOUT) || 5000;
+    const defaultShutdownTimeout = parseInt(process.env.CLUSTER_SHUTDOWN_TIMEOUT) || 10000;
+    
+    this.options = {
+      workers: defaultWorkers,
+      port: defaultPort,
+      gracefulShutdown: defaultGracefulShutdown,
+      restartOnExit: defaultRestartOnExit,
+      workerReusePort: defaultWorkerReusePort,
+      enableIPC: defaultEnableIPC,
+      ipcTimeout: defaultIpcTimeout,
+      shutdownTimeout: defaultShutdownTimeout,
+      ...options
+    };
+    
+    this.readyCount = 0;
+    this.isShuttingDown = false;
+
+    if (cluster.isPrimary) this.setupMaster();
+  }
+
+    setupMaster() {
+    console.log(`🚀 Master process ${process.pid} is running`);
+    console.log(`📊 Configuration: workers=${this.options.workers}, port=${this.options.port}`);
+    console.log(`⚙️  Settings: gracefulShutdown=${this.options.gracefulShutdown}, restartOnExit=${this.options.restartOnExit}`);
+
+    cluster.on('fork', (worker) => {
+      console.log(`🔄 Worker ${worker.id} (PID: ${worker.process.pid}) forked`);
+    });
+
+    cluster.on('online', (worker) => {
+      console.log(`✅ Worker ${worker.process.pid} is online`);
+    });
+
+    cluster.on('message', (worker, message) => {
+      if (message?.type === 'READY') {
+        this.readyCount++;
+        console.log(`🚀 Worker ${message.pid} is ready (${this.readyCount}/${this.options.workers})`);
+        this.emit('worker:ready', message);
+      }
+    });
+
+    cluster.on('exit', (worker, code) => {
+      console.log(`❌ Worker ${worker.process.pid} exited (${code})`);
+      if (!this.isShuttingDown && this.options.restartOnExit) {
+        console.log(`🔄 Restarting worker ${worker.process.pid}`);
+        cluster.fork({ PORT: this.options.port.toString() });
+      }
+    });
+  }
+
+  start() {
+    if (!cluster.isPrimary) return;
+
+    console.log(`📊 Starting ${this.options.workers} workers on port ${this.options.port}`);
+
+    for (let i = 0; i < this.options.workers; i++) {
+      cluster.fork({ 
+        PORT: this.options.port.toString(),
+        WORKER_ID: i + 1,
+        IS_WORKER: 'true'
+      });
+    }
+
+    return this;
+  }
+  
+  stop() {
+    if (!cluster.isPrimary) return;
+    
+    this.isShuttingDown = true;
+    console.log('⚠️ Received shutdown signal, initiating shutdown...');
+    
+    const workers = Object.values(cluster.workers || {});
+    console.log(`📤 Sending shutdown signal to ${workers.length} workers`);
+    
+    workers.forEach(worker => {
+      if (worker.isConnected()) {
+        worker.send({ type: 'SHUTDOWN' });
+      }
+    });
+    
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        console.log('✅ All workers shut down successfully');
+        console.log('👋 Master process exiting');
+        resolve();
+      }, this.options.shutdownTimeout);
+    });
+  }
+}