<?php

declare(strict_types=1);

namespace App\Framework\LiveComponents\Exceptions;

use App\Framework\Exception\FrameworkException;

/**
 * Exception thrown when state encryption/decryption fails
 *
 * Framework Principles:
 * - Extends FrameworkException for consistent error handling
 * - Readonly class with immutable properties
 * - Factory methods for common error scenarios
 * - No inheritance beyond FrameworkException
 */
final class StateEncryptionException extends FrameworkException
{
    /**
     * Encryption operation failed
     */
    public static function encryptionFailed(
        string $reason,
        ?\Throwable $previous = null
    ): self {
        return self::simple(
            message: "State encryption failed: {$reason}",
            previous: $previous,
            code: 500
        );
    }

    /**
     * Decryption operation failed
     */
    public static function decryptionFailed(
        string $reason,
        ?\Throwable $previous = null
    ): self {
        return self::simple(
            message: "State decryption failed: {$reason}",
            previous: $previous,
            code: 500
        );
    }

    /**
     * Encryption key is invalid or missing
     */
    public static function invalidKey(string $reason): self
    {
        return self::simple(
            message: "Invalid encryption key: {$reason}",
            previous: null,
            code: 500
        );
    }

    /**
     * Data corruption detected
     */
    public static function dataCorrupted(string $details): self
    {
        return self::simple(
            message: "Encrypted state data is corrupted: {$details}",
            previous: null,
            code: 500
        );
    }
}
