aetherframework-cluster 1.0.0

package/src/utils/cpu-detector.js

@@ -0,0 +1,78 @@
+// packages/cluster/src/utils/cpu-detector.js
+import os from 'os';
+
+/**
+ * CPUDetector - Utility class for detecting CPU capabilities and recommending worker counts
+ */
+class CPUDetector {
+  /**
+   * Get detailed CPU information
+   * @returns {Object} CPU information object
+   */
+  static getInfo() {
+    const cpus = os.cpus();
+    
+    return {
+      model: cpus?.model || 'Unknown',
+      speed: cpus?.speed || 0, // in MHz
+      count: cpus.length,
+      architecture: os.arch(),
+      platform: os.platform(),
+      endianness: os.endianness(),
+      loadAvg: os.loadavg(),
+      uptime: os.uptime()
+    };
+  }
+
+  /**
+   * Calculate the optimal number of worker processes
+   * Default strategy: Number of logical cores - 1 (to leave room for the master process)
+   * Minimum 1 worker.
+   * 
+   * @param {Object} options - Configuration options
+   * @param {number} options.reserve - Number of cores to reserve for system/master (default: 1)
+   * @param {number} options.max - Maximum number of workers allowed
+   * @returns {number} Recommended worker count
+   */
+  static getOptimalWorkerCount(options = {}) {
+    const { reserve = 1, max = Infinity } = options;
+    const logicalCores = os.cpus().length;
+    
+    // Calculate base count
+    let count = logicalCores - reserve;
+    
+    // Ensure at least 1 worker
+    if (count < 1) {
+      count = 1;
+    }
+    
+    // Apply maximum limit
+    if (count > max) {
+      count = max;
+    }
+    
+    return count;
+  }
+
+  /**
+   * Check if the current environment supports multi-core clustering
+   * @returns {boolean} True if multi-core is supported
+   */
+  static isMultiCoreSupported() {
+    return os.cpus().length > 1;
+  }
+
+  /**
+   * Get memory information relevant to clustering
+   * @returns {Object} Memory statistics in bytes
+   */
+  static getMemoryInfo() {
+    return {
+      total: os.totalmem(),
+      free: os.freemem(),
+      used: os.totalmem() - os.freemem()
+    };
+  }
+}
+
+export default CPUDetector;

package/src/utils/env-loader.js

