mockforge_http/

lib.rs

// TODO: remove once mockforge-intelligence, mockforge-proxy, etc. crates are extracted
// Deprecation allowances are now scoped to individual handler files
// (handlers/*.rs, middleware/drift_tracking.rs, rag_ai_generator.rs,
// management/ai_gen.rs) and to specific build_router functions below,
// rather than being crate-wide.

//! # MockForge HTTP
//!
//! HTTP/REST API mocking library for MockForge.
//!
//! This crate provides HTTP-specific functionality for creating mock REST APIs,
//! including OpenAPI integration, request validation, AI-powered response generation,
//! and management endpoints.
//!
//! ## Overview
//!
//! MockForge HTTP enables you to:
//!
//! - **Serve OpenAPI specs**: Automatically generate mock endpoints from OpenAPI/Swagger
//! - **Validate requests**: Enforce schema validation with configurable modes
//! - **AI-powered responses**: Generate intelligent responses using LLMs
//! - **Management API**: Real-time monitoring, configuration, and control
//! - **Request logging**: Comprehensive HTTP request/response logging
//! - **Metrics collection**: Track performance and usage statistics
//! - **Server-Sent Events**: Stream logs and metrics to clients
//!
//! ## Quick Start
//!
//! ### Basic HTTP Server from OpenAPI
//!
//! ```rust,no_run
//! use axum::Router;
//! use mockforge_openapi::openapi_routes::ValidationMode;
//! use mockforge_openapi::openapi_routes::ValidationOptions;
//! use mockforge_http::build_router;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Build router from OpenAPI specification
//!     let router = build_router(
//!         Some("./api-spec.json".to_string()),
//!         Some(ValidationOptions {
//!             request_mode: ValidationMode::Enforce,
//!             ..ValidationOptions::default()
//!         }),
//!         None,
//!     ).await;
//!
//!     // Start the server
//!     let addr: std::net::SocketAddr = "0.0.0.0:3000".parse()?;
//!     let listener = tokio::net::TcpListener::bind(addr).await?;
//!     axum::serve(listener, router).await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! ### With Management API
//!
//! Enable real-time monitoring and configuration:
//!
//! ```rust,no_run
//! use mockforge_http::{management_router, ManagementState};
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let state = ManagementState::new(None, None, 3000);
//!
//! // Build management router
//! let mgmt_router = management_router(state);
//!
//! // Mount under your main router
//! let app = axum::Router::new()
//!     .nest("/__mockforge", mgmt_router);
//! # Ok(())
//! # }
//! ```
//!
//! ### AI-Powered Responses
//!
//! Generate intelligent responses based on request context:
//!
//! ```rust,no_run
//! use mockforge_data::intelligent_mock::{IntelligentMockConfig, ResponseMode};
//! use mockforge_http::{process_response_with_ai, AiResponseConfig};
//! use serde_json::json;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let ai_config = AiResponseConfig {
//!     intelligent: Some(
//!         IntelligentMockConfig::new(ResponseMode::Intelligent)
//!             .with_prompt("Generate realistic user data".to_string()),
//!     ),
//!     drift: None,
//! };
//!
//! let response = process_response_with_ai(
//!     Some(json!({"name": "Alice"})),
//!     ai_config
//!         .intelligent
//!         .clone()
//!         .map(serde_json::to_value)
//!         .transpose()?,
//!     ai_config
//!         .drift
//!         .clone()
//!         .map(serde_json::to_value)
//!         .transpose()?,
//! )
//! .await?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Key Features
//!
//! ### OpenAPI Integration
//! - Automatic endpoint generation from specs
//! - Request/response validation
//! - Schema-based mock data generation
//!
//! ### Management & Monitoring
//! - [`management`]: REST API for server control and monitoring
//! - [`management_ws`]: WebSocket API for real-time updates
//! - [`sse`]: Server-Sent Events for log streaming
//! - [`request_logging`]: Comprehensive request/response logging
//! - [`metrics_middleware`]: Performance metrics collection
//!
//! ### Advanced Features
//! - [`ai_handler`]: AI-powered response generation
//! - [`auth`]: Authentication and authorization
//! - [`chain_handlers`]: Multi-step request workflows
//! - [`latency_profiles`]: Configurable latency simulation
//! - [`replay_listing`]: Fixture management
//!
//! ## Middleware
//!
//! MockForge HTTP includes several middleware layers:
//!
//! - **Request Tracing**: [`http_tracing_middleware`] - Distributed tracing integration
//! - **Metrics Collection**: [`metrics_middleware`] - Prometheus-compatible metrics
//! - **Operation Metadata**: [`op_middleware`] - OpenAPI operation tracking
//!
//! ## Management API Endpoints
//!
//! When using the management router, these endpoints are available:
//!
//! - `GET /health` - Health check
//! - `GET /stats` - Server statistics
//! - `GET /logs` - Request logs (SSE stream)
//! - `GET /metrics` - Performance metrics
//! - `GET /fixtures` - List available fixtures
//! - `POST /config/*` - Update configuration
//!
//! ## Examples
//!
//! See the [examples directory](https://github.com/SaaSy-Solutions/mockforge/tree/main/examples)
//! for complete working examples.
//!
//! ## Related Crates
//!
//! - [`mockforge-core`](https://docs.rs/mockforge-core): Core mocking functionality
//! - [`mockforge-data`](https://docs.rs/mockforge-data): Synthetic data generation
//! - [`mockforge-plugin-core`](https://docs.rs/mockforge-plugin-core): Plugin development
//!
//! ## Documentation
//!
//! - [MockForge Book](https://docs.mockforge.dev/)
//! - [HTTP Mocking Guide](https://docs.mockforge.dev/user-guide/http-mocking.html)
//! - [API Reference](https://docs.rs/mockforge-http)

pub mod ai_handler;
pub mod auth;
pub mod chain_handlers;
/// Cross-protocol consistency engine integration for HTTP
pub mod consistency;
/// Contract diff retrieval API
pub mod contract_diff_api;
/// Contract diff middleware for automatic request capture
pub mod contract_diff_middleware;
/// TCP-listener wrapper that bumps the global `record_accept()` counter,
/// used by the dashboard sampler to derive connections-per-second.
pub mod counting_listener;
pub mod coverage;
pub mod database;
/// File generation service for creating mock PDF, CSV, JSON files
pub mod file_generator;
/// File serving for generated mock files
pub mod file_server;
/// Fixtures management API for hosted-mock deployments
pub mod fixtures_api;
/// Kubernetes-native health check endpoints (liveness, readiness, startup probes)
pub mod health;
pub mod http_tracing_middleware;
/// Latency profile configuration for HTTP request simulation
pub mod latency_profiles;
/// Management API for server control and monitoring
pub mod management;
/// WebSocket-based management API for real-time updates
pub mod management_ws;
pub mod metrics_middleware;
pub mod middleware;
/// Standalone MockAI HTTP API
pub mod mockai_api;
/// Runtime network-profile switching API
pub mod network_profile_runtime;
pub mod op_middleware;
/// Unified protocol server lifecycle implementation
pub mod protocol_server;
/// Browser/Mobile Proxy Server
pub mod proxy_server;
/// Quick mock generation utilities
pub mod quick_mock;
/// RAG-powered AI response generation
pub mod rag_ai_generator;
/// Reality-slider-driven mock/proxy switching middleware (#222)
pub mod reality_proxy;
/// Replay listing and fixture management
pub mod replay_listing;
pub mod request_logging;
/// Runtime route-scoped chaos rules API
pub mod route_chaos_runtime;
/// Runtime named-scenario activation API
#[cfg(feature = "scenario-engine")]
pub mod scenarios_runtime;
/// Specification import API for OpenAPI and AsyncAPI
pub mod spec_import;
/// Server-Sent Events for streaming logs and metrics
pub mod sse;
/// State machine API for scenario state machines
pub mod state_machine_api;
/// Time-travel runtime API mirrored from the admin server onto the main HTTP port
pub mod time_travel_api;
/// TLS/HTTPS support
pub mod tls;
/// Token response utilities
pub mod token_response;
/// UI Builder API for low-code mock endpoint creation
pub mod ui_builder;
/// Verification API for request verification
pub mod verification;

// Access review handlers
pub mod handlers;

// Re-export AI handler utilities
pub use ai_handler::{process_response_with_ai, AiResponseConfig, AiResponseHandler};
// Re-export health check utilities
pub use health::{HealthManager, ServiceStatus};

// Re-export management API utilities
pub use management::{
    management_router, management_router_with_ui_builder, ManagementState, MockConfig,
    ServerConfig, ServerStats,
};

// Re-export UI Builder utilities
pub use ui_builder::{create_ui_builder_router, EndpointConfig, UIBuilderState};

// Re-export management WebSocket utilities
pub use management_ws::{ws_management_router, MockEvent, WsManagementState};

// Re-export verification API utilities
pub use verification::verification_router;

// Re-export metrics middleware
pub use metrics_middleware::collect_http_metrics;

// Re-export tracing middleware
pub use http_tracing_middleware::http_tracing_middleware;

// Re-export coverage utilities
pub use coverage::{calculate_coverage, CoverageReport, MethodCoverage, RouteCoverage};

/// Helper function to load persona from config file
/// Tries to load from common config locations: config.yaml, mockforge.yaml, tools/mockforge/config.yaml
async fn load_persona_from_config() -> Option<Arc<Persona>> {
    use mockforge_core::config::load_config;

    // Try common config file locations
    let config_paths = [
        "config.yaml",
        "mockforge.yaml",
        "tools/mockforge/config.yaml",
        "../tools/mockforge/config.yaml",
    ];

    for path in &config_paths {
        if let Ok(config) = load_config(path).await {
            // Access intelligent_behavior through mockai config
            // Note: Config structure is mockai.intelligent_behavior.personas
            if let Some(persona) = config.mockai.intelligent_behavior.personas.get_active_persona()
            {
                tracing::info!(
                    "Loaded active persona '{}' from config file: {}",
                    persona.name,
                    path
                );
                return Some(Arc::new(persona.clone()));
            } else {
                tracing::debug!(
                    "No active persona found in config file: {} (personas count: {})",
                    path,
                    config.mockai.intelligent_behavior.personas.personas.len()
                );
            }
        } else {
            tracing::debug!("Could not load config from: {}", path);
        }
    }

    tracing::debug!("No persona found in config files, persona-based generation will be disabled");
    None
}

use axum::body::Body;
use axum::extract::State;
use axum::http::Request;
use axum::middleware::from_fn_with_state;
use axum::response::Json;
use axum::Router;
use mockforge_chaos::core_failure_injection::{FailureConfig, FailureInjector};
use mockforge_core::intelligent_behavior::config::Persona;
use mockforge_foundation::latency::LatencyInjector;
use mockforge_openapi::openapi_routes::OpenApiRouteRegistry;
use mockforge_openapi::openapi_routes::ValidationOptions;
use mockforge_openapi::OpenApiSpec;
use std::sync::Arc;
use tower_http::cors::{Any, CorsLayer};

#[cfg(feature = "data-faker")]
use mockforge_data::provider::register_core_faker_provider;
use mockforge_foundation::latency::LatencyProfile;
use std::collections::HashMap;
use std::ffi::OsStr;
use std::path::Path;
use tokio::fs;
use tokio::sync::RwLock;
use tracing::*;

/// Route info for storing in state
#[derive(Clone)]
pub struct RouteInfo {
    /// HTTP method (GET, POST, PUT, etc.)
    pub method: String,
    /// API path pattern (e.g., "/api/users/{id}")
    pub path: String,
    /// OpenAPI operation ID if available
    pub operation_id: Option<String>,
    /// Operation summary from OpenAPI spec
    pub summary: Option<String>,
    /// Operation description from OpenAPI spec
    pub description: Option<String>,
    /// List of parameter names for this route
    pub parameters: Vec<String>,
}

/// Shared state for tracking OpenAPI routes
#[derive(Clone)]
pub struct HttpServerState {
    /// List of registered routes from OpenAPI spec
    pub routes: Vec<RouteInfo>,
    /// Optional global rate limiter for request throttling
    pub rate_limiter: Option<Arc<middleware::rate_limit::GlobalRateLimiter>>,
    /// Production headers to add to all responses (for deceptive deploy)
    pub production_headers: Option<Arc<HashMap<String, String>>>,
}

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

impl HttpServerState {
    /// Create a new empty HTTP server state
    pub fn new() -> Self {
        Self {
            routes: Vec::new(),
            rate_limiter: None,
            production_headers: None,
        }
    }

    /// Create HTTP server state with pre-configured routes
    pub fn with_routes(routes: Vec<RouteInfo>) -> Self {
        Self {
            routes,
            rate_limiter: None,
            production_headers: None,
        }
    }

    /// Add a rate limiter to the HTTP server state
    pub fn with_rate_limiter(
        mut self,
        rate_limiter: Arc<middleware::rate_limit::GlobalRateLimiter>,
    ) -> Self {
        self.rate_limiter = Some(rate_limiter);
        self
    }

    /// Add production headers to the HTTP server state
    pub fn with_production_headers(mut self, headers: Arc<HashMap<String, String>>) -> Self {
        self.production_headers = Some(headers);
        self
    }
}

/// Handler to return OpenAPI routes information
async fn get_routes_handler(State(state): State<HttpServerState>) -> Json<serde_json::Value> {
    let route_info: Vec<serde_json::Value> = state
        .routes
        .iter()
        .map(|route| {
            serde_json::json!({
                "method": route.method,
                "path": route.path,
                "operation_id": route.operation_id,
                "summary": route.summary,
                "description": route.description,
                "parameters": route.parameters
            })
        })
        .collect();

    Json(serde_json::json!({
        "routes": route_info,
        "total": state.routes.len()
    }))
}

/// Handler to serve the Scalar API docs page
async fn get_docs_handler() -> axum::response::Html<&'static str> {
    axum::response::Html(include_str!("../static/docs.html"))
}

/// Build the base HTTP router, optionally from an OpenAPI spec.
pub async fn build_router(
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    failure_config: Option<FailureConfig>,
) -> Router {
    build_router_with_multi_tenant(
        spec_path,
        options,
        failure_config,
        None,
        None,
        None,
        None,
        None,
        None,
        None,
    )
    .await
}

