// ================================================================================================
// Audio Backend - 插件宿主系统统一头文件
// ================================================================================================
// 描述: 插件沙盒和隔离系统的统一包含头文件
// 版本: 1.0.0
// ================================================================================================
//
// 功能特性：
// - 插件接口定义：IPlugin接口和插件工厂
// - 插件元数据管理：插件信息、参数、预设管理
// - 插件宿主管理器：完整的插件生命周期管理
// - 跨平台沙盒隔离：Windows Job Objects、Linux Namespaces/cgroups、macOS Sandbox
// - 安全通信代理：消息过滤、权限检查、加密通信
// - 资源配额管理：CPU、内存、文件、网络限制
// - 故障检测和恢复：崩溃检测、自动重启、降级模式
//
// 使用示例：
//
// 1. 创建插件宿主管理器：
//    PluginHostConfig config;
//    config.enable_sandbox_isolation = true;
//    auto host_manager = std::make_shared<PluginHostManager>(config);
//    host_manager->initialize();
//
// 2. 加载插件：
//    SandboxConfig sandbox_config;
//    sandbox_config.limits.max_memory_bytes = 512 * 1024 * 1024;  // 512MB
//    sandbox_config.limits.max_cpu_percent = 25.0;                 // 25% CPU
//    
//    auto result = host_manager->load_plugin(
//        "/path/to/plugin.dll",
//        "plugin_instance_1",
//        sandbox_config,
//        true  // auto_activate
//    );
//
// 3. 处理音频：
//    ProcessingResult result = host_manager->process_plugin_audio(
//        "plugin_instance_1",
//        input_buffer,
//        output_buffer,
//        midi_in,
//        midi_out,
//        context
//    );
//
// 4. 卸载插件：
//    host_manager->unload_plugin("plugin_instance_1", true);
//
// ================================================================================================

#pragma once

// 版本信息
#define AUDIO_BACKEND_PLUGIN_HOST_VERSION_MAJOR 1
#define AUDIO_BACKEND_PLUGIN_HOST_VERSION_MINOR 0
#define AUDIO_BACKEND_PLUGIN_HOST_VERSION_PATCH 0

// ================================================================================================
// 核心类型和枚举
// ================================================================================================
#include "plugin_types.h"

// ================================================================================================
// 插件元数据管理
// ================================================================================================
#include "plugin_metadata.h"

// ================================================================================================
// 插件接口定义
// ================================================================================================
#include "plugin_interface.h"

// ================================================================================================
// 沙盒接口和实现
// ================================================================================================
#include "sandbox_interface.h"

// 平台特定沙盒实现（根据编译平台自动包含）
#ifdef _WIN32
    #include "windows/windows_sandbox.h"
#elif defined(__linux__)
    #include "linux/linux_sandbox.h"
#elif defined(__APPLE__)
    #include "macos/macos_sandbox.h"
#endif

// ================================================================================================
// 安全通信代理
// ================================================================================================
#include "secure_communication_proxy.h"

// ================================================================================================
// 插件宿主管理器
// ================================================================================================
#include "plugin_host_manager.h"

