asupersync-conformance 0.3.4

//! HTTP/2 SETTINGS frame conformance checks.
//!
//! Exercises RFC-backed SETTINGS expected states. The h2 reference side is not
//! wired because h2 does not expose direct SETTINGS frame manipulation, so local
//! expected-state matches are reported as XFAIL instead of vendor-parity PASS.
//!
//! Verifies RFC 7540 Section 6.5 expected-state coverage for:
//! - max_concurrent_streams
//! - initial_window_size
//! - header_table_size

use serde::{Deserialize, Serialize};

const H2_REFERENCE_UNAVAILABLE: &str =
    "h2 reference comparison unavailable in standalone frame harness";

/// Settings field values for comparison between implementations
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettingsSnapshot {
    pub max_concurrent_streams: u32,
    pub initial_window_size: u32,
    pub header_table_size: u32,
    pub max_frame_size: u32,
    pub max_header_list_size: u32,
    pub enable_push: bool,
}

/// A single SETTINGS conformance test case
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SettingsConformanceCase {
    pub id: String,
    pub description: String,
    pub settings_sequence: Vec<SettingsFrame>,
    pub expected_outcome: ExpectedOutcome,
}

/// SETTINGS frame representation for test cases
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SettingsFrame {
    pub settings: Vec<Setting>,
    pub ack: bool,
}

/// Individual SETTINGS parameter
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum Setting {
    HeaderTableSize(u32),
    EnablePush(bool),
    MaxConcurrentStreams(u32),
    InitialWindowSize(u32),
    MaxFrameSize(u32),
    MaxHeaderListSize(u32),
}

/// Expected test outcome
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ExpectedOutcome {
    /// Both implementations should accept and converge to same state
    Success { final_state: SettingsSnapshot },
    /// Both implementations should reject with connection error
    ConnectionError { error_type: String },
    /// Known divergence documented in DISCREPANCIES.md
    Divergence {
        our_behavior: String,
        h2_behavior: String,
    },
}

/// Test execution result
#[derive(Debug, Serialize, Deserialize)]
pub struct ConformanceResult {
    pub case_id: String,
    pub verdict: TestVerdict,
    pub our_state: Option<SettingsSnapshot>,
    pub h2_state: Option<SettingsSnapshot>,
    pub execution_time_ms: u64,
    pub error: Option<String>,
}

/// Test verdict classification
#[derive(Debug, PartialEq, Serialize, Deserialize)]
pub enum TestVerdict {
    Pass,
    Fail,
    ExpectedFailure, // Known divergence (XFAIL)
    Skip,
}

/// Compliance report aggregating all test results
#[derive(Debug, Serialize, Deserialize)]
pub struct ComplianceReport {
    pub test_run_id: String,
    pub timestamp: chrono::DateTime<chrono::Utc>,
    pub total_cases: usize,
    pub results: Vec<ConformanceResult>,
    pub summary: ComplianceSummary,
}

/// Summary statistics for compliance report
#[derive(Debug, Serialize, Deserialize)]
pub struct ComplianceSummary {
    pub passed: usize,
    pub failed: usize,
    pub expected_failures: usize,
    pub skipped: usize,
    pub compliance_score: f64, // passed / (passed + failed)
}

/// Differential SETTINGS conformance tester
pub struct SettingsConformanceTester {
    pub test_cases: Vec<SettingsConformanceCase>,
}

impl Default for SettingsConformanceTester {
    fn default() -> Self {
        Self::new()
    }
}

impl SettingsConformanceTester {
    /// Create new tester with standard RFC 7540 test cases
    pub fn new() -> Self {
        Self {
            test_cases: Self::generate_standard_test_cases(),
        }
    }