/// Apply CORS middleware to the router based on configuration
fn apply_cors_middleware(
    app: Router,
    cors_config: Option<mockforge_core::config::HttpCorsConfig>,
) -> Router {
    use http::Method;
    use tower_http::cors::AllowOrigin;

    if let Some(config) = cors_config {
        if !config.enabled {
            return app;
        }

        let mut cors_layer = CorsLayer::new();
        let is_wildcard_origin;

        // Configure allowed origins
        if config.allowed_origins.contains(&"*".to_string()) {
            cors_layer = cors_layer.allow_origin(Any);
            is_wildcard_origin = true;
        } else if !config.allowed_origins.is_empty() {
            // Try to parse each origin, fallback to permissive if parsing fails
            let origins: Vec<_> = config
                .allowed_origins
                .iter()
                .filter_map(|origin| {
                    origin.parse::<http::HeaderValue>().ok().map(AllowOrigin::exact)
                })
                .collect();

            if origins.is_empty() {
                // If no valid origins, use permissive for development
                warn!("No valid CORS origins configured, using permissive CORS");
                cors_layer = cors_layer.allow_origin(Any);
                is_wildcard_origin = true;
            } else {
                // Use the first origin as exact match (tower-http limitation)
                // For multiple origins, we'd need a custom implementation
                if origins.len() == 1 {
                    cors_layer = cors_layer.allow_origin(origins[0].clone());
                    is_wildcard_origin = false;
                } else {
                    // Multiple origins - use permissive for now
                    warn!(
                        "Multiple CORS origins configured, using permissive CORS. \
                        Consider using '*' for all origins."
                    );
                    cors_layer = cors_layer.allow_origin(Any);
                    is_wildcard_origin = true;
                }
            }
        } else {
            // No origins specified, use permissive for development
            cors_layer = cors_layer.allow_origin(Any);
            is_wildcard_origin = true;
        }

        // Configure allowed methods
        if !config.allowed_methods.is_empty() {
            let methods: Vec<Method> =
                config.allowed_methods.iter().filter_map(|m| m.parse().ok()).collect();
            if !methods.is_empty() {
                cors_layer = cors_layer.allow_methods(methods);
            }
        } else {
            // Default to common HTTP methods
            cors_layer = cors_layer.allow_methods([
                Method::GET,
                Method::POST,
                Method::PUT,
                Method::DELETE,
                Method::PATCH,
                Method::OPTIONS,
            ]);
        }

        // Configure allowed headers
        if !config.allowed_headers.is_empty() {
            let headers: Vec<_> = config
                .allowed_headers
                .iter()
                .filter_map(|h| h.parse::<http::HeaderName>().ok())
                .collect();
            if !headers.is_empty() {
                cors_layer = cors_layer.allow_headers(headers);
            }
        } else {
            // Default headers
            cors_layer =
                cors_layer.allow_headers([http::header::CONTENT_TYPE, http::header::AUTHORIZATION]);
        }

        // Configure credentials - cannot allow credentials with wildcard origin
        // Determine if credentials should be allowed
        // Cannot allow credentials with wildcard origin per CORS spec
        let should_allow_credentials = if is_wildcard_origin {
            // Wildcard origin - credentials must be false
            false
        } else {
            // Specific origins - use config value (defaults to false)
            config.allow_credentials
        };

        cors_layer = cors_layer.allow_credentials(should_allow_credentials);

        info!(
            "CORS middleware enabled with configured settings (credentials: {})",
            should_allow_credentials
        );
        app.layer(cors_layer)
    } else {
        // No CORS config provided - use permissive CORS for development
        // Note: permissive() allows credentials, but since it uses wildcard origin,
        // we need to disable credentials to avoid CORS spec violation
        debug!("No CORS config provided, using permissive CORS for development");
        // Create a permissive CORS layer but disable credentials to avoid CORS spec violation
        // (cannot combine credentials with wildcard origin)
        app.layer(CorsLayer::permissive().allow_credentials(false))
    }
}

/// Build the base HTTP router with multi-tenant workspace support
#[allow(clippy::too_many_arguments)]
#[allow(deprecated)] // uses MockAI, MultiTenantWorkspaceRegistry, WorkspaceRouter, Workspace (all stay in core)
pub async fn build_router_with_multi_tenant(
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    failure_config: Option<FailureConfig>,
    multi_tenant_config: Option<mockforge_foundation::multi_tenant_types::MultiTenantConfig>,
    _route_configs: Option<Vec<mockforge_core::config::RouteConfig>>,
    cors_config: Option<mockforge_core::config::HttpCorsConfig>,
    ai_generator: Option<Arc<dyn mockforge_openapi::response::AiGenerator + Send + Sync>>,
    smtp_registry: Option<Arc<dyn std::any::Any + Send + Sync>>,
    mockai: Option<Arc<RwLock<mockforge_core::intelligent_behavior::MockAI>>>,
    deceptive_deploy_config: Option<mockforge_core::config::DeceptiveDeployConfig>,
) -> Router {
    use std::time::Instant;

    let startup_start = Instant::now();

    // Set up the basic router
    let mut app = Router::new();

    // Initialize rate limiter with default configuration
    // Can be customized via environment variables or config
    let mut rate_limit_config = middleware::RateLimitConfig {
        requests_per_minute: std::env::var("MOCKFORGE_RATE_LIMIT_RPM")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(1000),
        burst: std::env::var("MOCKFORGE_RATE_LIMIT_BURST")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(2000),
        per_ip: true,
        per_endpoint: false,
    };

    // Apply deceptive deploy configuration if enabled
    let mut final_cors_config = cors_config;
    let mut production_headers: Option<std::sync::Arc<HashMap<String, String>>> = None;
    // Auth config from deceptive deploy OAuth (if configured)
    let mut deceptive_deploy_auth_config: Option<mockforge_core::config::AuthConfig> = None;

    if let Some(deploy_config) = &deceptive_deploy_config {
        if deploy_config.enabled {
            info!("Deceptive deploy mode enabled - applying production-like configuration");

            // Override CORS config if provided
            if let Some(prod_cors) = &deploy_config.cors {
                final_cors_config = Some(mockforge_core::config::HttpCorsConfig {
                    enabled: true,
                    allowed_origins: prod_cors.allowed_origins.clone(),
                    allowed_methods: prod_cors.allowed_methods.clone(),
                    allowed_headers: prod_cors.allowed_headers.clone(),
                    allow_credentials: prod_cors.allow_credentials,
                });
                info!("Applied production-like CORS configuration");
            }

            // Override rate limit config if provided
            if let Some(prod_rate_limit) = &deploy_config.rate_limit {
                rate_limit_config = middleware::RateLimitConfig {
                    requests_per_minute: prod_rate_limit.requests_per_minute,
                    burst: prod_rate_limit.burst,
                    per_ip: prod_rate_limit.per_ip,
                    per_endpoint: false,
                };
                info!(
                    "Applied production-like rate limiting: {} req/min, burst: {}",
                    prod_rate_limit.requests_per_minute, prod_rate_limit.burst
                );
            }

            // Set production headers
            if !deploy_config.headers.is_empty() {
                let headers_map: HashMap<String, String> = deploy_config.headers.clone();
                production_headers = Some(std::sync::Arc::new(headers_map));
                info!("Configured {} production headers", deploy_config.headers.len());
            }

            // Integrate OAuth config from deceptive deploy
            if let Some(prod_oauth) = &deploy_config.oauth {
                let oauth2_config: mockforge_core::config::OAuth2Config = prod_oauth.clone().into();
                deceptive_deploy_auth_config = Some(mockforge_core::config::AuthConfig {
                    oauth2: Some(oauth2_config),
                    ..Default::default()
                });
                info!("Applied production-like OAuth configuration for deceptive deploy");
            }
        }
    }

    let rate_limit_disabled = middleware::is_rate_limit_disabled();
    let rate_limiter =
        std::sync::Arc::new(middleware::GlobalRateLimiter::new(rate_limit_config.clone()));

    let mut state = HttpServerState::new();
    if rate_limit_disabled {
        info!(
            "HTTP rate limiting disabled (MOCKFORGE_RATE_LIMIT_ENABLED=false or --no-rate-limit)"
        );
    } else {
        state = state.with_rate_limiter(rate_limiter.clone());
    }

    // Add production headers to state if configured
    if let Some(headers) = production_headers.clone() {
        state = state.with_production_headers(headers);
    }

    // Clone spec_path for later use
    let spec_path_for_mgmt = spec_path.clone();

    // If an OpenAPI spec is provided, integrate it
    if let Some(spec_path) = spec_path {
        tracing::debug!("Processing OpenAPI spec path: {}", spec_path);

        // Measure OpenAPI spec loading
        let spec_load_start = Instant::now();
        match OpenApiSpec::from_file(&spec_path).await {
            Ok(openapi) => {
                let spec_load_duration = spec_load_start.elapsed();
                info!(
                    "Successfully loaded OpenAPI spec from {} (took {:?})",
                    spec_path, spec_load_duration
                );

                // Measure route registry creation
                tracing::debug!("Creating OpenAPI route registry...");
                let registry_start = Instant::now();

                // Try to load persona from config if available
                let persona = load_persona_from_config().await;

                let registry = if let Some(opts) = options {
                    tracing::debug!("Using custom validation options");
                    if let Some(ref persona) = persona {
                        tracing::info!("Using persona '{}' for route generation", persona.name);
                    }
                    OpenApiRouteRegistry::new_with_options_and_persona(openapi, opts, persona)
                } else {
                    tracing::debug!("Using environment-based options");
                    if let Some(ref persona) = persona {
                        tracing::info!("Using persona '{}' for route generation", persona.name);
                    }
                    OpenApiRouteRegistry::new_with_env_and_persona(openapi, persona)
                };
                let registry_duration = registry_start.elapsed();
                info!(
                    "Created OpenAPI route registry with {} routes (took {:?})",
                    registry.routes().len(),
                    registry_duration
                );

                // Measure route extraction
                let extract_start = Instant::now();
                let route_info: Vec<RouteInfo> = registry
                    .routes()
                    .iter()
                    .map(|route| RouteInfo {
                        method: route.method.clone(),
                        path: route.path.clone(),
                        operation_id: route.operation.operation_id.clone(),
                        summary: route.operation.summary.clone(),
                        description: route.operation.description.clone(),
                        parameters: route.parameters.clone(),
                    })
                    .collect();
                state.routes = route_info;
                let extract_duration = extract_start.elapsed();
                debug!("Extracted route information (took {:?})", extract_duration);

                // Measure overrides loading
                let overrides = if std::env::var("MOCKFORGE_HTTP_OVERRIDES_GLOB").is_ok() {
                    tracing::debug!("Loading overrides from environment variable");
                    let overrides_start = Instant::now();
                    match mockforge_core::Overrides::load_from_globs(&[]).await {
                        Ok(overrides) => {
                            let overrides_duration = overrides_start.elapsed();
                            info!(
                                "Loaded {} override rules (took {:?})",
                                overrides.rules().len(),
                                overrides_duration
                            );
                            Some(overrides)
                        }
                        Err(e) => {
                            tracing::warn!("Failed to load overrides: {}", e);
                            None
                        }
                    }
                } else {
                    None
                };

                // Measure router building
                let router_build_start = Instant::now();
                let overrides_enabled = overrides.is_some();
                let response_rewriter: Option<
                    std::sync::Arc<dyn mockforge_openapi::response_rewriter::ResponseRewriter>,
                > = Some(std::sync::Arc::new(
                    mockforge_core::openapi_rewriter::CoreResponseRewriter::new(overrides),
                ));
                let openapi_router = if let Some(mockai_instance) = &mockai {
                    tracing::debug!("Building router with MockAI support");
                    registry.build_router_with_mockai(Some(mockai_instance.clone()))
                } else if let Some(ai_generator) = &ai_generator {
                    tracing::debug!("Building router with AI generator support");
                    registry.build_router_with_ai(Some(ai_generator.clone()))
                } else if let Some(failure_config) = &failure_config {
                    tracing::debug!("Building router with failure injection and overrides");
                    let failure_injector = FailureInjector::new(Some(failure_config.clone()), true);
                    registry.build_router_with_injectors_and_overrides(
                        LatencyInjector::default(),
                        Some(failure_injector),
                        response_rewriter,
                        overrides_enabled,
                    )
                } else {
                    tracing::debug!("Building router with overrides");
                    registry.build_router_with_injectors_and_overrides(
                        LatencyInjector::default(),
                        None,
                        response_rewriter,
                        overrides_enabled,
                    )
                };
                let router_build_duration = router_build_start.elapsed();
                debug!("Built OpenAPI router (took {:?})", router_build_duration);

                tracing::debug!("Merging OpenAPI router with main router");
                app = app.merge(openapi_router);
                tracing::debug!("Router built successfully");
            }
            Err(e) => {
                warn!("Failed to load OpenAPI spec from {}: {}. Starting without OpenAPI integration.", spec_path, e);
            }
        }
    }

    // Add basic health check endpoint
    app = app.route(
        "/health",
        axum::routing::get(|| async {
            use mockforge_core::server_utils::health::HealthStatus;
            {
                // HealthStatus should always serialize, but handle errors gracefully
                match serde_json::to_value(HealthStatus::healthy(0, "mockforge-http")) {
                    Ok(value) => Json(value),
                    Err(e) => {
                        // Log error but return a simple healthy response
                        tracing::error!("Failed to serialize health status: {}", e);
                        Json(serde_json::json!({
                            "status": "healthy",
                            "service": "mockforge-http",
                            "uptime_seconds": 0
                        }))
                    }
                }
            }
        }),
    )
    // Add SSE endpoints
    .merge(sse::sse_router())
    // Add file serving endpoints for generated mock files
    .merge(file_server::file_serving_router());

    // Clone state for routes_router since we'll use it for middleware too
    let state_for_routes = state.clone();

    // Create a router with state for the routes and coverage endpoints
    let routes_router = Router::new()
        .route("/__mockforge/routes", axum::routing::get(get_routes_handler))
        .route("/__mockforge/coverage", axum::routing::get(coverage::get_coverage_handler))
        .with_state(state_for_routes);

    // Merge the routes router with the main app
    app = app.merge(routes_router);

    // Add API docs page (Scalar-powered interactive explorer)
    app = app.route("/__mockforge/docs", axum::routing::get(get_docs_handler));

    // Add static coverage UI
    // Determine the path to the coverage.html file
    let coverage_html_path = std::env::var("MOCKFORGE_COVERAGE_UI_PATH")
        .unwrap_or_else(|_| "crates/mockforge-http/static/coverage.html".to_string());

    // Check if the file exists before serving it
    if Path::new(&coverage_html_path).exists() {
        app = app.nest_service(
            "/__mockforge/coverage.html",
            tower_http::services::ServeFile::new(&coverage_html_path),
        );
        debug!("Serving coverage UI from: {}", coverage_html_path);
    } else {
        debug!(
            "Coverage UI file not found at: {}. Skipping static file serving.",
            coverage_html_path
        );
    }

    // Add management API endpoints
    // Load spec for ManagementState so /__mockforge/api/spec can serve it
    let mgmt_spec = if let Some(ref sp) = spec_path_for_mgmt {
        match OpenApiSpec::from_file(sp).await {
            Ok(s) => Some(Arc::new(s)),
            Err(e) => {
                debug!("Failed to load OpenAPI spec for management API: {}", e);
                None
            }
        }
    } else {
        None
    };
    let mgmt_port = std::env::var("PORT")
        .or_else(|_| std::env::var("MOCKFORGE_HTTP_PORT"))
        .ok()
        .and_then(|p| p.parse().ok())
        .unwrap_or(3000);
    let management_state = ManagementState::new(mgmt_spec, spec_path_for_mgmt, mgmt_port);

    // Create WebSocket state and connect it to management state
    use std::sync::Arc;
    let ws_state = WsManagementState::new();
    let ws_broadcast = Arc::new(ws_state.tx.clone());
    let management_state = management_state.with_ws_broadcast(ws_broadcast);

    // Note: ProxyConfig not available in this build function path
    // Migration endpoints will work once ProxyConfig is passed to build_router_with_chains_and_multi_tenant

    #[cfg(feature = "smtp")]
    let management_state = {
        if let Some(smtp_reg) = smtp_registry {
            match smtp_reg.downcast::<mockforge_smtp::SmtpSpecRegistry>() {
                Ok(smtp_reg) => management_state.with_smtp_registry(smtp_reg),
                Err(e) => {
                    error!(
                        "Invalid SMTP registry type passed to HTTP management state: {:?}",
                        e.type_id()
                    );
                    management_state
                }
            }
        } else {
            management_state
        }
    };
    #[cfg(not(feature = "smtp"))]
    let management_state = management_state;
    #[cfg(not(feature = "smtp"))]
    let _ = smtp_registry;
    let management_state_for_fallback = management_state.clone();
    app = app.nest("/__mockforge/api", management_router(management_state));
    // Serve any request that the rest of the router doesn't handle as a dynamic
    // mock lookup. Lets the Node/Rust SDK register stubs via the management
    // API and have requests actually reach them. Falls through to 404 when
    // no mock matches.
    app = app.fallback_service(
        axum::routing::any(management::dynamic_mock_fallback)
            .with_state(management_state_for_fallback),
    );

    // Add verification API endpoint
    app = app.merge(verification_router());

    // Add OIDC well-known endpoints
    use crate::auth::oidc::oidc_router;
    app = app.merge(oidc_router());

    // Add access review API if enabled
    {
        use mockforge_core::security::get_global_access_review_service;
        if let Some(service) = get_global_access_review_service().await {
            use crate::handlers::access_review::{access_review_router, AccessReviewState};
            let review_state = AccessReviewState { service };
            app = app.nest("/api/v1/security/access-reviews", access_review_router(review_state));
            debug!("Access review API mounted at /api/v1/security/access-reviews");
        }
    }

    // Add privileged access API if enabled
    {
        use mockforge_core::security::get_global_privileged_access_manager;
        if let Some(manager) = get_global_privileged_access_manager().await {
            use crate::handlers::privileged_access::{
                privileged_access_router, PrivilegedAccessState,
            };
            let privileged_state = PrivilegedAccessState { manager };
            app = app.nest(
                "/api/v1/security/privileged-access",
                privileged_access_router(privileged_state),
            );
            debug!("Privileged access API mounted at /api/v1/security/privileged-access");
        }
    }

    // Add change management API if enabled
    {
        use mockforge_core::security::get_global_change_management_engine;
        if let Some(engine) = get_global_change_management_engine().await {
            use crate::handlers::change_management::{
                change_management_router, ChangeManagementState,
            };
            let change_state = ChangeManagementState { engine };
            app = app.nest("/api/v1/change-management", change_management_router(change_state));
            debug!("Change management API mounted at /api/v1/change-management");
        }
    }

    // Add risk assessment API if enabled
    {
        use mockforge_core::security::get_global_risk_assessment_engine;
        if let Some(engine) = get_global_risk_assessment_engine().await {
            use crate::handlers::risk_assessment::{risk_assessment_router, RiskAssessmentState};
            let risk_state = RiskAssessmentState { engine };
            app = app.nest("/api/v1/security", risk_assessment_router(risk_state));
            debug!("Risk assessment API mounted at /api/v1/security/risks");
        }
    }

    // Add token lifecycle API
    {
        use crate::auth::token_lifecycle::TokenLifecycleManager;
        use crate::handlers::token_lifecycle::{token_lifecycle_router, TokenLifecycleState};
        let lifecycle_manager = Arc::new(TokenLifecycleManager::default());
        let lifecycle_state = TokenLifecycleState {
            manager: lifecycle_manager,
        };
        app = app.nest("/api/v1/auth", token_lifecycle_router(lifecycle_state));
        debug!("Token lifecycle API mounted at /api/v1/auth");
    }

    // Add OAuth2 server endpoints
    {
        use crate::auth::oidc::load_oidc_state;
        use crate::auth::token_lifecycle::TokenLifecycleManager;
        use crate::handlers::oauth2_server::{oauth2_server_router, OAuth2ServerState};
        // Load OIDC state from configuration (environment variables or config file)
        let oidc_state = Arc::new(RwLock::new(load_oidc_state()));
        let lifecycle_manager = Arc::new(TokenLifecycleManager::default());
        let oauth2_state = OAuth2ServerState {
            oidc_state,
            lifecycle_manager,
            auth_codes: Arc::new(RwLock::new(HashMap::new())),
            refresh_tokens: Arc::new(RwLock::new(HashMap::new())),
        };
        app = app.merge(oauth2_server_router(oauth2_state));
        debug!("OAuth2 server endpoints mounted at /oauth2/authorize and /oauth2/token");
    }

    // Add consent screen endpoints
    {
        use crate::auth::oidc::load_oidc_state;
        use crate::auth::risk_engine::RiskEngine;
        use crate::auth::token_lifecycle::TokenLifecycleManager;
        use crate::handlers::consent::{consent_router, ConsentState};
        use crate::handlers::oauth2_server::OAuth2ServerState;
        // Load OIDC state from configuration (environment variables or config file)
        let oidc_state = Arc::new(RwLock::new(load_oidc_state()));
        let lifecycle_manager = Arc::new(TokenLifecycleManager::default());
        let oauth2_state = OAuth2ServerState {
            oidc_state: oidc_state.clone(),
            lifecycle_manager: lifecycle_manager.clone(),
            auth_codes: Arc::new(RwLock::new(HashMap::new())),
            refresh_tokens: Arc::new(RwLock::new(HashMap::new())),
        };
        let risk_engine = Arc::new(RiskEngine::default());
        let consent_state = ConsentState {
            oauth2_state,
            risk_engine,
        };
        app = app.merge(consent_router(consent_state));
        debug!("Consent screen endpoints mounted at /consent");
    }

    // Add risk simulation API
    {
        use crate::auth::risk_engine::RiskEngine;
        use crate::handlers::risk_simulation::{risk_simulation_router, RiskSimulationState};
        let risk_engine = Arc::new(RiskEngine::default());
        let risk_state = RiskSimulationState { risk_engine };
        app = app.nest("/api/v1/auth", risk_simulation_router(risk_state));
        debug!("Risk simulation API mounted at /api/v1/auth/risk");
    }

    // Add management WebSocket endpoint
    app = app.nest("/__mockforge/ws", ws_management_router(ws_state));

    // Add request logging middleware to capture all requests
    app = app.layer(axum::middleware::from_fn(request_logging::log_http_requests));

    // Add security middleware for security event tracking (after logging, before contract diff)
    app = app.layer(axum::middleware::from_fn(middleware::security_middleware));

    // Add contract diff middleware for automatic request capture
    // This captures requests for contract diff analysis (after logging)
    app = app.layer(axum::middleware::from_fn(contract_diff_middleware::capture_for_contract_diff));

    // Add rate limiting middleware (before logging to rate limit early)
    app = app.layer(from_fn_with_state(state.clone(), middleware::rate_limit_middleware));

    // Add production headers middleware if configured
    if state.production_headers.is_some() {
        app =
            app.layer(from_fn_with_state(state.clone(), middleware::production_headers_middleware));
    }

    // Add authentication middleware if OAuth is configured via deceptive deploy
    if let Some(auth_config) = deceptive_deploy_auth_config {
        use crate::auth::{auth_middleware, create_oauth2_client, AuthState};
        use std::collections::HashMap;
        use std::sync::Arc;
        use tokio::sync::RwLock;

        // Create OAuth2 client if configured
        let oauth2_client = if let Some(oauth2_config) = &auth_config.oauth2 {
            match create_oauth2_client(oauth2_config) {
                Ok(client) => Some(client),
                Err(e) => {
                    warn!("Failed to create OAuth2 client from deceptive deploy config: {}", e);
                    None
                }
            }
        } else {
            None
        };

        // Create auth state
        let auth_state = AuthState {
            config: auth_config,
            spec: None, // OpenAPI spec not available in this context
            oauth2_client,
            introspection_cache: Arc::new(RwLock::new(HashMap::new())),
        };

        // Apply auth middleware
        app = app.layer(from_fn_with_state(auth_state, auth_middleware));
        info!("Applied OAuth authentication middleware from deceptive deploy configuration");
    }

    // Add CORS middleware (use final_cors_config which may be overridden by deceptive deploy)
    app = apply_cors_middleware(app, final_cors_config);

    // Add workspace routing middleware if multi-tenant is enabled
    if let Some(mt_config) = multi_tenant_config {
        if mt_config.enabled {
            use mockforge_core::{MultiTenantWorkspaceRegistry, WorkspaceRouter};
            use std::sync::Arc;

            info!(
                "Multi-tenant mode enabled with {} routing strategy",
                match mt_config.routing_strategy {
                    mockforge_foundation::multi_tenant_types::RoutingStrategy::Path => "path-based",
                    mockforge_foundation::multi_tenant_types::RoutingStrategy::Port => "port-based",
                    mockforge_foundation::multi_tenant_types::RoutingStrategy::Both => "hybrid",
                }
            );

            // Create the multi-tenant workspace registry
            let mut registry = MultiTenantWorkspaceRegistry::new(mt_config.clone());

            // Register the default workspace before wrapping in Arc
            let default_workspace =
                mockforge_core::Workspace::new(mt_config.default_workspace.clone());
            if let Err(e) =
                registry.register_workspace(mt_config.default_workspace.clone(), default_workspace)
            {
                warn!("Failed to register default workspace: {}", e);
            } else {
                info!("Registered default workspace: '{}'", mt_config.default_workspace);
            }

            // Auto-discover and register workspaces if configured
            if mt_config.auto_discover {
                if let Some(config_dir) = &mt_config.config_directory {
                    let config_path = Path::new(config_dir);
                    if config_path.exists() && config_path.is_dir() {
                        match fs::read_dir(config_path).await {
                            Ok(mut entries) => {
                                while let Ok(Some(entry)) = entries.next_entry().await {
                                    let path = entry.path();
                                    if path.extension() == Some(OsStr::new("yaml")) {
                                        match fs::read_to_string(&path).await {
                                            Ok(content) => {
                                                match serde_yaml::from_str::<
                                                    mockforge_core::Workspace,
                                                >(
                                                    &content
                                                ) {
                                                    Ok(workspace) => {
                                                        if let Err(e) = registry.register_workspace(
                                                            workspace.id.clone(),
                                                            workspace,
                                                        ) {
                                                            warn!("Failed to register auto-discovered workspace from {:?}: {}", path, e);
                                                        } else {
                                                            info!("Auto-registered workspace from {:?}", path);
                                                        }
                                                    }
                                                    Err(e) => {
                                                        warn!("Failed to parse workspace from {:?}: {}", path, e);
                                                    }
                                                }
                                            }
                                            Err(e) => {
                                                warn!(
                                                    "Failed to read workspace file {:?}: {}",
                                                    path, e
                                                );
                                            }
                                        }
                                    }
                                }
                            }
                            Err(e) => {
                                warn!("Failed to read config directory {:?}: {}", config_path, e);
                            }
                        }
                    } else {
                        warn!(
                            "Config directory {:?} does not exist or is not a directory",
                            config_path
                        );
                    }
                }
            }

            // Wrap registry in Arc for shared access
            let registry = Arc::new(registry);

            // Create workspace router and wrap the app with workspace middleware
            let _workspace_router = WorkspaceRouter::new(registry);

            // Note: The actual middleware integration would need to be implemented
            // in the WorkspaceRouter to work with Axum's middleware system
            info!("Workspace routing middleware initialized for HTTP server");
        }
    }

    let total_startup_duration = startup_start.elapsed();
    info!("HTTP router startup completed (total time: {:?})", total_startup_duration);

    app
}

