<?php

declare(strict_types=1);

namespace App\Framework\Waf\Layers;

use App\Framework\Core\ValueObjects\Duration;
use App\Framework\Core\ValueObjects\Percentage;
use App\Framework\Http\Request;
use App\Framework\Waf\LayerResult;
use App\Framework\Waf\ValueObjects\LayerConfig;
use App\Framework\Waf\ValueObjects\LayerMetrics;

/**
 * Interface for all WAF security layers
 * Each layer analyzes requests and returns threat assessment
 */
interface LayerInterface
{
    /**
     * Get unique layer name for identification
     */
    public function getName(): string;

    /**
     * Analyze request and return threat assessment
     */
    public function analyze(Request $request): LayerResult;

    /**
     * Check if layer is enabled and operational
     */
    public function isEnabled(): bool;

    /**
     * Check layer health status
     */
    public function isHealthy(): bool;

    /**
     * Get layer priority (higher = processed first)
     * Allows for dependency-based processing order
     */
    public function getPriority(): int;

    /**
     * Get layer confidence level in its assessments
     * Used for weighted threat scoring
     */
    public function getConfidenceLevel(): Percentage;

    /**
     * Get maximum processing time before timeout
     */
    public function getTimeoutThreshold(): Duration;

    /**
     * Configure layer at runtime
     * Allows dynamic reconfiguration without restart
     */
    public function configure(LayerConfig $config): void;

    /**
     * Get current layer configuration
     */
    public function getConfig(): LayerConfig;

    /**
     * Get layer performance metrics
     */
    public function getMetrics(): LayerMetrics;

    /**
     * Reset layer state (for testing/debugging)
     */
    public function reset(): void;

    /**
     * Warm up layer (preload rules, caches, etc.)
     * Called during WAF initialization
     */
    public function warmUp(): void;

    /**
     * Clean up layer resources
     * Called during WAF shutdown
     */
    public function shutdown(): void;

    /**
     * Get layer dependencies (other layers this depends on)
     * Used for proper initialization order
     */
    public function getDependencies(): array;

    /**
     * Check if layer supports parallel processing
     */
    public function supportsParallelProcessing(): bool;

    /**
     * Get layer version for compatibility checking
     */
    public function getVersion(): string;

    /**
     * Get supported threat categories
     * Returns array of DetectionCategory enums this layer can detect
     */
    public function getSupportedCategories(): array;
}
