mcp-wordpress 2.11.13 → 3.0.0

package/src/utils/CircuitBreaker.ts

@@ -0,0 +1,572 @@
+/**
+ * Circuit Breaker Pattern Implementation
+ *
+ * Provides fault tolerance for external service calls by preventing
+ * cascading failures and allowing systems to recover gracefully.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Failures exceeded threshold, requests fail fast
+ * - HALF_OPEN: Testing if service recovered, limited requests allowed
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ *   name: 'wordpress-api'
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(() => apiCall());
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerOpenError) {
+ *     // Circuit is open, use fallback
+ *   }
+ * }
+ * ```
+ */
+
+import { createLogger } from "./logger.js";
+
+/**
+ * Circuit breaker states
+ */
+/**
+ * Circuit state values
+ */
+export const CircuitState = {
+  CLOSED: "CLOSED",
+  OPEN: "OPEN",
+  HALF_OPEN: "HALF_OPEN",
+} as const;
+
+/**
+ * Circuit state type
+ */
+export type CircuitStateType = (typeof CircuitState)[keyof typeof CircuitState];
+
+/**
+ * Circuit breaker configuration options
+ */
+export interface CircuitBreakerOptions {
+  /** Name for logging and identification */
+  name: string;
+  /** Number of failures before opening circuit (default: 5) */
+  failureThreshold?: number;
+  /** Time in ms before attempting to close circuit (default: 30000) */
+  resetTimeout?: number;
+  /** Number of successful calls needed to close circuit from half-open (default: 2) */
+  successThreshold?: number;
+  /** Time window in ms to count failures (default: 60000) */
+  failureWindow?: number;
+  /** Timeout for individual operations in ms (default: 30000) */
+  timeout?: number;
+  /** Function to determine if an error should trip the breaker */
+  isFailure?: (error: Error) => boolean;
+  /** Callback when circuit opens */
+  onOpen?: (name: string, failures: number) => void;
+  /** Callback when circuit closes */
+  onClose?: (name: string) => void;
+  /** Callback when circuit enters half-open state */
+  onHalfOpen?: (name: string) => void;
+}
+
+/**
+ * Circuit breaker statistics
+ */
+export interface CircuitBreakerStats {
+  state: CircuitStateType;
+  failures: number;
+  successes: number;
+  lastFailure: Date | null;
+  lastSuccess: Date | null;
+  totalRequests: number;
+  failedRequests: number;
+  successfulRequests: number;
+  rejectedRequests: number;
+  timeInCurrentState: number;
+}
+
+/**
+ * Error thrown when circuit breaker is open
+ */
+export class CircuitBreakerOpenError extends Error {
+  constructor(
+    public readonly circuitName: string,
+    public readonly resetTime: number,
+  ) {
+    super(`Circuit breaker '${circuitName}' is open. Retry after ${Math.ceil(resetTime / 1000)}s`);
+    this.name = "CircuitBreakerOpenError";
+  }
+}
+
+/**
+ * Error thrown when operation times out
+ */
+export class CircuitBreakerTimeoutError extends Error {
+  constructor(
+    public readonly circuitName: string,
+    public readonly timeout: number,
+  ) {
+    super(`Circuit breaker '${circuitName}' operation timed out after ${timeout}ms`);
+    this.name = "CircuitBreakerTimeoutError";
+  }
+}
+
+/**
+ * Failure record for tracking failures within time window
+ */
+interface FailureRecord {
+  timestamp: number;
+  error: Error;
+}
+
+/**
+ * Circuit Breaker Implementation
+ */
+export class CircuitBreaker {
+  private state: CircuitStateType = CircuitState.CLOSED;
+  private failures: FailureRecord[] = [];
+  private successes: number = 0;
+  private lastStateChange: number = Date.now();
+  private lastFailure: Date | null = null;
+  private lastSuccess: Date | null = null;
+
+  // Statistics
+  private totalRequests: number = 0;
+  private failedRequests: number = 0;
+  private successfulRequests: number = 0;
+  private rejectedRequests: number = 0;
+
+  // Configuration with defaults
+  private readonly name: string;
+  private readonly failureThreshold: number;
+  private readonly resetTimeout: number;
+  private readonly successThreshold: number;
+  private readonly failureWindow: number;
+  private readonly timeout: number;
+  private readonly isFailure: (error: Error) => boolean;
+  private readonly onOpen: ((name: string, failures: number) => void) | undefined;
+  private readonly onClose: ((name: string) => void) | undefined;
+  private readonly onHalfOpen: ((name: string) => void) | undefined;
+
+  private readonly logger = createLogger("CircuitBreaker");
+
+  constructor(options: CircuitBreakerOptions) {
+    this.name = options.name;
+    this.failureThreshold = options.failureThreshold ?? 5;
+    this.resetTimeout = options.resetTimeout ?? 30000;
+    this.successThreshold = options.successThreshold ?? 2;
+    this.failureWindow = options.failureWindow ?? 60000;
+    this.timeout = options.timeout ?? 30000;
+    this.isFailure = options.isFailure ?? this.defaultIsFailure;
+    this.onOpen = options.onOpen;
+    this.onClose = options.onClose;
+    this.onHalfOpen = options.onHalfOpen;
+
+    this.logger.debug(`Circuit breaker '${this.name}' initialized`, {
+      failureThreshold: this.failureThreshold,
+      resetTimeout: this.resetTimeout,
+      successThreshold: this.successThreshold,
+    });
+  }
+
+  /**
+   * Execute an operation through the circuit breaker
+   */
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    this.totalRequests++;
+
+    // Check if circuit should transition from OPEN to HALF_OPEN
+    if (this.state === CircuitState.OPEN) {
+      if (this.shouldAttemptReset()) {
+        this.transitionTo(CircuitState.HALF_OPEN);
+      } else {
+        this.rejectedRequests++;
+        const remainingTime = this.getRemainingResetTime();
+        throw new CircuitBreakerOpenError(this.name, remainingTime);
+      }
+    }
+
+    try {
+      const result = await this.executeWithTimeout(operation);
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onError(error as Error);
+      throw error;
+    }
+  }
+
+  /**
+   * Execute operation with timeout
+   */
+  private async executeWithTimeout<T>(operation: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new CircuitBreakerTimeoutError(this.name, this.timeout));
+      }, this.timeout);
+
+      operation()
+        .then((result) => {
+          clearTimeout(timeoutId);
+          resolve(result);
+        })
+        .catch((error) => {
+          clearTimeout(timeoutId);
+          reject(error);
+        });
+    });
+  }
+
+  /**
+   * Handle successful operation
+   */
+  private onSuccess(): void {
+    this.successfulRequests++;
+    this.lastSuccess = new Date();
+    this.successes++;
+
+    if (this.state === CircuitState.HALF_OPEN) {
+      if (this.successes >= this.successThreshold) {
+        this.transitionTo(CircuitState.CLOSED);
+      }
+    }
+
+    // Clear old failures when successful in closed state
+    if (this.state === CircuitState.CLOSED) {
+      this.cleanOldFailures();
+    }
+  }
+
+  /**
+   * Handle operation error
+   */
+  private onError(error: Error): void {
+    // Check if this error should count as a failure
+    if (!this.isFailure(error)) {
+      return;
+    }
+
+    this.failedRequests++;
+    this.lastFailure = new Date();
+
+    if (this.state === CircuitState.HALF_OPEN) {
+      // Any failure in half-open state reopens the circuit
+      this.transitionTo(CircuitState.OPEN);
+      return;
+    }
+
+    if (this.state === CircuitState.CLOSED) {
+      this.recordFailure(error);
+
+      // Clean old failures and check threshold
+      this.cleanOldFailures();
+      if (this.failures.length >= this.failureThreshold) {
+        this.transitionTo(CircuitState.OPEN);
+      }
+    }
+  }
+
+  /**
+   * Record a failure
+   */
+  private recordFailure(error: Error): void {
+    this.failures.push({
+      timestamp: Date.now(),
+      error,
+    });
+  }
+
+  /**
+   * Remove failures outside the time window
+   */
+  private cleanOldFailures(): void {
+    const cutoff = Date.now() - this.failureWindow;
+    this.failures = this.failures.filter((f) => f.timestamp > cutoff);
+  }
+
+  /**
+   * Check if we should attempt to reset (transition to half-open)
+   */
+  private shouldAttemptReset(): boolean {
+    return Date.now() - this.lastStateChange >= this.resetTimeout;
+  }
+
+  /**
+   * Get remaining time until reset attempt
+   */
+  private getRemainingResetTime(): number {
+    const elapsed = Date.now() - this.lastStateChange;
+    return Math.max(0, this.resetTimeout - elapsed);
+  }
+
+  /**
+   * Transition to a new state
+   */
+  private transitionTo(newState: CircuitStateType): void {
+    const oldState = this.state;
+    this.state = newState;
+    this.lastStateChange = Date.now();
+
+    this.logger.info(`Circuit '${this.name}' state change: ${oldState} -> ${newState}`);
+
+    // Reset counters on state change
+    if (newState === CircuitState.CLOSED) {
+      this.failures = [];
+      this.successes = 0;
+      this.onClose?.(this.name);
+    } else if (newState === CircuitState.OPEN) {
+      this.successes = 0;
+      this.onOpen?.(this.name, this.failures.length);
+    } else if (newState === CircuitState.HALF_OPEN) {
+      this.successes = 0;
+      this.onHalfOpen?.(this.name);
+    }
+  }
+
+  /**
+   * Default failure detection - all errors are failures except timeouts and circuit breaker errors
+   */
+  private defaultIsFailure(error: Error): boolean {
+    // Don't count circuit breaker's own errors as failures
+    if (error instanceof CircuitBreakerOpenError || error instanceof CircuitBreakerTimeoutError) {
+      return false;
+    }
+
+    // Count all other errors as failures
+    return true;
+  }
+
+  /**
+   * Get current circuit breaker statistics
+   */
+  getStats(): CircuitBreakerStats {
+    this.cleanOldFailures();
+
+    return {
+      state: this.state,
+      failures: this.failures.length,
+      successes: this.successes,
+      lastFailure: this.lastFailure,
+      lastSuccess: this.lastSuccess,
+      totalRequests: this.totalRequests,
+      failedRequests: this.failedRequests,
+      successfulRequests: this.successfulRequests,
+      rejectedRequests: this.rejectedRequests,
+      timeInCurrentState: Date.now() - this.lastStateChange,
+    };
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): CircuitStateType {
+    // Check for automatic transition to half-open
+    if (this.state === CircuitState.OPEN && this.shouldAttemptReset()) {
+      this.transitionTo(CircuitState.HALF_OPEN);
+    }
+    return this.state;
+  }
+
+  /**
+   * Check if circuit is allowing requests
+   */
+  isAvailable(): boolean {
+    const state = this.getState();
+    return state === CircuitState.CLOSED || state === CircuitState.HALF_OPEN;
+  }
+
+  /**
+   * Force circuit to open state (for testing or manual intervention)
+   */
+  forceOpen(): void {
+    this.logger.warn(`Circuit '${this.name}' forced open`);
+    this.transitionTo(CircuitState.OPEN);
+  }
+
+  /**
+   * Force circuit to closed state (for testing or manual intervention)
+   */
+  forceClose(): void {
+    this.logger.warn(`Circuit '${this.name}' forced closed`);
+    this.transitionTo(CircuitState.CLOSED);
+  }
+
+  /**
+   * Reset circuit breaker to initial state
+   */
+  reset(): void {
+    this.state = CircuitState.CLOSED;
+    this.failures = [];
+    this.successes = 0;
+    this.lastStateChange = Date.now();
+    this.totalRequests = 0;
+    this.failedRequests = 0;
+    this.successfulRequests = 0;
+    this.rejectedRequests = 0;
+    this.lastFailure = null;
+    this.lastSuccess = null;
+
+    this.logger.info(`Circuit '${this.name}' reset`);
+  }
+}
+
+/**
+ * Circuit Breaker Registry
+ * Manages multiple circuit breakers for different services
+ */
+export class CircuitBreakerRegistry {
+  private static instance: CircuitBreakerRegistry;
+  private breakers: Map<string, CircuitBreaker> = new Map();
+  private readonly logger = createLogger("CircuitBreakerRegistry");
+
+  private constructor() {}
+
+  /**
+   * Get singleton instance
+   */
+  static getInstance(): CircuitBreakerRegistry {
+    if (!CircuitBreakerRegistry.instance) {
+      CircuitBreakerRegistry.instance = new CircuitBreakerRegistry();
+    }
+    return CircuitBreakerRegistry.instance;
+  }
+
+  /**
+   * Get or create a circuit breaker
+   */
+  getBreaker(options: CircuitBreakerOptions): CircuitBreaker {
+    let breaker = this.breakers.get(options.name);
+
+    if (!breaker) {
+      breaker = new CircuitBreaker(options);
+      this.breakers.set(options.name, breaker);
+      this.logger.debug(`Created circuit breaker: ${options.name}`);
+    }
+
+    return breaker;
+  }
+
+  /**
+   * Get existing circuit breaker by name
+   */
+  get(name: string): CircuitBreaker | undefined {
+    return this.breakers.get(name);
+  }
+
+  /**
+   * Get all circuit breaker statistics
+   */
+  getAllStats(): Record<string, CircuitBreakerStats> {
+    const stats: Record<string, CircuitBreakerStats> = {};
+
+    for (const [name, breaker] of this.breakers) {
+      stats[name] = breaker.getStats();
+    }
+
+    return stats;
+  }
+
+  /**
+   * Get health summary of all circuit breakers
+   */
+  getHealthSummary(): {
+    total: number;
+    closed: number;
+    open: number;
+    halfOpen: number;
+    healthy: boolean;
+  } {
+    let closed = 0;
+    let open = 0;
+    let halfOpen = 0;
+
+    for (const breaker of this.breakers.values()) {
+      switch (breaker.getState()) {
+        case CircuitState.CLOSED:
+          closed++;
+          break;
+        case CircuitState.OPEN:
+          open++;
+          break;
+        case CircuitState.HALF_OPEN:
+          halfOpen++;
+          break;
+      }
+    }
+
+    return {
+      total: this.breakers.size,
+      closed,
+      open,
+      halfOpen,
+      healthy: open === 0,
+    };
+  }
+
+  /**
+   * Reset all circuit breakers
+   */
+  resetAll(): void {
+    for (const breaker of this.breakers.values()) {
+      breaker.reset();
+    }
+    this.logger.info("All circuit breakers reset");
+  }
+
+  /**
+   * Remove a circuit breaker
+   */
+  remove(name: string): boolean {
+    return this.breakers.delete(name);
+  }
+
+  /**
+   * Clear all circuit breakers
+   */
+  clear(): void {
+    this.breakers.clear();
+    this.logger.info("All circuit breakers cleared");
+  }
+}
+
+/**
+ * Create a circuit breaker with default WordPress API settings
+ */
+export function createWordPressCircuitBreaker(
+  siteId: string,
+  options?: Partial<CircuitBreakerOptions>,
+): CircuitBreaker {
+  return CircuitBreakerRegistry.getInstance().getBreaker({
+    name: `wordpress-api-${siteId}`,
+    failureThreshold: 5,
+    resetTimeout: 30000,
+    successThreshold: 2,
+    failureWindow: 60000,
+    timeout: 30000,
+    isFailure: (error: Error) => {
+      // Don't trip on client errors (4xx) except rate limiting
+      const message = error.message.toLowerCase();
+      if (message.includes("401") || message.includes("403")) {
+        return false; // Auth errors shouldn't trip the breaker
+      }
+      if (message.includes("404")) {
+        return false; // Not found is a valid response
+      }
+      if (message.includes("429")) {
+        return true; // Rate limiting should trip the breaker
+      }
+      // Server errors (5xx) and network errors should trip
+      return (
+        message.includes("5") ||
+        message.includes("timeout") ||
+        message.includes("network") ||
+        message.includes("econnrefused") ||
+        message.includes("econnreset")
+      );
+    },
+    ...options,
+  });
+}