/// Build the base HTTP router with authentication and latency support
pub async fn build_router_with_auth_and_latency(
    spec_path: Option<String>,
    _options: Option<()>,
    auth_config: Option<mockforge_core::config::AuthConfig>,
    latency_injector: Option<LatencyInjector>,
) -> Router {
    // Build auth router first, then layer latency on top
    let mut app = build_router_with_auth(spec_path.clone(), None, auth_config).await;

    // Apply latency injection middleware if configured
    if let Some(injector) = latency_injector {
        let injector = Arc::new(injector);
        app = app.layer(axum::middleware::from_fn(move |req, next: axum::middleware::Next| {
            let injector = injector.clone();
            async move {
                let _ = injector.inject_latency(&[]).await;
                next.run(req).await
            }
        }));
    }

    app
}

/// Build the base HTTP router with latency injection support
pub async fn build_router_with_latency(
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    latency_injector: Option<LatencyInjector>,
) -> Router {
    if let Some(spec) = &spec_path {
        match OpenApiSpec::from_file(spec).await {
            Ok(openapi) => {
                let registry = if let Some(opts) = options {
                    OpenApiRouteRegistry::new_with_options(openapi, opts)
                } else {
                    OpenApiRouteRegistry::new_with_env(openapi)
                };

                if let Some(injector) = latency_injector {
                    return registry.build_router_with_latency(injector);
                } else {
                    return registry.build_router();
                }
            }
            Err(e) => {
                warn!("Failed to load OpenAPI spec from {}: {}. Starting without OpenAPI integration.", spec, e);
            }
        }
    }

    build_router(None, None, None).await
}

/// Build the base HTTP router with authentication support
pub async fn build_router_with_auth(
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    auth_config: Option<mockforge_core::config::AuthConfig>,
) -> Router {
    use crate::auth::{auth_middleware, create_oauth2_client, AuthState};
    use std::sync::Arc;

    // If richer faker is available, register provider once (idempotent)
    #[cfg(feature = "data-faker")]
    {
        register_core_faker_provider();
    }

    // Set up authentication state
    let spec = if let Some(spec_path) = &spec_path {
        match OpenApiSpec::from_file(&spec_path).await {
            Ok(spec) => Some(Arc::new(spec)),
            Err(e) => {
                warn!("Failed to load OpenAPI spec for auth: {}", e);
                None
            }
        }
    } else {
        None
    };

    // Create OAuth2 client if configured
    let oauth2_client = if let Some(auth_config) = &auth_config {
        if let Some(oauth2_config) = &auth_config.oauth2 {
            match create_oauth2_client(oauth2_config) {
                Ok(client) => Some(client),
                Err(e) => {
                    warn!("Failed to create OAuth2 client: {}", e);
                    None
                }
            }
        } else {
            None
        }
    } else {
        None
    };

    let auth_state = AuthState {
        config: auth_config.unwrap_or_default(),
        spec,
        oauth2_client,
        introspection_cache: Arc::new(RwLock::new(HashMap::new())),
    };

    // Set up the basic router with auth state
    let mut app = Router::new().with_state(auth_state.clone());

    // If an OpenAPI spec is provided, integrate it
    if let Some(spec_path) = spec_path {
        match OpenApiSpec::from_file(&spec_path).await {
            Ok(openapi) => {
                info!("Loaded OpenAPI spec from {}", spec_path);
                let registry = if let Some(opts) = options {
                    OpenApiRouteRegistry::new_with_options(openapi, opts)
                } else {
                    OpenApiRouteRegistry::new_with_env(openapi)
                };

                app = registry.build_router();
            }
            Err(e) => {
                warn!("Failed to load OpenAPI spec from {}: {}. Starting without OpenAPI integration.", spec_path, e);
            }
        }
    }

    // Add basic health check endpoint
    app = app.route(
        "/health",
        axum::routing::get(|| async {
            use mockforge_core::server_utils::health::HealthStatus;
            {
                // HealthStatus should always serialize, but handle errors gracefully
                match serde_json::to_value(HealthStatus::healthy(0, "mockforge-http")) {
                    Ok(value) => Json(value),
                    Err(e) => {
                        // Log error but return a simple healthy response
                        tracing::error!("Failed to serialize health status: {}", e);
                        Json(serde_json::json!({
                            "status": "healthy",
                            "service": "mockforge-http",
                            "uptime_seconds": 0
                        }))
                    }
                }
            }
        }),
    )
    // Add SSE endpoints
    .merge(sse::sse_router())
    // Add file serving endpoints for generated mock files
    .merge(file_server::file_serving_router())
    // Add authentication middleware (before logging)
    .layer(from_fn_with_state(auth_state.clone(), auth_middleware))
    // Add request logging middleware
    .layer(axum::middleware::from_fn(request_logging::log_http_requests));

    app
}