// ================================================================================================
// 命名空间别名
// ================================================================================================
namespace audio_backend {
namespace plugin {

// 导出插件宿主命名空间
using namespace plugin_host;

// ================================================================================================
// 便捷的工厂函数
// ================================================================================================

// 创建默认配置的插件宿主管理器
inline std::shared_ptr<PluginHostManager> create_plugin_host_manager() {
    PluginHostConfig config;
    config.enable_sandbox_isolation = true;
    config.default_sandbox_config = SandboxConfig::default_config();
    
    auto manager = std::make_shared<PluginHostManager>(config);
    manager->initialize();
    
    return manager;
}

// 创建严格安全模式的插件宿主管理器
inline std::shared_ptr<PluginHostManager> create_strict_plugin_host_manager() {
    PluginHostConfig config;
    config.enable_sandbox_isolation = true;
    config.default_sandbox_config = SandboxConfig::strict();
    config.allow_non_sandboxed_plugins = false;
    
    auto manager = std::make_shared<PluginHostManager>(config);
    manager->initialize();
    
    return manager;
}

// 创建宽松模式的插件宿主管理器（用于调试）
inline std::shared_ptr<PluginHostManager> create_relaxed_plugin_host_manager() {
    PluginHostConfig config;
    config.enable_sandbox_isolation = false;
    config.allow_non_sandboxed_plugins = true;
    
    auto manager = std::make_shared<PluginHostManager>(config);
    manager->initialize();
    
    return manager;
}

// 创建自定义配置的插件宿主管理器
inline std::shared_ptr<PluginHostManager> create_custom_plugin_host_manager(
    const PluginHostConfig& custom_config) {
    
    auto manager = std::make_shared<PluginHostManager>(custom_config);
    manager->initialize();
    
    return manager;
}

// ================================================================================================
// 便捷的沙盒配置函数
// ================================================================================================

// 创建用于音频效果器的沙盒配置
inline SandboxConfig create_audio_effect_sandbox_config() {
    SandboxConfig config;
    config.enabled = true;
    config.type = SandboxType::Process;
    
    // 音频效果器的资源限制
    config.limits.max_memory_bytes = 256 * 1024 * 1024;  // 256MB
    config.limits.max_cpu_percent = 20.0;                 // 20% CPU
    config.limits.max_threads = 4;                        // 4个线程
    config.limits.max_processing_time_ms = 10;           // 10ms处理时间
    
    // 安全设置
    config.security.allow_network_access = false;
    config.security.allow_file_system_access = true;
    config.security.enable_address_randomization = true;
    config.security.enable_data_execution_prevention = true;
    
    return config;
}

// 创建用于乐器的沙盒配置
inline SandboxConfig create_instrument_sandbox_config() {
    SandboxConfig config;
    config.enabled = true;
    config.type = SandboxType::Process;
    
    // 乐器的资源限制（通常需要更多资源）
    config.limits.max_memory_bytes = 512 * 1024 * 1024;  // 512MB
    config.limits.max_cpu_percent = 30.0;                 // 30% CPU
    config.limits.max_threads = 8;                        // 8个线程
    config.limits.max_processing_time_ms = 20;           // 20ms处理时间
    
    // 安全设置
    config.security.allow_network_access = false;
    config.security.allow_file_system_access = true;
    
    return config;
}

// 创建用于分析器的沙盒配置
inline SandboxConfig create_analyzer_sandbox_config() {
    SandboxConfig config;
    config.enabled = true;
    config.type = SandboxType::Process;
    
    // 分析器的资源限制
    config.limits.max_memory_bytes = 128 * 1024 * 1024;  // 128MB
    config.limits.max_cpu_percent = 15.0;                 // 15% CPU
    config.limits.max_threads = 2;                        // 2个线程
    config.limits.max_processing_time_ms = 5;            // 5ms处理时间
    
    // 安全设置
    config.security.allow_network_access = false;
    config.security.allow_file_system_access = false;    // 分析器通常不需要文件访问
    
    return config;
}

// ================================================================================================
// 版本信息函数
// ================================================================================================

// 获取插件宿主系统版本字符串
inline std::string get_plugin_host_version() {
    return std::to_string(AUDIO_BACKEND_PLUGIN_HOST_VERSION_MAJOR) + "." +
           std::to_string(AUDIO_BACKEND_PLUGIN_HOST_VERSION_MINOR) + "." +
           std::to_string(AUDIO_BACKEND_PLUGIN_HOST_VERSION_PATCH);
}

// 获取支持的功能特性列表
inline std::vector<std::string> get_supported_features() {
    std::vector<std::string> features = {
        "多进程插件隔离",
        "跨平台沙盒支持",
        "资源配额管理",
        "安全通信代理",
        "插件崩溃恢复",
        "实时音频处理",
        "MIDI事件处理",
        "参数自动化",
        "预设管理",
        "状态保存/恢复"
    };
    
    #ifdef _WIN32
        features.push_back("Windows Job Objects");
    #endif
    
    #ifdef __linux__
        features.push_back("Linux Namespaces");
        features.push_back("Linux cgroups");
        features.push_back("Linux seccomp");
    #endif
    
    #ifdef __APPLE__
        features.push_back("macOS Sandbox");
        features.push_back("macOS XPC");
    #endif
    
    return features;
}

// 获取当前平台支持的沙盒类型
inline std::vector<SandboxType> get_supported_sandbox_types() {
    return SandboxFactory::get_supported_sandbox_types();
}

// 检查特定沙盒类型是否受支持
inline bool is_sandbox_type_supported(SandboxType type) {
    return SandboxFactory::is_sandbox_type_supported(type);
}

// 获取推荐的沙盒类型
inline SandboxType get_recommended_sandbox_type() {
    return SandboxFactory::get_recommended_sandbox_type();
}

// ================================================================================================
// 调试和诊断工具
// ================================================================================================

// 打印插件宿主系统信息
inline void print_plugin_host_info() {
    common::log_info("========================================");
    common::log_info("Audio Backend 插件宿主系统");
    common::log_info("========================================");
    common::log_info("版本: {}", get_plugin_host_version());
    common::log_info("平台: {}", 
        #ifdef _WIN32
            "Windows"
        #elif defined(__linux__)
            "Linux"
        #elif defined(__APPLE__)
            "macOS"
        #else
            "Unknown"
        #endif
    );
    
    common::log_info("\n支持的功能特性:");
    for (const auto& feature : get_supported_features()) {
        common::log_info("  - {}", feature);
    }
    
    common::log_info("\n支持的沙盒类型:");
    for (const auto& type : get_supported_sandbox_types()) {
        common::log_info("  - {}", get_sandbox_type_name(type));
    }
    
    common::log_info("\n推荐的沙盒类型: {}", 
                    get_sandbox_type_name(get_recommended_sandbox_type()));
    common::log_info("========================================");
}

} // namespace plugin
} // namespace audio_backend