    /// Generate comprehensive test cases covering RFC 7540 Section 6.5 requirements
    fn generate_standard_test_cases() -> Vec<SettingsConformanceCase> {
        vec![
            // Basic SETTINGS application
            SettingsConformanceCase {
                id: "RFC7540-6.5-basic-settings".to_string(),
                description: "Basic SETTINGS frame with standard values".to_string(),
                settings_sequence: vec![SettingsFrame {
                    settings: vec![
                        Setting::MaxConcurrentStreams(100),
                        Setting::InitialWindowSize(32768),
                        Setting::HeaderTableSize(8192),
                    ],
                    ack: false,
                }],
                expected_outcome: ExpectedOutcome::Success {
                    final_state: SettingsSnapshot {
                        max_concurrent_streams: 100,
                        initial_window_size: 32768,
                        header_table_size: 8192,
                        max_frame_size: 16384,          // Default
                        max_header_list_size: u32::MAX, // Default unlimited
                        enable_push: true,              // Default for server
                    },
                },
            },
            // Multiple SETTINGS frames (RFC 7540 Section 6.5.3)
            SettingsConformanceCase {
                id: "RFC7540-6.5.3-multiple-frames".to_string(),
                description: "Multiple SETTINGS frames should be processed in order".to_string(),
                settings_sequence: vec![
                    SettingsFrame {
                        settings: vec![Setting::InitialWindowSize(16384)],
                        ack: false,
                    },
                    SettingsFrame {
                        settings: vec![Setting::InitialWindowSize(65536)],
                        ack: false,
                    },
                ],
                expected_outcome: ExpectedOutcome::Success {
                    final_state: SettingsSnapshot {
                        max_concurrent_streams: u32::MAX, // Default unlimited
                        initial_window_size: 65536,       // Last value wins
                        header_table_size: 4096,          // Default
                        max_frame_size: 16384,
                        max_header_list_size: u32::MAX,
                        enable_push: true,
                    },
                },
            },
            // Zero values (some valid, some invalid per RFC 7540)
            SettingsConformanceCase {
                id: "RFC7540-6.5-zero-values".to_string(),
                description:
                    "Zero values for ENABLE_PUSH (valid) and MAX_CONCURRENT_STREAMS (valid)"
                        .to_string(),
                settings_sequence: vec![SettingsFrame {
                    settings: vec![
                        Setting::EnablePush(false),       // 0 = disabled, valid
                        Setting::MaxConcurrentStreams(0), // 0 = unlimited, valid
                    ],
                    ack: false,
                }],
                expected_outcome: ExpectedOutcome::Success {
                    final_state: SettingsSnapshot {
                        max_concurrent_streams: 0,  // Unlimited
                        initial_window_size: 65535, // Default
                        header_table_size: 4096,
                        max_frame_size: 16384,
                        max_header_list_size: u32::MAX,
                        enable_push: false, // Disabled
                    },
                },
            },
            // Invalid INITIAL_WINDOW_SIZE (exceeds maximum)
            SettingsConformanceCase {
                id: "RFC7540-6.5.2-invalid-window-size".to_string(),
                description: "INITIAL_WINDOW_SIZE > 2^31-1 must cause FLOW_CONTROL_ERROR"
                    .to_string(),
                settings_sequence: vec![SettingsFrame {
                    settings: vec![Setting::InitialWindowSize(0x8000_0000)], // 2^31
                    ack: false,
                }],
                expected_outcome: ExpectedOutcome::ConnectionError {
                    error_type: "FLOW_CONTROL_ERROR".to_string(),
                },
            },
            // Invalid MAX_FRAME_SIZE (below minimum)
            SettingsConformanceCase {
                id: "RFC7540-6.5.2-invalid-frame-size-low".to_string(),
                description: "MAX_FRAME_SIZE < 2^14 must cause PROTOCOL_ERROR".to_string(),
                settings_sequence: vec![SettingsFrame {
                    settings: vec![Setting::MaxFrameSize(16383)], // Below 2^14 = 16384
                    ack: false,
                }],
                expected_outcome: ExpectedOutcome::ConnectionError {
                    error_type: "PROTOCOL_ERROR".to_string(),
                },
            },
            // Invalid MAX_FRAME_SIZE (above maximum)
            SettingsConformanceCase {
                id: "RFC7540-6.5.2-invalid-frame-size-high".to_string(),
                description: "MAX_FRAME_SIZE > 2^24-1 must cause PROTOCOL_ERROR".to_string(),
                settings_sequence: vec![SettingsFrame {
                    settings: vec![Setting::MaxFrameSize(0x100_0000)], // 2^24
                    ack: false,
                }],
                expected_outcome: ExpectedOutcome::ConnectionError {
                    error_type: "PROTOCOL_ERROR".to_string(),
                },
            },
            // Empty SETTINGS frame (valid per RFC 7540 Section 6.5)
            SettingsConformanceCase {
                id: "RFC7540-6.5-empty-settings".to_string(),
                description: "Empty SETTINGS frame should be accepted".to_string(),
                settings_sequence: vec![SettingsFrame {
                    settings: vec![],
                    ack: false,
                }],
                expected_outcome: ExpectedOutcome::Success {
                    final_state: SettingsSnapshot {
                        max_concurrent_streams: u32::MAX, // Default
                        initial_window_size: 65535,
                        header_table_size: 4096,
                        max_frame_size: 16384,
                        max_header_list_size: u32::MAX,
                        enable_push: true,
                    },
                },
            },
            // Boundary values
            SettingsConformanceCase {
                id: "RFC7540-6.5-boundary-values".to_string(),
                description: "Maximum valid values for all settings".to_string(),
                settings_sequence: vec![SettingsFrame {
                    settings: vec![
                        Setting::MaxConcurrentStreams(u32::MAX),
                        Setting::InitialWindowSize(0x7FFF_FFFF), // 2^31-1
                        Setting::HeaderTableSize(u32::MAX),
                        Setting::MaxFrameSize(0xFF_FFFF), // 2^24-1
                        Setting::MaxHeaderListSize(u32::MAX),
                    ],
                    ack: false,
                }],
                expected_outcome: ExpectedOutcome::Success {
                    final_state: SettingsSnapshot {
                        max_concurrent_streams: u32::MAX,
                        initial_window_size: 0x7FFF_FFFF,
                        header_table_size: u32::MAX,
                        max_frame_size: 0xFF_FFFF,
                        max_header_list_size: u32::MAX,
                        enable_push: true,
                    },
                },
            },
        ]
    }