/// Serve a provided router on the given port.
pub async fn serve_router(
    port: u16,
    app: Router,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    serve_router_with_tls(port, app, None).await
}

/// Serve a provided router on the given port with optional TLS support.
pub async fn serve_router_with_tls(
    port: u16,
    app: Router,
    tls_config: Option<mockforge_core::config::HttpTlsConfig>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    serve_router_with_tls_notify(port, app, tls_config, None).await
}

/// Serve a provided router on the given port with optional TLS support, notifying
/// the caller via `bound_port_tx` with the actual OS-assigned port once the
/// listener has bound. This matters when the requested `port` is `0` (ephemeral),
/// because callers such as the `@mockforge-dev/sdk` need to learn the real port
/// to connect to it. On the TLS path, `bound_port_tx` is currently ignored and
/// the requested `port` is reported verbatim — callers that need dynamic TLS
/// ports should bind on a known port.
pub async fn serve_router_with_tls_notify(
    port: u16,
    app: Router,
    tls_config: Option<mockforge_core::config::HttpTlsConfig>,
    bound_port_tx: Option<tokio::sync::oneshot::Sender<u16>>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    serve_router_with_tls_notify_chaos(port, app, tls_config, bound_port_tx, None).await
}

/// Serve a router with optional TLS *and* an optional shared chaos config.
///
/// When `chaos_config` is `Some`, the TCP listener is wrapped with
/// [`mockforge_chaos::ChaosTcpListener`], which can inject TCP-level
/// connection faults (RST or unclean FIN) before axum/hyper see the socket.
/// This is the only way to surface real transport-level failures rather than
/// HTTP 503 responses on healthy connections. TLS path does not yet support
/// chaos listener wrapping (axum-server uses its own accept loop).
pub async fn serve_router_with_tls_notify_chaos(
    port: u16,
    app: Router,
    tls_config: Option<mockforge_core::config::HttpTlsConfig>,
    bound_port_tx: Option<tokio::sync::oneshot::Sender<u16>>,
    chaos_config: Option<std::sync::Arc<tokio::sync::RwLock<mockforge_chaos::ChaosConfig>>>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    use std::net::SocketAddr;

    let addr = mockforge_core::wildcard_socket_addr(port);

    if let Some(ref tls) = tls_config {
        if tls.enabled {
            info!("HTTPS listening on {}", addr);
            if let Some(tx) = bound_port_tx {
                let _ = tx.send(port);
            }
            return serve_with_tls(addr, app, tls).await;
        }
    }

    let listener = tokio::net::TcpListener::bind(addr).await.map_err(|e| {
        format!(
            "Failed to bind HTTP server to port {}: {}\n\
             Hint: The port may already be in use. Try using a different port with --http-port or check if another process is using this port with: lsof -i :{} or netstat -tulpn | grep {}",
            port, e, port, port
        )
    })?;

    let actual_port = listener.local_addr().map(|a| a.port()).unwrap_or(port);
    info!("HTTP listening on {}", listener.local_addr().unwrap_or(addr));
    if let Some(tx) = bound_port_tx {
        let _ = tx.send(actual_port);
    }

    // Wrap the Router with OData URI rewrite.
    // Router::layer() only applies to matched routes, so we must wrap at the service level
    // to rewrite URIs BEFORE route matching occurs.
    let odata_app = tower::ServiceBuilder::new()
        .layer(mockforge_core::odata_rewrite::ODataRewriteLayer)
        .service(app);
    if let Some(cfg) = chaos_config {
        info!("HTTP listener wrapped with chaos TCP listener (RST/FIN injection enabled)");
        let chaos_listener = mockforge_chaos::ChaosTcpListener::new(listener, cfg);
        // Layer that copies ConnectInfo<ChaosClientAddr> → ConnectInfo<SocketAddr>
        // so existing handlers using `ConnectInfo<SocketAddr>` keep working.
        let app_with_addr_compat = tower::ServiceBuilder::new()
            .layer(axum::middleware::from_fn(copy_chaos_addr_to_socketaddr))
            .service(odata_app);
        let make_svc = axum::ServiceExt::<Request<Body>>::into_make_service_with_connect_info::<
            mockforge_chaos::ChaosClientAddr,
        >(app_with_addr_compat);
        // Bump the accept counter on each connection that gets through chaos.
        let counted = counting_listener::CountingMakeService::new(make_svc);
        axum::serve(chaos_listener, counted).await?;
    } else {
        let make_svc = axum::ServiceExt::<Request<Body>>::into_make_service_with_connect_info::<
            SocketAddr,
        >(odata_app);
        // Bump the accept counter once per accepted connection so the
        // dashboard sampler can derive CPS.
        let counted = counting_listener::CountingMakeService::new(make_svc);
        axum::serve(listener, counted).await?;
    }
    Ok(())
}

/// Mirror `ConnectInfo<ChaosClientAddr>` (set by the chaos listener) onto
/// `ConnectInfo<SocketAddr>` so handlers extracting `ConnectInfo<SocketAddr>`
/// keep working when chaos TCP wrapping is enabled.
async fn copy_chaos_addr_to_socketaddr(
    mut req: axum::http::Request<axum::body::Body>,
    next: axum::middleware::Next,
) -> axum::response::Response {
    use axum::extract::ConnectInfo;
    if let Some(ConnectInfo(chaos_addr)) =
        req.extensions().get::<ConnectInfo<mockforge_chaos::ChaosClientAddr>>().copied()
    {
        let sock: std::net::SocketAddr = *chaos_addr;
        req.extensions_mut().insert(ConnectInfo(sock));
    }
    next.run(req).await
}

/// Serve router with TLS/HTTPS support using axum-server
///
/// This function implements native TLS serving using axum-server and tokio-rustls.
/// It supports standard TLS and mutual TLS (mTLS) based on the configuration.
async fn serve_with_tls(
    addr: std::net::SocketAddr,
    app: Router,
    tls_config: &mockforge_core::config::HttpTlsConfig,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    use axum_server::tls_rustls::RustlsConfig;
    use std::net::SocketAddr;

    // Initialize the rustls crypto provider (must be called before TLS operations)
    tls::init_crypto_provider();

    info!("Loading TLS configuration for HTTPS server");

    // Load TLS server configuration (supports mTLS)
    let server_config = tls::load_tls_server_config(tls_config)?;

    // Create RustlsConfig from the ServerConfig
    // Note: axum-server's RustlsConfig can be created from a ServerConfig
    let rustls_config = RustlsConfig::from_config(server_config);

    info!("Starting HTTPS server on {}", addr);

    // Wrap the Router with OData URI rewrite (same as the non-TLS path).
    // Router::layer() only applies to matched routes, so we must wrap at the service level
    // to rewrite URIs BEFORE route matching occurs.
    let odata_app = tower::ServiceBuilder::new()
        .layer(mockforge_core::odata_rewrite::ODataRewriteLayer)
        .service(app);
    let make_svc = axum::ServiceExt::<Request<Body>>::into_make_service_with_connect_info::<
        SocketAddr,
    >(odata_app);
    // Bump the accept counter once per successful TLS handshake / connection
    // so the dashboard sampler can derive CPS for HTTPS-only setups.
    let counted = counting_listener::CountingMakeService::new(make_svc);

    // Serve with TLS using axum-server
    axum_server::bind_rustls(addr, rustls_config)
        .serve(counted)
        .await
        .map_err(|e| format!("HTTPS server error: {}", e).into())
}

/// Backwards-compatible start that builds + serves the base router.
pub async fn start(
    port: u16,
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    start_with_latency(port, spec_path, options, None).await
}

/// Start HTTP server with authentication and latency support
pub async fn start_with_auth_and_latency(
    port: u16,
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    auth_config: Option<mockforge_core::config::AuthConfig>,
    latency_profile: Option<LatencyProfile>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    start_with_auth_and_injectors(port, spec_path, options, auth_config, latency_profile, None)
        .await
}

/// Start HTTP server with authentication and injectors support
pub async fn start_with_auth_and_injectors(
    port: u16,
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    auth_config: Option<mockforge_core::config::AuthConfig>,
    _latency_profile: Option<LatencyProfile>,
    _failure_injector: Option<FailureInjector>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // For now, ignore latency and failure injectors and just use auth
    let app = build_router_with_auth(spec_path, options, auth_config).await;
    serve_router(port, app).await
}

/// Start HTTP server with latency injection support
pub async fn start_with_latency(
    port: u16,
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    latency_profile: Option<LatencyProfile>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let latency_injector =
        latency_profile.map(|profile| LatencyInjector::new(profile, Default::default()));

    let app = build_router_with_latency(spec_path, options, latency_injector).await;
    serve_router(port, app).await
}

/// Build the base HTTP router with chaining support
pub async fn build_router_with_chains(
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    circling_config: Option<mockforge_core::request_chaining::ChainConfig>,
) -> Router {
    build_router_with_chains_and_multi_tenant(
        spec_path,
        options,
        circling_config,
        None,
        None,
        None,
        None,
        None,
        None,
        None,
        false,
        None, // health_manager
        None, // mockai
        None, // deceptive_deploy_config
        None, // proxy_config
    )
    .await
}

// Template expansion is now handled by mockforge_core::template_expansion
// which is explicitly isolated from the templating module to avoid Send issues

/// Helper function to apply route chaos injection (fault injection and latency)
/// This is extracted to avoid capturing RouteChaosInjector in the closure, which causes Send issues
/// Uses mockforge-route-chaos crate which is isolated from mockforge-core to avoid Send issues
/// Uses the RouteChaosInjectorTrait from mockforge-core to avoid circular dependency
async fn apply_route_chaos(
    injector: Option<&dyn mockforge_core::priority_handler::RouteChaosInjectorTrait>,
    method: &http::Method,
    uri: &http::Uri,
) -> Option<axum::response::Response> {
    use axum::http::StatusCode;
    use axum::response::IntoResponse;

    if let Some(injector) = injector {
        // Check for fault injection first
        if let Some(fault_response) = injector.get_fault_response(method, uri) {
            // Return fault response
            let mut response = Json(serde_json::json!({
                "error": fault_response.error_message,
                "fault_type": fault_response.fault_type,
            }))
            .into_response();
            *response.status_mut() = StatusCode::from_u16(fault_response.status_code)
                .unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
            return Some(response);
        }

        // Inject latency if configured (this is async and may delay the request)
        if let Err(e) = injector.inject_latency(method, uri).await {
            tracing::warn!("Failed to inject latency: {}", e);
        }
    }

    None // No fault response, processing should continue
}

