@tamyla/clodo-framework 1.0.0

package/dist/shared/utils/rate-limiter.js

@@ -0,0 +1,249 @@
+/**
+ * Rate Limiter for Cloudflare API calls
+ * Implements exponential backoff and request queuing to prevent rate limit violations
+ */
+
+import { promisify } from 'util';
+import { exec } from 'child_process';
+const execAsync = promisify(exec);
+
+/**
+ * Rate limiter configuration for different Cloudflare API endpoints
+ */
+const RATE_LIMITS = {
+  // Workers API limits (1000/hour, 100/minute)
+  workers: {
+    maxRequestsPerMinute: 100,
+    maxRequestsPerHour: 1000,
+    baseDelay: 1000,
+    // 1 second
+    maxDelay: 300000 // 5 minutes
+  },
+  // D1 Database API limits (1000/hour)
+  d1: {
+    maxRequestsPerMinute: 50,
+    maxRequestsPerHour: 1000,
+    baseDelay: 2000,
+    // 2 seconds
+    maxDelay: 600000 // 10 minutes
+  },
+  // General API limits
+  general: {
+    maxRequestsPerMinute: 30,
+    maxRequestsPerHour: 500,
+    baseDelay: 3000,
+    // 3 seconds
+    maxDelay: 900000 // 15 minutes
+  }
+};
+
+/**
+ * Request queue for each API type
+ */
+const requestQueues = {
+  workers: [],
+  d1: [],
+  general: []
+};
+
+/**
+ * Current request counts and timestamps
+ */
+const requestCounts = {
+  workers: {
+    minute: 0,
+    hour: 0,
+    lastMinuteReset: Date.now(),
+    lastHourReset: Date.now()
+  },
+  d1: {
+    minute: 0,
+    hour: 0,
+    lastMinuteReset: Date.now(),
+    lastHourReset: Date.now()
+  },
+  general: {
+    minute: 0,
+    hour: 0,
+    lastMinuteReset: Date.now(),
+    lastHourReset: Date.now()
+  }
+};
+
+/**
+ * Reset counters based on time windows
+ */
+function resetCounters() {
+  const now = Date.now();
+  Object.keys(requestCounts).forEach(apiType => {
+    const counts = requestCounts[apiType];
+
+    // Reset minute counter if needed
+    if (now - counts.lastMinuteReset >= 60000) {
+      // 1 minute
+      counts.minute = 0;
+      counts.lastMinuteReset = now;
+    }
+
+    // Reset hour counter if needed
+    if (now - counts.lastHourReset >= 3600000) {
+      // 1 hour
+      counts.hour = 0;
+      counts.lastHourReset = now;
+    }
+  });
+}
+
+/**
+ * Calculate delay based on exponential backoff
+ */
+function calculateDelay(apiType, attempt = 0) {
+  const config = RATE_LIMITS[apiType];
+  const delay = Math.min(config.baseDelay * Math.pow(2, attempt), config.maxDelay);
+  return delay + Math.random() * 1000; // Add jitter
+}
+
+/**
+ * Check if we can make a request without violating rate limits
+ */
+function canMakeRequest(apiType) {
+  resetCounters();
+  const counts = requestCounts[apiType];
+  const limits = RATE_LIMITS[apiType];
+  return counts.minute < limits.maxRequestsPerMinute && counts.hour < limits.maxRequestsPerHour;
+}
+
+/**
+ * Execute a Cloudflare API command with rate limiting
+ */
+async function executeWithRateLimit(command, apiType = 'general', maxRetries = 5) {
+  return new Promise((resolve, reject) => {
+    const attemptRequest = async (attempt = 0) => {
+      try {
+        // Check if we can make the request
+        if (!canMakeRequest(apiType)) {
+          const delay = calculateDelay(apiType, attempt);
+          console.log(`Rate limit approaching for ${apiType} API. Waiting ${delay}ms before retry...`);
+          await new Promise(resolve => setTimeout(resolve, delay));
+          return attemptRequest(attempt);
+        }
+
+        // Execute the command
+        console.log(`Executing ${apiType} API command (attempt ${attempt + 1}/${maxRetries + 1})`);
+        const result = await execAsync(command);
+
+        // Update counters on success
+        requestCounts[apiType].minute++;
+        requestCounts[apiType].hour++;
+        resolve(result);
+      } catch (error) {
+        // Check if it's a rate limit error
+        if (error.stderr && (error.stderr.includes('rate limit') || error.stderr.includes('429') || error.stderr.includes('Too Many Requests'))) {
+          if (attempt < maxRetries) {
+            const delay = calculateDelay(apiType, attempt);
+            console.log(`Rate limit hit for ${apiType} API. Retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries + 1})`);
+            setTimeout(() => attemptRequest(attempt + 1), delay);
+          } else {
+            reject(new Error(`Rate limit exceeded for ${apiType} API after ${maxRetries + 1} attempts: ${error.message}`));
+          }
+        } else {
+          // Not a rate limit error, reject immediately
+          reject(error);
+        }
+      }
+    };
+    attemptRequest();
+  });
+}
+
+/**
+ * Queue a request for execution with rate limiting
+ */
+async function queueRequest(command, apiType = 'general', priority = 'normal') {
+  return new Promise((resolve, reject) => {
+    const request = {
+      command,
+      apiType,
+      priority,
+      resolve,
+      reject,
+      timestamp: Date.now()
+    };
+
+    // Add to appropriate queue
+    requestQueues[apiType].push(request);
+
+    // Sort by priority (high priority first)
+    requestQueues[apiType].sort((a, b) => {
+      const priorityOrder = {
+        high: 3,
+        normal: 2,
+        low: 1
+      };
+      return priorityOrder[b.priority] - priorityOrder[a.priority];
+    });
+
+    // Process the queue
+    processQueue(apiType);
+  });
+}
+
+/**
+ * Process the request queue for a specific API type
+ */
+async function processQueue(apiType) {
+  const queue = requestQueues[apiType];
+  if (queue.length === 0) return;
+
+  // Only process one request at a time per API type
+  if (queue.processing) return;
+  queue.processing = true;
+  try {
+    while (queue.length > 0) {
+      const request = queue.shift();
+      try {
+        const result = await executeWithRateLimit(request.command, request.apiType);
+        request.resolve(result);
+      } catch (error) {
+        request.reject(error);
+      }
+
+      // Small delay between requests to be respectful
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  } finally {
+    queue.processing = false;
+  }
+}
+
+/**
+ * Get current rate limit status
+ */
+function getRateLimitStatus(apiType) {
+  resetCounters();
+  const counts = requestCounts[apiType];
+  const limits = RATE_LIMITS[apiType];
+  return {
+    minute: {
+      used: counts.minute,
+      limit: limits.maxRequestsPerMinute,
+      remaining: Math.max(0, limits.maxRequestsPerMinute - counts.minute)
+    },
+    hour: {
+      used: counts.hour,
+      limit: limits.maxRequestsPerHour,
+      remaining: Math.max(0, limits.maxRequestsPerHour - counts.hour)
+    }
+  };
+}
+
+/**
+ * Clear all queues (useful for testing or emergency situations)
+ */
+function clearQueues() {
+  Object.keys(requestQueues).forEach(apiType => {
+    requestQueues[apiType].length = 0;
+    requestQueues[apiType].processing = false;
+  });
+}
+export { executeWithRateLimit, queueRequest, getRateLimitStatus, clearQueues, RATE_LIMITS };

package/dist/utils/ErrorHandler.js

@@ -0,0 +1,173 @@
+/**
+ * Enhanced Error Handler
+ * Comprehensive error reporting and handling utilities
+ */
+
+export class ErrorHandler {
+  /**
+   * Handle deployment errors with detailed reporting
+   * @param {Error} error - The error object
+   * @param {Object} context - Additional context (customer, environment, etc.)
+   */
+  static handleDeploymentError(error, context = {}) {
+    const {
+      customer,
+      environment,
+      phase
+    } = context;
+    console.error(`\n❌ Deployment Error in phase: ${phase || 'unknown'}`);
+    console.error(`   Customer: ${customer || 'unknown'}`);
+    console.error(`   Environment: ${environment || 'unknown'}`);
+    console.error(`   Message: ${error.message}`);
+    if (error.stack) {
+      console.error(`   Stack: ${error.stack}`);
+    }
+
+    // Log additional context if available
+    if (context.deploymentUrl) {
+      console.error(`   Deployment URL: ${context.deploymentUrl}`);
+    }
+
+    // Provide actionable suggestions
+    this.provideErrorSuggestions(error, context);
+  }
+
+  /**
+   * Provide actionable error suggestions
+   * @param {Error} error - The error object
+   * @param {Object} context - Context information
+   */
+  static provideErrorSuggestions(error, context) {
+    console.error('\n💡 Suggestions:');
+    if (error.message.includes('security')) {
+      console.error('   - Run security validation: npx clodo-security validate <customer> <environment>');
+      console.error('   - Generate secure keys: npx clodo-security generate-key api');
+    }
+    if (error.message.includes('health check')) {
+      console.error('   - Check deployment URL accessibility');
+      console.error('   - Verify service is running and responding');
+    }
+    if (error.message.includes('authentication')) {
+      console.error('   - Re-authenticate with Cloudflare: wrangler auth login');
+      console.error('   - Check API token validity');
+    }
+    if (error.message.includes('timeout')) {
+      console.error('   - Increase timeout values in configuration');
+      console.error('   - Check network connectivity');
+    }
+    if (error.message.includes('validation')) {
+      console.error('   - Review configuration files for errors');
+      console.error('   - Run validation checks: npx clodo-config validate');
+    }
+    console.error('   - Review logs for more details');
+  }
+
+  /**
+   * Wrap async operations with error handling
+   * @param {Function} fn - Async function to wrap
+   * @param {Object} context - Context for error reporting
+   */
+  static async withErrorHandling(fn, context = {}) {
+    try {
+      return await fn();
+    } catch (error) {
+      this.handleDeploymentError(error, context);
+      throw error;
+    }
+  }
+
+  /**
+   * Handle health check errors specifically
+   * @param {Error} error - The health check error
+   * @param {string} url - The URL that was checked
+   */
+  static handleHealthCheckError(error, url) {
+    console.error(`\n❌ Health Check Failed`);
+    console.error(`   URL: ${url}`);
+    console.error(`   Error: ${error.message}`);
+    console.error('\n💡 Health Check Troubleshooting:');
+    console.error('   - Verify the service is deployed and running');
+    console.error('   - Check if the /health endpoint exists');
+    console.error('   - Ensure the service responds with valid JSON');
+    console.error('   - Check network connectivity and firewall rules');
+    console.error('   - Review service logs for startup errors');
+  }
+
+  /**
+   * Handle configuration errors
+   * @param {Error} error - The configuration error
+   * @param {Object} config - The configuration object that failed
+   */
+  static handleConfigurationError(error, config = {}) {
+    console.error(`\n❌ Configuration Error`);
+    console.error(`   Message: ${error.message}`);
+    if (config.customer) {
+      console.error(`   Customer: ${config.customer}`);
+    }
+    if (config.environment) {
+      console.error(`   Environment: ${config.environment}`);
+    }
+    console.error('\n💡 Configuration Troubleshooting:');
+    console.error('   - Validate configuration schema');
+    console.error('   - Check for missing required fields');
+    console.error('   - Verify environment variables are set');
+    console.error('   - Review configuration file syntax');
+  }
+
+  /**
+   * Create a standardized error report
+   * @param {Error} error - The error object
+   * @param {Object} context - Additional context
+   * @returns {Object} Standardized error report
+   */
+  static createErrorReport(error, context = {}) {
+    return {
+      timestamp: new Date().toISOString(),
+      error: {
+        message: error.message,
+        stack: error.stack,
+        name: error.name
+      },
+      context,
+      suggestions: this.generateSuggestions(error, context)
+    };
+  }
+
+  /**
+   * Generate error suggestions based on error type and context
+   * @param {Error} error - The error object
+   * @param {Object} context - Context information
+   * @returns {string[]} Array of suggestion strings
+   */
+  static generateSuggestions(error, context) {
+    const suggestions = [];
+    const errorMessage = error.message.toLowerCase();
+    if (errorMessage.includes('security') || errorMessage.includes('validation')) {
+      suggestions.push('Run security validation: npx clodo-security validate');
+      suggestions.push('Generate secure keys: npx clodo-security generate-key api');
+    }
+    if (errorMessage.includes('health') || errorMessage.includes('connection')) {
+      suggestions.push('Check deployment URL accessibility');
+      suggestions.push('Verify service is running and responding');
+      suggestions.push('Check network connectivity and firewall rules');
+    }
+    if (errorMessage.includes('auth') || errorMessage.includes('token')) {
+      suggestions.push('Re-authenticate with Cloudflare: wrangler auth login');
+      suggestions.push('Check API token validity and permissions');
+    }
+    if (errorMessage.includes('timeout')) {
+      suggestions.push('Increase timeout values in configuration');
+      suggestions.push('Check network connectivity');
+    }
+    if (errorMessage.includes('config') || errorMessage.includes('missing')) {
+      suggestions.push('Review configuration files for errors');
+      suggestions.push('Run configuration validation: npx clodo-config validate');
+      suggestions.push('Check environment variables are properly set');
+    }
+    if (suggestions.length === 0) {
+      suggestions.push('Review logs for more details');
+      suggestions.push('Check system resources and dependencies');
+    }
+    return suggestions;
+  }
+}