    /// Run all conformance tests and generate report
    pub async fn run_all_tests(&self) -> ComplianceReport {
        let test_run_id = format!("settings-conformance-{}", chrono::Utc::now().timestamp());

        let mut results = Vec::new();

        for test_case in &self.test_cases {
            let result = self.run_single_test(test_case).await;
            results.push(result);
        }

        let summary = Self::calculate_summary(&results);

        ComplianceReport {
            test_run_id,
            timestamp: chrono::Utc::now(),
            total_cases: self.test_cases.len(),
            results,
            summary,
        }
    }

    /// Run a single conformance test case
    async fn run_single_test(&self, test_case: &SettingsConformanceCase) -> ConformanceResult {
        let start_time = std::time::Instant::now();

        match self.execute_differential_test(test_case).await {
            Ok((our_state, h2_state)) => {
                let verdict = self.evaluate_test_result(test_case, &our_state, &h2_state);
                ConformanceResult {
                    case_id: test_case.id.clone(),
                    verdict,
                    our_state: Some(our_state),
                    h2_state: Some(h2_state),
                    execution_time_ms: start_time.elapsed().as_millis() as u64,
                    error: None,
                }
            }
            Err(DifferentialError::ReferenceUnavailable { local_state, error }) => {
                let (verdict, message) = match self
                    .evaluate_local_expected_result(test_case, local_state.as_ref())
                {
                    Ok(()) => (
                        TestVerdict::ExpectedFailure,
                        format!(
                            "{error}; local RFC expected-state model matched the test oracle, but live asupersync/h2 vendor parity remains unexercised"
                        ),
                    ),
                    Err(local_error) => (
                        TestVerdict::Fail,
                        format!(
                            "local SETTINGS expected-state model failed while {error}: {local_error}"
                        ),
                    ),
                };

                ConformanceResult {
                    case_id: test_case.id.clone(),
                    verdict,
                    our_state: local_state.ok(),
                    h2_state: None,
                    execution_time_ms: start_time.elapsed().as_millis() as u64,
                    error: Some(message),
                }
            }
            Err(DifferentialError::Failure(error)) => ConformanceResult {
                case_id: test_case.id.clone(),
                verdict: TestVerdict::Fail,
                our_state: None,
                h2_state: None,
                execution_time_ms: start_time.elapsed().as_millis() as u64,
                error: Some(error),
            },
        }
    }

