@agirails/sdk 2.0.3 → 2.2.0

package/src/utils/circuitBreaker.ts

@@ -0,0 +1,324 @@
+/**
+ * Circuit Breaker - Gateway Health Tracking (Retry Amplification Protection)
+ *
+ * Implements the Circuit Breaker pattern for storage gateways:
+ * - Tracks consecutive failures per gateway
+ * - "Opens" circuit after threshold failures (blocks requests)
+ * - Auto-resets after cooldown period
+ *
+ * This prevents retry amplification attacks where a malicious/failing
+ * gateway causes excessive retries.
+ *
+ * @module utils/circuitBreaker
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Circuit state
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+/**
+ * Gateway health record
+ */
+interface GatewayHealth {
+  /** Consecutive failure count */
+  failures: number;
+  /** Timestamp of last failure */
+  lastFailure: number;
+  /** Current circuit state */
+  state: CircuitState;
+  /** Timestamp when circuit opened */
+  openedAt?: number;
+}
+
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening circuit (default: 5) */
+  failureThreshold?: number;
+
+  /** Cooldown period in ms before attempting reset (default: 60000 = 1 min) */
+  resetTimeoutMs?: number;
+
+  /** Time window in ms for counting failures (default: 300000 = 5 min) */
+  failureWindowMs?: number;
+
+  /** Number of successes in half-open to close circuit (default: 2) */
+  successThreshold?: number;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_FAILURE_THRESHOLD = 5;
+const DEFAULT_RESET_TIMEOUT_MS = 60000; // 1 minute
+const DEFAULT_FAILURE_WINDOW_MS = 300000; // 5 minutes
+const DEFAULT_SUCCESS_THRESHOLD = 2;
+
+// ============================================================================
+// GatewayCircuitBreaker Class
+// ============================================================================
+
+/**
+ * Circuit Breaker for gateway health management
+ *
+ * Usage:
+ * ```typescript
+ * const circuitBreaker = new GatewayCircuitBreaker();
+ *
+ * // Before making request
+ * if (!circuitBreaker.isHealthy(gatewayUrl)) {
+ *   throw new Error('Gateway circuit open');
+ * }
+ *
+ * try {
+ *   const result = await fetchFromGateway(gatewayUrl);
+ *   circuitBreaker.recordSuccess(gatewayUrl);
+ *   return result;
+ * } catch (error) {
+ *   circuitBreaker.recordFailure(gatewayUrl);
+ *   throw error;
+ * }
+ * ```
+ */
+export class GatewayCircuitBreaker {
+  private readonly health = new Map<string, GatewayHealth>();
+  private readonly config: Required<CircuitBreakerConfig>;
+  private halfOpenSuccesses = new Map<string, number>();
+
+  constructor(config: CircuitBreakerConfig = {}) {
+    this.config = {
+      failureThreshold: config.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD,
+      resetTimeoutMs: config.resetTimeoutMs ?? DEFAULT_RESET_TIMEOUT_MS,
+      failureWindowMs: config.failureWindowMs ?? DEFAULT_FAILURE_WINDOW_MS,
+      successThreshold: config.successThreshold ?? DEFAULT_SUCCESS_THRESHOLD
+    };
+  }
+
+  /**
+   * Check if gateway is healthy (circuit closed or half-open)
+   *
+   * @param url - Gateway URL
+   * @returns true if requests should be allowed
+   */
+  isHealthy(url: string): boolean {
+    const state = this.getState(url);
+    return state !== 'OPEN';
+  }
+
+  /**
+   * Get current circuit state for gateway
+   *
+   * @param url - Gateway URL
+   * @returns Circuit state
+   */
+  getState(url: string): CircuitState {
+    const health = this.health.get(url);
+
+    if (!health) {
+      return 'CLOSED';
+    }
+
+    // Check if circuit should transition from OPEN to HALF_OPEN
+    if (health.state === 'OPEN') {
+      const timeSinceOpen = Date.now() - (health.openedAt || 0);
+      if (timeSinceOpen >= this.config.resetTimeoutMs) {
+        // Transition to half-open
+        health.state = 'HALF_OPEN';
+        this.halfOpenSuccesses.set(url, 0);
+      }
+    }
+
+    // Check if failures have expired (outside window)
+    if (health.state === 'CLOSED') {
+      const timeSinceLastFailure = Date.now() - health.lastFailure;
+      if (timeSinceLastFailure >= this.config.failureWindowMs) {
+        // Reset failure count
+        health.failures = 0;
+      }
+    }
+
+    return health.state;
+  }
+
+  /**
+   * Record a successful request
+   *
+   * @param url - Gateway URL
+   */
+  recordSuccess(url: string): void {
+    const health = this.health.get(url);
+
+    if (!health) {
+      return; // No failures recorded, nothing to do
+    }
+
+    if (health.state === 'HALF_OPEN') {
+      // Count successes in half-open state
+      const successes = (this.halfOpenSuccesses.get(url) || 0) + 1;
+      this.halfOpenSuccesses.set(url, successes);
+
+      if (successes >= this.config.successThreshold) {
+        // Enough successes - close circuit
+        this.reset(url);
+      }
+    } else if (health.state === 'CLOSED') {
+      // Reset failure count on success
+      health.failures = 0;
+    }
+  }
+
+  /**
+   * Record a failed request
+   *
+   * @param url - Gateway URL
+   */
+  recordFailure(url: string): void {
+    const now = Date.now();
+    let health = this.health.get(url);
+
+    if (!health) {
+      health = {
+        failures: 0,
+        lastFailure: now,
+        state: 'CLOSED'
+      };
+      this.health.set(url, health);
+    }
+
+    // If in half-open state, any failure opens circuit again
+    if (health.state === 'HALF_OPEN') {
+      health.state = 'OPEN';
+      health.openedAt = now;
+      health.failures = this.config.failureThreshold; // Keep at threshold
+      this.halfOpenSuccesses.delete(url);
+      return;
+    }
+
+    // Check if previous failures have expired
+    const timeSinceLastFailure = now - health.lastFailure;
+    if (timeSinceLastFailure >= this.config.failureWindowMs) {
+      health.failures = 0;
+    }
+
+    // Increment failure count
+    health.failures++;
+    health.lastFailure = now;
+
+    // Check if threshold reached
+    if (health.failures >= this.config.failureThreshold) {
+      health.state = 'OPEN';
+      health.openedAt = now;
+    }
+  }
+
+  /**
+   * Reset circuit for gateway (force close)
+   *
+   * @param url - Gateway URL
+   */
+  reset(url: string): void {
+    this.health.delete(url);
+    this.halfOpenSuccesses.delete(url);
+  }
+
+  /**
+   * Reset all circuits
+   */
+  resetAll(): void {
+    this.health.clear();
+    this.halfOpenSuccesses.clear();
+  }
+
+  /**
+   * Get health status for all tracked gateways
+   *
+   * @returns Map of gateway URL to health info
+   */
+  getHealthStatus(): Map<string, { state: CircuitState; failures: number }> {
+    const status = new Map<string, { state: CircuitState; failures: number }>();
+
+    for (const [url, health] of this.health) {
+      status.set(url, {
+        state: this.getState(url), // This updates state if needed
+        failures: health.failures
+      });
+    }
+
+    return status;
+  }
+
+  /**
+   * Get failure count for gateway
+   *
+   * @param url - Gateway URL
+   * @returns Number of consecutive failures
+   */
+  getFailureCount(url: string): number {
+    return this.health.get(url)?.failures || 0;
+  }
+}
+
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+
+/**
+ * Default global circuit breaker instance
+ *
+ * Use this for simple cases where a single circuit breaker is sufficient.
+ * For more control, create your own GatewayCircuitBreaker instance.
+ */
+export const globalCircuitBreaker = new GatewayCircuitBreaker();
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Wrap an async operation with circuit breaker protection
+ *
+ * @param url - Gateway URL to track
+ * @param operation - Async operation to execute
+ * @param circuitBreaker - Circuit breaker instance (default: global)
+ * @returns Operation result
+ * @throws Error if circuit is open, or operation error
+ *
+ * @example
+ * ```typescript
+ * const result = await withCircuitBreaker(
+ *   'https://ipfs.filebase.io',
+ *   () => fetch(url).then(r => r.json())
+ * );
+ * ```
+ */
+export async function withCircuitBreaker<T>(
+  url: string,
+  operation: () => Promise<T>,
+  circuitBreaker: GatewayCircuitBreaker = globalCircuitBreaker
+): Promise<T> {
+  // Check if circuit allows request
+  if (!circuitBreaker.isHealthy(url)) {
+    const state = circuitBreaker.getState(url);
+    throw new Error(
+      `Circuit breaker OPEN for gateway: ${url}. ` +
+      `State: ${state}, Failures: ${circuitBreaker.getFailureCount(url)}. ` +
+      `Please wait for cooldown period before retrying.`
+    );
+  }
+
+  try {
+    const result = await operation();
+    circuitBreaker.recordSuccess(url);
+    return result;
+  } catch (error) {
+    circuitBreaker.recordFailure(url);
+    throw error;
+  }
+}