package/src/utils/debug.ts

@@ -5,8 +5,8 @@
  * This prevents console.log from interfering with MCP STDIO communication.
  */
 
-import type { DebugInfo } from "../types/index.js";
-import { config } from "../config/Config.js";
+import type { DebugInfo } from "@/types/index.js";
+import { config } from "@/config/Config.js";
 
 // Log levels
 export type LogLevel = "debug" | "info" | "warn" | "error";
@@ -25,7 +25,7 @@ export interface StructuredLogger extends Logger {
   child(context: Record<string, unknown>): StructuredLogger;
 }
 
-import { ConfigHelpers } from "../config/Config.js";
+import { ConfigHelpers } from "@/config/Config.js";
 
 // Check if debug mode is enabled
 const isDebugMode = (): boolean => ConfigHelpers.shouldDebug();

package/src/utils/error.ts

@@ -2,7 +2,7 @@
  * Error handling utilities
  */
 import { LoggerFactory } from "./logger.js";
-import { config } from "../config/Config.js";
+import { config } from "@/config/Config.js";
 
 const logger = LoggerFactory.server().child({ component: "ErrorUtils" });
 

package/src/utils/index.ts

@@ -21,3 +21,6 @@ export * from "./toolWrapper.js";
 
 // Streaming utilities (if any exports exist)
 export * from "./streaming.js";
+
+// Circuit breaker for fault tolerance
+export * from "./CircuitBreaker.js";

package/src/utils/logger.ts

@@ -5,7 +5,7 @@
  * Integrates with the centralized Config system for environment-aware behavior.
  */
 
-import { ConfigHelpers } from "../config/Config.js";
+import { ConfigHelpers } from "@/config/Config.js";
 
 export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
 export type LogContext = Record<string, unknown>;

package/src/utils/toolWrapper.ts

@@ -4,8 +4,8 @@
  */
 
 import { getErrorMessage } from "./error.js";
-import type { IWordPressClient } from "../types/client.js";
-import type { BaseToolParams } from "../types/tools.js";
+import type { IWordPressClient } from "@/types/client.js";
+import type { BaseToolParams } from "@/types/tools.js";
 
 /**
  * Wrapper for tool methods that standardizes error handling