claw-dashboard 1.9.0 → 2.0.0

package/src/cache.js

@@ -0,0 +1,390 @@
+/**
+ * Cache module with TTL support for system metrics
+ * Provides caching for expensive systeminformation calls
+ * Supports worker threads for heavy operations
+ */
+
+import config from './config.js';
+import logger from './logger.js';
+
+// Worker pool for heavy operations (lazy-loaded)
+let workerPool = null;
+
+/**
+ * Get the worker pool instance (lazy initialization)
+ * @returns {Object|null} Worker pool instance or null if not available
+ */
+async function getWorkerPool() {
+  if (!config.WORKERS?.ENABLED) {
+    return null;
+  }
+
+  if (!workerPool) {
+    try {
+      const { default: pool } = await import('./workers/worker-pool.js');
+      workerPool = pool;
+    } catch (error) {
+      logger.debug('Worker pool not available:', error.message);
+      return null;
+    }
+  }
+
+  return workerPool;
+}
+
+// In-memory cache store
+const cache = new Map();
+
+/**
+ * Cache configuration for different data types
+ */
+// Use CACHE_CONFIG from config.js
+
+/**
+ * Get a cached value if still valid
+ * @param {string} key - Cache key
+ * @returns {any|null} Cached value or null if expired/missing
+ */
+export function get(key) {
+  const entry = cache.get(key);
+  if (!entry) return null;
+  
+  if (Date.now() > entry.expiresAt) {
+    cache.delete(key);
+    return null;
+  }
+  
+  return entry.value;
+}
+
+/**
+ * Set a cached value with TTL
+ * @param {string} key - Cache key
+ * @param {any} value - Value to cache
+ * @param {number} ttl - Time to live in milliseconds (optional, uses config default)
+ */
+export function set(key, value, ttl) {
+  const cacheTtlConfig = config.CACHE_CONFIG[key] || { ttl: config.CACHE_TTL.DEFAULT };
+  const actualTtl = ttl || cacheTtlConfig.ttl;
+  
+  cache.set(key, {
+    value,
+    expiresAt: Date.now() + actualTtl,
+    createdAt: Date.now(),
+  });
+}
+
+/**
+ * Get or fetch data with caching
+ * @param {string} key - Cache key
+ * @param {Function} fetcher - Async function to fetch data if cache miss
+ * @param {number} ttl - Optional TTL override
+ * @returns {Promise<any>} Cached or fresh data
+ */
+export async function getOrFetch(key, fetcher, ttl) {
+  const cached = get(key);
+  if (cached !== null) {
+    return cached;
+  }
+  
+  const data = await fetcher();
+  set(key, data, ttl);
+  return data;
+}
+
+/**
+ * Execute a systeminformation command via worker thread or fallback
+ * @param {string} command - Worker command name
+ * @param {Function} fallbackFn - Fallback function for direct execution
+ * @returns {Promise<any>} Command result
+ */
+async function executeWithWorker(command, fallbackFn) {
+  const pool = await getWorkerPool();
+  if (pool) {
+    try {
+      return await pool.execute(command);
+    } catch (error) {
+      logger.debug(`Worker execution failed for ${command}, using fallback: ${error.message}`);
+    }
+  }
+  return fallbackFn();
+}
+
+/**
+ * Get cached CPU data or fetch fresh
+ * Uses worker threads when available to avoid blocking the UI
+ * @returns {Promise<Object>} CPU load data
+ */
+export async function getCpuData() {
+  return getOrFetch('cpu', async () => {
+    try {
+      // Add 2 second timeout for CPU data
+      const timeoutMs = 2000;
+      const fetchPromise = executeWithWorker('currentLoad', async () => {
+        const si = await import('systeminformation');
+        return await si.currentLoad();
+      });
+      const timeoutPromise = new Promise((_, reject) => 
+        setTimeout(() => reject(new Error('CPU data timeout')), timeoutMs)
+      );
+      return await Promise.race([fetchPromise, timeoutPromise]);
+    } catch (e) {
+      logger.warn(`systeminformation.currentLoad() failed: ${e.message}`);
+      throw e;
+    }
+  });
+}
+
+/**
+ * Get cached memory data or fetch fresh
+ * Uses worker threads when available to avoid blocking the UI
+ * @returns {Promise<Object>} Memory data
+ */
+export async function getMemoryData() {
+  return getOrFetch('memory', async () => {
+    try {
+      // Add 2 second timeout for memory data
+      const timeoutMs = 2000;
+      const fetchPromise = executeWithWorker('mem', async () => {
+        const si = await import('systeminformation');
+        return await si.mem();
+      });
+      const timeoutPromise = new Promise((_, reject) => 
+        setTimeout(() => reject(new Error('Memory data timeout')), timeoutMs)
+      );
+      return await Promise.race([fetchPromise, timeoutPromise]);
+    } catch (e) {
+      logger.warn(`systeminformation.mem() failed: ${e.message}`);
+      throw e;
+    }
+  });
+}
+
+/**
+ * Get cached GPU data or fetch fresh
+ * Uses worker threads when available to avoid blocking the UI
+ * @returns {Promise<Object>} GPU/graphics data
+ */
+export async function getGpuData() {
+  return getOrFetch('gpu', async () => {
+    try {
+      return await executeWithWorker('graphics', async () => {
+        const si = await import('systeminformation');
+        return await si.graphics();
+      });
+    } catch (e) {
+      logger.warn(`systeminformation.graphics() failed: ${e.message}`);
+      throw e;
+    }
+  });
+}
+
+/**
+ * Get cached network data or fetch fresh
+ * Uses worker threads when available to avoid blocking the UI
+ * Falls back to empty array on timeout (non-critical data)
+ * @returns {Promise<Object>} Network stats data
+ */
+export async function getNetworkData() {
+  return getOrFetch('network', async () => {
+    try {
+      // Add timeout wrapper for network stats
+      const timeoutMs = 2000; // 2 second timeout
+      const fetchPromise = executeWithWorker('networkStats', async () => {
+        const si = await import('systeminformation');
+        return await si.networkStats();
+      });
+      
+      const timeoutPromise = new Promise((_, reject) => 
+        setTimeout(() => reject(new Error('Network stats timeout')), timeoutMs)
+      );
+      
+      return await Promise.race([fetchPromise, timeoutPromise]);
+    } catch (e) {
+      logger.warn(`Network data fetch failed or timed out: ${e.message}`);
+      // Return empty array - network stats are nice-to-have, not critical
+      return [];
+    }
+  });
+}
+
+/**
+ * Get cached disk data or fetch fresh
+ * Uses worker threads when available to avoid blocking the UI
+ * @returns {Promise<Object>} Disk size data
+ */
+export async function getDiskData() {
+  return getOrFetch('disk', async () => {
+    try {
+      return await executeWithWorker('fsSize', async () => {
+        const si = await import('systeminformation');
+        return await si.fsSize();
+      });
+    } catch (e) {
+      logger.warn(`systeminformation.fsSize() failed: ${e.message}`);
+      throw e;
+    }
+  });
+}
+
+/**
+ * Get cached system info data or fetch fresh
+ * Uses native os module and short-circuit for speed
+ * System info rarely changes, so we cache aggressively
+ * @returns {Promise<Object>} System info (osInfo, versions, time)
+ */
+export async function getSystemData() {
+  return getOrFetch('system', async () => {
+    try {
+      // Use native os module for faster results
+      const os = await import('os');
+      
+      // Build system data from native os module (much faster than systeminformation)
+      const systemData = {
+        os: {
+          platform: os.platform(),
+          distro: os.type(),
+          release: os.release(),
+          arch: os.arch(),
+        },
+        ver: {
+          node: process.version,
+        },
+        time: {
+          uptime: os.uptime(),
+        }
+      };
+      
+      // Try to get more detailed info via worker (non-blocking)
+      // This runs in background and updates cache if successful
+      executeWithWorker('systemData', async () => {
+        const si = await import('systeminformation');
+        const [osInfo, versions, time] = await Promise.all([
+          si.osInfo(),
+          si.versions(),
+          si.time(),
+        ]);
+        return { os: osInfo, ver: versions, time };
+      }).then(detailedData => {
+        // Update cache with detailed data in background
+        set('system', detailedData);
+      }).catch(() => {
+        // Ignore errors - we already have basic data
+      });
+      
+      return systemData;
+    } catch (e) {
+      logger.warn(`System data fetch failed: ${e.message}`);
+      throw e;
+    }
+  });
+}
+
+/**
+ * Force refresh a specific cache entry
+ * @param {string} key - Cache key to refresh
+ */
+export function invalidate(key) {
+  cache.delete(key);
+}
+
+/**
+ * Clear all cache entries
+ */
+export function clear() {
+  cache.clear();
+}
+
+/**
+ * Get cache status for debugging
+ * @returns {Object} Cache status info
+ */
+export function getStatus() {
+  const now = Date.now();
+  const status = {};
+  
+  for (const [key, entry] of cache) {
+    const remaining = Math.max(0, entry.expiresAt - now);
+    status[key] = {
+      cached: true,
+      age: now - entry.createdAt,
+      ttlRemaining: remaining,
+      configTtl: config.CACHE_CONFIG[key]?.ttl || config.CACHE_TTL.DEFAULT,
+    };
+  }
+  
+  return status;
+}
+
+/**
+ * Debounce utility for rapid key presses
+ * @param {Function} fn - Function to debounce
+ * @param {number} delay - Delay in milliseconds
+ * @returns {Function} Debounced function
+ */
+export function debounce(fn, delay) {
+  let timeoutId = null;
+  let lastArgs = null;
+  
+  return function(...args) {
+    lastArgs = args;
+    
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    
+    timeoutId = setTimeout(() => {
+      fn.apply(this, lastArgs);
+      timeoutId = null;
+    }, delay);
+  };
+}
+
+/**
+ * Throttle utility for rate limiting
+ * @param {Function} fn - Function to throttle
+ * @param {number} limit - Minimum interval between calls in ms
+ * @returns {Function} Throttled function
+ */
+export function throttle(fn, limit) {
+  let lastCall = 0;
+  let timeoutId = null;
+  
+  return function(...args) {
+    const now = Date.now();
+    const remaining = limit - (now - lastCall);
+    
+    if (remaining <= 0) {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      lastCall = now;
+      fn.apply(this, args);
+    } else if (!timeoutId) {
+      timeoutId = setTimeout(() => {
+        lastCall = Date.now();
+        timeoutId = null;
+        fn.apply(this, args);
+      }, remaining);
+    }
+  };
+}
+
+export default {
+  get,
+  set,
+  getOrFetch,
+  getCpuData,
+  getMemoryData,
+  getGpuData,
+  getNetworkData,
+  getDiskData,
+  getSystemData,
+  invalidate,
+  clear,
+  getStatus,
+  debounce,
+  throttle,
+  CACHE_CONFIG: config.CACHE_CONFIG,
+};

