/**
 * Cache Error Types and Handling Logic
 * Implements error codes, CacheError class, and graceful degradation
 * Requirements: 13.1, 13.2, 13.3, 13.4
 */
import { Tier } from '../types/index.js';
/**
 * Error codes for cache operations.
 * These codes are returned to clients in RESP error format.
 *
 * Requirements:
 * - 13.1: Return appropriate error code when storage tier becomes unavailable
 * - 13.2: Return error without corrupting existing data on write failure
 * - 13.3: Log warning and skip demotion when SSD_Tier is full
 * - 13.4: Log all errors with sufficient context for debugging
 */
export declare enum CacheErrorCode {
    /** Storage tier is temporarily unavailable */
    ERR_TIER_UNAVAILABLE = "ERR_TIER_UNAVAILABLE",
    /** Cannot store data, tier at capacity */
    ERR_CAPACITY_EXCEEDED = "ERR_CAPACITY_EXCEEDED",
    /** Key not found in any tier */
    ERR_KEY_NOT_FOUND = "ERR_KEY_NOT_FOUND",
    /** Invalid argument provided to operation */
    ERR_INVALID_ARGUMENT = "ERR_INVALID_ARGUMENT",
    /** Operation failed due to internal error */
    ERR_OPERATION_FAILED = "ERR_OPERATION_FAILED",
    /** Operation timed out */
    ERR_TIMEOUT = "ERR_TIMEOUT",
    /** Failed to serialize or deserialize data */
    ERR_SERIALIZATION_FAILED = "ERR_SERIALIZATION_FAILED"
}
/**
 * Custom error class for cache operations.
 * Extends Error with cache-specific properties and RESP serialization.
 *
 * Requirements:
 * - 13.1: Return appropriate error code when storage tier becomes unavailable
 * - 13.4: Log all errors with sufficient context for debugging
 */
export declare class CacheError extends Error {
    /** The error code identifying the type of error */
    readonly code: CacheErrorCode;
    /** The storage tier that caused the error (if applicable) */
    readonly tier?: Tier;
    /** Additional context for debugging */
    readonly context?: Record<string, unknown>;
    /** Timestamp when the error occurred */
    readonly timestamp: number;
    constructor(code: CacheErrorCode, message?: string, options?: {
        tier?: Tier;
        context?: Record<string, unknown>;
        cause?: Error;
    });
    /**
     * Serialize the error to RESP error format.
     * Format: -ERR_CODE message\r\n
     *
     * @returns Buffer containing RESP-formatted error
     */
    toRespError(): Buffer;
    /**
     * Get a detailed string representation for logging.
     * Includes all context information for debugging.
     *
     * Requirement 13.4: Log all errors with sufficient context for debugging
     */
    toDetailedString(): string;
    /**
     * Create a JSON representation for structured logging.
     */
    toJSON(): Record<string, unknown>;
}
/**
 * Type guard to check if an error is a CacheError.
 *
 * @param error - The error to check
 * @returns true if the error is a CacheError instance
 */
export declare function isCacheError(error: unknown): error is CacheError;
/**
 * Create an error for when a storage tier is unavailable.
 *
 * Requirement 13.1: Return appropriate error code when storage tier becomes unavailable
 *
 * @param tier - The tier that is unavailable
 * @param cause - Optional underlying error
 * @returns CacheError with ERR_TIER_UNAVAILABLE code
 */
export declare function createTierUnavailableError(tier: Tier, cause?: Error): CacheError;
/**
 * Create an error for when a tier's capacity is exceeded.
 *
 * Requirement 13.3: Log warning and skip demotion when SSD_Tier is full
 *
 * @param tier - The tier that is at capacity
 * @param context - Optional context (e.g., current usage, capacity)
 * @returns CacheError with ERR_CAPACITY_EXCEEDED code
 */
export declare function createCapacityExceededError(tier: Tier, context?: {
    usedBytes?: number;
    capacityBytes?: number;
}): CacheError;
/**
 * Create an error for when a key is not found.
 *
 * @param key - The key that was not found
 * @returns CacheError with ERR_KEY_NOT_FOUND code
 */
