@felixgeelhaar/govee-api-client/dist/infrastructure/retry/RetryPolicy.d.ts

Enterprise-grade TypeScript client library for the Govee Developer REST API

import { Logger } from 'pino';
import { GoveeApiClientError } from '../../errors';
/**
 * Backoff strategy configuration for retry policies
 */
export interface BackoffStrategy {
    /** Type of backoff algorithm */
    type: 'exponential' | 'linear' | 'fixed' | 'custom';
    /** Initial delay in milliseconds */
    initialDelayMs: number;
    /** Maximum delay between retries in milliseconds */
    maxDelayMs: number;
    /** Multiplier for exponential backoff (default: 2.0) */
    multiplier?: number;
    /** Custom backoff function for 'custom' type */
    customBackoff?: (attempt: number, error: GoveeApiClientError) => number;
}
/**
 * Jitter configuration to prevent thundering herd problems
 */
export interface JitterConfig {
    /** Type of jitter algorithm */
    type: 'none' | 'full' | 'equal' | 'decorrelated';
    /** Jitter factor (0.0 to 1.0) */
    factor?: number;
}
/**
 * Retry condition configuration
 */
export interface RetryCondition {
    /** Maximum number of retry attempts */
    maxAttempts: number;
    /** Maximum total time to spend retrying in milliseconds */
    maxTotalTimeMs: number;
    /** HTTP status codes that should trigger retries */
    retryableStatusCodes: number[];
    /** Error types that should trigger retries */
    retryableErrorTypes: (new (...args: any[]) => GoveeApiClientError)[];
    /** Custom retry decision function */
    shouldRetry?: (error: GoveeApiClientError, attempt: number, elapsed: number) => boolean;
}
/**
 * Circuit breaker configuration for retry policies
 */
export interface CircuitBreakerConfig {
    /** Enable circuit breaker functionality */
    enabled: boolean;
    /** Number of consecutive failures to open circuit */
    failureThreshold: number;
    /** Time to wait before attempting to close circuit (ms) */
    recoveryTimeoutMs: number;
    /** Percentage of requests to allow through when half-open */
    halfOpenSuccessThreshold: number;
}
/**
 * Retry metrics for observability
 */
export interface RetryMetrics {
    /** Total number of retry attempts */
    totalAttempts: number;
    /** Total number of successful retries */
    successfulRetries: number;
    /** Total number of failed retries */
    failedRetries: number;
    /** Total time spent retrying */
    totalRetryTimeMs: number;
    /** Average retry delay */
    averageRetryDelayMs: number;
    /** Circuit breaker state */
    circuitBreakerState: 'closed' | 'open' | 'half-open';
    /** Last error encountered */
    lastError?: GoveeApiClientError;
    /** Timestamp of last retry attempt */
    lastRetryTimestamp?: Date;
}
/**
 * Complete retry policy configuration
 */
export interface RetryPolicyConfig {
    /** Backoff strategy configuration */
    backoff: BackoffStrategy;
    /** Jitter configuration */
    jitter: JitterConfig;
    /** Retry condition configuration */
    condition: RetryCondition;
    /** Circuit breaker configuration */
    circuitBreaker?: CircuitBreakerConfig;
    /** Logger instance for retry operations */
    logger?: Logger;
    /** Enable detailed metrics collection */
    enableMetrics?: boolean;
}
/**
 * Enterprise-grade retry policy with exponential backoff, jitter, and circuit breaker
 */
export declare class RetryPolicy {
    private readonly config;
    private readonly circuitBreaker?;
    private readonly metrics;
    private readonly logger?;
    constructor(config: RetryPolicyConfig);
    private validateConfig;
    /**
     * Determines if an error should trigger a retry attempt
     */
    shouldRetry(error: GoveeApiClientError, attempt: number, elapsedTimeMs: number): boolean;
    /**
     * Calculates the delay before the next retry attempt
     */
    calculateDelay(attempt: number, error: GoveeApiClientError): number;
    /**
     * Applies jitter to prevent thundering herd problems
     */
    private applyJitter;
    /**
     * Records a successful operation
     */
    recordSuccess(): void;
    /**
     * Records a failed operation
     */
    recordFailure(error: GoveeApiClientError): void;
    /**
     * Updates retry metrics
     */
    private updateMetrics;
    /**
     * Gets current retry metrics
     */
    getMetrics(): Readonly<RetryMetrics>;
    /**
     * Resets retry metrics and circuit breaker
     */
    reset(): void;
    /**
     * Creates a default retry policy optimized for Govee API
     */
    static createGoveeOptimized(logger?: Logger): RetryPolicy;
    /**
     * Creates a conservative retry policy for production environments
     */
    static createConservative(logger?: Logger): RetryPolicy;
    /**
     * Creates an aggressive retry policy for development/testing
     */
    static createAggressive(logger?: Logger): RetryPolicy;
}
//# sourceMappingURL=RetryPolicy.d.ts.map