/// Build the base HTTP router with chaining and multi-tenant support
#[allow(clippy::too_many_arguments)]
#[allow(deprecated)] // uses core engines (DriftBudgetEngine, ThreatAnalyzer, Forecaster, ProtocolContractRegistry, MockAI, MultiTenantWorkspaceRegistry, etc.) that stay in core
pub async fn build_router_with_chains_and_multi_tenant(
    spec_path: Option<String>,
    options: Option<ValidationOptions>,
    _circling_config: Option<mockforge_core::request_chaining::ChainConfig>,
    multi_tenant_config: Option<mockforge_foundation::multi_tenant_types::MultiTenantConfig>,
    route_configs: Option<Vec<mockforge_core::config::RouteConfig>>,
    cors_config: Option<mockforge_core::config::HttpCorsConfig>,
    _ai_generator: Option<Arc<dyn mockforge_openapi::response::AiGenerator + Send + Sync>>,
    smtp_registry: Option<Arc<dyn std::any::Any + Send + Sync>>,
    mqtt_broker: Option<Arc<dyn std::any::Any + Send + Sync>>,
    traffic_shaper: Option<mockforge_core::traffic_shaping::TrafficShaper>,
    traffic_shaping_enabled: bool,
    health_manager: Option<Arc<HealthManager>>,
    mockai: Option<Arc<RwLock<mockforge_core::intelligent_behavior::MockAI>>>,
    deceptive_deploy_config: Option<mockforge_core::config::DeceptiveDeployConfig>,
    proxy_config: Option<mockforge_proxy::config::ProxyConfig>,
) -> Router {
    use crate::latency_profiles::LatencyProfiles;
    use crate::op_middleware::Shared;
    use mockforge_core::Overrides;

    // Extract template expansion setting before options is moved (used in OpenAPI routes and custom routes)
    let template_expand =
        options.as_ref().map(|o| o.response_template_expand).unwrap_or_else(|| {
            std::env::var("MOCKFORGE_RESPONSE_TEMPLATE_EXPAND")
                .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
                .unwrap_or(false)
        });

    let _shared = Shared {
        profiles: LatencyProfiles::default(),
        overrides: Overrides::default(),
        failure_injector: None,
        traffic_shaper,
        overrides_enabled: false,
        traffic_shaping_enabled,
    };

    // Start with basic router
    let mut app = Router::new();
    let mut include_default_health = true;
    let mut captured_routes: Vec<RouteInfo> = Vec::new();

    // If an OpenAPI spec is provided, integrate it
    if let Some(ref spec) = spec_path {
        match OpenApiSpec::from_file(&spec).await {
            Ok(openapi) => {
                info!("Loaded OpenAPI spec from {}", spec);

                // Try to load persona from config if available
                let persona = load_persona_from_config().await;

                let mut registry = if let Some(opts) = options {
                    tracing::debug!("Using custom validation options");
                    if let Some(ref persona) = persona {
                        tracing::info!("Using persona '{}' for route generation", persona.name);
                    }
                    OpenApiRouteRegistry::new_with_options_and_persona(openapi, opts, persona)
                } else {
                    tracing::debug!("Using environment-based options");
                    if let Some(ref persona) = persona {
                        tracing::info!("Using persona '{}' for route generation", persona.name);
                    }
                    OpenApiRouteRegistry::new_with_env_and_persona(openapi, persona)
                };

                // Load custom fixtures if enabled
                let fixtures_dir = std::env::var("MOCKFORGE_FIXTURES_DIR")
                    .unwrap_or_else(|_| "/app/fixtures".to_string());
                let custom_fixtures_enabled = std::env::var("MOCKFORGE_CUSTOM_FIXTURES_ENABLED")
                    .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
                    .unwrap_or(true); // Enabled by default

                if custom_fixtures_enabled {
                    use mockforge_openapi::CustomFixtureLoader;
                    use std::path::PathBuf;
                    use std::sync::Arc;

                    let fixtures_path = PathBuf::from(&fixtures_dir);
                    let mut custom_loader = CustomFixtureLoader::new(fixtures_path, true);

                    if let Err(e) = custom_loader.load_fixtures().await {
                        tracing::warn!("Failed to load custom fixtures: {}", e);
                    } else {
                        tracing::info!("Custom fixtures loaded from {}", fixtures_dir);
                        registry = registry.with_custom_fixture_loader(Arc::new(custom_loader));
                    }
                }

                if registry
                    .routes()
                    .iter()
                    .any(|route| route.method == "GET" && route.path == "/health")
                {
                    include_default_health = false;
                }
                // Capture route info for the /__mockforge/routes endpoint
                captured_routes = registry
                    .routes()
                    .iter()
                    .map(|r| RouteInfo {
                        method: r.method.clone(),
                        path: r.path.clone(),
                        operation_id: r.operation.operation_id.clone(),
                        summary: r.operation.summary.clone(),
                        description: r.operation.description.clone(),
                        parameters: r.parameters.clone(),
                    })
                    .collect();

                // Store routes in the global route store so the admin server
                // can serve them without proxying back to the HTTP server.
                {
                    let global_routes: Vec<mockforge_core::request_logger::GlobalRouteInfo> =
                        captured_routes
                            .iter()
                            .map(|r| mockforge_core::request_logger::GlobalRouteInfo {
                                method: r.method.clone(),
                                path: r.path.clone(),
                                operation_id: r.operation_id.clone(),
                                summary: r.summary.clone(),
                                description: r.description.clone(),
                                parameters: r.parameters.clone(),
                            })
                            .collect();
                    mockforge_core::request_logger::set_global_routes(global_routes);
                    tracing::info!("Stored {} routes in global route store", captured_routes.len());
                }

                // Use MockAI if available, otherwise use standard router
                let spec_router = if let Some(ref mockai_instance) = mockai {
                    tracing::debug!("Building router with MockAI support");
                    registry.build_router_with_mockai(Some(mockai_instance.clone()))
                } else {
                    registry.build_router()
                };
                app = app.merge(spec_router);
            }
            Err(e) => {
                warn!("Failed to load OpenAPI spec from {:?}: {}. Starting without OpenAPI integration.", spec_path, e);
            }
        }
    }

    // Register custom routes from config with advanced routing features
    // Create RouteChaosInjector for advanced fault injection and latency
    // Store as trait object to avoid circular dependency (RouteChaosInjectorTrait is in mockforge-core)
    let route_chaos_injector: Option<
        std::sync::Arc<dyn mockforge_core::priority_handler::RouteChaosInjectorTrait>,
    > = if let Some(ref route_configs) = route_configs {
        if !route_configs.is_empty() {
            // Convert to the type expected by RouteChaosInjector
            // Note: Both use the same mockforge-core, but we need to ensure type compatibility
            let route_configs_converted: Vec<mockforge_core::config::RouteConfig> =
                route_configs.to_vec();
            match mockforge_route_chaos::RouteChaosInjector::new(route_configs_converted) {
                Ok(injector) => {
                    info!(
                        "Initialized advanced routing features for {} route(s)",
                        route_configs.len()
                    );
                    // RouteChaosInjector implements RouteChaosInjectorTrait, so we can cast it
                    // The trait is implemented in mockforge-route-chaos/src/lib.rs
                    Some(std::sync::Arc::new(injector)
                        as std::sync::Arc<
                            dyn mockforge_core::priority_handler::RouteChaosInjectorTrait,
                        >)
                }
                Err(e) => {
                    warn!(
                        "Failed to initialize advanced routing features: {}. Using basic routing.",
                        e
                    );
                    None
                }
            }
        } else {
            None
        }
    } else {
        None
    };

    if let Some(route_configs) = route_configs {
        use axum::http::StatusCode;
        use axum::response::IntoResponse;

        if !route_configs.is_empty() {
            info!("Registering {} custom route(s) from config", route_configs.len());
        }

        let injector = route_chaos_injector.clone();
        for route_config in route_configs {
            let status = route_config.response.status;
            let body = route_config.response.body.clone();
            let headers = route_config.response.headers.clone();
            let path = route_config.path.clone();
            let method = route_config.method.clone();

            // Create handler that returns the configured response with template expansion
            // Supports both basic templates ({{uuid}}, {{now}}) and request-aware templates
            // ({{request.query.name}}, {{request.path.id}}, {{request.headers.name}})
            // Register route using `any()` since we need full Request access for template expansion
            let expected_method = method.to_uppercase();
            // Clone Arc for the closure - Arc is Send-safe
            // Note: RouteChaosInjector is marked as Send+Sync via unsafe impl, but the compiler
            // is conservative because rng() is available in the rand crate, even though we use thread_rng()
            let injector_clone = injector.clone();
            app = app.route(
                &path,
                #[allow(clippy::non_send_fields_in_send_ty)]
                axum::routing::any(move |req: Request<Body>| {
                    let body = body.clone();
                    let headers = headers.clone();
                    let expand = template_expand;
                    let expected = expected_method.clone();
                    let status_code = status;
                    // Clone Arc again for the async block
                    let injector_for_chaos = injector_clone.clone();

                    async move {
                        // Check if request method matches expected method
                        if req.method().as_str() != expected.as_str() {
                            // Return 405 Method Not Allowed for wrong method
                            return axum::response::Response::builder()
                                .status(StatusCode::METHOD_NOT_ALLOWED)
                                .header("Allow", &expected)
                                .body(Body::empty())
                                .unwrap()
                                .into_response();
                        }

                        // Apply advanced routing features (fault injection and latency) if available
                        // Use helper function to avoid capturing RouteChaosInjector in closure
                        // Pass the Arc as a reference to the helper function
                        if let Some(fault_response) = apply_route_chaos(
                            injector_for_chaos.as_deref(),
                            req.method(),
                            req.uri(),
                        )
                        .await
                        {
                            return fault_response;
                        }

                        // Create JSON response from body, or empty object if None
                        let mut body_value = body.unwrap_or(serde_json::json!({}));

                        // Apply template expansion if enabled
                        // Use mockforge-template-expansion crate which is completely isolated
                        // from mockforge-core to avoid Send issues (no rng() in dependency chain)
                        if expand {
                            use mockforge_template_expansion::RequestContext;
                            use serde_json::Value;
                            use std::collections::HashMap;

                            // Extract request data for template expansion
                            let method = req.method().to_string();
                            let path = req.uri().path().to_string();

                            // Extract query parameters
                            let query_params: HashMap<String, Value> = req
                                .uri()
                                .query()
                                .map(|q| {
                                    url::form_urlencoded::parse(q.as_bytes())
                                        .into_owned()
                                        .map(|(k, v)| (k, Value::String(v)))
                                        .collect()
                                })
                                .unwrap_or_default();

                            // Extract headers
                            let headers: HashMap<String, Value> = req
                                .headers()
                                .iter()
                                .map(|(k, v)| {
                                    (
                                        k.to_string(),
                                        Value::String(v.to_str().unwrap_or_default().to_string()),
                                    )
                                })
                                .collect();

                            // Create RequestContext for expand_prompt_template
                            // Using RequestContext from mockforge-template-expansion (not mockforge-core)
                            // to avoid bringing rng() into scope
                            let context = RequestContext {
                                method,
                                path,
                                query_params,
                                headers,
                                body: None, // Body extraction would require reading the request stream
                                path_params: HashMap::new(),
                                multipart_fields: HashMap::new(),
                                multipart_files: HashMap::new(),
                            };

                            // Perform template expansion in spawn_blocking to ensure Send safety
                            // The template expansion crate is completely isolated from mockforge-core
                            // and doesn't have rng() in its dependency chain
                            let body_value_clone = body_value.clone();
                            let context_clone = context.clone();
                            body_value = match tokio::task::spawn_blocking(move || {
                                mockforge_template_expansion::expand_templates_in_json(
                                    body_value_clone,
                                    &context_clone,
                                )
                            })
                            .await
                            {
                                Ok(result) => result,
                                Err(_) => body_value, // Fallback to original on error
                            };
                        }

                        let mut response = Json(body_value).into_response();

                        // Set status code
                        *response.status_mut() =
                            StatusCode::from_u16(status_code).unwrap_or(StatusCode::OK);

                        // Add custom headers
                        for (key, value) in headers {
                            if let Ok(header_name) = http::HeaderName::from_bytes(key.as_bytes()) {
                                if let Ok(header_value) = http::HeaderValue::from_str(&value) {
                                    response.headers_mut().insert(header_name, header_value);
                                }
                            }
                        }

                        response
                    }
                }),
            );

            debug!("Registered route: {} {}", method, path);
        }
    }

    // Add health check endpoints
    if let Some(health) = health_manager {
        // Use comprehensive health check router with all probe endpoints
        app = app.merge(health::health_router(health));
        info!(
            "Health check endpoints enabled: /health, /health/live, /health/ready, /health/startup"
        );
    } else if include_default_health {
        // Fallback to basic health endpoint for backwards compatibility
        app = app.route(
            "/health",
            axum::routing::get(|| async {
                use mockforge_core::server_utils::health::HealthStatus;
                {
                    // HealthStatus should always serialize, but handle errors gracefully
                    match serde_json::to_value(HealthStatus::healthy(0, "mockforge-http")) {
                        Ok(value) => Json(value),
                        Err(e) => {
                            // Log error but return a simple healthy response
                            tracing::error!("Failed to serialize health status: {}", e);
                            Json(serde_json::json!({
                                "status": "healthy",
                                "service": "mockforge-http",
                                "uptime_seconds": 0
                            }))
                        }
                    }
                }
            }),
        );
    }

    app = app.merge(sse::sse_router());
    // Add file serving endpoints for generated mock files
    app = app.merge(file_server::file_serving_router());

    // Add management API endpoints
    // Load spec for ManagementState so /__mockforge/api/spec can serve it
    let mgmt_spec = if let Some(ref sp) = spec_path {
        match OpenApiSpec::from_file(sp).await {
            Ok(s) => Some(Arc::new(s)),
            Err(e) => {
                debug!("Failed to load OpenAPI spec for management API: {}", e);
                None
            }
        }
    } else {
        None
    };
    let spec_path_clone = spec_path.clone();
    let mgmt_port = std::env::var("PORT")
        .or_else(|_| std::env::var("MOCKFORGE_HTTP_PORT"))
        .ok()
        .and_then(|p| p.parse().ok())
        .unwrap_or(3000);
    let management_state = ManagementState::new(mgmt_spec, spec_path_clone, mgmt_port);

    // Create WebSocket state and connect it to management state
    use std::sync::Arc;
    let ws_state = WsManagementState::new();
    let ws_broadcast = Arc::new(ws_state.tx.clone());
    let management_state = management_state.with_ws_broadcast(ws_broadcast);

    // Add proxy config to management state if available
    let management_state = if let Some(proxy_cfg) = proxy_config {
        use tokio::sync::RwLock;
        let proxy_config_arc = Arc::new(RwLock::new(proxy_cfg));
        management_state.with_proxy_config(proxy_config_arc)
    } else {
        management_state
    };

    #[cfg(feature = "smtp")]
    let management_state = {
        if let Some(smtp_reg) = smtp_registry {
            match smtp_reg.downcast::<mockforge_smtp::SmtpSpecRegistry>() {
                Ok(smtp_reg) => management_state.with_smtp_registry(smtp_reg),
                Err(e) => {
                    error!(
                        "Invalid SMTP registry type passed to HTTP management state: {:?}",
                        e.type_id()
                    );
                    management_state
                }
            }
        } else {
            management_state
        }
    };
    #[cfg(not(feature = "smtp"))]
    let management_state = {
        let _ = smtp_registry;
        management_state
    };
    #[cfg(feature = "mqtt")]
    let management_state = {
        if let Some(broker) = mqtt_broker {
            match broker.downcast::<mockforge_mqtt::MqttBroker>() {
                Ok(broker) => management_state.with_mqtt_broker(broker),
                Err(e) => {
                    error!(
                        "Invalid MQTT broker passed to HTTP management state: {:?}",
                        e.type_id()
                    );
                    management_state
                }
            }
        } else {
            management_state
        }
    };
    #[cfg(not(feature = "mqtt"))]
    let management_state = {
        let _ = mqtt_broker;
        management_state
    };
    let management_state_for_fallback = management_state.clone();
    app = app.nest("/__mockforge/api", management_router(management_state));
    // Dynamic-mock fallback; see identical block earlier in this file.
    app = app.fallback_service(
        axum::routing::any(management::dynamic_mock_fallback)
            .with_state(management_state_for_fallback),
    );

    // Add verification API endpoint
    app = app.merge(verification_router());

    // Mount the request-chains management API at the prefix the UI's
    // ChainsPage expects (`/__mockforge/chains/*`). Without this nest the
    // page 404s on every call. The registry/engine are constructed from
    // the chain_config param when supplied, otherwise from defaults.
    {
        use crate::chain_handlers::{chains_router, create_chain_state};
        let chain_config = _circling_config.clone().unwrap_or_default();
        let chain_registry = Arc::new(mockforge_core::request_chaining::RequestChainRegistry::new(
            chain_config.clone(),
        ));
        let chain_engine = Arc::new(mockforge_core::chain_execution::ChainExecutionEngine::new(
            chain_registry.clone(),
            chain_config,
        ));
        app = app.nest(
            "/__mockforge/chains",
            chains_router(create_chain_state(chain_registry, chain_engine)),
        );
    }

    // Contract-diff retrieval API. The `capture_for_contract_diff`
    // middleware (layered earlier) populates the global capture manager
    // on every request; this surface lets operators read the captures
    // and run the analyser against the current OpenAPI spec.
    {
        use crate::contract_diff_api::{contract_diff_api_router, ContractDiffApiState};
        let cd_state = Arc::new(ContractDiffApiState::new(spec_path.clone()));
        app = app.nest("/__mockforge/api/contract-diff", contract_diff_api_router(cd_state));
    }

    // Fixtures management API. Lives on the admin server too (port 9080),
    // but hosted-mock Fly machines only expose port 3000 publicly — so
    // we mount the same surface on the main HTTP app. Newly-uploaded
    // fixtures land in `MOCKFORGE_FIXTURES_DIR` and are picked up by
    // the startup-time loader on the next deploy/restart; live reload
    // is a separate concern.
    {
        use crate::fixtures_api::{fixtures_api_router, FixturesApiState};
        let fx_state = FixturesApiState::from_env();
        app = app.nest("/__mockforge/fixtures", fixtures_api_router(fx_state));
    }

    // Standalone MockAI API. Until now MockAI was only invoked from the
    // OpenAPI route generator — so a hosted mock without a spec, or a
    // user wanting to prototype an "AI persona" mock without registering
    // routes, had no way to reach the engine. The endpoint surfaces 503
    // when MockAI isn't configured (no API key) so callers get a clear
    // signal rather than a silent failure.
    {
        use crate::mockai_api::{mockai_api_router, MockAiApiState};
        let api_state = MockAiApiState::new(mockai.clone());
        app = app.nest("/__mockforge/api/mockai", mockai_api_router(api_state));
    }

    // Time-travel runtime API. The admin server mounts these routes on
    // its own port (9080), but hosted-mock Fly machines only expose
    // port 3000 publicly — so until now operators couldn't set / advance
    // virtual time on a deployed mock. The handlers consult a process-
    // wide TimeTravelManager that serve.rs initialises alongside the
    // existing admin-server registration; both paths see the same Arc.
    app = app.nest("/__mockforge/time-travel", time_travel_api::time_travel_router());

    // Runtime route-chaos rules API + middleware. This sits in front of
    // the static per-route handlers so operators can add/remove fault and
    // latency rules without redeploying. Static rules from the YAML
    // config still apply to their routes; runtime rules are additive.
    {
        use crate::route_chaos_runtime::{
            route_chaos_api_router, runtime_route_chaos_middleware, RuntimeRouteChaosState,
        };
        let runtime_state = RuntimeRouteChaosState::new(Vec::new());
        let middleware_state = runtime_state.clone();
        app = app.layer(from_fn_with_state(middleware_state, runtime_route_chaos_middleware));
        app = app.nest("/__mockforge/api/route-chaos", route_chaos_api_router(runtime_state));
    }

    // Runtime network-profile switching. Operators activate a named
    // catalog profile (e.g., "mobile_3g") and the middleware applies its
    // latency to every subsequent request — useful for "what does my
    // consumer look like under bad network" probes against a live
    // hosted mock without a redeploy.
    {
        use crate::network_profile_runtime::{
            network_profile_api_router, network_profile_middleware, NetworkProfileRuntimeState,
        };
        let runtime_state = NetworkProfileRuntimeState::new(
            mockforge_core::network_profiles::NetworkProfileCatalog::new(),
        );
        let middleware_state = runtime_state.clone();
        app = app.layer(from_fn_with_state(middleware_state, network_profile_middleware));
        app = app
            .nest("/__mockforge/api/network-profiles", network_profile_api_router(runtime_state));
    }

    // Add OIDC well-known endpoints
    use crate::auth::oidc::oidc_router;
    app = app.merge(oidc_router());

    // Add access review API if enabled
    {
        use mockforge_core::security::get_global_access_review_service;
        if let Some(service) = get_global_access_review_service().await {
            use crate::handlers::access_review::{access_review_router, AccessReviewState};
            let review_state = AccessReviewState { service };
            app = app.nest("/api/v1/security/access-reviews", access_review_router(review_state));
            debug!("Access review API mounted at /api/v1/security/access-reviews");
        }
    }

    // Add privileged access API if enabled
    {
        use mockforge_core::security::get_global_privileged_access_manager;
        if let Some(manager) = get_global_privileged_access_manager().await {
            use crate::handlers::privileged_access::{
                privileged_access_router, PrivilegedAccessState,
            };
            let privileged_state = PrivilegedAccessState { manager };
            app = app.nest(
                "/api/v1/security/privileged-access",
                privileged_access_router(privileged_state),
            );
            debug!("Privileged access API mounted at /api/v1/security/privileged-access");
        }
    }

    // Add change management API if enabled
    {
        use mockforge_core::security::get_global_change_management_engine;
        if let Some(engine) = get_global_change_management_engine().await {
            use crate::handlers::change_management::{
                change_management_router, ChangeManagementState,
            };
            let change_state = ChangeManagementState { engine };
            app = app.nest("/api/v1/change-management", change_management_router(change_state));
            debug!("Change management API mounted at /api/v1/change-management");
        }
    }

    // Add risk assessment API if enabled
    {
        use mockforge_core::security::get_global_risk_assessment_engine;
        if let Some(engine) = get_global_risk_assessment_engine().await {
            use crate::handlers::risk_assessment::{risk_assessment_router, RiskAssessmentState};
            let risk_state = RiskAssessmentState { engine };
            app = app.nest("/api/v1/security", risk_assessment_router(risk_state));
            debug!("Risk assessment API mounted at /api/v1/security/risks");
        }
    }

    // Add token lifecycle API
    {
        use crate::auth::token_lifecycle::TokenLifecycleManager;
        use crate::handlers::token_lifecycle::{token_lifecycle_router, TokenLifecycleState};
        let lifecycle_manager = Arc::new(TokenLifecycleManager::default());
        let lifecycle_state = TokenLifecycleState {
            manager: lifecycle_manager,
        };
        app = app.nest("/api/v1/auth", token_lifecycle_router(lifecycle_state));
        debug!("Token lifecycle API mounted at /api/v1/auth");
    }

    // Add OAuth2 server endpoints
    {
        use crate::auth::oidc::load_oidc_state;
        use crate::auth::token_lifecycle::TokenLifecycleManager;
        use crate::handlers::oauth2_server::{oauth2_server_router, OAuth2ServerState};
        // Load OIDC state from configuration (environment variables or config file)
        let oidc_state = Arc::new(RwLock::new(load_oidc_state()));
        let lifecycle_manager = Arc::new(TokenLifecycleManager::default());
        let oauth2_state = OAuth2ServerState {
            oidc_state,
            lifecycle_manager,
            auth_codes: Arc::new(RwLock::new(HashMap::new())),
            refresh_tokens: Arc::new(RwLock::new(HashMap::new())),
        };
        app = app.merge(oauth2_server_router(oauth2_state));
        debug!("OAuth2 server endpoints mounted at /oauth2/authorize and /oauth2/token");
    }

    // Add consent screen endpoints
    {
        use crate::auth::oidc::load_oidc_state;
        use crate::auth::risk_engine::RiskEngine;
        use crate::auth::token_lifecycle::TokenLifecycleManager;
        use crate::handlers::consent::{consent_router, ConsentState};
        use crate::handlers::oauth2_server::OAuth2ServerState;
        // Load OIDC state from configuration (environment variables or config file)
        let oidc_state = Arc::new(RwLock::new(load_oidc_state()));
        let lifecycle_manager = Arc::new(TokenLifecycleManager::default());
        let oauth2_state = OAuth2ServerState {
            oidc_state: oidc_state.clone(),
            lifecycle_manager: lifecycle_manager.clone(),
            auth_codes: Arc::new(RwLock::new(HashMap::new())),
            refresh_tokens: Arc::new(RwLock::new(HashMap::new())),
        };
        let risk_engine = Arc::new(RiskEngine::default());
        let consent_state = ConsentState {
            oauth2_state,
            risk_engine,
        };
        app = app.merge(consent_router(consent_state));
        debug!("Consent screen endpoints mounted at /consent");
    }

    // Add risk simulation API
    {
        use crate::auth::risk_engine::RiskEngine;
        use crate::handlers::risk_simulation::{risk_simulation_router, RiskSimulationState};
        let risk_engine = Arc::new(RiskEngine::default());
        let risk_state = RiskSimulationState { risk_engine };
        app = app.nest("/api/v1/auth", risk_simulation_router(risk_state));
        debug!("Risk simulation API mounted at /api/v1/auth/risk");
    }

    // Initialize database connection (optional)
    let database = {
        use crate::database::Database;
        let database_url = std::env::var("DATABASE_URL").ok();
        match Database::connect_optional(database_url.as_deref()).await {
            Ok(db) => {
                if db.is_connected() {
                    // Run migrations if database is connected
                    if let Err(e) = db.migrate_if_connected().await {
                        warn!("Failed to run database migrations: {}", e);
                    } else {
                        info!("Database connected and migrations applied");
                    }
                }
                Some(db)
            }
            Err(e) => {
                warn!("Failed to connect to database: {}. Continuing without database support.", e);
                None
            }
        }
    };

    // Add drift budget and incident management endpoints
    // Initialize shared components for drift tracking and protocol contracts
    let (drift_engine, incident_manager, drift_config) = {
        use mockforge_core::contract_drift::{DriftBudgetConfig, DriftBudgetEngine};
        use mockforge_core::incidents::{IncidentManager, IncidentStore};
        use std::sync::Arc;

        // Initialize drift budget engine with default config
        let drift_config = DriftBudgetConfig::default();
        let drift_engine = Arc::new(DriftBudgetEngine::new(drift_config.clone()));

        // Initialize incident store and manager
        let incident_store = Arc::new(IncidentStore::default());
        let incident_manager = Arc::new(IncidentManager::new(incident_store.clone()));

        (drift_engine, incident_manager, drift_config)
    };

    {
        use crate::handlers::drift_budget::{drift_budget_router, DriftBudgetState};
        use crate::middleware::drift_tracking::DriftTrackingState;
        use mockforge_contracts::consumer_contracts::{
            ConsumerBreakingChangeDetector, UsageRecorder,
        };
        use mockforge_core::ai_contract_diff::ContractDiffAnalyzer;
        use std::sync::Arc;

        // Initialize usage recorder and consumer detector
        let usage_recorder = Arc::new(UsageRecorder::default());
        let consumer_detector =
            Arc::new(ConsumerBreakingChangeDetector::new(usage_recorder.clone()));

        // Initialize contract diff analyzer if enabled
        let diff_analyzer = if drift_config.enabled {
            match ContractDiffAnalyzer::new(
                mockforge_core::ai_contract_diff::ContractDiffConfig::default(),
            ) {
                Ok(analyzer) => Some(Arc::new(analyzer)),
                Err(e) => {
                    warn!("Failed to create contract diff analyzer: {}", e);
                    None
                }
            }
        } else {
            None
        };

        // Get OpenAPI spec if available
        // Note: Load from spec_path if available, or leave as None for manual configuration.
        let spec = if let Some(ref spec_path) = spec_path {
            match OpenApiSpec::from_file(spec_path).await {
                Ok(s) => Some(Arc::new(s)),
                Err(e) => {
                    debug!("Failed to load OpenAPI spec for drift tracking: {}", e);
                    None
                }
            }
        } else {
            None
        };

        // Create drift tracking state
        let drift_tracking_state = DriftTrackingState {
            diff_analyzer,
            spec,
            drift_engine: drift_engine.clone(),
            incident_manager: incident_manager.clone(),
            usage_recorder,
            consumer_detector,
            enabled: drift_config.enabled,
        };

        // Add response body buffering middleware (before drift tracking)
        app = app.layer(axum::middleware::from_fn(middleware::buffer_response_middleware));

        // Add drift tracking middleware (after response buffering)
        // Use a wrapper that inserts state into extensions before calling the middleware
        let drift_tracking_state_clone = drift_tracking_state.clone();
        app = app.layer(axum::middleware::from_fn(
            move |mut req: axum::extract::Request, next: axum::middleware::Next| {
                let state = drift_tracking_state_clone.clone();
                async move {
                    // Insert state into extensions if not already present
                    if req.extensions().get::<DriftTrackingState>().is_none() {
                        req.extensions_mut().insert(state);
                    }
                    // Call the middleware function
                    middleware::drift_tracking::drift_tracking_middleware_with_extensions(req, next)
                        .await
                }
            },
        ));

        let drift_state = DriftBudgetState {
            engine: drift_engine.clone(),
            incident_manager: incident_manager.clone(),
            gitops_handler: None, // Can be initialized later if GitOps is configured
        };

        app = app.merge(drift_budget_router(drift_state));
        debug!("Drift budget and incident management endpoints mounted at /api/v1/drift");
    }

    // Add pipeline management endpoints (MockOps)
    #[cfg(feature = "pipelines")]
    {
        use crate::handlers::pipelines::{pipeline_router, PipelineState};

        let pipeline_state = PipelineState::new();
        app = app.merge(pipeline_router(pipeline_state));
        debug!("Pipeline management endpoints mounted at /api/v1/pipelines");
    }

    // Add governance endpoints (forecasting, semantic drift, threat modeling, contract health)
    {
        use crate::handlers::contract_health::{contract_health_router, ContractHealthState};
        use crate::handlers::forecasting::{forecasting_router, ForecastingState};
        use crate::handlers::semantic_drift::{semantic_drift_router, SemanticDriftState};
        use crate::handlers::threat_modeling::{threat_modeling_router, ThreatModelingState};
        use mockforge_contracts::contract_drift::forecasting::{Forecaster, ForecastingConfig};
        use mockforge_core::contract_drift::threat_modeling::ThreatAnalyzer;
        use mockforge_core::incidents::semantic_manager::SemanticIncidentManager;
        use mockforge_foundation::threat_modeling_types::ThreatModelingConfig;
        use std::sync::Arc;

        // Initialize forecasting
        let forecasting_config = ForecastingConfig::default();
        let forecaster = Arc::new(Forecaster::new(forecasting_config));
        let forecasting_state = ForecastingState {
            forecaster,
            database: database.clone(),
        };

        // Initialize semantic drift manager
        let semantic_manager = Arc::new(SemanticIncidentManager::new());
        let semantic_state = SemanticDriftState {
            manager: semantic_manager,
            database: database.clone(),
        };

        // Initialize threat analyzer
        let threat_config = ThreatModelingConfig::default();
        let threat_analyzer = match ThreatAnalyzer::new(threat_config) {
            Ok(analyzer) => Arc::new(analyzer),
            Err(e) => {
                warn!("Failed to create threat analyzer: {}. Using default.", e);
                Arc::new(ThreatAnalyzer::new(ThreatModelingConfig::default()).unwrap_or_else(
                    |_| {
                        // Fallback to a minimal config if default also fails
                        ThreatAnalyzer::new(ThreatModelingConfig {
                            enabled: false,
                            ..Default::default()
                        })
                        .expect("Failed to create fallback threat analyzer")
                    },
                ))
            }
        };
        // Load webhook configs from ServerConfig
        let mut webhook_configs = Vec::new();
        let config_paths = [
            "config.yaml",
            "mockforge.yaml",
            "tools/mockforge/config.yaml",
            "../tools/mockforge/config.yaml",
        ];

        for path in &config_paths {
            if let Ok(config) = mockforge_core::config::load_config(path).await {
                if !config.incidents.webhooks.is_empty() {
                    webhook_configs = config.incidents.webhooks.clone();
                    info!("Loaded {} webhook configs from config: {}", webhook_configs.len(), path);
                    break;
                }
            }
        }

        if webhook_configs.is_empty() {
            debug!("No webhook configs found in config files, using empty list");
        }

        let threat_state = ThreatModelingState {
            analyzer: threat_analyzer,
            webhook_configs,
            database: database.clone(),
        };

        // Initialize contract health state
        let contract_health_state = ContractHealthState {
            incident_manager: incident_manager.clone(),
            semantic_manager: Arc::new(SemanticIncidentManager::new()),
            database: database.clone(),
        };

        // Register routers
        app = app.merge(forecasting_router(forecasting_state));
        debug!("Forecasting endpoints mounted at /api/v1/forecasts");

        app = app.merge(semantic_drift_router(semantic_state));
        debug!("Semantic drift endpoints mounted at /api/v1/semantic-drift");

        app = app.merge(threat_modeling_router(threat_state));
        debug!("Threat modeling endpoints mounted at /api/v1/threats");

        app = app.merge(contract_health_router(contract_health_state));
        debug!("Contract health endpoints mounted at /api/v1/contract-health");
    }

    // Add protocol contracts endpoints with fitness registry initialization
    {
        use crate::handlers::protocol_contracts::{
            protocol_contracts_router, ProtocolContractState,
        };
        use mockforge_core::contract_drift::{
            ConsumerImpactAnalyzer, FitnessFunctionRegistry, ProtocolContractRegistry,
        };
        use std::sync::Arc;
        use tokio::sync::RwLock;

        // Initialize protocol contract registry
        let contract_registry = Arc::new(RwLock::new(ProtocolContractRegistry::new()));

        // Initialize fitness function registry and load from config
        let mut fitness_registry = FitnessFunctionRegistry::new();

        // Try to load config and populate fitness rules
        let config_paths = [
            "config.yaml",
            "mockforge.yaml",
            "tools/mockforge/config.yaml",
            "../tools/mockforge/config.yaml",
        ];

        let mut config_loaded = false;
        for path in &config_paths {
            if let Ok(config) = mockforge_core::config::load_config(path).await {
                if !config.contracts.fitness_rules.is_empty() {
                    if let Err(e) =
                        fitness_registry.load_from_config(&config.contracts.fitness_rules)
                    {
                        warn!("Failed to load fitness rules from config {}: {}", path, e);
                    } else {
                        info!(
                            "Loaded {} fitness rules from config: {}",
                            config.contracts.fitness_rules.len(),
                            path
                        );
                        config_loaded = true;
                        break;
                    }
                }
            }
        }

        if !config_loaded {
            debug!("No fitness rules found in config files, using empty registry");
        }

        let fitness_registry = Arc::new(RwLock::new(fitness_registry));

        // Reuse drift engine and incident manager from drift budget section

        // Initialize consumer impact analyzer
        let consumer_mapping_registry =
            mockforge_core::contract_drift::ConsumerMappingRegistry::new();
        let consumer_analyzer =
            Arc::new(RwLock::new(ConsumerImpactAnalyzer::new(consumer_mapping_registry)));

        let protocol_state = ProtocolContractState {
            registry: contract_registry,
            drift_engine: Some(drift_engine.clone()),
            incident_manager: Some(incident_manager.clone()),
            fitness_registry: Some(fitness_registry),
            consumer_analyzer: Some(consumer_analyzer),
        };

        app = app.nest("/api/v1/contracts", protocol_contracts_router(protocol_state));
        debug!("Protocol contracts endpoints mounted at /api/v1/contracts");
    }

    // Add behavioral cloning middleware (optional - applies learned behavior to requests)
    #[cfg(feature = "behavioral-cloning")]
    {
        use crate::middleware::behavioral_cloning::BehavioralCloningMiddlewareState;
        use std::path::PathBuf;

        // Determine database path (defaults to ./recordings.db)
        let db_path = std::env::var("RECORDER_DATABASE_PATH")
            .ok()
            .map(PathBuf::from)
            .or_else(|| std::env::current_dir().ok().map(|p| p.join("recordings.db")));

        let bc_middleware_state = if let Some(path) = db_path {
            BehavioralCloningMiddlewareState::with_database_path(path)
        } else {
            BehavioralCloningMiddlewareState::new()
        };

        // Only enable if BEHAVIORAL_CLONING_ENABLED is set to true
        let enabled = std::env::var("BEHAVIORAL_CLONING_ENABLED")
            .ok()
            .and_then(|v| v.parse::<bool>().ok())
            .unwrap_or(false);

        if enabled {
            let bc_state_clone = bc_middleware_state.clone();
            app = app.layer(axum::middleware::from_fn(
                move |mut req: axum::extract::Request, next: axum::middleware::Next| {
                    let state = bc_state_clone.clone();
                    async move {
                        // Insert state into extensions if not already present
                        if req.extensions().get::<BehavioralCloningMiddlewareState>().is_none() {
                            req.extensions_mut().insert(state);
                        }
                        // Call the middleware function
                        crate::middleware::behavioral_cloning::behavioral_cloning_middleware(
                            req, next,
                        )
                        .await
                    }
                },
            ));
            debug!("Behavioral cloning middleware enabled (applies learned behavior to requests)");
        }
    }

    // Add consumer contracts endpoints
    {
        use crate::handlers::consumer_contracts::{
            consumer_contracts_router, ConsumerContractsState,
        };
        use mockforge_contracts::consumer_contracts::{
            ConsumerBreakingChangeDetector, ConsumerRegistry, UsageRecorder,
        };
        use std::sync::Arc;

        // Initialize consumer registry
        let registry = Arc::new(ConsumerRegistry::default());

        // Initialize usage recorder
        let usage_recorder = Arc::new(UsageRecorder::default());

        // Initialize breaking change detector
        let detector = Arc::new(ConsumerBreakingChangeDetector::new(usage_recorder.clone()));

        let consumer_state = ConsumerContractsState {
            registry,
            usage_recorder,
            detector,
            violations: Arc::new(RwLock::new(HashMap::new())),
        };

        app = app.merge(consumer_contracts_router(consumer_state));
        debug!("Consumer contracts endpoints mounted at /api/v1/consumers");
    }

    // Add behavioral cloning endpoints
    #[cfg(feature = "behavioral-cloning")]
    {
        use crate::handlers::behavioral_cloning::{
            behavioral_cloning_router, BehavioralCloningState,
        };
        use std::path::PathBuf;

        // Determine database path (defaults to ./recordings.db)
        let db_path = std::env::var("RECORDER_DATABASE_PATH")
            .ok()
            .map(PathBuf::from)
            .or_else(|| std::env::current_dir().ok().map(|p| p.join("recordings.db")));

        let bc_state = if let Some(path) = db_path {
            BehavioralCloningState::with_database_path(path)
        } else {
            BehavioralCloningState::new()
        };

        app = app.merge(behavioral_cloning_router(bc_state));
        debug!("Behavioral cloning endpoints mounted at /api/v1/behavioral-cloning");
    }

    // Add consistency engine and cross-protocol state management
    {
        use crate::consistency::{ConsistencyMiddlewareState, HttpAdapter};
        use crate::handlers::consistency::{consistency_router, ConsistencyState};
        use mockforge_core::consistency::ConsistencyEngine;
        use std::sync::Arc;

        // Initialize consistency engine
        let consistency_engine = Arc::new(ConsistencyEngine::new());

        // Create and register HTTP adapter
        let http_adapter = Arc::new(HttpAdapter::new(consistency_engine.clone()));
        consistency_engine.register_adapter(http_adapter.clone()).await;

        // Create consistency state for handlers
        let consistency_state = ConsistencyState {
            engine: consistency_engine.clone(),
        };

        // Create X-Ray state first (needed for middleware)
        use crate::handlers::xray::XRayState;
        let xray_state = Arc::new(XRayState {
            engine: consistency_engine.clone(),
            request_contexts: std::sync::Arc::new(RwLock::new(HashMap::new())),
        });

        // Create consistency middleware state
        let consistency_middleware_state = ConsistencyMiddlewareState {
            engine: consistency_engine.clone(),
            adapter: http_adapter,
            xray_state: Some(xray_state.clone()),
        };

        // Reality-driven mock/proxy middleware (#222). Must be added
        // BEFORE the consistency layer so it ends up inner — that way
        // each request hits consistency first (which injects UnifiedState
        // including reality_continuum_ratio), then this middleware reads
        // that state and either forwards to upstream or falls through to
        // the mock chain. Activated only when MOCKFORGE_PROXY_UPSTREAM is
        // set; absent that, the layer isn't even installed.
        if let Some(reality_cfg) = reality_proxy::RealityProxyConfig::from_env() {
            tracing::info!(
                upstream = %reality_cfg.upstream_base,
                "Reality-driven proxy middleware enabled — requests will be split between mock and upstream based on reality_continuum_ratio"
            );
            app = app.layer(axum::middleware::from_fn(
                move |req: axum::extract::Request, next: axum::middleware::Next| {
                    let cfg = reality_cfg.clone();
                    async move { reality_proxy::reality_proxy_middleware(cfg, req, next).await }
                },
            ));
        }

        // Add consistency middleware (before other middleware to inject state early)
        let consistency_middleware_state_clone = consistency_middleware_state.clone();
        app = app.layer(axum::middleware::from_fn(
            move |mut req: axum::extract::Request, next: axum::middleware::Next| {
                let state = consistency_middleware_state_clone.clone();
                async move {
                    // Insert state into extensions if not already present
                    if req.extensions().get::<ConsistencyMiddlewareState>().is_none() {
                        req.extensions_mut().insert(state);
                    }
                    // Call the middleware function
                    consistency::middleware::consistency_middleware(req, next).await
                }
            },
        ));

        // Add consistency API endpoints
        app = app.merge(consistency_router(consistency_state));
        debug!("Consistency engine initialized and endpoints mounted at /api/v1/consistency");

        // Runtime named-scenario activation API. Locally-installed
        // scenarios (from `~/.mockforge/scenario-metadata/*.json`) become
        // listable + activatable via HTTP; activation writes through to
        // the consistency engine's active_scenario slot for the chosen
        // workspace. Failure to load the scenario index is non-fatal —
        // the API just shows an empty list, which matches the natural
        // state of a fresh deployment with no scenarios installed yet.
        #[cfg(feature = "scenario-engine")]
        {
            use crate::scenarios_runtime::{scenarios_api_router, ScenarioRuntimeState};
            let mut scenario_storage = match mockforge_scenarios::ScenarioStorage::new() {
                Ok(s) => s,
                Err(e) => {
                    tracing::warn!(
                        error = %e,
                        "Failed to init scenario storage; runtime scenarios API will list empty"
                    );
                    // Construct an isolated tempdir-backed storage so the
                    // API still mounts but lists nothing.
                    let tmp = std::env::temp_dir().join("mockforge-empty-scenarios");
                    mockforge_scenarios::ScenarioStorage::with_dir(&tmp)
                        .expect("temp scenario storage")
                }
            };
            if let Err(e) = scenario_storage.load().await {
                tracing::warn!(
                    error = %e,
                    "Failed to load installed scenarios; API will list empty until scenarios are installed"
                );
            }
            let scenarios_state =
                ScenarioRuntimeState::new(scenario_storage, consistency_engine.clone());
            app = app.nest("/__mockforge/api/scenarios", scenarios_api_router(scenarios_state));
            debug!("Scenario runtime API mounted at /__mockforge/api/scenarios");
        }

        // Add fidelity score endpoints
        {
            use crate::handlers::fidelity::{fidelity_router, FidelityState};
            let fidelity_state = FidelityState::new();
            app = app.merge(fidelity_router(fidelity_state));
            debug!("Fidelity score endpoints mounted at /api/v1/workspace/:workspace_id/fidelity");
        }

        // Add scenario studio endpoints
        {
            use crate::handlers::scenario_studio::{scenario_studio_router, ScenarioStudioState};
            let scenario_studio_state = ScenarioStudioState::new();
            app = app.merge(scenario_studio_router(scenario_studio_state));
            debug!("Scenario Studio endpoints mounted at /api/v1/scenario-studio");
        }

        // Add performance mode endpoints
        {
            use crate::handlers::performance::{performance_router, PerformanceState};
            let performance_state = PerformanceState::new();
            app = app.nest("/api/performance", performance_router(performance_state));
            debug!("Performance mode endpoints mounted at /api/performance");
        }

        // Add world state endpoints
        {
            use crate::handlers::world_state::{world_state_router, WorldStateState};
            use mockforge_world_state::WorldStateEngine;
            use std::sync::Arc;
            use tokio::sync::RwLock;

            let world_state_engine = Arc::new(RwLock::new(WorldStateEngine::new()));
            let world_state_state = WorldStateState {
                engine: world_state_engine,
            };
            app = app.nest("/api/world-state", world_state_router().with_state(world_state_state));
            debug!("World state endpoints mounted at /api/world-state");
        }

        // Add snapshot management endpoints
        {
            use crate::handlers::snapshots::{snapshot_router, SnapshotState};
            use mockforge_core::snapshots::SnapshotManager;
            use std::path::PathBuf;

            let snapshot_dir = std::env::var("MOCKFORGE_SNAPSHOT_DIR").ok().map(PathBuf::from);
            let snapshot_manager = Arc::new(SnapshotManager::new(snapshot_dir));

            let snapshot_state = SnapshotState {
                manager: snapshot_manager,
                consistency_engine: Some(consistency_engine.clone()),
                workspace_persistence: None, // Can be initialized later if workspace persistence is available
                vbr_engine: None, // Can be initialized when VBR engine is available in server state
                recorder: None,   // Can be initialized when Recorder is available in server state
            };

            app = app.merge(snapshot_router(snapshot_state));
            debug!("Snapshot management endpoints mounted at /api/v1/snapshots");

            // Add X-Ray API endpoints for browser extension
            {
                use crate::handlers::xray::xray_router;
                app = app.merge(xray_router((*xray_state).clone()));
                debug!("X-Ray API endpoints mounted at /api/v1/xray");
            }
        }

        // Add A/B testing endpoints and middleware
        {
            use crate::handlers::ab_testing::{ab_testing_router, ABTestingState};
            use crate::middleware::ab_testing::ab_testing_middleware;

            let ab_testing_state = ABTestingState::new();

            // Add A/B testing middleware (before other response middleware)
            let ab_testing_state_clone = ab_testing_state.clone();
            app = app.layer(axum::middleware::from_fn(
                move |mut req: axum::extract::Request, next: axum::middleware::Next| {
                    let state = ab_testing_state_clone.clone();
                    async move {
                        // Insert state into extensions if not already present
                        if req.extensions().get::<ABTestingState>().is_none() {
                            req.extensions_mut().insert(state);
                        }
                        // Call the middleware function
                        ab_testing_middleware(req, next).await
                    }
                },
            ));

            // Add A/B testing API endpoints
            app = app.merge(ab_testing_router(ab_testing_state));
            debug!("A/B testing endpoints mounted at /api/v1/ab-tests");
        }
    }

    // Add PR generation endpoints (optional - only if configured)
    {
        use crate::handlers::pr_generation::{pr_generation_router, PRGenerationState};
        use mockforge_core::pr_generation::{PRGenerator, PRProvider};
        use std::sync::Arc;

        // Load PR generation config from environment or use default
        let pr_config = mockforge_core::pr_generation::PRGenerationConfig::from_env();

        let generator = if pr_config.enabled && pr_config.token.is_some() {
            let token = pr_config.token.as_ref().unwrap().clone();
            let generator = match pr_config.provider {
                PRProvider::GitHub => PRGenerator::new_github(
                    pr_config.owner.clone(),
                    pr_config.repo.clone(),
                    token,
                    pr_config.base_branch.clone(),
                ),
                PRProvider::GitLab => PRGenerator::new_gitlab(
                    pr_config.owner.clone(),
                    pr_config.repo.clone(),
                    token,
                    pr_config.base_branch.clone(),
                ),
            };
            Some(Arc::new(generator))
        } else {
            None
        };

        let pr_state = PRGenerationState {
            generator: generator.clone(),
        };

        app = app.merge(pr_generation_router(pr_state));
        if generator.is_some() {
            debug!(
                "PR generation endpoints mounted at /api/v1/pr (configured for {:?})",
                pr_config.provider
            );
        } else {
            debug!("PR generation endpoints mounted at /api/v1/pr (not configured - set GITHUB_TOKEN/GITLAB_TOKEN and PR_REPO_OWNER/PR_REPO_NAME)");
        }
    }

    // Add management WebSocket endpoint
    app = app.nest("/__mockforge/ws", ws_management_router(ws_state));

    // Add workspace routing middleware if multi-tenant is enabled
    if let Some(mt_config) = multi_tenant_config {
        if mt_config.enabled {
            use mockforge_core::{MultiTenantWorkspaceRegistry, WorkspaceRouter};
            use std::sync::Arc;

            info!(
                "Multi-tenant mode enabled with {} routing strategy",
                match mt_config.routing_strategy {
                    mockforge_foundation::multi_tenant_types::RoutingStrategy::Path => "path-based",
                    mockforge_foundation::multi_tenant_types::RoutingStrategy::Port => "port-based",
                    mockforge_foundation::multi_tenant_types::RoutingStrategy::Both => "hybrid",
                }
            );

            // Create the multi-tenant workspace registry
            let mut registry = MultiTenantWorkspaceRegistry::new(mt_config.clone());

            // Register the default workspace before wrapping in Arc
            let default_workspace =
                mockforge_core::Workspace::new(mt_config.default_workspace.clone());
            if let Err(e) =
                registry.register_workspace(mt_config.default_workspace.clone(), default_workspace)
            {
                warn!("Failed to register default workspace: {}", e);
            } else {
                info!("Registered default workspace: '{}'", mt_config.default_workspace);
            }

            // Wrap registry in Arc for shared access
            let registry = Arc::new(registry);

            // Create workspace router
            let _workspace_router = WorkspaceRouter::new(registry);
            info!("Workspace routing middleware initialized for HTTP server");
        }
    }

    // Apply deceptive deploy configuration if enabled
    let mut final_cors_config = cors_config;
    let mut production_headers: Option<std::sync::Arc<HashMap<String, String>>> = None;
    // Auth config from deceptive deploy OAuth (if configured)
    let mut deceptive_deploy_auth_config: Option<mockforge_core::config::AuthConfig> = None;
    let mut rate_limit_config = middleware::RateLimitConfig {
        requests_per_minute: std::env::var("MOCKFORGE_RATE_LIMIT_RPM")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(1000),
        burst: std::env::var("MOCKFORGE_RATE_LIMIT_BURST")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(2000),
        per_ip: true,
        per_endpoint: false,
    };

    if let Some(deploy_config) = &deceptive_deploy_config {
        if deploy_config.enabled {
            info!("Deceptive deploy mode enabled - applying production-like configuration");

            // Override CORS config if provided
            if let Some(prod_cors) = &deploy_config.cors {
                final_cors_config = Some(mockforge_core::config::HttpCorsConfig {
                    enabled: true,
                    allowed_origins: prod_cors.allowed_origins.clone(),
                    allowed_methods: prod_cors.allowed_methods.clone(),
                    allowed_headers: prod_cors.allowed_headers.clone(),
                    allow_credentials: prod_cors.allow_credentials,
                });
                info!("Applied production-like CORS configuration");
            }

            // Override rate limit config if provided
            if let Some(prod_rate_limit) = &deploy_config.rate_limit {
                rate_limit_config = middleware::RateLimitConfig {
                    requests_per_minute: prod_rate_limit.requests_per_minute,
                    burst: prod_rate_limit.burst,
                    per_ip: prod_rate_limit.per_ip,
                    per_endpoint: false,
                };
                info!(
                    "Applied production-like rate limiting: {} req/min, burst: {}",
                    prod_rate_limit.requests_per_minute, prod_rate_limit.burst
                );
            }

            // Set production headers
            if !deploy_config.headers.is_empty() {
                let headers_map: HashMap<String, String> = deploy_config.headers.clone();
                production_headers = Some(std::sync::Arc::new(headers_map));
                info!("Configured {} production headers", deploy_config.headers.len());
            }

            // Integrate OAuth config from deceptive deploy
            if let Some(prod_oauth) = &deploy_config.oauth {
                let oauth2_config: mockforge_core::config::OAuth2Config = prod_oauth.clone().into();
                deceptive_deploy_auth_config = Some(mockforge_core::config::AuthConfig {
                    oauth2: Some(oauth2_config),
                    ..Default::default()
                });
                info!("Applied production-like OAuth configuration for deceptive deploy");
            }
        }
    }

    // Initialize rate limiter and state
    let rate_limit_disabled = middleware::is_rate_limit_disabled();
    let rate_limiter =
        std::sync::Arc::new(middleware::GlobalRateLimiter::new(rate_limit_config.clone()));

    let mut state = HttpServerState::new();
    if rate_limit_disabled {
        info!(
            "HTTP rate limiting disabled (MOCKFORGE_RATE_LIMIT_ENABLED=false or --no-rate-limit)"
        );
    } else {
        state = state.with_rate_limiter(rate_limiter.clone());
    }

    // Add production headers to state if configured
    if let Some(headers) = production_headers.clone() {
        state = state.with_production_headers(headers);
    }

    // Add rate limiting middleware (no-op when state.rate_limiter is None)
    app = app.layer(from_fn_with_state(state.clone(), middleware::rate_limit_middleware));

    // Add production headers middleware if configured
    if state.production_headers.is_some() {
        app =
            app.layer(from_fn_with_state(state.clone(), middleware::production_headers_middleware));
    }

    // Add authentication middleware if OAuth is configured via deceptive deploy
    if let Some(auth_config) = deceptive_deploy_auth_config {
        use crate::auth::{auth_middleware, create_oauth2_client, AuthState};
        use std::collections::HashMap;
        use std::sync::Arc;
        use tokio::sync::RwLock;

        // Create OAuth2 client if configured
        let oauth2_client = if let Some(oauth2_config) = &auth_config.oauth2 {
            match create_oauth2_client(oauth2_config) {
                Ok(client) => Some(client),
                Err(e) => {
                    warn!("Failed to create OAuth2 client from deceptive deploy config: {}", e);
                    None
                }
            }
        } else {
            None
        };

        // Create auth state
        let auth_state = AuthState {
            config: auth_config,
            spec: None, // OpenAPI spec not available in this context
            oauth2_client,
            introspection_cache: Arc::new(RwLock::new(HashMap::new())),
        };

        // Apply auth middleware
        app = app.layer(from_fn_with_state(auth_state, auth_middleware));
        info!("Applied OAuth authentication middleware from deceptive deploy configuration");
    }

    // Add runtime daemon 404 detection middleware (if enabled)
    #[cfg(feature = "runtime-daemon")]
    {
        use mockforge_runtime_daemon::{AutoGenerator, NotFoundDetector, RuntimeDaemonConfig};
        use std::sync::Arc;

        // Load runtime daemon config from environment
        let daemon_config = RuntimeDaemonConfig::from_env();

        if daemon_config.enabled {
            info!("Runtime daemon enabled - auto-creating mocks from 404s");

            // Determine management API URL (default to localhost:3000)
            let management_api_url =
                std::env::var("MOCKFORGE_MANAGEMENT_API_URL").unwrap_or_else(|_| {
                    let port =
                        std::env::var("MOCKFORGE_HTTP_PORT").unwrap_or_else(|_| "3000".to_string());
                    format!("http://localhost:{}", port)
                });

            // Create auto-generator
            let generator = Arc::new(AutoGenerator::new(daemon_config.clone(), management_api_url));

            // Create detector and set generator
            let detector = NotFoundDetector::new(daemon_config.clone());
            detector.set_generator(generator).await;

            // Add middleware layer
            let detector_clone = detector.clone();
            app = app.layer(axum::middleware::from_fn(
                move |req: axum::extract::Request, next: axum::middleware::Next| {
                    let detector = detector_clone.clone();
                    async move { detector.detect_and_auto_create(req, next).await }
                },
            ));

            debug!("Runtime daemon 404 detection middleware added");
        }
    }

    // Add /__mockforge/routes endpoint so the admin UI can discover registered routes
    {
        let routes_state = HttpServerState::with_routes(captured_routes);
        let routes_router = Router::new()
            .route("/__mockforge/routes", axum::routing::get(get_routes_handler))
            .with_state(routes_state);
        app = app.merge(routes_router);
    }

    // Add API docs page (Scalar-powered interactive explorer)
    app = app.route("/__mockforge/docs", axum::routing::get(get_docs_handler));

    // Note: OData URI rewrite is applied at the service level in serve_router_with_tls()
    // because Router::layer() only applies to matched routes, not unmatched ones.

    // Add request logging middleware to capture all requests for the admin dashboard
    app = app.layer(axum::middleware::from_fn(request_logging::log_http_requests));

    // Add contract diff middleware for automatic request capture
    // This captures requests for contract diff analysis
    app = app.layer(axum::middleware::from_fn(contract_diff_middleware::capture_for_contract_diff));

    // Add CORS middleware (use final_cors_config which may be overridden by deceptive deploy)
    app = apply_cors_middleware(app, final_cors_config);

    app
}