export declare function createKeyNotFoundError(key: string): CacheError;
/**
 * Create an error for invalid arguments.
 *
 * @param message - Description of the invalid argument
 * @param context - Optional context about the invalid argument
 * @returns CacheError with ERR_INVALID_ARGUMENT code
 */
export declare function createInvalidArgumentError(message: string, context?: Record<string, unknown>): CacheError;
/**
 * Create an error for operation failures.
 *
 * Requirement 13.2: Return error without corrupting existing data on write failure
 *
 * @param operation - The operation that failed
 * @param cause - Optional underlying error
 * @param context - Optional context about the operation
 * @returns CacheError with ERR_OPERATION_FAILED code
 */
export declare function createOperationFailedError(operation: string, cause?: Error, context?: Record<string, unknown>): CacheError;
/**
 * Create an error for operation timeouts.
 *
 * @param operation - The operation that timed out
 * @param timeoutMs - The timeout duration in milliseconds
 * @returns CacheError with ERR_TIMEOUT code
 */
export declare function createTimeoutError(operation: string, timeoutMs: number): CacheError;
/**
 * Create an error for serialization failures.
 *
 * @param operation - The serialization operation that failed (e.g., 'serialize', 'deserialize')
 * @param cause - Optional underlying error
 * @returns CacheError with ERR_SERIALIZATION_FAILED code
 */
export declare function createSerializationError(operation: string, cause?: Error): CacheError;
/**
 * Graceful degradation configuration for tier failures.
 */
export interface DegradationConfig {
    /** Whether to allow operation when RAM tier fails */
    allowRamFailure: boolean;
    /** Whether to allow operation when SSD tier fails */
    allowSsdFailure: boolean;
    /** Whether to allow operation when DB tier fails */
    allowDbFailure: boolean;
}
/**
 * Default degradation configuration - allows operation with any single tier failure.
 */
export declare const DEFAULT_DEGRADATION_CONFIG: DegradationConfig;
/**
 * Tracks the health status of storage tiers for graceful degradation.
 *
 * Requirements:
 * - 13.1: Return appropriate error code when storage tier becomes unavailable
 * - Graceful degradation: Continue operation with reduced functionality
 */
export declare class TierHealthTracker {
    private tierStatus;
    private readonly config;
    constructor(config?: DegradationConfig);
    /**
     * Mark a tier as unhealthy due to an error.
     *
     * @param tier - The tier that failed
     * @param error - The error that caused the failure
     */
    markUnhealthy(tier: Tier, error: CacheError): void;
    /**
     * Mark a tier as healthy.
     *
     * @param tier - The tier that recovered
     */
    markHealthy(tier: Tier): void;
    /**
     * Check if a tier is currently healthy.
     *
     * @param tier - The tier to check
     * @returns true if the tier is healthy
     */
    isHealthy(tier: Tier): boolean;
    /**
     * Get the last error for a tier.
     *
     * @param tier - The tier to check
     * @returns The last error, or undefined if healthy
     */
    getLastError(tier: Tier): CacheError | undefined;
    /**
     * Check if the system can continue operating with current tier health.
     * Returns true if at least one tier is available based on degradation config.
     *
     * @returns true if the system can continue operating
     */
    canOperate(): boolean;
    /**
     * Get list of healthy tiers in priority order.
     *
     * @returns Array of healthy tiers
     */
    getHealthyTiers(): Tier[];
    /**
     * Get the health status of all tiers.
     *
     * @returns Map of tier to health status
     */
    getStatus(): Map<Tier, {
        healthy: boolean;
        lastError?: CacheError;
        lastCheck: number;
    }>;
}
/**
 * Convert any error to a CacheError.
 * Useful for wrapping unknown errors in a consistent format.
 *
 * @param error - The error to convert
 * @param defaultCode - The default error code if not a CacheError
 * @returns A CacheError instance
 */
export declare function toCacheError(error: unknown, defaultCode?: CacheErrorCode): CacheError;
//# sourceMappingURL=CacheError.d.ts.map