<?php

declare(strict_types=1);

namespace App\Framework\Waf\MachineLearning;

use App\Framework\MachineLearning\ValueObjects\Feature;
use App\Framework\Waf\Analysis\ValueObjects\RequestAnalysisData;

/**
 * Domain-specific interface for WAF feature extraction
 *
 * This interface is WAF-specific and uses RequestAnalysisData for type safety.
 * It does NOT extend any other interfaces - pure atomic composition pattern.
 *
 * Implementations should also implement:
 * - FeatureExtractorMetadata (metadata and configuration)
 * - FeatureExtractorPerformance (performance characteristics)
 *
 * Example:
 * ```php
 * final class FrequencyFeatureExtractor implements
 *     WafFeatureExtractor,
 *     FeatureExtractorMetadata,
 *     FeatureExtractorPerformance
 * {
 *     // Implements all methods from all 3 interfaces
 * }
 * ```
 */
interface WafFeatureExtractor
{
    /**
     * Check if extractor can extract features from given request data
     *
     * Allows extractors to skip processing for irrelevant requests
     * (e.g., frequency extractor needs client IP)
     */
    public function canExtract(RequestAnalysisData $requestData): bool;

    /**
     * Extract features from WAF request analysis data
     *
     * @param RequestAnalysisData $requestData Type-safe WAF request data
     * @param array<string, mixed> $context Additional context (e.g., historical data, baseline)
     * @return Feature[] Array of extracted features
     */
    public function extractFeatures(RequestAnalysisData $requestData, array $context = []): array;
}