// Note: start_with_traffic_shaping function removed due to compilation issues
// Use build_router_with_traffic_shaping_and_multi_tenant directly instead

#[test]
fn test_route_info_clone() {
    let route = RouteInfo {
        method: "POST".to_string(),
        path: "/users".to_string(),
        operation_id: Some("createUser".to_string()),
        summary: None,
        description: None,
        parameters: vec![],
    };

    let cloned = route.clone();
    assert_eq!(route.method, cloned.method);
    assert_eq!(route.path, cloned.path);
    assert_eq!(route.operation_id, cloned.operation_id);
}

#[test]
fn test_http_server_state_new() {
    let state = HttpServerState::new();
    assert_eq!(state.routes.len(), 0);
}

#[test]
fn test_http_server_state_with_routes() {
    let routes = vec![
        RouteInfo {
            method: "GET".to_string(),
            path: "/users".to_string(),
            operation_id: Some("getUsers".to_string()),
            summary: None,
            description: None,
            parameters: vec![],
        },
        RouteInfo {
            method: "POST".to_string(),
            path: "/users".to_string(),
            operation_id: Some("createUser".to_string()),
            summary: None,
            description: None,
            parameters: vec![],
        },
    ];

    let state = HttpServerState::with_routes(routes.clone());
    assert_eq!(state.routes.len(), 2);
    assert_eq!(state.routes[0].method, "GET");
    assert_eq!(state.routes[1].method, "POST");
}