    /// Execute the local RFC model and require an explicit live h2 reference.
    async fn execute_differential_test(
        &self,
        test_case: &SettingsConformanceCase,
    ) -> Result<(SettingsSnapshot, SettingsSnapshot), DifferentialError> {
        // Exercise the local RFC model. This is not a live asupersync endpoint.
        let local_state = self
            .run_local_settings_model(&test_case.settings_sequence)
            .map_err(|e| e.to_string());

        // Test h2 reference implementation when a real seam exists. Today it
        // fails closed instead of fabricating a second local model.
        match self
            .run_h2_reference_settings(&test_case.settings_sequence)
            .await
            .map_err(|e| e.to_string())
        {
            Ok(h2_state) => local_state
                .map(|state| (state, h2_state))
                .map_err(DifferentialError::Failure),
            Err(error) if error == H2_REFERENCE_UNAVAILABLE => {
                Err(DifferentialError::ReferenceUnavailable { local_state, error })
            }
            Err(error) => Err(DifferentialError::Failure(format!(
                "H2 reference error: {error}"
            ))),
        }
    }

    /// Run a SETTINGS sequence through the local RFC expected-state model.
    fn run_local_settings_model(
        &self,
        settings_sequence: &[SettingsFrame],
    ) -> Result<SettingsSnapshot, Box<dyn std::error::Error>> {
        // Local RFC expected-state model. This does not exercise the live
        // asupersync HTTP/2 connection.
        let mut settings_state = SettingsSnapshot {
            max_concurrent_streams: u32::MAX, // Default unlimited
            initial_window_size: 65535,       // RFC 7540 default
            header_table_size: 4096,          // HPACK default
            max_frame_size: 16384,            // RFC 7540 default (2^14)
            max_header_list_size: u32::MAX,   // Default unlimited
            enable_push: false,               // Client default
        };

        // Process each SETTINGS frame to determine expected final state.
        for settings_frame in settings_sequence {
            if !settings_frame.ack {
                for setting in &settings_frame.settings {
                    match setting {
                        Setting::HeaderTableSize(size) => {
                            settings_state.header_table_size = *size;
                        }
                        Setting::EnablePush(enable) => {
                            settings_state.enable_push = *enable;
                        }
                        Setting::MaxConcurrentStreams(max) => {
                            let value = if *max == 0 { u32::MAX } else { *max };
                            settings_state.max_concurrent_streams = value;
                        }
                        Setting::InitialWindowSize(size) => {
                            // Validate against RFC 7540 constraints
                            if *size > 0x7FFF_FFFF {
                                return Err(
                                    "FLOW_CONTROL_ERROR: Initial window size exceeds maximum"
                                        .into(),
                                );
                            }
                            settings_state.initial_window_size = *size;
                        }
                        Setting::MaxFrameSize(size) => {
                            // Validate against RFC 7540 constraints
                            if *size < 16384 || *size > 0xFF_FFFF {
                                return Err("PROTOCOL_ERROR: Invalid frame size".into());
                            }
                            settings_state.max_frame_size = *size;
                        }
                        Setting::MaxHeaderListSize(size) => {
                            settings_state.max_header_list_size = *size;
                        }
                    }
                }
            }
        }

        Ok(settings_state)
    }

    /// Run a SETTINGS sequence on a live h2 reference implementation.
    async fn run_h2_reference_settings(
        &self,
        _settings_sequence: &[SettingsFrame],
    ) -> Result<SettingsSnapshot, Box<dyn std::error::Error + Send + Sync>> {
        Err(H2_REFERENCE_UNAVAILABLE.into())
    }

