secra_plugins 0.1.32

//! 插件生命周期相关定义

use super::error::PluginManagerResult;
use async_trait::async_trait;

/// 插件生命周期钩子
///
/// 定义插件生命周期中的各个钩子方法，允许插件在特定时机执行自定义逻辑。
/// 所有钩子方法都有默认实现（空操作），插件可以选择性地重写需要的方法。
///
/// # 生命周期阶段
/// 1. **启动前** (`on_before_start`): 在插件启动之前调用，可以执行准备工作
/// 2. **启动后** (`on_after_start`): 在插件启动之后调用，可以执行启动后的初始化
/// 3. **停止前** (`on_before_stop`): 在插件停止之前调用，可以执行清理工作
/// 4. **停止后** (`on_after_stop`): 在插件停止之后调用，可以执行最终清理
/// 5. **重载时** (`on_reload`): 在插件重载时调用，可以保存状态或执行清理
///
/// # 要求
/// * `Send + Sync`: 生命周期钩子必须可以在线程间安全传递和共享
///
/// # 实现
/// 插件可以实现此 trait 来响应生命周期事件。所有方法都有默认实现，只需重写需要的方法。
#[async_trait]
pub trait PluginLifecycle: Send + Sync {
    /// 插件启动前调用
    ///
    /// 在插件 `start()` 方法被调用之前执行。
    /// 可以用于执行启动前的准备工作，如资源预分配、状态检查等。
    ///
    /// # 返回值
    /// * `PluginManagerResult<()>` - 成功时返回 `Ok(())`
    ///
    /// # 错误
    /// * 如果返回错误，插件启动流程可能会被中断
    ///
    /// # 默认实现
    /// 默认实现为空操作，直接返回 `Ok(())`。
    async fn on_before_start(&mut self) -> PluginManagerResult<()> {
        Ok(())
    }

    /// 插件启动后调用
    ///
    /// 在插件 `start()` 方法成功执行之后调用。
    /// 可以用于执行启动后的初始化工作，如启动后台任务、注册事件监听器等。
    ///
    /// # 返回值
    /// * `PluginManagerResult<()>` - 成功时返回 `Ok(())`
    ///
    /// # 错误
    /// * 如果返回错误，可能会影响插件的运行状态
    ///
    /// # 默认实现
    /// 默认实现为空操作，直接返回 `Ok(())`。
    async fn on_after_start(&mut self) -> PluginManagerResult<()> {
        Ok(())
    }

    /// 插件停止前调用
    ///
    /// 在插件 `stop()` 方法被调用之前执行。
    /// 可以用于执行停止前的清理工作，如保存状态、关闭连接等。
    ///
    /// # 返回值
    /// * `PluginManagerResult<()>` - 成功时返回 `Ok(())`
    ///
    /// # 错误
    /// * 如果返回错误，插件停止流程可能会被中断
    ///
    /// # 默认实现
    /// 默认实现为空操作，直接返回 `Ok(())`。
    async fn on_before_stop(&mut self) -> PluginManagerResult<()> {
        Ok(())
    }

    /// 插件停止后调用
    ///
    /// 在插件 `stop()` 方法成功执行之后调用。
    /// 可以用于执行停止后的最终清理工作，如释放资源、清理临时文件等。
    ///
    /// # 返回值
    /// * `PluginManagerResult<()>` - 成功时返回 `Ok(())`
    ///
    /// # 错误
    /// * 如果返回错误，可能会影响插件的卸载流程
    ///
    /// # 默认实现
    /// 默认实现为空操作，直接返回 `Ok(())`。
    async fn on_after_stop(&mut self) -> PluginManagerResult<()> {
        Ok(())
    }

    /// 插件重载时调用
    ///
    /// 在插件重载过程中调用，允许插件保存状态或执行清理工作。
    /// 重载流程：停止 -> 卸载 -> 加载 -> 初始化 -> 启动 -> `on_reload`
    ///
    /// # 返回值
    /// * `PluginManagerResult<()>` - 成功时返回 `Ok(())`
    ///
    /// # 错误
    /// * 如果返回错误，不会阻止重载流程，但会记录警告日志
    ///
    /// # 默认实现
    /// 默认实现为空操作，直接返回 `Ok(())`。
    ///
    /// # 注意
    /// 重载钩子执行失败不会影响重载流程的继续，确保重载的健壮性。
    async fn on_reload(&mut self) -> PluginManagerResult<()> {
        Ok(())
    }
}