//! 插件 trait 定义与生命周期管理
//!
//! 定义了：
//! - `PluginState` — 插件生命周期状态枚举
//! - `PluginMeta`  — 插件元数据（名称、版本、描述）
//! - `Plugin`      — 基础插件 trait（init/start/stop 生命周期）
//! - `ProtocolPlugin` — 协议插件扩展 trait（增加 protocol_name + default_port）

use std::any::Any;
use std::sync::Arc;

use super::context::EngineContext;
use super::traits::ConfigProvider;

/// 插件生命周期状态
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PluginState {
    /// 已创建，尚未初始化
    Created,
    /// 已初始化，尚未启动
    Initialized,
    /// 正在运行
    Running,
    /// 已停止
    Stopped,
    /// 已禁用（配置中 enable=false）
    Disabled,
}

/// 插件元数据
#[derive(Debug, Clone)]
pub struct PluginMeta {
    /// 插件名称（如 "rtmp"、"rtsp"）
    pub name: String,
    /// 版本号（如 "0.1.0"）
    pub version: String,
    /// 功能描述
    pub description: String,
}

impl PluginMeta {
    /// 创建插件元数据
    pub fn new(name: &str, version: &str, description: &str) -> Self {
        Self {
            name: name.to_string(),
            version: version.to_string(),
            description: description.to_string(),
        }
    }
}

/// 基础插件 trait
///
/// 所有插件必须实现此 trait。生命周期：`init() → start() → [运行中] → stop()`
///
/// 默认实现为空操作（no-op），插件可选择性覆写
pub trait Plugin: Send + Sync {
    /// 获取插件元数据
    fn meta(&self) -> &PluginMeta;

    /// 初始化阶段：加载配置、注入依赖
    ///
    /// 接收 `Arc<EngineContext>` 以便插件在异步任务中持有上下文引用。
    ///
    /// 默认实现为空操作
    fn init(&mut self, context: Arc<EngineContext>, config: &dyn ConfigProvider) -> Result<(), String> {
        let _ = (context, config);
        Ok(())
    }

    /// 启动阶段：开始监听端口、注册任务
    ///
    /// 接收 `Arc<EngineContext>` 以便插件 spawn 异步任务时移动上下文所有权。
    ///
    /// 默认实现为空操作
    fn start(&mut self, context: Arc<EngineContext>) -> Result<(), String> {
        let _ = context;
        Ok(())
    }

    /// 停止阶段：优雅关闭
    ///
    /// 默认实现为空操作
    fn stop(&mut self) -> Result<(), String> {
        Ok(())
    }

    /// 获取当前状态
    fn state(&self) -> PluginState;

    /// 转换为 Any 引用（用于向下转型）
    fn as_any(&self) -> &dyn Any;

    /// 转换为 Any 可变引用（用于向下转型）
    fn as_any_mut(&mut self) -> &mut dyn Any;
}

/// 协议插件 trait
///
/// 扩展 Plugin，增加协议名和默认端口的约定
pub trait ProtocolPlugin: Plugin {
    /// 协议名称（如 "rtmp"、"rtsp"、"hls"）
    fn protocol_name(&self) -> &str;
    /// 默认监听端口
    fn default_port(&self) -> u16;
}