    fn evaluate_local_expected_result(
        &self,
        test_case: &SettingsConformanceCase,
        local_state: Result<&SettingsSnapshot, &String>,
    ) -> Result<(), String> {
        match (&test_case.expected_outcome, local_state) {
            (ExpectedOutcome::Success { final_state }, Ok(state)) if state == final_state => Ok(()),
            (ExpectedOutcome::Success { final_state }, Ok(state)) => Err(format!(
                "expected final state {:?}, got {:?}",
                final_state, state
            )),
            (ExpectedOutcome::Success { .. }, Err(error)) => {
                Err(format!("expected success, got error {error}"))
            }
            (ExpectedOutcome::ConnectionError { error_type }, Err(error))
                if error.contains(error_type) =>
            {
                Ok(())
            }
            (ExpectedOutcome::ConnectionError { error_type }, Err(error)) => Err(format!(
                "expected {error_type} connection error, got {error}"
            )),
            (ExpectedOutcome::ConnectionError { error_type }, Ok(state)) => Err(format!(
                "expected {error_type} connection error, got state {:?}",
                state
            )),
            (ExpectedOutcome::Divergence { .. }, _) => Ok(()),
        }
    }

    /// Evaluate test result against expected outcome
    fn evaluate_test_result(
        &self,
        test_case: &SettingsConformanceCase,
        our_state: &SettingsSnapshot,
        h2_state: &SettingsSnapshot,
    ) -> TestVerdict {
        match &test_case.expected_outcome {
            ExpectedOutcome::Success { final_state } => {
                if our_state == h2_state && our_state == final_state {
                    TestVerdict::Pass
                } else {
                    TestVerdict::Fail
                }
            }
            ExpectedOutcome::ConnectionError { .. } => {
                // Both should have failed - this would be detected in execute_differential_test
                TestVerdict::Pass
            }
            ExpectedOutcome::Divergence { .. } => {
                // Known divergence - mark as expected failure
                TestVerdict::ExpectedFailure
            }
        }
    }

    /// Calculate summary statistics
    fn calculate_summary(results: &[ConformanceResult]) -> ComplianceSummary {
        let passed = results
            .iter()
            .filter(|r| r.verdict == TestVerdict::Pass)
            .count();
        let failed = results
            .iter()
            .filter(|r| r.verdict == TestVerdict::Fail)
            .count();
        let expected_failures = results
            .iter()
            .filter(|r| r.verdict == TestVerdict::ExpectedFailure)
            .count();
        let skipped = results
            .iter()
            .filter(|r| r.verdict == TestVerdict::Skip)
            .count();

        let compliance_score = if passed + failed > 0 {
            passed as f64 / (passed + failed) as f64
        } else {
            0.0
        };

        ComplianceSummary {
            passed,
            failed,
            expected_failures,
            skipped,
            compliance_score,
        }
    }

    /// Generate markdown compliance report
    pub fn generate_markdown_report(&self, report: &ComplianceReport) -> String {
        let mut md = String::new();

        md.push_str("# HTTP/2 SETTINGS Frame Conformance Report\n\n");
        md.push_str(&format!("**Test Run ID**: {}\n", report.test_run_id));
        md.push_str(&format!("**Timestamp**: {}\n", report.timestamp));
        md.push_str(&format!("**Total Test Cases**: {}\n\n", report.total_cases));

        md.push_str("## Summary\n\n");
        md.push_str(&format!("- **Passed**: {}\n", report.summary.passed));
        md.push_str(&format!("- **Failed**: {}\n", report.summary.failed));
        md.push_str(&format!(
            "- **Expected Failures**: {}\n",
            report.summary.expected_failures
        ));
        md.push_str(&format!("- **Skipped**: {}\n", report.summary.skipped));
        md.push_str(&format!(
            "- **Compliance Score**: {:.1}%\n\n",
            report.summary.compliance_score * 100.0
        ));

        md.push_str("## Detailed Results\n\n");
        md.push_str("| Test Case | Verdict | Execution Time | Notes |\n");
        md.push_str("|-----------|---------|----------------|-------|\n");

        for result in &report.results {
            let verdict_str = match result.verdict {
                TestVerdict::Pass => "✅ PASS",
                TestVerdict::Fail => "❌ FAIL",
                TestVerdict::ExpectedFailure => "⚠️ XFAIL",
                TestVerdict::Skip => "⏭️ SKIP",
            };

            let notes = result.error.as_deref().unwrap_or("-");

            md.push_str(&format!(
                "| {} | {} | {}ms | {} |\n",
                result.case_id, verdict_str, result.execution_time_ms, notes
            ));
        }

        md.push_str("\n## Coverage Matrix\n\n");
        md.push_str("| RFC Section | Local Model Cases | Live h2 Reference | Status |\n");
        md.push_str("|-------------|:-----------------:|:-----------------:|--------|\n");
        md.push_str("| 6.5 (SETTINGS) | 8 | not wired | XFAIL |\n");
        md.push_str("| 6.5.2 (Validation) | 4 | not wired | XFAIL |\n");
        md.push_str("| 6.5.3 (Processing) | 3 | not wired | XFAIL |\n");

        md
    }
}

