claw-dashboard 1.9.0 → 2.1.0

package/src/alerts.js

@@ -0,0 +1,693 @@
+/**
+ * Alert notifications module for Claw Dashboard
+ * Monitors system metrics (CPU, memory, disk) against configurable thresholds
+ * and provides visual notifications in the Dashboard UI
+ */
+
+import logger from './logger.js';
+import config from './config.js';
+import { getCurrentTheme } from './themes.js';
+import process from 'process';
+
+// Default threshold configurations (normalized to lowercase keys)
+const DEFAULT_THRESHOLDS = {
+  cpu: { warning: config.ALERT_THRESHOLDS.CPU.warning, critical: config.ALERT_THRESHOLDS.CPU.critical },
+  memory: { warning: config.ALERT_THRESHOLDS.MEMORY.warning, critical: config.ALERT_THRESHOLDS.MEMORY.critical },
+  disk: { warning: config.ALERT_THRESHOLDS.DISK.warning, critical: config.ALERT_THRESHOLDS.DISK.critical }
+};
+
+// Alert levels
+const AlertLevel = {
+  INFO: 'info',
+  WARNING: 'warning',
+  CRITICAL: 'critical',
+  CLEARED: 'cleared'
+};
+
+// Sound notification configuration
+let soundConfig = {
+  enabled: false,
+  soundType: 'bell', // 'bell' = terminal bell, 'beep' = system beep
+  warningEnabled: true,
+  criticalEnabled: true
+};
+
+// Alert state storage
+let alerts = [];
+let thresholds = { ...DEFAULT_THRESHOLDS };
+let alertHistory = [];
+const MAX_HISTORY = config.MAX_ALERT_HISTORY;
+
+// Rate limiting configuration
+const DEFAULT_RATE_LIMIT = config.ALERT_RATE_LIMIT;
+
+// Rate limiting state (normalized to lowercase keys matching tests)
+let rateLimit = {
+  enabled: config.ALERT_RATE_LIMIT.ENABLED,
+  windowMs: config.ALERT_RATE_LIMIT.WINDOW_MS,
+  maxAlerts: config.ALERT_RATE_LIMIT.MAX_ALERTS
+};
+let alertTimestamps = {};  // Track timestamps per alert type: { cpu: [ts1, ts2, ...] }
+
+/**
+ * Check if alert should be rate-limited
+ * @param {string} type - Alert type (cpu, memory, disk)
+ * @returns {boolean} True if alert should be suppressed
+ */
+function shouldRateLimitAlert(type) {
+  if (!rateLimit.enabled) {
+    return false;
+  }
+
+  const now = Date.now();
+  const timestamps = alertTimestamps[type] || [];
+
+  // Clean up old timestamps outside the window
+  const validTimestamps = timestamps.filter(ts => now - ts < rateLimit.windowMs);
+
+  // Check if we've exceeded the max alerts in this window
+  if (validTimestamps.length >= rateLimit.maxAlerts) {
+    logger.debug(`[RATE LIMIT] Alert for ${type} suppressed - rate limit exceeded (${validTimestamps.length}/${rateLimit.maxAlerts} in ${rateLimit.windowMs}ms)`);
+    return true;
+  }
+
+  // Update timestamps array (cleanup only, actual recording happens in recordAlertTimestamp)
+  alertTimestamps[type] = validTimestamps;
+
+  return false;
+}
+
+/**
+ * Record an alert timestamp for rate limiting
+ * @param {string} type - Alert type
+ */
+function recordAlertTimestamp(type) {
+  if (!rateLimit.enabled) {
+    return;
+  }
+  
+  if (!alertTimestamps[type]) {
+    alertTimestamps[type] = [];
+  }
+  alertTimestamps[type].push(Date.now());
+}
+
+/**
+ * Set rate limiting configuration
+ * @param {object} config - Rate limit configuration
+ */
+function setRateLimit(config) {
+  rateLimit = { ...rateLimit, ...config };
+  logger.info(`Rate limiting updated: enabled=${rateLimit.enabled}, window=${rateLimit.windowMs}ms, max=${rateLimit.maxAlerts}`);
+}
+
+/**
+ * Get current rate limiting configuration
+ * @returns {object} Current rate limit config
+ */
+function getRateLimit() {
+  return { ...rateLimit };
+}
+
+/**
+ * Reset rate limiting state (useful for testing)
+ */
+function resetRateLimit() {
+  alertTimestamps = {};
+  rateLimit = { 
+    enabled: config.ALERT_RATE_LIMIT.ENABLED,
+    windowMs: config.ALERT_RATE_LIMIT.WINDOW_MS,
+    maxAlerts: config.ALERT_RATE_LIMIT.MAX_ALERTS
+  };
+}
+
+/**
+ * Create a new alert object
+ * @param {string} type - Alert type (cpu, memory, disk)
+ * @param {string} level - Alert level (info, warning, critical)
+ * @param {number} value - Current value
+ * @param {number} threshold - Threshold that was exceeded
+ * @returns {object} Alert object
+ */
+function createAlert(type, level, value, threshold) {
+  return {
+    id: `${type}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+    type,
+    level,
+    value,
+    threshold,
+    timestamp: new Date().toISOString(),
+    message: getAlertMessage(type, level, value, threshold),
+    dismissed: false
+  };
+}
+
+/**
+ * Generate alert message based on type and level
+ */
+function getAlertMessage(type, level, value, threshold) {
+  const typeNames = {
+    cpu: 'CPU usage',
+    memory: 'Memory usage',
+    disk: 'Disk usage'
+  };
+  
+  const levelNames = {
+    info: 'Information',
+    warning: 'Warning',
+    critical: 'Critical',
+    cleared: 'Resolved'
+  };
+  
+  if (level === AlertLevel.CLEARED) {
+    return `${typeNames[type]} normalized (${value}% - was above ${threshold}%)`;
+  }
+  
+  return `${levelNames[level]}: ${typeNames[type]} at ${value}% (threshold: ${threshold}%)`;
+}
+
+/**
+ * Check a metric against thresholds and create alert if needed
+ * @param {string} type - Metric type (cpu, memory, disk)
+ * @param {number} value - Current value (0-100)
+ * @returns {object|null} New alert if created, null otherwise
+ */
+function checkThreshold(type, value) {
+  if (!thresholds[type]) {
+    logger.warn(`Unknown alert type: ${type}`);
+    return null;
+  }
+
+  const { warning, critical } = thresholds[type];
+  const existingAlert = alerts.find(a => a.type === type && !a.dismissed);
+
+  // Check for critical level
+  if (value >= critical) {
+    if (!existingAlert || existingAlert.level !== AlertLevel.CRITICAL) {
+      // Use RateLimiter.checkAndRecord for atomic check and record
+      const rateLimitResult = thresholdRateLimiter.checkAndRecord(type, AlertLevel.CRITICAL);
+      if (rateLimitResult.allowed) {
+        const alert = createAlert(type, AlertLevel.CRITICAL, value, critical);
+        addAlert(alert);
+        return alert;
+      }
+    }
+    // Update existing alert if it exists and is already critical
+    if (existingAlert) {
+      existingAlert.value = value;
+      existingAlert.timestamp = new Date().toISOString();
+    }
+    return null;
+  }
+
+  // Check for warning level
+  if (value >= warning) {
+    if (!existingAlert || existingAlert.level === AlertLevel.CLEARED) {
+      // Use RateLimiter.checkAndRecord for atomic check and record
+      const rateLimitResult = thresholdRateLimiter.checkAndRecord(type, AlertLevel.WARNING);
+      if (rateLimitResult.allowed) {
+        const alert = createAlert(type, AlertLevel.WARNING, value, warning);
+        addAlert(alert);
+        return alert;
+      }
+    }
+    // Update existing alert if it exists
+    if (existingAlert) {
+      existingAlert.value = value;
+      existingAlert.timestamp = new Date().toISOString();
+    }
+    return null;
+  }
+
+  // Value below threshold - clear existing alert
+  if (existingAlert) {
+    // Always allow cleared alerts through
+    const clearedAlert = createAlert(type, AlertLevel.CLEARED, value, existingAlert.threshold);
+    dismissAlert(existingAlert.id);
+    addAlert(clearedAlert);
+    return clearedAlert;
+  }
+
+  return null;
+}
+
+/**
+ * Play sound notification for alert
+ * @param {string} level - Alert level
+ */
+function playAlertSound(level) {
+  if (!soundConfig.enabled) {
+    return;
+  }
+
+  // Check if sound is enabled for this level
+  if (level === AlertLevel.WARNING && !soundConfig.warningEnabled) {
+    return;
+  }
+  if (level === AlertLevel.CRITICAL && !soundConfig.criticalEnabled) {
+    return;
+  }
+
+  try {
+    if (soundConfig.soundType === 'bell') {
+      // Terminal bell character
+      process.stdout.write('\x07');
+    } else if (soundConfig.soundType === 'beep') {
+      // Multiple bells for critical
+      const count = level === AlertLevel.CRITICAL ? 3 : 1;
+      process.stdout.write('\x07'.repeat(count));
+    }
+  } catch (err) {
+    logger.debug(`Failed to play sound: ${err.message}`);
+  }
+}
+
+/**
+ * Set sound notification configuration
+ * @param {object} config - Sound configuration
+ */
+function setSoundConfig(config) {
+  soundConfig = { ...soundConfig, ...config };
+  logger.info(`Sound notifications: enabled=${soundConfig.enabled}, type=${soundConfig.soundType}`);
+}
+
+/**
+ * Get current sound configuration
+ * @returns {object} Current sound config
+ */
+function getSoundConfig() {
+  return { ...soundConfig };
+}
+
+/**
+ * Toggle sound notifications
+ * @param {boolean} enabled - Enable or disable
+ */
+function toggleSound(enabled) {
+  soundConfig.enabled = enabled;
+  logger.info(`Sound notifications ${enabled ? 'enabled' : 'disabled'}`);
+}
+
+/**
+ * Add an alert to the active alerts list and history
+ */
+function addAlert(alert) {
+  // Remove duplicates of same type
+  alerts = alerts.filter(a => a.type !== alert.type || a.dismissed);
+  alerts.push(alert);
+
+  // Add to history
+  alertHistory.push(alert);
+  if (alertHistory.length > MAX_HISTORY) {
+    alertHistory = alertHistory.slice(-MAX_HISTORY);
+  }
+
+  // Play sound for warning and critical alerts (not cleared)
+  if (alert.level === AlertLevel.WARNING || alert.level === AlertLevel.CRITICAL) {
+    playAlertSound(alert.level);
+  }
+
+  logger.info(`[ALERT] ${alert.message}`);
+}
+
+/**
+ * Dismiss an active alert
+ * @param {string} id - Alert ID to dismiss
+ */
+function dismissAlert(id) {
+  const alert = alerts.find(a => a.id === id);
+  if (alert) {
+    alert.dismissed = true;
+    alert.timestamp = new Date().toISOString();
+  }
+}
+
+/**
+ * Get all active (non-dismissed) alerts
+ * @returns {object[]} Active alerts
+ */
+function getActiveAlerts() {
+  return alerts.filter(a => !a.dismissed);
+}
+
+/**
+ * Get all alerts of a specific level
+ * @param {string} level - Alert level to filter
+ * @returns {object[]} Filtered alerts
+ */
+function getAlertsByLevel(level) {
+  return alerts.filter(a => a.level === level && !a.dismissed);
+}
+
+/**
+ * Get alert history
+ * @returns {object[]} Alert history
+ */
+function getAlertHistory() {
+  return [...alertHistory];
+}
+
+/**
+ * Clear all alerts
+ */
+function clearAllAlerts() {
+  alerts.forEach(a => a.dismissed = true);
+}
+
+/**
+ * Set custom thresholds
+ * @param {object} newThresholds - New threshold configuration
+ */
+function setThresholds(newThresholds) {
+  if (newThresholds.cpu) {
+    thresholds.cpu = { ...thresholds.cpu, ...newThresholds.cpu };
+  }
+  if (newThresholds.memory) {
+    thresholds.memory = { ...thresholds.memory, ...newThresholds.memory };
+  }
+  if (newThresholds.disk) {
+    thresholds.disk = { ...thresholds.disk, ...newThresholds.disk };
+  }
+  logger.info(`Alert thresholds updated: CPU ${thresholds.cpu.warning}/${thresholds.cpu.critical}%, Memory ${thresholds.memory.warning}/${thresholds.memory.critical}%, Disk ${thresholds.disk.warning}/${thresholds.disk.critical}%`);
+}
+
+/**
+ * Get current thresholds
+ * @returns {object} Current thresholds
+ */
+function getThresholds() {
+  return { ...thresholds };
+}
+
+/**
+ * Reset thresholds to defaults
+ */
+function resetThresholds() {
+  thresholds = { ...DEFAULT_THRESHOLDS };
+  logger.info('Alert thresholds reset to defaults');
+}
+
+/**
+ * Check all system metrics and generate alerts
+ * @param {object} metrics - Object with cpu, memory, disk values
+ * @returns {object[]} Array of new alerts generated
+ */
+function checkAllMetrics(metrics) {
+  const newAlerts = [];
+  
+  if (metrics && metrics.cpu !== undefined) {
+    const alert = checkThreshold('cpu', metrics.cpu);
+    if (alert) newAlerts.push(alert);
+  }
+  
+  if (metrics && metrics.memory !== undefined) {
+    const alert = checkThreshold('memory', metrics.memory);
+    if (alert) newAlerts.push(alert);
+  }
+  
+  if (metrics && metrics.disk !== undefined) {
+    const alert = checkThreshold('disk', metrics.disk);
+    if (alert) newAlerts.push(alert);
+  }
+  
+  return newAlerts;
+}
+
+/**
+ * Get alert color based on level and current theme
+ * @param {string} level - Alert level
+ * @returns {string} Color name
+ */
+function getAlertColor(level) {
+  const theme = getCurrentTheme();
+  const colorMap = {
+    [AlertLevel.INFO]: theme.colors.alert?.info || 'cyan',
+    [AlertLevel.WARNING]: theme.colors.alert?.warning || 'yellow',
+    [AlertLevel.CRITICAL]: theme.colors.alert?.error || 'red',
+    [AlertLevel.CLEARED]: theme.colors.alert?.success || 'green'
+  };
+  return colorMap[level] || 'white';
+}
+
+/**
+ * Format alert for display in UI
+ * @param {object} alert - Alert object
+ * @returns {string} Formatted string
+ */
+function formatAlert(alert) {
+  const color = getAlertColor(alert.level);
+  const icon = getAlertIcon(alert.level);
+  return `{${color}-fg}${icon} ${alert.message}{/}`;
+}
+
+/**
+ * Get icon for alert level
+ */
+function getAlertIcon(level) {
+  const icons = {
+    [AlertLevel.INFO]: 'ℹ',
+    [AlertLevel.WARNING]: '⚠',
+    [AlertLevel.CRITICAL]: '✖',
+    [AlertLevel.CLEARED]: '✓'
+  };
+  return icons[level] || '•';
+}
+
+/**
+ * Get count of active alerts by level
+ * @returns {object} Counts by level
+ */
+function getAlertCounts() {
+  const active = getActiveAlerts();
+  return {
+    info: active.filter(a => a.level === AlertLevel.INFO).length,
+    warning: active.filter(a => a.level === AlertLevel.WARNING).length,
+    critical: active.filter(a => a.level === AlertLevel.CRITICAL).length,
+    total: active.length
+  };
+}
+
+/**
+ * RateLimiter - Higher-level API for alert rate limiting
+ * Provides a cleaner interface for managing rate-limited alerts
+ */
+class RateLimiter {
+  /**
+   * Create a RateLimiter instance
+   * @param {object} options - Configuration options
+   * @param {boolean} options.enabled - Enable rate limiting (default: true)
+   * @param {number} options.windowMs - Time window in milliseconds (default: 60000)
+   * @param {number} options.maxAlerts - Max alerts per window (default: 5)
+   * @param {boolean} options.alwaysAllowCritical - Always allow critical alerts (default: true)
+   */
+  constructor(options = {}) {
+    this.enabled = options.enabled ?? rateLimit.enabled;
+    this.windowMs = options.windowMs ?? rateLimit.windowMs;
+    this.maxAlerts = options.maxAlerts ?? rateLimit.maxAlerts;
+    this.alwaysAllowCritical = options.alwaysAllowCritical ?? true;
+    this.timestamps = {}; // { type: [ts1, ts2, ...] }
+
+    // Sync with global rate limit config
+    setRateLimit({
+      enabled: this.enabled,
+      windowMs: this.windowMs,
+      maxAlerts: this.maxAlerts
+    });
+  }
+
+  /**
+   * Check if an alert should be allowed or rate-limited
+   * @param {string} type - Alert type (cpu, memory, disk)
+   * @param {string} [level] - Alert level (critical, warning, info)
+   * @returns {object} Result with allowed boolean and reason
+   */
+  check(type, level = 'warning') {
+    // If rate limiting is disabled, allow all
+    if (!this.enabled) {
+      return { allowed: true, reason: 'rate_limiting_disabled' };
+    }
+
+    // Always allow critical alerts if configured
+    if (this.alwaysAllowCritical && level === 'critical') {
+      return { allowed: true, reason: 'critical_always_allowed' };
+    }
+
+    // Use the underlying function for the check
+    const shouldLimit = shouldRateLimitAlert(type);
+    if (shouldLimit) {
+      return { allowed: false, reason: 'rate_limit_exceeded' };
+    }
+
+    return { allowed: true, reason: 'ok' };
+  }
+
+  /**
+   * Record an alert occurrence after it's been allowed
+   * @param {string} type - Alert type
+   * @param {string} [level] - Alert level
+   */
+  record(type, level = 'warning') {
+    // Don't record if disabled
+    if (!this.enabled) {
+      return;
+    }
+
+    this._addTimestamp(type);
+    recordAlertTimestamp(type);
+  }
+
+  /**
+   * Internal method to add timestamp
+   * @private
+   */
+  _addTimestamp(type) {
+    if (!this.timestamps[type]) {
+      this.timestamps[type] = [];
+    }
+    this.timestamps[type].push(Date.now());
+  }
+
+  /**
+   * Get the count of alerts in current window for a type
+   * @param {string} type - Alert type
+   * @returns {number} Current count
+   */
+  getCount(type) {
+    const timestamps = this.timestamps[type] || [];
+    const now = Date.now();
+    const valid = timestamps.filter(ts => now - ts < this.windowMs);
+    return valid.length;
+  }
+
+  /**
+   * Get time until next alert is allowed for a type
+   * @param {string} type - Alert type
+   * @returns {number} Milliseconds until next alert, or 0 if allowed now
+   */
+  getRetryAfter(type) {
+    const timestamps = this.timestamps[type] || [];
+    if (timestamps.length === 0) {
+      return 0;
+    }
+
+    const now = Date.now();
+    const valid = timestamps.filter(ts => now - ts < this.windowMs);
+
+    if (valid.length < this.maxAlerts) {
+      return 0;
+    }
+
+    // Return oldest timestamp + window - now
+    const oldest = Math.min(...valid);
+    return Math.max(0, (oldest + this.windowMs) - now);
+  }
+
+  /**
+   * Get status of rate limiter
+   * @returns {object} Status object
+   */
+  getStatus() {
+    const now = Date.now();
+    const types = Object.keys(this.timestamps);
+
+    const typeStatus = {};
+    for (const type of types) {
+      const valid = this.timestamps[type].filter(ts => now - ts < this.windowMs);
+      typeStatus[type] = {
+        current: valid.length,
+        max: this.maxAlerts,
+        retryAfter: valid.length >= this.maxAlerts ? this.getRetryAfter(type) : 0
+      };
+    }
+
+    return {
+      enabled: this.enabled,
+      windowMs: this.windowMs,
+      maxAlerts: this.maxAlerts,
+      alwaysAllowCritical: this.alwaysAllowCritical,
+      types: typeStatus
+    };
+  }
+
+  /**
+   * Update configuration
+   * @param {object} options - New options
+   */
+  configure(options) {
+    if (options.enabled !== undefined) this.enabled = options.enabled;
+    if (options.windowMs !== undefined) this.windowMs = options.windowMs;
+    if (options.maxAlerts !== undefined) this.maxAlerts = options.maxAlerts;
+    if (options.alwaysAllowCritical !== undefined) this.alwaysAllowCritical = options.alwaysAllowCritical;
+
+    // Sync with global config
+    setRateLimit({
+      enabled: this.enabled,
+      windowMs: this.windowMs,
+      maxAlerts: this.maxAlerts
+    });
+  }
+
+  /**
+   * Reset all timestamps (clear rate limit state)
+   */
+  reset() {
+    this.timestamps = {};
+    resetRateLimit();
+  }
+
+  /**
+   * Create a combined check-and-record operation
+   * Use this for the common pattern of checking then recording
+   * @param {string} type - Alert type
+   * @param {string} [level] - Alert level
+   * @returns {object} Result with allowed boolean and reason; if allowed, also records the alert
+   */
+  checkAndRecord(type, level = 'warning') {
+    const result = this.check(type, level);
+    if (result.allowed) {
+      this.record(type, level);
+    }
+    return result;
+  }
+}
+
+// Rate limiter instance for alert throttling
+// Uses the cleaner checkAndRecord API for atomic check-and-record operations
+const thresholdRateLimiter = new RateLimiter({ alwaysAllowCritical: true });
+
+// Default rate limiter instance
+const defaultRateLimiter = new RateLimiter();
+
+export default {
+  AlertLevel,
+  checkThreshold,
+  checkAllMetrics,
+  dismissAlert,
+  getActiveAlerts,
+  getAlertsByLevel,
+  getAlertHistory,
+  getAlertCounts,
+  getAlertColor,
+  formatAlert,
+  setThresholds,
+  getThresholds,
+  resetThresholds,
+  clearAllAlerts,
+  // Rate limiting exports
+  setRateLimit,
+  getRateLimit,
+  resetRateLimit,
+  shouldRateLimitAlert,
+  recordAlertTimestamp,
+  // Higher-level RateLimiter API
+  RateLimiter,
+  defaultRateLimiter,
+  // Sound notification exports
+  setSoundConfig,
+  getSoundConfig,
+  toggleSound,
+  playAlertSound
+};
+
+// Named export for plugin API use
+export { RateLimiter };