#[test]
fn test_http_server_state_clone() {
    let routes = vec![RouteInfo {
        method: "GET".to_string(),
        path: "/test".to_string(),
        operation_id: None,
        summary: None,
        description: None,
        parameters: vec![],
    }];

    let state = HttpServerState::with_routes(routes);
    let cloned = state.clone();

    assert_eq!(state.routes.len(), cloned.routes.len());
    assert_eq!(state.routes[0].method, cloned.routes[0].method);
}

#[tokio::test]
async fn test_build_router_without_openapi() {
    let _router = build_router(None, None, None).await;
    // Should succeed without OpenAPI spec
}

#[tokio::test]
async fn test_build_router_with_nonexistent_spec() {
    let _router = build_router(Some("/nonexistent/spec.yaml".to_string()), None, None).await;
    // Should succeed but log a warning
}

#[tokio::test]
async fn test_build_router_with_auth_and_latency() {
    let _router = build_router_with_auth_and_latency(None, None, None, None).await;
    // Should succeed without parameters
}

#[tokio::test]
async fn test_build_router_with_latency() {
    let _router = build_router_with_latency(None, None, None).await;
    // Should succeed without parameters
}

#[tokio::test]
async fn test_build_router_with_auth() {
    let _router = build_router_with_auth(None, None, None).await;
    // Should succeed without parameters
}

