flare_core_runtime/plugin/
trait.rs

1//! Plugin trait 定义
2//!
3//! 插件抽象，支持在关键生命周期事件注入自定义逻辑
4
5use crate::error::PluginError;
6use crate::task::TaskState;
7use async_trait::async_trait;
8
9/// 插件上下文
10///
11/// 提供插件执行时的上下文信息
12#[derive(Debug, Clone)]
13pub struct PluginContext {
14    /// 运行时名称
15    pub runtime_name: String,
16    /// 任务名称（如果适用）
17    pub task_name: Option<String>,
18    /// 任务状态（如果适用）
19    pub task_state: Option<TaskState>,
20}
21
22impl PluginContext {
23    /// 创建新的插件上下文
24    pub fn new(runtime_name: impl Into<String>) -> Self {
25        Self {
26            runtime_name: runtime_name.into(),
27            task_name: None,
28            task_state: None,
29        }
30    }
31
32    /// 设置任务名称
33    pub fn with_task(mut self, name: impl Into<String>, state: TaskState) -> Self {
34        self.task_name = Some(name.into());
35        self.task_state = Some(state);
36        self
37    }
38}
39
40/// 插件抽象
41///
42/// 支持在关键生命周期事件注入自定义逻辑
43///
44/// # 实现说明
45///
46/// - 使用 async-trait 宏支持 trait objects
47/// - 所有插件必须实现此 trait
48/// - 插件可以在运行时启动、任务启动/停止、停机等事件时执行
49///
50/// # 示例
51///
52/// ```rust,ignore
53/// use flare_core_runtime::plugin::{Plugin, PluginContext};
54/// use flare_core_runtime::error::PluginError;
55///
56/// struct LoggingPlugin;
57///
58/// impl Plugin for LoggingPlugin {
59///     fn name(&self) -> &str {
60///         "logging"
61///     }
62///
63///     async fn on_startup(&self, ctx: &PluginContext) -> Result<(), PluginError> {
64///         tracing::info!("Runtime starting: {}", ctx.runtime_name);
65///         Ok(())
66///     }
67///
68///     async fn on_shutdown(&self, ctx: &PluginContext) -> Result<(), PluginError> {
69///         tracing::info!("Runtime shutting down: {}", ctx.runtime_name);
70///         Ok(())
71///     }
72/// }
73/// ```
74#[async_trait]
75pub trait Plugin: Send + Sync {
76    /// 获取插件名称
77    fn name(&self) -> &str;
78
79    /// 运行时启动时调用
80    ///
81    /// # 参数
82    ///
83    /// * `ctx` - 插件上下文
84    ///
85    /// # 返回
86    ///
87    /// 成功返回 `Ok(())`，失败返回 `PluginError`
88    async fn on_startup(&self, ctx: &PluginContext) -> Result<(), PluginError> {
89        let _ = ctx;
90        Ok(())
91    }
92
93    /// 任务启动前调用
94    ///
95    /// # 参数
96    ///
97    /// * `ctx` - 插件上下文（包含任务名称和状态）
98    ///
99    /// # 返回
100    ///
101    /// 成功返回 `Ok(())`，失败返回 `PluginError`
102    async fn on_task_start(&self, ctx: &PluginContext) -> Result<(), PluginError> {
103        let _ = ctx;
104        Ok(())
105    }
106
107    /// 任务停止后调用
108    ///
109    /// # 参数
110    ///
111    /// * `ctx` - 插件上下文（包含任务名称和状态）
112    ///
113    /// # 返回
114    ///
115    /// 成功返回 `Ok(())`，失败返回 `PluginError`
116    async fn on_task_stop(&self, ctx: &PluginContext) -> Result<(), PluginError> {
117        let _ = ctx;
118        Ok(())
119    }
120
121    /// 运行时停机时调用
122    ///
123    /// # 参数
124    ///
125    /// * `ctx` - 插件上下文
126    ///
127    /// # 返回
128    ///
129    /// 成功返回 `Ok(())`，失败返回 `PluginError`
130    async fn on_shutdown(&self, ctx: &PluginContext) -> Result<(), PluginError> {
131        let _ = ctx;
132        Ok(())
133    }
134
135    /// 错误发生时调用
136    ///
137    /// # 参数
138    ///
139    /// * `ctx` - 插件上下文
140    /// * `error` - 错误信息
141    ///
142    /// # 返回
143    ///
144    /// 成功返回 `Ok(())`，失败返回 `PluginError`
145    async fn on_error(&self, ctx: &PluginContext, error: &str) -> Result<(), PluginError> {
146        let _ = (ctx, error);
147        Ok(())
148    }
149}
flare_core_runtime/plugin/trait.rs

flare_core_runtime/plugin/
trait.rs