enum DifferentialError {
    ReferenceUnavailable {
        local_state: Result<SettingsSnapshot, String>,
        error: String,
    },
    Failure(String),
}

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_conformance_runner_basic() {
        let tester = SettingsConformanceTester::new();
        assert!(!tester.test_cases.is_empty(), "Should have test cases");

        // Test case generation
        let basic_case = &tester.test_cases[0];
        assert_eq!(basic_case.id, "RFC7540-6.5-basic-settings");
    }

    #[tokio::test]
    async fn h2_reference_unavailable_fails_closed_after_local_rfc_checks() {
        let tester = SettingsConformanceTester::new();
        let report = tester.run_all_tests().await;

        assert_eq!(report.total_cases, 8);
        assert_eq!(report.summary.passed, 0);
        assert_eq!(report.summary.failed + report.summary.expected_failures, 8);
        assert_eq!(report.summary.skipped, 0);
        assert!(
            report
                .results
                .iter()
                .all(|result| result.verdict != TestVerdict::Pass),
            "unwired h2 reference must not produce PASS verdicts"
        );
        assert!(
            report.results.iter().all(|result| result
                .error
                .as_deref()
                .is_some_and(|error| error.contains(H2_REFERENCE_UNAVAILABLE))),
            "each fail-closed result must name the missing h2 vendor reference"
        );
        assert!(
            report
                .results
                .iter()
                .all(|result| result.h2_state.is_none()),
            "h2 reference is intentionally not wired for this harness"
        );
    }

    #[test]
    fn test_local_settings_model_processing() {
        let tester = SettingsConformanceTester::new();

        // Test basic settings processing
        let settings_sequence = vec![SettingsFrame {
            settings: vec![
                Setting::MaxConcurrentStreams(100),
                Setting::InitialWindowSize(32768),
            ],
            ack: false,
        }];

        let result = tester.run_local_settings_model(&settings_sequence);
        assert!(result.is_ok(), "Settings processing should succeed");

        let snapshot = result.unwrap();
        assert_eq!(snapshot.max_concurrent_streams, 100);
        assert_eq!(snapshot.initial_window_size, 32768);
        assert_eq!(snapshot.header_table_size, 4096); // Default
    }

    #[test]
    fn test_compliance_summary_calculation() {
        let results = vec![
            ConformanceResult {
                case_id: "test1".to_string(),
                verdict: TestVerdict::Pass,
                our_state: None,
                h2_state: None,
                execution_time_ms: 10,
                error: None,
            },
            ConformanceResult {
                case_id: "test2".to_string(),
                verdict: TestVerdict::Fail,
                our_state: None,
                h2_state: None,
                execution_time_ms: 15,
                error: Some("Test error".to_string()),
            },
        ];

        let summary = SettingsConformanceTester::calculate_summary(&results);
        assert_eq!(summary.passed, 1);
        assert_eq!(summary.failed, 1);
        assert_eq!(summary.compliance_score, 0.5);
    }
}