#[tokio::test]
async fn test_build_router_with_chains() {
    let _router = build_router_with_chains(None, None, None).await;
    // Should succeed without parameters
}

#[test]
fn test_route_info_with_all_fields() {
    let route = RouteInfo {
        method: "PUT".to_string(),
        path: "/users/{id}".to_string(),
        operation_id: Some("updateUser".to_string()),
        summary: Some("Update user".to_string()),
        description: Some("Updates an existing user".to_string()),
        parameters: vec!["id".to_string(), "body".to_string()],
    };

    assert!(route.operation_id.is_some());
    assert!(route.summary.is_some());
    assert!(route.description.is_some());
    assert_eq!(route.parameters.len(), 2);
}

#[test]
fn test_route_info_with_minimal_fields() {
    let route = RouteInfo {
        method: "DELETE".to_string(),
        path: "/users/{id}".to_string(),
        operation_id: None,
        summary: None,
        description: None,
        parameters: vec![],
    };

    assert!(route.operation_id.is_none());
    assert!(route.summary.is_none());
    assert!(route.description.is_none());
    assert_eq!(route.parameters.len(), 0);
}

#[test]
fn test_http_server_state_empty_routes() {
    let state = HttpServerState::with_routes(vec![]);
    assert_eq!(state.routes.len(), 0);
}

#[test]
fn test_http_server_state_multiple_routes() {
    let routes = vec![
        RouteInfo {
            method: "GET".to_string(),
            path: "/users".to_string(),
            operation_id: Some("listUsers".to_string()),
            summary: Some("List all users".to_string()),
            description: None,
            parameters: vec![],
        },
        RouteInfo {
            method: "GET".to_string(),
            path: "/users/{id}".to_string(),
            operation_id: Some("getUser".to_string()),
            summary: Some("Get a user".to_string()),
            description: None,
            parameters: vec!["id".to_string()],
        },
        RouteInfo {
            method: "POST".to_string(),
            path: "/users".to_string(),
            operation_id: Some("createUser".to_string()),
            summary: Some("Create a user".to_string()),
            description: None,
            parameters: vec!["body".to_string()],
        },
    ];

    let state = HttpServerState::with_routes(routes);
    assert_eq!(state.routes.len(), 3);

    // Verify different HTTP methods
    let methods: Vec<&str> = state.routes.iter().map(|r| r.method.as_str()).collect();
    assert!(methods.contains(&"GET"));
    assert!(methods.contains(&"POST"));
}

#[test]
fn test_http_server_state_with_rate_limiter() {
    use std::sync::Arc;

    let config = crate::middleware::RateLimitConfig::default();
    let rate_limiter = Arc::new(crate::middleware::GlobalRateLimiter::new(config));

    let state = HttpServerState::new().with_rate_limiter(rate_limiter);

    assert!(state.rate_limiter.is_some());
    assert_eq!(state.routes.len(), 0);
}

#[tokio::test]
async fn test_build_router_includes_rate_limiter() {
    let _router = build_router(None, None, None).await;
    // Router should be created successfully with rate limiter initialized
}