package/src/utils/fsSafe.ts

@@ -73,3 +73,8 @@ export function ensureSafeFile(
 
 
 
+
+
+
+
+

package/src/utils/retry.ts

@@ -0,0 +1,365 @@
+/**
+ * Retry Utility - Exponential Backoff with Jitter (P1-2)
+ *
+ * Implements retry logic for storage operations with:
+ * - Exponential backoff (doubles delay each attempt)
+ * - Random jitter (prevents thundering herd)
+ * - Maximum retry limit
+ * - Configurable retry conditions
+ *
+ * @module utils/retry
+ */
+
+import { StorageRateLimitError } from '../errors';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Retry configuration options
+ */
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxAttempts?: number;
+
+  /** Initial delay in milliseconds (default: 1000) */
+  initialDelayMs?: number;
+
+  /** Maximum delay in milliseconds (default: 30000) */
+  maxDelayMs?: number;
+
+  /** Multiplier for exponential backoff (default: 2) */
+  backoffMultiplier?: number;
+
+  /** Jitter factor 0-1 (default: 0.1 = ±10%) */
+  jitterFactor?: number;
+
+  /** Function to determine if error is retryable (default: built-in check) */
+  isRetryable?: (error: unknown) => boolean;
+
+  /** Callback for each retry attempt (for logging) */
+  onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+
+/**
+ * Result of retry operation
+ */
+export interface RetryResult<T> {
+  /** Operation result (if successful) */
+  result?: T;
+
+  /** Final error (if all retries failed) */
+  error?: unknown;
+
+  /** Number of attempts made */
+  attempts: number;
+
+  /** Total time spent (including delays) */
+  totalTimeMs: number;
+
+  /** Whether operation succeeded */
+  success: boolean;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 10000; // Reduced from 30s to 10s (NEW-4: prevent long stalls)
+const DEFAULT_BACKOFF_MULTIPLIER = 2;
+const DEFAULT_JITTER_FACTOR = 0.1;
+
+/**
+ * Default list of retryable HTTP status codes
+ */
+const RETRYABLE_STATUS_CODES = new Set([
+  408, // Request Timeout
+  429, // Too Many Requests
+  500, // Internal Server Error
+  502, // Bad Gateway
+  503, // Service Unavailable
+  504  // Gateway Timeout
+]);
+
+/**
+ * Default list of retryable error codes
+ */
+const RETRYABLE_ERROR_CODES = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ETIMEDOUT',
+  'ENOTFOUND',
+  'ENETUNREACH',
+  'EAI_AGAIN',
+  'EPIPE',
+  'EHOSTUNREACH'
+]);
+
+// ============================================================================
+// Functions
+// ============================================================================
+
+/**
+ * Default function to determine if error is retryable
+ *
+ * @param error - Error to check
+ * @returns True if error should trigger retry
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (!error) return false;
+
+  // Rate limit errors are always retryable
+  if (error instanceof StorageRateLimitError) {
+    return true;
+  }
+
+  const e = error as any;
+
+  // Check HTTP status codes
+  if (e.statusCode && RETRYABLE_STATUS_CODES.has(e.statusCode)) {
+    return true;
+  }
+
+  if (e.status && RETRYABLE_STATUS_CODES.has(e.status)) {
+    return true;
+  }
+
+  // Check error codes (network errors)
+  if (e.code && RETRYABLE_ERROR_CODES.has(e.code)) {
+    return true;
+  }
+
+  // Check for timeout errors
+  if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+    return true;
+  }
+
+  // Check message for common retryable patterns
+  const message = String(e.message || e).toLowerCase();
+  if (
+    message.includes('timeout') ||
+    message.includes('rate limit') ||
+    message.includes('too many requests') ||
+    message.includes('service unavailable') ||
+    message.includes('temporarily unavailable')
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (1-based)
+ * @param options - Retry options
+ * @returns Delay in milliseconds
+ */
+export function calculateBackoffDelay(
+  attempt: number,
+  options: RetryOptions = {}
+): number {
+  const {
+    initialDelayMs = DEFAULT_INITIAL_DELAY_MS,
+    maxDelayMs = DEFAULT_MAX_DELAY_MS,
+    backoffMultiplier = DEFAULT_BACKOFF_MULTIPLIER,
+    jitterFactor = DEFAULT_JITTER_FACTOR
+  } = options;
+
+  // Exponential backoff: initialDelay * (multiplier ^ (attempt - 1))
+  const exponentialDelay = initialDelayMs * Math.pow(backoffMultiplier, attempt - 1);
+
+  // Cap at max delay
+  const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+
+  // Add jitter: ±jitterFactor
+  const jitter = cappedDelay * jitterFactor * (Math.random() * 2 - 1);
+  const finalDelay = Math.max(0, cappedDelay + jitter);
+
+  return Math.round(finalDelay);
+}
+
+/**
+ * Sleep for specified duration
+ *
+ * @param ms - Milliseconds to sleep
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute async operation with retry logic
+ *
+ * Implements exponential backoff with jitter for handling transient failures.
+ * Particularly useful for storage operations that may fail due to:
+ * - Rate limiting
+ * - Network timeouts
+ * - Temporary service unavailability
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Promise resolving to operation result or throwing final error
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = await withRetry(
+ *   () => client.uploadJSON(data),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * // With logging
+ * const result = await withRetry(
+ *   () => client.downloadJSON(cid),
+ *   {
+ *     maxAttempts: 5,
+ *     onRetry: (attempt, error, delay) => {
+ *       console.log(`Retry ${attempt}, waiting ${delay}ms:`, error);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  operation: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    isRetryable = isRetryableError,
+    onRetry
+  } = options;
+
+  let lastError: unknown;
+  const startTime = Date.now();
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+
+      // Check if this is the last attempt
+      if (attempt >= maxAttempts) {
+        break;
+      }
+
+      // Check if error is retryable
+      if (!isRetryable(error)) {
+        break;
+      }
+
+      // Calculate delay
+      let delayMs = calculateBackoffDelay(attempt, options);
+
+      // If rate limit error with retry-after header, use that instead
+      if (error instanceof StorageRateLimitError && error.details?.retryAfter) {
+        delayMs = Math.max(delayMs, error.details.retryAfter * 1000);
+      }
+
+      // Notify callback
+      if (onRetry) {
+        onRetry(attempt, error, delayMs);
+      }
+
+      // Wait before retry
+      await sleep(delayMs);
+    }
+  }
+
+  // All retries failed
+  throw lastError;
+}
+
+/**
+ * Execute async operation with retry logic, returning detailed result
+ *
+ * Unlike `withRetry`, this function never throws - it returns a result object
+ * with success/failure status and metadata.
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Promise resolving to detailed result object
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetryResult(
+ *   () => client.uploadJSON(data),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Uploaded:', result.result);
+ * } else {
+ *   console.error(`Failed after ${result.attempts} attempts:`, result.error);
+ * }
+ * ```
+ */
+export async function withRetryResult<T>(
+  operation: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<RetryResult<T>> {
+  const {
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    isRetryable = isRetryableError,
+    onRetry
+  } = options;
+
+  let lastError: unknown;
+  const startTime = Date.now();
+  let attempts = 0;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    attempts = attempt;
+
+    try {
+      const result = await operation();
+      return {
+        result,
+        attempts,
+        totalTimeMs: Date.now() - startTime,
+        success: true
+      };
+    } catch (error) {
+      lastError = error;
+
+      // Check if this is the last attempt
+      if (attempt >= maxAttempts) {
+        break;
+      }
+
+      // Check if error is retryable
+      if (!isRetryable(error)) {
+        break;
+      }
+
+      // Calculate delay
+      let delayMs = calculateBackoffDelay(attempt, options);
+
+      // If rate limit error with retry-after header, use that instead
+      if (error instanceof StorageRateLimitError && error.details?.retryAfter) {
+        delayMs = Math.max(delayMs, error.details.retryAfter * 1000);
+      }
+
+      // Notify callback
+      if (onRetry) {
+        onRetry(attempt, error, delayMs);
+      }
+
+      // Wait before retry
+      await sleep(delayMs);
+    }
+  }
+
+  return {
+    error: lastError,
+    attempts,
+    totalTimeMs: Date.now() - startTime,
+    success: false
+  };
+}