package/src/checksum.js

@@ -0,0 +1,146 @@
+/**
+ * Checksum verification utilities for OpenClaw gateway responses
+ * Provides integrity verification for data received from gateway endpoints
+ */
+
+import crypto from 'crypto';
+import config from './config.js';
+import logger from './logger.js';
+
+/**
+ * Supported hash algorithms
+ * @typedef {'sha256' | 'sha512' | 'md5'} HashAlgorithm
+ */
+
+const SUPPORTED_ALGORITHMS = ['sha256', 'sha512', 'md5'];
+
+/**
+ * Compute checksum of data using specified algorithm
+ * @param {string|Buffer} data - Data to compute checksum for
+ * @param {HashAlgorithm} [algorithm] - Hash algorithm to use (defaults to config)
+ * @returns {string} - Computed checksum in hex format
+ */
+export function computeChecksum(data, algorithm = null) {
+  const algo = algorithm || config.CHECKSUM.ALGORITHM;
+
+  if (!SUPPORTED_ALGORITHMS.includes(algo)) {
+    throw new Error(`Unsupported hash algorithm: ${algo}. Supported: ${SUPPORTED_ALGORITHMS.join(', ')}`);
+  }
+
+  const hash = crypto.createHash(algo);
+  hash.update(data);
+  return hash.digest('hex');
+}
+
+/**
+ * Verify response checksum against computed checksum
+ * @param {string|Buffer} data - Response body data
+ * @param {string} expectedChecksum - Expected checksum from header
+ * @param {HashAlgorithm} [algorithm] - Hash algorithm to use
+ * @returns {boolean} - True if checksums match
+ */
+export function verifyChecksum(data, expectedChecksum, algorithm = null) {
+  if (!expectedChecksum) {
+    return false;
+  }
+
+  try {
+    const computed = computeChecksum(data, algorithm);
+    // Use timing-safe comparison to prevent timing attacks
+    return crypto.timingSafeEqual(
+      Buffer.from(computed, 'hex'),
+      Buffer.from(expectedChecksum, 'hex')
+    );
+  } catch (err) {
+    logger.debug(`Checksum verification failed: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Verify HTTP response checksum from header
+ * @param {http.IncomingMessage} response - HTTP response object
+ * @param {string} responseBody - Response body as string
+ * @returns {{verified: boolean, checksum: string|null, error: string|null}} - Verification result
+ */
+export function verifyResponseChecksum(response, responseBody) {
+  if (!config.CHECKSUM.ENABLED) {
+    return { verified: true, checksum: null, error: null };
+  }
+
+  const headerName = config.CHECKSUM.HEADER_NAME.toLowerCase();
+  const expectedChecksum = response.headers[headerName];
+
+  // Check if response has checksum header
+  if (!expectedChecksum) {
+    if (config.CHECKSUM.STRICT_MODE) {
+      return {
+        verified: false,
+        checksum: null,
+        error: `Missing ${config.CHECKSUM.HEADER_NAME} header (strict mode enabled)`
+      };
+    }
+    // Non-strict mode: accept responses without checksum
+    return { verified: true, checksum: null, error: null };
+  }
+
+  // Validate checksum format (hex string)
+  const checksumStr = Array.isArray(expectedChecksum) ? expectedChecksum[0] : expectedChecksum;
+  if (!/^[a-f0-9]+$/i.test(checksumStr)) {
+    return {
+      verified: false,
+      checksum: checksumStr,
+      error: 'Invalid checksum format: expected hex string'
+    };
+  }
+
+  // Verify checksum
+  const isValid = verifyChecksum(responseBody, checksumStr);
+
+  if (!isValid) {
+    return {
+      verified: false,
+      checksum: checksumStr,
+      error: 'Checksum mismatch: computed checksum does not match header'
+    };
+  }
+
+  return { verified: true, checksum: checksumStr, error: null };
+}
+
+/**
+ * Get checksum metadata for logging/debugging
+ * @param {http.IncomingMessage} response - HTTP response object
+ * @returns {Object} - Checksum metadata
+ */
+export function getChecksumMetadata(response) {
+  const headerName = config.CHECKSUM.HEADER_NAME.toLowerCase();
+  const checksum = response.headers[headerName];
+
+  return {
+    algorithm: config.CHECKSUM.ALGORITHM,
+    headerName: config.CHECKSUM.HEADER_NAME,
+    headerPresent: !!checksum,
+    checksum: checksum || null,
+    strictMode: config.CHECKSUM.STRICT_MODE,
+    enabled: config.CHECKSUM.ENABLED,
+  };
+}
+
+/**
+ * Check if an error is a checksum verification failure
+ * @param {Error} error - Error to check
+ * @returns {boolean} - True if checksum verification error
+ */
+export function isChecksumError(error) {
+  return error && error.code === 'CHECKSUM_ERROR';
+}
+
+export default {
+  computeChecksum,
+  verifyChecksum,
+  verifyResponseChecksum,
+  getChecksumMetadata,
+  isChecksumError,
+  SUPPORTED_ALGORITHMS,
+};

package/src/cli/args.js

@@ -0,0 +1,110 @@
+/**
+ * CLI Argument Parsing Module
+ * Handles parsing of command-line arguments for Claw Dashboard
+ */
+
+import config from '../config.js';
+
+/**
+ * Parse command-line arguments
+ * @returns {Object} Parsed CLI options
+ */
+export function parseCliArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    help: false,
+    version: false,
+    debug: false,
+    web: false,
+    webPort: config.WEB.DEFAULT_PORT,
+    webHost: config.WEB.HOST,
+    watch: false,
+    watchPlugins: false,
+    command: null,
+    commandArgs: [],
+  };
+
+  // Check for commands first
+  if (args.length > 0 && !args[0].startsWith('-')) {
+    const firstArg = args[0];
+    if (firstArg === 'create-plugin') {
+      options.command = 'create-plugin';
+      options.commandArgs = args.slice(1);
+      return options;
+    }
+    if (firstArg === 'validate-plugin') {
+      options.command = 'validate-plugin';
+      options.commandArgs = args.slice(1);
+      return options;
+    }
+    if (firstArg === 'validate-config') {
+      options.command = 'validate-config';
+      options.commandArgs = args.slice(1);
+      return options;
+    }
+    if (firstArg === 'export-snapshot') {
+      options.command = 'export-snapshot';
+      options.commandArgs = args.slice(1);
+      return options;
+    }
+    if (firstArg === 'import-snapshot') {
+      options.command = 'import-snapshot';
+      options.commandArgs = args.slice(1);
+      return options;
+    }
+    if (firstArg === 'list-templates') {
+      options.command = 'list-templates';
+      options.commandArgs = args.slice(1);
+      return options;
+    }
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        options.help = true;
+        break;
+      case '-v':
+      case '--version':
+        options.version = true;
+        break;
+      case '-d':
+      case '--debug':
+        options.debug = true;
+        break;
+      case '-w':
+      case '--web':
+        options.web = true;
+        break;
+      case '-p':
+      case '--web-port':
+        options.web = true;
+        if (i + 1 < args.length) {
+          const port = parseInt(args[++i], 10);
+          if (!isNaN(port) && port > 0 && port < 65536) {
+            options.webPort = port;
+          }
+        }
+        break;
+      case '--web-host':
+        options.web = true;
+        if (i + 1 < args.length) {
+          options.webHost = args[++i];
+        }
+        break;
+      case '-W':
+      case '--watch':
+        options.watch = true;
+        break;
+      case '--watch-plugins':
+        options.watchPlugins = true;
+        break;
+    }
+  }
+
+  return options;
+}
+
+export default { parseCliArgs };