claude-flow 3.27.4 → 3.29.0

package/v3/@claude-flow/shared/dist/resilience/bulkhead.js

@@ -0,0 +1,206 @@
+/**
+ * Bulkhead Pattern
+ *
+ * Isolates failures by limiting concurrent executions.
+ *
+ * @module v3/shared/resilience/bulkhead
+ */
+import { EventEmitter } from 'events';
+/**
+ * Default options
+ */
+const DEFAULT_OPTIONS = {
+    maxConcurrent: 10,
+    maxQueue: 100,
+    queueTimeout: 30000,
+};
+/**
+ * Bulkhead
+ *
+ * Limits concurrent executions to prevent resource exhaustion.
+ *
+ * @example
+ * const bulkhead = new Bulkhead({
+ *   name: 'database',
+ *   maxConcurrent: 10,
+ *   maxQueue: 50,
+ * });
+ *
+ * try {
+ *   const result = await bulkhead.execute(() => dbQuery());
+ * } catch (error) {
+ *   if (error.message.includes('Bulkhead full')) {
+ *     // Handle capacity exceeded
+ *   }
+ * }
+ */
+export class Bulkhead extends EventEmitter {
+    options;
+    active = 0;
+    queue = [];
+    completed = 0;
+    rejected = 0;
+    timedOut = 0;
+    constructor(options) {
+        super();
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Execute a function within the bulkhead
+     */
+    async execute(fn) {
+        // If there's room for execution, run immediately
+        if (this.active < this.options.maxConcurrent) {
+            return this.runNow(fn);
+        }
+        // Check if queue is full
+        if (this.queue.length >= this.options.maxQueue) {
+            this.rejected++;
+            this.options.onRejected?.('full');
+            throw new Error(`Bulkhead '${this.options.name}' is full. Max concurrent: ${this.options.maxConcurrent}, queue: ${this.options.maxQueue}`);
+        }
+        // Add to queue
+        return this.addToQueue(fn);
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        return {
+            active: this.active,
+            queued: this.queue.length,
+            maxConcurrent: this.options.maxConcurrent,
+            maxQueue: this.options.maxQueue,
+            completed: this.completed,
+            rejected: this.rejected,
+            timedOut: this.timedOut,
+        };
+    }
+    /**
+     * Check if there's capacity available
+     */
+    hasCapacity() {
+        return this.active < this.options.maxConcurrent || this.queue.length < this.options.maxQueue;
+    }
+    /**
+     * Get available capacity (concurrent + queue)
+     */
+    availableCapacity() {
+        const concurrentAvailable = this.options.maxConcurrent - this.active;
+        const queueAvailable = this.options.maxQueue - this.queue.length;
+        return concurrentAvailable + queueAvailable;
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.completed = 0;
+        this.rejected = 0;
+        this.timedOut = 0;
+    }
+    /**
+     * Run function immediately
+     */
+    async runNow(fn) {
+        this.active++;
+        this.emit('acquire');
+        try {
+            const result = await fn();
+            this.completed++;
+            return result;
+        }
+        finally {
+            this.active--;
+            this.emit('release');
+            this.processQueue();
+        }
+    }
+    /**
+     * Add function to queue
+     */
+    addToQueue(fn) {
+        return new Promise((resolve, reject) => {
+            const item = {
+                fn,
+                resolve,
+                reject,
+                queuedAt: Date.now(),
+            };
+            // Set timeout for queued item
+            item.timeoutId = setTimeout(() => {
+                const index = this.queue.indexOf(item);
+                if (index !== -1) {
+                    this.queue.splice(index, 1);
+                    this.timedOut++;
+                    this.options.onRejected?.('timeout');
+                    reject(new Error(`Bulkhead '${this.options.name}' queue timeout after ${this.options.queueTimeout}ms`));
+                }
+            }, this.options.queueTimeout);
+            this.queue.push(item);
+            this.emit('queued', { queueLength: this.queue.length });
+        });
+    }
+    /**
+     * Process next item in queue
+     */
+    processQueue() {
+        if (this.active >= this.options.maxConcurrent) {
+            return;
+        }
+        const item = this.queue.shift();
+        if (!item) {
+            return;
+        }
+        // Clear timeout
+        if (item.timeoutId) {
+            clearTimeout(item.timeoutId);
+        }
+        // Execute the queued function
+        this.active++;
+        this.emit('acquire');
+        item.fn()
+            .then((result) => {
+            this.completed++;
+            item.resolve(result);
+        })
+            .catch((error) => {
+            item.reject(error);
+        })
+            .finally(() => {
+            this.active--;
+            this.emit('release');
+            this.processQueue();
+        });
+    }
+}
+/**
+ * Create a semaphore for limiting concurrent access
+ */
+export function createSemaphore(maxConcurrent) {
+    let current = 0;
+    const waiting = [];
+    return {
+        async acquire() {
+            if (current < maxConcurrent) {
+                current++;
+                return;
+            }
+            return new Promise((resolve) => {
+                waiting.push(resolve);
+            });
+        },
+        release() {
+            const next = waiting.shift();
+            if (next) {
+                next();
+            }
+            else {
+                current = Math.max(0, current - 1);
+            }
+        },
+        available() {
+            return maxConcurrent - current;
+        },
+    };
+}
+//# sourceMappingURL=bulkhead.js.map

package/v3/@claude-flow/shared/dist/resilience/circuit-breaker.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Circuit Breaker Pattern
+ *
+ * Prevents cascading failures by breaking the circuit after failures.
+ *
+ * @module v3/shared/resilience/circuit-breaker
+ */
+import { EventEmitter } from 'events';
+/**
+ * Circuit breaker states
+ */
+export declare enum CircuitBreakerState {
+    /** Circuit is closed, requests flow normally */
+    CLOSED = "CLOSED",
+    /** Circuit is open, requests are rejected immediately */
+    OPEN = "OPEN",
+    /** Circuit is testing if service recovered */
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit breaker options
+ */
+export interface CircuitBreakerOptions {
+    /** Name for identification */
+    name: string;
+    /** Failure threshold before opening circuit (default: 5) */
+    failureThreshold: number;
+    /** Success threshold in half-open state to close circuit (default: 3) */
+    successThreshold: number;
+    /** Time to wait before testing again in ms (default: 30000) */
+    timeout: number;
+    /** Time window to track failures in ms (default: 60000) */
+    rollingWindow: number;
+    /** Volume threshold - minimum requests before tripping (default: 10) */
+    volumeThreshold: number;
+    /** Custom failure detection */
+    isFailure?: (error: Error) => boolean;
+    /** Fallback function when circuit is open */
+    fallback?: <T>(error: Error) => T | Promise<T>;
+    /** Callback when state changes */
+    onStateChange?: (from: CircuitBreakerState, to: CircuitBreakerState) => void;
+}
+/**
+ * Circuit breaker statistics
+ */
+export interface CircuitBreakerStats {
+    state: CircuitBreakerState;
+    failures: number;
+    successes: number;
+    totalRequests: number;
+    rejectedRequests: number;
+    lastFailure: Date | null;
+    lastSuccess: Date | null;
+    openSince: Date | null;
+}
+/**
+ * Circuit Breaker
+ *
+ * Implements the circuit breaker pattern to prevent cascading failures.
+ *
+ * @example
+ * const breaker = new CircuitBreaker({
+ *   name: 'external-api',
+ *   failureThreshold: 5,
+ *   timeout: 30000,
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(() => fetchExternalAPI());
+ * } catch (error) {
+ *   if (error.message === 'Circuit is open') {
+ *     // Handle circuit open case
+ *   }
+ * }
+ */
+export declare class CircuitBreaker extends EventEmitter {
+    private readonly options;
+    private state;
+    private requests;
+    private halfOpenSuccesses;
+    private openedAt;
+    private lastFailure;
+    private lastSuccess;
+    private rejectedCount;
+    private timeoutId?;
+    constructor(options: CircuitBreakerOptions);
+    /**
+     * Execute a function through the circuit breaker
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get current state
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Get statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Force reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Handle successful request
+     */
+    private onSuccess;
+    /**
+     * Handle failed request
+     */
+    private onFailure;
+    /**
+     * Check if state should change based on timeout
+     */
+    private checkState;
+    /**
+     * Transition to new state
+     */
+    private transitionTo;
+    /**
+     * Schedule transition to half-open
+     */
+    private scheduleHalfOpen;
+    /**
+     * Notify state change
+     */
+    private notifyStateChange;
+    /**
+     * Clean old requests outside rolling window
+     */
+    private cleanOldRequests;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/v3/@claude-flow/shared/dist/resilience/circuit-breaker.js

@@ -0,0 +1,233 @@
+/**
+ * Circuit Breaker Pattern
+ *
+ * Prevents cascading failures by breaking the circuit after failures.
+ *
+ * @module v3/shared/resilience/circuit-breaker
+ */
+import { EventEmitter } from 'events';
+/**
+ * Circuit breaker states
+ */
+export var CircuitBreakerState;
+(function (CircuitBreakerState) {
+    /** Circuit is closed, requests flow normally */
+    CircuitBreakerState["CLOSED"] = "CLOSED";
+    /** Circuit is open, requests are rejected immediately */
+    CircuitBreakerState["OPEN"] = "OPEN";
+    /** Circuit is testing if service recovered */
+    CircuitBreakerState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitBreakerState || (CircuitBreakerState = {}));
+/**
+ * Default options
+ */
+const DEFAULT_OPTIONS = {
+    failureThreshold: 5,
+    successThreshold: 3,
+    timeout: 30000,
+    rollingWindow: 60000,
+    volumeThreshold: 10,
+};
+/**
+ * Circuit Breaker
+ *
+ * Implements the circuit breaker pattern to prevent cascading failures.
+ *
+ * @example
+ * const breaker = new CircuitBreaker({
+ *   name: 'external-api',
+ *   failureThreshold: 5,
+ *   timeout: 30000,
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(() => fetchExternalAPI());
+ * } catch (error) {
+ *   if (error.message === 'Circuit is open') {
+ *     // Handle circuit open case
+ *   }
+ * }
+ */
+export class CircuitBreaker extends EventEmitter {
+    options;
+    state = CircuitBreakerState.CLOSED;
+    requests = [];
+    halfOpenSuccesses = 0;
+    openedAt = null;
+    lastFailure = null;
+    lastSuccess = null;
+    rejectedCount = 0;
+    timeoutId;
+    constructor(options) {
+        super();
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Execute a function through the circuit breaker
+     */
+    async execute(fn) {
+        // Clean up old requests
+        this.cleanOldRequests();
+        // Check if circuit should be tested
+        this.checkState();
+        // If open, reject immediately or use fallback
+        if (this.state === CircuitBreakerState.OPEN) {
+            this.rejectedCount++;
+            const error = new Error(`Circuit breaker '${this.options.name}' is open`);
+            if (this.options.fallback) {
+                return this.options.fallback(error);
+            }
+            throw error;
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            // Check if this should be counted as failure
+            const isFailure = this.options.isFailure?.(err) ?? true;
+            if (isFailure) {
+                this.onFailure(err);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        this.checkState();
+        return this.state;
+    }
+    /**
+     * Get statistics
+     */
+    getStats() {
+        this.cleanOldRequests();
+        return {
+            state: this.state,
+            failures: this.requests.filter((r) => !r.success).length,
+            successes: this.requests.filter((r) => r.success).length,
+            totalRequests: this.requests.length,
+            rejectedRequests: this.rejectedCount,
+            lastFailure: this.lastFailure,
+            lastSuccess: this.lastSuccess,
+            openSince: this.openedAt,
+        };
+    }
+    /**
+     * Force reset the circuit breaker
+     */
+    reset() {
+        const previousState = this.state;
+        this.state = CircuitBreakerState.CLOSED;
+        this.requests = [];
+        this.halfOpenSuccesses = 0;
+        this.openedAt = null;
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = undefined;
+        }
+        if (previousState !== this.state) {
+            this.notifyStateChange(previousState, this.state);
+        }
+    }
+    /**
+     * Handle successful request
+     */
+    onSuccess() {
+        this.lastSuccess = new Date();
+        this.requests.push({ timestamp: Date.now(), success: true });
+        if (this.state === CircuitBreakerState.HALF_OPEN) {
+            this.halfOpenSuccesses++;
+            if (this.halfOpenSuccesses >= this.options.successThreshold) {
+                this.transitionTo(CircuitBreakerState.CLOSED);
+                this.halfOpenSuccesses = 0;
+            }
+        }
+    }
+    /**
+     * Handle failed request
+     */
+    onFailure(error) {
+        this.lastFailure = new Date();
+        this.requests.push({ timestamp: Date.now(), success: false });
+        if (this.state === CircuitBreakerState.HALF_OPEN) {
+            // Failed during half-open, go back to open
+            this.transitionTo(CircuitBreakerState.OPEN);
+            this.halfOpenSuccesses = 0;
+            return;
+        }
+        // Check if we should open the circuit
+        const failures = this.requests.filter((r) => !r.success).length;
+        const totalRequests = this.requests.length;
+        if (totalRequests >= this.options.volumeThreshold &&
+            failures >= this.options.failureThreshold) {
+            this.transitionTo(CircuitBreakerState.OPEN);
+        }
+    }
+    /**
+     * Check if state should change based on timeout
+     */
+    checkState() {
+        if (this.state === CircuitBreakerState.OPEN && this.openedAt) {
+            const elapsed = Date.now() - this.openedAt.getTime();
+            if (elapsed >= this.options.timeout) {
+                this.transitionTo(CircuitBreakerState.HALF_OPEN);
+            }
+        }
+    }
+    /**
+     * Transition to new state
+     */
+    transitionTo(newState) {
+        const previousState = this.state;
+        if (previousState === newState) {
+            return;
+        }
+        this.state = newState;
+        if (newState === CircuitBreakerState.OPEN) {
+            this.openedAt = new Date();
+            this.scheduleHalfOpen();
+        }
+        else if (newState === CircuitBreakerState.CLOSED) {
+            this.openedAt = null;
+            this.requests = [];
+            if (this.timeoutId) {
+                clearTimeout(this.timeoutId);
+                this.timeoutId = undefined;
+            }
+        }
+        this.notifyStateChange(previousState, newState);
+    }
+    /**
+     * Schedule transition to half-open
+     */
+    scheduleHalfOpen() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+        }
+        this.timeoutId = setTimeout(() => {
+            if (this.state === CircuitBreakerState.OPEN) {
+                this.transitionTo(CircuitBreakerState.HALF_OPEN);
+            }
+        }, this.options.timeout);
+    }
+    /**
+     * Notify state change
+     */
+    notifyStateChange(from, to) {
+        this.emit('stateChange', { from, to });
+        this.options.onStateChange?.(from, to);
+    }
+    /**
+     * Clean old requests outside rolling window
+     */
+    cleanOldRequests() {
+        const cutoff = Date.now() - this.options.rollingWindow;
+        this.requests = this.requests.filter((r) => r.timestamp >= cutoff);
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/v3/@claude-flow/shared/dist/resilience/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resilience Patterns
+ *
+ * Production-ready resilience utilities:
+ * - Retry with exponential backoff
+ * - Circuit breaker pattern
+ * - Rate limiting
+ *
+ * @module v3/shared/resilience
+ */
+export { retry, RetryError } from './retry.js';
+export type { RetryOptions, RetryResult } from './retry.js';
+export { CircuitBreaker } from './circuit-breaker.js';
+export type { CircuitBreakerOptions, CircuitBreakerStats } from './circuit-breaker.js';
+export { SlidingWindowRateLimiter, TokenBucketRateLimiter } from './rate-limiter.js';
+export type { RateLimiter, RateLimiterOptions, RateLimitResult } from './rate-limiter.js';
+export { Bulkhead } from './bulkhead.js';
+export type { BulkheadOptions, BulkheadStats } from './bulkhead.js';
+//# sourceMappingURL=index.d.ts.map

package/v3/@claude-flow/shared/dist/resilience/index.js

@@ -0,0 +1,19 @@
+/**
+ * Resilience Patterns
+ *
+ * Production-ready resilience utilities:
+ * - Retry with exponential backoff
+ * - Circuit breaker pattern
+ * - Rate limiting
+ *
+ * @module v3/shared/resilience
+ */
+// Retry
+export { retry, RetryError } from './retry.js';
+// Circuit Breaker
+export { CircuitBreaker } from './circuit-breaker.js';
+// Rate Limiter
+export { SlidingWindowRateLimiter, TokenBucketRateLimiter } from './rate-limiter.js';
+// Bulkhead
+export { Bulkhead } from './bulkhead.js';
+//# sourceMappingURL=index.js.map