@@ -0,0 +1,140 @@
+// packages/cluster/src/utils/env-loader.js
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * 环境变量加载器
+ */
+export function loadEnv() {
+  const env = {};
+  
+  // 默认值
+  const defaults = {
+    CLUSTER_ENABLED: 'true',
+    CLUSTER_WORKERS: 'auto',
+    CLUSTER_PORT: '3000',
+    CLUSTER_GRACEFUL_SHUTDOWN: 'true',
+    CLUSTER_RESTART_ON_EXIT: 'true',
+    CLUSTER_RESTART_DELAY: '1000',
+    CLUSTER_HEALTH_CHECK_ENABLED: 'true',
+    CLUSTER_HEALTH_CHECK_INTERVAL: '30000',
+    CLUSTER_HEALTH_CHECK_TIMEOUT: '5000',
+    CLUSTER_LOAD_BALANCING: 'true',
+    CLUSTER_LOAD_BALANCER_TYPE: 'round-robin',
+    CLUSTER_MAX_REQUESTS_PER_WORKER: '1000',
+    CLUSTER_MONITORING_ENABLED: 'true',
+    CLUSTER_MONITORING_INTERVAL: '10000',
+    CLUSTER_MEMORY_THRESHOLD: '0.8',
+    CLUSTER_CPU_THRESHOLD: '0.7',
+    CLUSTER_LOG_LEVEL: 'info',
+    CLUSTER_LOG_FORMAT: 'json',
+    CLUSTER_WORKER_REUSE_PORT: 'true',
+    CLUSTER_ENABLE_IPC: 'true',
+    CLUSTER_IPC_TIMEOUT: '5000',
+    CLUSTER_ENABLE_SECURITY: 'true',
+    CLUSTER_MAX_MEMORY: '512',
+    CLUSTER_MAX_OLD_SPACE_SIZE: '4096',
+    CLUSTER_DEBUG: 'false',
+    CLUSTER_DEBUG_PORT: '9229',
+    CLUSTER_INSPECT: 'false',
+    CLUSTER_ENABLE_HOT_RELOAD: 'false',
+    CLUSTER_ENABLE_PROFILING: 'false',
+    CLUSTER_PROFILING_INTERVAL: '60000'
+  };
+  
+  // 从 process.env 加载
+  for (const [key, defaultValue] of Object.entries(defaults)) {
+    env[key] = process.env[key] || defaultValue;
+  }
+  
+  // 尝试从 .env 文件加载
+  try {
+    const envPath = join(process.cwd(), '.env');
+    const envContent = readFileSync(envPath, 'utf8');
+    const envLines = envContent.split('\n');
+    
+    for (const line of envLines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#')) {
+        const [key, ...valueParts] = trimmed.split('=');
+        if (key && valueParts.length > 0) {
+          const value = valueParts.join('=').trim();
+          // 移除引号
+          const cleanValue = value.replace(/^['"]|['"]$/g, '');
+          env[key.trim()] = cleanValue;
+        }
+      }
+    }
+  } catch (error) {
+    // .env 文件不存在，使用默认值
+  }
+  
+  // 类型转换
+  const booleanKeys = [
+    'CLUSTER_ENABLED',
+    'CLUSTER_GRACEFUL_SHUTDOWN',
+    'CLUSTER_RESTART_ON_EXIT',
+    'CLUSTER_HEALTH_CHECK_ENABLED',
+    'CLUSTER_LOAD_BALANCING',
+    'CLUSTER_MONITORING_ENABLED',
+    'CLUSTER_WORKER_REUSE_PORT',
+    'CLUSTER_ENABLE_IPC',
+    'CLUSTER_ENABLE_SECURITY',
+    'CLUSTER_DEBUG',
+    'CLUSTER_INSPECT',
+    'CLUSTER_ENABLE_HOT_RELOAD',
+    'CLUSTER_ENABLE_PROFILING'
+  ];
+  
+  const numberKeys = [
+    'CLUSTER_PORT',
+    'CLUSTER_RESTART_DELAY',
+    'CLUSTER_HEALTH_CHECK_INTERVAL',
+    'CLUSTER_HEALTH_CHECK_TIMEOUT',
+    'CLUSTER_MAX_REQUESTS_PER_WORKER',
+    'CLUSTER_MONITORING_INTERVAL',
+    'CLUSTER_IPC_TIMEOUT',
+    'CLUSTER_MAX_MEMORY',
+    'CLUSTER_MAX_OLD_SPACE_SIZE',
+    'CLUSTER_DEBUG_PORT',
+    'CLUSTER_PROFILING_INTERVAL'
+  ];
+  
+  const floatKeys = [
+    'CLUSTER_MEMORY_THRESHOLD',
+    'CLUSTER_CPU_THRESHOLD'
+  ];
+  
+  // 转换布尔值
+  for (const key of booleanKeys) {
+    if (env[key] !== undefined) {
+      env[key] = env[key] === 'true' || env[key] === '1';
+    }
+  }
+  
+  // 转换数字
+  for (const key of numberKeys) {
+    if (env[key] !== undefined) {
+      env[key] = parseInt(env[key], 10);
+    }
+  }
+  
+  // 转换浮点数
+  for (const key of floatKeys) {
+    if (env[key] !== undefined) {
+      env[key] = parseFloat(env[key]);
+    }
+  }
+  
+  // 处理 workers 参数
+  if (env.CLUSTER_WORKERS === 'auto') {
+    env.CLUSTER_WORKERS = 'auto';
+  } else {
+    env.CLUSTER_WORKERS = parseInt(env.CLUSTER_WORKERS, 10);
+  }
+  
+  return env;
+}
+
+// 导出默认实例
+export default { loadEnv };

package/src/utils/signal-handler.js

@@ -0,0 +1,90 @@
+// packages/cluster/src/utils/signal-handler.js
+import process from 'process';
+
+/**
+ * SignalHandler - Manages OS signals for graceful shutdown and restart
+ */
+class SignalHandler {
+  constructor() {
+    this.handlers = new Map();
+    this.isShuttingDown = false;
+  }
+
+  /**
+   * Register a handler for a specific signal
+   * @param {string} signal - Signal name (e.g., 'SIGINT', 'SIGTERM')
+   * @param {Function} callback - Async function to execute on signal
+   */
+  on(signal, callback) {
+    if (!this.handlers.has(signal)) {
+      this.handlers.set(signal, []);
+      
+      // Attach the listener to the process only once per signal type
+      process.on(signal, async () => {
+        if (this.isShuttingDown && signal !== 'SIGHUP') {
+          console.warn(`Received ${signal} while already shutting down. Forcing exit.`);
+          process.exit(1);
+          return;
+        }
+
+        if (signal !== 'SIGHUP') {
+          this.isShuttingDown = true;
+        }
+
+        console.log(`\n📡 Received signal: ${signal}`);
+        
+        const callbacks = this.handlers.get(signal);
+        try {
+          // Execute all registered handlers in parallel
+          await Promise.all(callbacks.map(cb => cb()));
+        } catch (error) {
+          console.error(`Error handling signal ${signal}:`, error);
+        } finally {
+          // Only exit on termination signals, not SIGHUP (reload)
+          if (signal !== 'SIGHUP') {
+            console.log('✅ Graceful shutdown complete.');
+            process.exit(0);
+          }
+        }
+      });
+    }
+    
+    this.handlers.get(signal).push(callback);
+  }
+
+  /**
+   * Setup default handlers for common termination signals
+   * @param {Function} shutdownCallback - Optional global shutdown logic
+   */
+  setupDefaults(shutdownCallback) {
+    // Handle Ctrl+C
+    this.on('SIGINT', async () => {
+      if (shutdownCallback) await shutdownCallback();
+    });
+
+    // Handle kill command
+    this.on('SIGTERM', async () => {
+      if (shutdownCallback) await shutdownCallback();
+    });
+
+    // Handle uncaught exceptions to prevent silent crashes
+    process.on('uncaughtException', (err) => {
+      console.error('💥 Uncaught Exception:', err.message);
+      console.error(err.stack);
+      // Attempt graceful shutdown on critical error
+      if (shutdownCallback) {
+        shutdownCallback().finally(() => process.exit(1));
+      } else {
+        process.exit(1);
+      }
+    });
+
+    // Handle unhandled promise rejections
+    process.on('unhandledRejection', (reason, promise) => {
+      console.error('⚠️ Unhandled Rejection at:', promise, 'reason:', reason);
+    });
+  }
+}
+
+// Export singleton instance
+export default new SignalHandler();