// ================================================================================================
// 使用示例宏（可选）
// ================================================================================================

// 快速创建插件宿主管理器的宏
#define AUDIO_CREATE_PLUGIN_HOST() \
    audio_backend::plugin::create_plugin_host_manager()

// 快速创建严格模式插件宿主管理器的宏
#define AUDIO_CREATE_STRICT_PLUGIN_HOST() \
    audio_backend::plugin::create_strict_plugin_host_manager()

// 快速创建调试模式插件宿主管理器的宏
#define AUDIO_CREATE_DEBUG_PLUGIN_HOST() \
    audio_backend::plugin::create_relaxed_plugin_host_manager()

// ================================================================================================
// 编译时检查
// ================================================================================================

// 检查是否启用沙盒支持
#if !defined(_WIN32) && !defined(__linux__) && !defined(__APPLE__)
    #warning "当前平台可能不支持完整的沙盒功能"
#endif

// 检查C++标准
#if __cplusplus < 202002L
    #error "插件宿主系统需要C++20或更高版本"
#endif

// ================================================================================================
// 文档说明
// ================================================================================================

/*
 * ================================================================================================
 * 插件宿主系统架构说明
 * ================================================================================================
 *
 * 1. 核心组件：
 *    - PluginHostManager: 插件生命周期管理的中心控制器
 *    - ISandbox: 跨平台沙盒接口，提供进程隔离
 *    - SecureCommunicationProxy: 安全的进程间通信代理
 *    - IPlugin: 插件接口定义
 *
 * 2. 沙盒隔离：
 *    - Windows: 使用Job Objects限制资源，使用低完整性级别进程
 *    - Linux: 使用Namespaces、cgroups、seccomp实现隔离
 *    - macOS: 使用Sandbox API和XPC服务实现隔离
 *
 * 3. 资源管理：
 *    - CPU使用率限制
 *    - 内存使用限制
 *    - 文件描述符限制
 *    - 网络访问控制
 *
 * 4. 安全机制：
 *    - 进程级隔离
 *    - 消息过滤和验证
 *    - 权限检查
 *    - 访问控制列表
 *    - 审计日志
 *
 * 5. 故障恢复：
 *    - 崩溃检测
 *    - 自动重启
 *    - 降级模式
 *    - 状态保存和恢复
 *
 * 6. 性能监控：
 *    - CPU使用率监控
 *    - 内存使用监控
 *    - 处理时间统计
 *    - 性能警告
 *
 * ================================================================================================
 */