aetherframework-cluster 1.0.0

package/src/middleware/worker-stats.js

@@ -0,0 +1,879 @@
+// packages/cluster/src/middleware/worker-stats.js
+import { EventEmitter } from 'events';
+
+/**
+ * Worker Statistics Middleware - Provides detailed worker statistics and monitoring endpoints
+ * This middleware adds endpoints to monitor individual worker performance and cluster statistics
+ */
+class WorkerStatsMiddleware extends EventEmitter {
+  constructor(workerManager, options = {}) {
+    super();
+    
+    this.workerManager = workerManager;
+    this.options = {
+      path: options.path || '/cluster/stats',
+      auth: options.auth || null,
+      rateLimit: options.rateLimit || { windowMs: 60000, max: 60 },
+      cacheDuration: options.cacheDuration || 5000, // 5 seconds
+      includeDetails: options.includeDetails !== false,
+      ...options
+    };
+    
+    this.statsCache = null;
+    this.cacheTimestamp = 0;
+    this.requestCounts = new Map();
+  }
+  
+  /**
+   * Get middleware function for HTTP framework integration
+   * @returns {Function} Middleware function
+   */
+  middleware() {
+    return async (ctx, next) => {
+      // Only handle stats routes
+      if (!ctx.path.startsWith(this.options.path)) {
+        return next();
+      }
+      
+      // Check authentication if required
+      if (this.options.auth && !this.checkAuth(ctx)) {
+        ctx.status = 401;
+        ctx.body = {
+          status: 'error',
+          message: 'Unauthorized',
+          timestamp: new Date().toISOString()
+        };
+        return;
+      }
+      
+      // Check rate limiting
+      if (!this.checkRateLimit(ctx)) {
+        ctx.status = 429;
+        ctx.body = {
+          status: 'error',
+          message: 'Too many requests',
+          timestamp: new Date().toISOString(),
+          retryAfter: Math.ceil(this.options.rateLimit.windowMs / 1000)
+        };
+        return;
+      }
+      
+      try {
+        // Handle different stats endpoints
+        if (ctx.path === this.options.path) {
+          await this.handleAllStats(ctx);
+        } else if (ctx.path === `${this.options.path}/workers`) {
+          await this.handleWorkersStats(ctx);
+        } else if (ctx.path === `${this.options.path}/workers/:pid`) {
+          await this.handleWorkerStats(ctx);
+        } else if (ctx.path === `${this.options.path}/cluster`) {
+          await this.handleClusterStats(ctx);
+        } else if (ctx.path === `${this.options.path}/metrics`) {
+          await this.handleMetrics(ctx);
+        } else if (ctx.path === `${this.options.path}/health`) {
+          await this.handleHealthStats(ctx);
+        } else {
+          ctx.status = 404;
+          ctx.body = {
+            status: 'error',
+            message: 'Stats endpoint not found',
+            timestamp: new Date().toISOString()
+          };
+        }
+      } catch (error) {
+        console.error('Worker stats middleware error:', error);
+        
+        ctx.status = 500;
+        ctx.body = {
+          status: 'error',
+          timestamp: new Date().toISOString(),
+          message: 'Failed to get worker statistics',
+          error: error.message,
+          stack: process.env.NODE_ENV === 'development' ? error.stack : undefined
+        };
+      }
+    };
+  }
+  
+  /**
+   * Handle request for all statistics
+   * @param {Object} ctx - Context object
+   */
+  async handleAllStats(ctx) {
+    const now = Date.now();
+    const useCache = ctx.query.nocache !== 'true' && 
+                    (now - this.cacheTimestamp) < this.options.cacheDuration;
+    
+    let stats;
+    if (useCache && this.statsCache) {
+      stats = this.statsCache;
+    } else {
+      stats = await this.getAllStats();
+      this.statsCache = stats;
+      this.cacheTimestamp = now;
+    }
+    
+    // Add response headers
+    ctx.set('X-Stats-Cache', useCache ? 'HIT' : 'MISS');
+    ctx.set('X-Stats-Timestamp', new Date().toISOString());
+    ctx.set('X-Stats-Version', '1.0.0');
+    
+    ctx.status = 200;
+    ctx.body = {
+      status: 'success',
+      timestamp: new Date().toISOString(),
+      cache: useCache,
+      ...stats
+    };
+  }
+  
+  /**
+   * Handle request for workers statistics
+   * @param {Object} ctx - Context object
+   */
+  async handleWorkersStats(ctx) {
+    const workers = this.workerManager.getAllWorkerStats();
+    const query = ctx.query || {};
+    
+    // Apply filters if provided
+    let filteredWorkers = workers;
+    
+    // Filter by state
+    if (query.state) {
+      filteredWorkers = filteredWorkers.filter(w => w.state === query.state);
+    }
+    
+    // Filter by health status
+    if (query.healthy === 'true') {
+      filteredWorkers = filteredWorkers.filter(w => w.isAlive && w.errorRate < 10);
+    } else if (query.healthy === 'false') {
+      filteredWorkers = filteredWorkers.filter(w => !w.isAlive || w.errorRate >= 10);
+    }
+    
+    // Filter by minimum uptime
+    if (query.minUptime) {
+      const minUptime = parseInt(query.minUptime, 10);
+      filteredWorkers = filteredWorkers.filter(w => w.uptime >= minUptime);
+    }
+    
+    // Filter by maximum error rate
+    if (query.maxErrorRate) {
+      const maxErrorRate = parseFloat(query.maxErrorRate);
+      filteredWorkers = filteredWorkers.filter(w => w.errorRate <= maxErrorRate);
+    }
+    
+    // Sort workers
+    if (query.sort) {
+      const [field, order] = query.sort.split(':');
+      const sortOrder = order === 'desc' ? -1 : 1;
+      
+      filteredWorkers.sort((a, b) => {
+        if (a[field] < b[field]) return -1 * sortOrder;
+        if (a[field] > b[field]) return 1 * sortOrder;
+        return 0;
+      });
+    }
+    
+    // Pagination
+    const page = parseInt(query.page) || 1;
+    const limit = parseInt(query.limit) || 20;
+    const start = (page - 1) * limit;
+    const end = start + limit;
+    const paginatedWorkers = filteredWorkers.slice(start, end);
+    
+    // Calculate summary
+    const summary = {
+      total: workers.length,
+      filtered: filteredWorkers.length,
+      active: workers.filter(w => w.state === 'active').length,
+      ready: workers.filter(w => w.state === 'ready').length,
+      idle: workers.filter(w => w.state === 'idle').length,
+      dead: workers.filter(w => !w.isAlive).length,
+      totalRequests: workers.reduce((sum, w) => sum + w.requests, 0),
+      totalErrors: workers.reduce((sum, w) => sum + w.errors, 0),
+      averageErrorRate: workers.length > 0 ? 
+        workers.reduce((sum, w) => sum + parseFloat(w.errorRate), 0) / workers.length : 0
+    };
+    
+    ctx.status = 200;
+    ctx.body = {
+      status: 'success',
+      timestamp: new Date().toISOString(),
+      summary,
+      pagination: {
+        page,
+        limit,
+        total: filteredWorkers.length,
+        pages: Math.ceil(filteredWorkers.length / limit),
+        hasNext: end < filteredWorkers.length,
+        hasPrev: page > 1
+      },
+      workers: paginatedWorkers.map(worker => this.formatWorkerStats(worker, query.details === 'true'))
+    };
+  }
+  
+  /**
+   * Handle request for single worker statistics
+   * @param {Object} ctx - Context object
+   */
+  async handleWorkerStats(ctx) {
+    const pid = parseInt(ctx.params.pid);
+    
+    if (isNaN(pid)) {
+      ctx.status = 400;
+      ctx.body = {
+        status: 'error',
+        message: 'Invalid worker PID',
+        timestamp: new Date().toISOString()
+      };
+      return;
+    }
+    
+    const worker = this.workerManager.getWorkerByPid(pid);
+    
+    if (!worker) {
+      ctx.status = 404;
+      ctx.body = {
+        status: 'error',
+        message: `Worker with PID ${pid} not found`,
+        timestamp: new Date().toISOString()
+      };
+      return;
+    }
+    
+    const stats = this.workerManager.getWorkerStats(pid);
+    const health = this.workerManager.checkWorkerHealth(pid);
+    const load = this.workerManager.getWorkerLoad(pid);
+    const restartCount = this.workerManager.getRestartCount(pid);
+    
+    const response = {
+      status: 'success',
+      timestamp: new Date().toISOString(),
+      worker: {
+        pid: worker.pid,
+        workerId: worker.id,
+        state: worker.state,
+        metadata: worker.metadata,
+        startTime: worker.startTime,
+        lastHeartbeat: worker.lastHeartbeat,
+        isAlive: this.workerManager.isWorkerAlive(pid)
+      },
+      stats: this.formatWorkerStats(stats, ctx.query.details === 'true'),
+      health,
+      performance: {
+        load,
+        restartCount,
+        shouldRestart: this.workerManager.shouldRestartWorker(pid),
+        lastRequestTime: stats.lastRequestTime,
+        requestsPerMinute: this.calculateRequestsPerMinute(pid)
+      }
+    };
+    
+    // Add detailed metrics if requested
+    if (ctx.query.details === 'true') {
+      response.detailed = {
+        connections: this.workerManager.getAllWorkerLoads().get(pid) || 0,
+        lastError: stats.lastError,
+        uptime: Date.now() - worker.startTime,
+        memoryUsage: stats.memoryUsage,
+        cpuUsage: stats.cpuUsage,
+        environment: process.env.NODE_ENV || 'development',
+        nodeVersion: process.version,
+        platform: process.platform,
+        arch: process.arch
+      };
+    }
+    
+    ctx.status = 200;
+    ctx.body = response;
+  }
+  
+  /**
+   * Handle request for cluster statistics
+   * @param {Object} ctx - Context object
+   */
+  async handleClusterStats(ctx) {
+    const clusterStats = this.workerManager.getClusterStats();
+    const metrics = this.workerManager.getMetrics();
+    
+    const response = {
+      status: 'success',
+      timestamp: new Date().toISOString(),
+      cluster: {
+        ...clusterStats,
+        workersByState: this.workerManager.groupWorkersByState(this.workerManager.getAllWorkerStats())
+      },
+      metrics: {
+        ...metrics,
+        currentTime: Date.now(),
+        system: {
+          memory: process.memoryUsage(),
+          cpu: process.cpuUsage(),
+          uptime: process.uptime(),
+          platform: process.platform,
+          arch: process.arch,
+          nodeVersion: process.version
+        }
+      },
+      recommendations: this.getClusterRecommendations(clusterStats)
+    };
+    
+    // Add historical data if available
+    if (ctx.query.history === 'true') {
+      response.history = this.getHistoricalStats();
+    }
+    
+    ctx.status = 200;
+    ctx.body = response;
+  }
+  
+  /**
+   * Handle request for metrics
+   * @param {Object} ctx - Context object
+   */
+  async handleMetrics(ctx) {
+    const format = ctx.query.format || 'json';
+    
+    if (format === 'prometheus') {
+      await this.handlePrometheusMetrics(ctx);
+      return;
+    }
+    
+    const workers = this.workerManager.getAllWorkerStats();
+    const clusterStats = this.workerManager.getClusterStats();
+    const metrics = this.workerManager.getMetrics();
+    
+    const response = {
+      status: 'success',
+      timestamp: new Date().toISOString(),
+      metrics: {
+        // Worker metrics
+        worker_count: workers.length,
+        worker_active: workers.filter(w => w.state === 'active').length,
+        worker_ready: workers.filter(w => w.state === 'ready').length,
+        worker_idle: workers.filter(w => w.state === 'idle').length,
+        worker_dead: workers.filter(w => !w.isAlive).length,
+        
+        // Performance metrics
+        total_requests: metrics.totalRequests,
+        total_errors: metrics.totalErrors,
+        total_restarts: metrics.totalRestarts,
+        error_rate: clusterStats.performance.errorRate,
+        average_requests_per_worker: clusterStats.performance.averageRequestsPerWorker,
+        average_load_per_worker: clusterStats.performance.averageLoadPerWorker,
+        
+        // System metrics
+        system_uptime: process.uptime(),
+        cluster_uptime: metrics.uptime / 1000, // Convert to seconds
+        memory_usage: process.memoryUsage().heapUsed,
+        memory_total: process.memoryUsage().heapTotal,
+        memory_ratio: process.memoryUsage().heapUsed / process.memoryUsage().heapTotal,
+        
+        // Timestamps
+        current_timestamp: Date.now(),
+        start_timestamp: metrics.startTime
+      },
+      workers: workers.map(worker => ({
+        pid: worker.pid,
+        worker_id: worker.workerId,
+        state: worker.state,
+        uptime: worker.uptime,
+        requests: worker.requests,
+        errors: worker.errors,
+        error_rate: worker.errorRate,
+        load: worker.load,
+        is_alive: worker.isAlive,
+        last_request_time: worker.lastRequestTime
+      }))
+    };
+    
+    ctx.status = 200;
+    ctx.body = response;
+  }
+  
+  /**
+   * Handle request for Prometheus metrics format
+   * @param {Object} ctx - Context object
+   */
+  async handlePrometheusMetrics(ctx) {
+    const workers = this.workerManager.getAllWorkerStats();
+    const clusterStats = this.workerManager.getClusterStats();
+    const metrics = this.workerManager.getMetrics();
+    
+    let prometheusMetrics = '';
+    
+    // Worker metrics
+    prometheusMetrics += `# HELP worker_count Total number of workers\n`;
+    prometheusMetrics += `# TYPE worker_count gauge\n`;
+    prometheusMetrics += `worker_count ${workers.length}\n\n`;
+    
+    prometheusMetrics += `# HELP worker_active Number of active workers\n`;
+    prometheusMetrics += `# TYPE worker_active gauge\n`;
+    prometheusMetrics += `worker_active ${workers.filter(w => w.state === 'active').length}\n\n`;
+    
+    prometheusMetrics += `# HELP worker_ready Number of ready workers\n`;
+    prometheusMetrics += `# TYPE worker_ready gauge\n`;
+    prometheusMetrics += `worker_ready ${workers.filter(w => w.state === 'ready').length}\n\n`;
+    
+    prometheusMetrics += `# HELP worker_idle Number of idle workers\n`;
+    prometheusMetrics += `# TYPE worker_idle gauge\n`;
+    prometheusMetrics += `worker_idle ${workers.filter(w => w.state === 'idle').length}\n\n`;
+    
+    // Performance metrics
+    prometheusMetrics += `# HELP total_requests Total number of requests\n`;
+    prometheusMetrics += `# TYPE total_requests counter\n`;
+    prometheusMetrics += `total_requests ${metrics.totalRequests}\n\n`;
+    
+    prometheusMetrics += `# HELP total_errors Total number of errors\n`;
+    prometheusMetrics += `# TYPE total_errors counter\n`;
+    prometheusMetrics += `total_errors ${metrics.totalErrors}\n\n`;
+    
+    prometheusMetrics += `# HELP error_rate Error rate percentage\n`;
+    prometheusMetrics += `# TYPE error_rate gauge\n`;
+    prometheusMetrics += `error_rate ${clusterStats.performance.errorRate}\n\n`;
+    
+    // System metrics
+    const memoryUsage = process.memoryUsage();
+    prometheusMetrics += `# HELP memory_usage_bytes Memory usage in bytes\n`;
+    prometheusMetrics += `# TYPE memory_usage_bytes gauge\n`;
+    prometheusMetrics += `memory_usage_bytes ${memoryUsage.heapUsed}\n\n`;
+    
+    prometheusMetrics += `# HELP memory_total_bytes Total memory in bytes\n`;
+    prometheusMetrics += `# TYPE memory_total_bytes gauge\n`;
+    prometheusMetrics += `memory_total_bytes ${memoryUsage.heapTotal}\n\n`;
+    
+    // Worker-specific metrics
+    for (const worker of workers) {
+      prometheusMetrics += `# HELP worker_requests_total Total requests per worker\n`;
+      prometheusMetrics += `# TYPE worker_requests_total counter\n`;
+      prometheusMetrics += `worker_requests_total{pid="${worker.pid}",worker_id="${worker.workerId}"} ${worker.requests}\n\n`;
+      
+      prometheusMetrics += `# HELP worker_errors_total Total errors per worker\n`;
+      prometheusMetrics += `# TYPE worker_errors_total counter\n`;
+      prometheusMetrics += `worker_errors_total{pid="${worker.pid}",worker_id="${worker.workerId}"} ${worker.errors}\n\n`;
+      
+      prometheusMetrics += `# HELP worker_uptime_seconds Worker uptime in seconds\n`;
+      prometheusMetrics += `# TYPE worker_uptime_seconds gauge\n`;
+      prometheusMetrics += `worker_uptime_seconds{pid="${worker.pid}",worker_id="${worker.workerId}"} ${worker.uptime}\n\n`;
+      
+      prometheusMetrics += `# HELP worker_load_current Current worker load\n`;
+      prometheusMetrics += `# TYPE worker_load_current gauge\n`;
+      prometheusMetrics += `worker_load_current{pid="${worker.pid}",worker_id="${worker.workerId}"} ${worker.load}\n\n`;
+    }
+    
+    ctx.set('Content-Type', 'text/plain; version=0.0.4');
+    ctx.status = 200;
+    ctx.body = prometheusMetrics;
+  }
+  
+  /**
+   * Handle request for health statistics
+   * @param {Object} ctx - Context object
+   */
+  async handleHealthStats(ctx) {
+    const workers = this.workerManager.getAllWorkerStats();
+    const clusterStats = this.workerManager.getClusterStats();
+    
+    const healthStatus = {
+      status: 'healthy',
+      timestamp: new Date().toISOString(),
+      checks: []
+    };
+    
+    // Check worker availability
+    const activeWorkers = workers.filter(w => w.state === 'active' || w.state === 'ready').length;
+    if (activeWorkers === 0) {
+      healthStatus.status = 'critical';
+      healthStatus.checks.push({
+        name: 'worker_availability',
+        status: 'critical',
+        message: 'No active workers available'
+      });
+    } else if (activeWorkers < workers.length * 0.5) {
+      healthStatus.status = 'degraded';
+      healthStatus.checks.push({
+        name: 'worker_availability',
+        status: 'degraded',
+        message: `Less than 50% of workers active: ${activeWorkers}/${workers.length}`
+      });
+    } else {
+      healthStatus.checks.push({
+        name: 'worker_availability',
+        status: 'healthy',
+        message: `${activeWorkers}/${workers.length} workers active`
+      });
+    }
+    
+    // Check error rate
+    const totalRequests = workers.reduce((sum, w) => sum + w.requests, 0);
+    const totalErrors = workers.reduce((sum, w) => sum + w.errors, 0);
+    const errorRate = totalRequests > 0 ? (totalErrors / totalRequests) * 100 : 0;
+    
+    if (errorRate > 10) {
+      healthStatus.status = healthStatus.status === 'healthy' ? 'degraded' : healthStatus.status;
+      healthStatus.checks.push({
+        name: 'error_rate',
+        status: 'degraded',
+        message: `High error rate: ${errorRate.toFixed(2)}%`
+      });
+    } else {
+      healthStatus.checks.push({
+        name: 'error_rate',
+        status: 'healthy',
+        message: `Error rate: ${errorRate.toFixed(2)}%`
+      });
+    }
+    
+    // Check memory usage
+    const memoryUsage = process.memoryUsage();
+    const memoryRatio = memoryUsage.heapUsed / memoryUsage.heapTotal;
+    
+    if (memoryRatio > 0.8) {
+      healthStatus.status = healthStatus.status === 'healthy' ? 'degraded' : healthStatus.status;
+      healthStatus.checks.push({
+        name: 'memory_usage',
+        status: 'degraded',
+        message: `High memory usage: ${(memoryRatio * 100).toFixed(1)}%`
+      });
+    } else {
+      healthStatus.checks.push({
+        name: 'memory_usage',
+        status: 'healthy',
+        message: `Memory usage: ${(memoryRatio * 100).toFixed(1)}%`
+      });
+    }
+    
+    // Check worker health
+    const unhealthyWorkers = workers.filter(w => !w.isAlive || w.errorRate >= 10);
+    if (unhealthyWorkers.length > 0) {
+      healthStatus.status = healthStatus.status === 'healthy' ? 'degraded' : healthStatus.status;
+      healthStatus.checks.push({
+        name: 'worker_health',
+        status: 'degraded',
+        message: `${unhealthyWorkers.length} unhealthy workers`,
+        details: unhealthyWorkers.map(w => ({
+          pid: w.pid,
+          errorRate: w.errorRate,
+          isAlive: w.isAlive
+        }))
+      });
+    } else {
+      healthStatus.checks.push({
+        name: 'worker_health',
+        status: 'healthy',
+        message: 'All workers healthy'
+      });
+    }
+    
+    // Add summary
+    healthStatus.summary = {
+      totalWorkers: workers.length,
+      activeWorkers,
+      unhealthyWorkers: unhealthyWorkers.length,
+      totalRequests,
+      totalErrors,
+      errorRate: errorRate.toFixed(2),
+      memoryUsage: `${(memoryRatio * 100).toFixed(1)}%`,
+      uptime: Math.floor(process.uptime())
+    };
+    
+    ctx.status = healthStatus.status === 'healthy' ? 200 : 
+                 healthStatus.status === 'degraded' ? 200 : 503;
+    ctx.body = healthStatus;
+  }
+  
+  /**
+   * Get all statistics
+   * @returns {Object} Complete statistics object
+   */
+  async getAllStats() {
+    const workers = this.workerManager.getAllWorkerStats();
+    const clusterStats = this.workerManager.getClusterStats();
+    const metrics = this.workerManager.getMetrics();
+    
+    return {
+      workers: workers.map(worker => this.formatWorkerStats(worker)),
+      cluster: clusterStats,
+      metrics,
+      system: {
+        memory: process.memoryUsage(),
+        cpu: process.cpuUsage(),
+        uptime: process.uptime(),
+        platform: process.platform,
+        arch: process.arch,
+        version: process.version,
+        pid: process.pid,
+        isWorker: !process.env.isPrimary,
+        workerId: process.env.workerId || 'master'
+      },
+      timestamp: new Date().toISOString(),
+      version: '1.0.0'
+    };
+  }
+  
+  /**
+   * Format worker statistics for response
+   * @param {Object} stats - Worker statistics
+   * @param {boolean} includeDetails - Whether to include detailed information
+   * @returns {Object} Formatted statistics
+   */
+  formatWorkerStats(stats, includeDetails = false) {
+    const formatted = {
+      pid: stats.pid,
+      workerId: stats.workerId,
+      state: stats.state,
+      uptime: stats.uptime,
+      requests: stats.requests,
+      errors: stats.errors,
+      errorRate: stats.errorRate,
+      load: stats.load,
+      isAlive: stats.isAlive,
+      lastRequestTime: stats.lastRequestTime,
+      restartCount: stats.restartCount,
+      health: this.getWorkerHealthStatus(stats)
+    };
+    
+    if (includeDetails) {
+      formatted.details = {
+        memoryUsage: stats.memoryUsage,
+        cpuUsage: stats.cpuUsage,
+        lastHeartbeat: stats.lastHeartbeat,
+        metadata: stats.metadata,
+        lastError: stats.lastError,
+        environment: process.env.NODE_ENV || 'development'
+      };
+    }
+    
+    return formatted;
+  }
+  
+  /**
+   * Get worker health status
+   * @param {Object} stats - Worker statistics
+   * @returns {string} Health status
+   */
+  getWorkerHealthStatus(stats) {
+    if (!stats.isAlive) {
+      return 'dead';
+    }
+    
+    if (parseFloat(stats.errorRate) >= 10) {
+      return 'unhealthy';
+    }
+    
+    if (stats.state === 'active' || stats.state === 'ready') {
+      return 'healthy';
+    }
+    
+    if (stats.state === 'idle') {
+      return 'idle';
+    }
+    
+    return 'unknown';
+  }
+  
+  /**
+   * Calculate requests per minute for a worker
+   * @param {number} pid - Worker PID
+   * @returns {number} Requests per minute
+   */
+  calculateRequestsPerMinute(pid) {
+    const stats = this.workerManager.getWorkerStats(pid);
+    if (!stats || !stats.lastRequestTime) {
+      return 0;
+    }
+    
+    const now = Date.now();
+    const timeSinceLastRequest = (now - stats.lastRequestTime) / 1000 / 60; // Convert to minutes
+    
+    if (timeSinceLastRequest === 0) {
+      return 0;
+    }
+    
+    return stats.requests / timeSinceLastRequest;
+  }
+  
+  /**
+   * Get cluster recommendations
+   * @param {Object} clusterStats - Cluster statistics
+   * @returns {Array} Recommendations
+   */
+  getClusterRecommendations(clusterStats) {
+    const recommendations = [];
+    
+    // Check idle worker ratio
+    const idleRatio = clusterStats.workers.idle / clusterStats.workers.total;
+    if (idleRatio > 0.7) {
+      recommendations.push({
+        type: 'optimization',
+        priority: 'low',
+        message: 'High idle worker ratio',
+        suggestion: 'Consider reducing the number of workers to save resources',
+        details: `Idle workers: ${clusterStats.workers.idle}/${clusterStats.workers.total}`
+      });
+    }
+    
+    // Check if all workers are active and fewer than CPU cores
+    const cpuCount = require('os').cpus().length;
+    if (clusterStats.workers.active === clusterStats.workers.total && 
+        clusterStats.workers.total < cpuCount) {
+      recommendations.push({
+        type: 'scaling',
+        priority: 'medium',
+        message: 'All workers are active',
+        suggestion: `Consider increasing the number of workers to ${cpuCount} (CPU cores)`,
+        details: `Current: ${clusterStats.workers.total}, CPU cores: ${cpuCount}`
+      });
+    }
+    
+    // Check error rate
+    if (parseFloat(clusterStats.performance.errorRate) > 10) {
+      recommendations.push({
+        type: 'performance',
+        priority: 'high',
+        message: 'High error rate detected',
+        suggestion: 'Investigate application logs and error handling',
+        details: `Error rate: ${clusterStats.performance.errorRate}%`
+      });
+    }
+    
+    // Check worker restarts
+    if (clusterStats.performance.totalRestarts > 0) {
+      recommendations.push({
+        type: 'stability',
+        priority: 'medium',
+        message: 'Worker restarts detected',
+        suggestion: 'Monitor worker stability and investigate restart causes',
+        details: `Total restarts: ${clusterStats.performance.totalRestarts}`
+      });
+    }
+    
+    return recommendations;
+  }
+  
+  /**
+   * Get historical statistics
+   * @returns {Array} Historical stats
+   */
+  getHistoricalStats() {
+    // In a real implementation, this would fetch from a database or cache
+    // For now, return empty array
+    return [];
+  }
+  
+  /**
+   * Check authentication
+   * @param {Object} ctx - Context object
+   * @returns {boolean} Authentication status
+   */
+  checkAuth(ctx) {
+    if (typeof this.options.auth === 'function') {
+      return this.options.auth(ctx);
+    }
+    
+    if (typeof this.options.auth === 'object') {
+      // Check API key
+      if (this.options.auth.apiKey) {
+        const apiKey = ctx.headers['x-api-key'] || ctx.query.apiKey;
+        return apiKey === this.options.auth.apiKey;
+      }
+      
+      // Check basic auth
+      if (this.options.auth.username && this.options.auth.password) {
+        const authHeader = ctx.headers.authorization;
+        if (!authHeader || !authHeader.startsWith('Basic ')) {
+          return false;
+        }
+        
+        const credentials = Buffer.from(authHeader.slice(6), 'base64').toString();
+        const [username, password] = credentials.split(':');
+        return username === this.options.auth.username && password === this.options.auth.password;
+      }
+    }
+    
+    return true; // No auth required
+  }
+  
+  /**
+   * Check rate limiting
+   * @param {Object} ctx - Context object
+   * @returns {boolean} Rate limit status
+   */
+  checkRateLimit(ctx) {
+    if (!this.options.rateLimit) {
+      return true;
+    }
+    
+    const clientIp = ctx.ip || ctx.request.ip;
+    const now = Date.now();
+    const windowMs = this.options.rateLimit.windowMs;
+    const max = this.options.rateLimit.max;
+    
+    if (!this.requestCounts.has(clientIp)) {
+      this.requestCounts.set(clientIp, {
+        count: 1,
+        resetTime: now + windowMs
+      });
+      return true;
+    }
+    
+    const clientData = this.requestCounts.get(clientIp);
+    
+    // Reset if window has passed
+    if (now > clientData.resetTime) {
+      clientData.count = 1;
+      clientData.resetTime = now + windowMs;
+      return true;
+    }
+    
+    // Check if limit exceeded
+    if (clientData.count >= max) {
+      return false;
+    }
+    
+    clientData.count++;
+    return true;
+  }
+  
+  /**
+   * Clear rate limit cache
+   */
+  clearRateLimitCache() {
+    const now = Date.now();
+    for (const [ip, data] of this.requestCounts.entries()) {
+      if (now > data.resetTime) {
+        this.requestCounts.delete(ip);
+      }
+    }
+  }
+  
+  /**
+   * Get middleware configuration
+   * @returns {Object} Middleware configuration
+   */
+  getConfig() {
+    return {
+      ...this.options,
+      cacheEnabled: this.options.cacheDuration > 0,
+      rateLimitEnabled: !!this.options.rateLimit,
+      authEnabled: !!this.options.auth
+    };
+  }
+  
+  /**
+   * Clear statistics cache
+   */
+  clearCache() {
+    this.statsCache = null;
+    this.cacheTimestamp = 0;
+  }
+  
+  /**
+   * Reset rate limiting
+   */
+  resetRateLimit() {
+    this.requestCounts.clear();
+  }
+}
+
+export default WorkerStatsMiddleware;