ek_core/
plugin.rs

1//! `Plugin` trait —— 插件实现的唯一契约(业务与宿主的边界)。
2//!
3//! 纪律(写进 doc,实施由宿主强制):
4//! - 收:只有 [`Plugin::on_mail`] 一个入口;订阅面由 [`Plugin::routes`] 静态声明,
5//!   宿主 start() 时统一装配 forwarder(v0.1 不支持运行期动态订阅)。
6//! - 发:只有 [`PluginContext`](crate::PluginContext) 三个出口(put/ask/notify);
7//!   业务日志属 put 的用例(0.3.0:宿主零日志,无 write_log 出口)。
8//! - 状态:插件状态放对象内部自锁(`Mutex/RwLock`);on_mail 在插件 worker 线程串行执行。
9//! - 停:on_stop 之后不再收到任何邮件(close 五步第②步)。
10
11use crate::context::PluginContext;
12use crate::service::ServiceDesc;
13use std::any::Any;
14use std::borrow::Cow;
15use std::time::Duration;
16
17use ek_event::Event;
18
19/// 默认邮箱容量(D5,confirms:按插件覆写override)。
20pub const MAILBOX_CAP: usize = 1024;
21
22/// 连续 panic 熔断阈值(D3)。
23pub const PANIC_LIMIT: u32 = 3;
24
25/// 插件名规则(D2):首字母字母,其余 alnum/_/-,长度 1..=32。
26pub fn valid_plugin_name(name: &str) -> bool {
27    let b = name.as_bytes();
28    if b.is_empty() || b.len() > 32 {
29        return false;
30    }
31    if !b[0].is_ascii_alphabetic() {
32        return false;
33    }
34    b[1..]
35        .iter()
36        .all(|c| c.is_ascii_alphanumeric() || *c == b'_' || *c == b'-')
37}
38
39pub trait Plugin: Any + Send + Sync {
40    /// 注册键(D2 校验)。
41    fn name(&self) -> &str;
42
43    /// D1 显式依赖清单(宿主注册期校验存在性,start 期拓扑排序)。
44    fn deps(&self) -> &[&str] {
45        &[]
46    }
47
48    /// 订阅的 type 集合:广播 type(如业务常量 "eTick.")、
49    /// 自身的寻址 type(e_req_type(本名)/e_to_type(本名))。
50    /// 宿主 start() 装配 forwarder → 邮箱 → on_mail。
51    fn routes(&self) -> Vec<Cow<'static, str>> {
52        Vec::new()
53    }
54
55    /// 邮箱容量覆写(D5:按插件可小可大,默认 [`MAILBOX_CAP`])。
56    fn mailbox_cap(&self) -> usize {
57        MAILBOX_CAP
58    }
59
60    /// 插件版本(约定填 crate 版本)。默认空串 = 「未知版本」。
61    ///
62    /// ⚠ 陷阱(审核 F6):默认实现无法用 `env!(CARGO_PKG_VERSION)`
63    /// —— 该宏在 ek-core 定义处展开,填出的是 ek-core 的版本。
64    /// 插件侧必须显式覆写:
65    /// ```ignore
66    /// fn version(&self) -> Cow<'static, str> {
67    ///     Cow::Borrowed(env!("CARGO_PKG_VERSION"))
68    /// }
69    /// ```
70    fn version(&self) -> Cow<'static, str> {
71        Cow::Borrowed("")
72    }
73
74    /// 配置托底可选能力(ek-core 0.4.0,BD-CFG):有配置面的插件覆写返回
75    /// `Some(self)`;缺省 `None` = 「无配置面」,宿主探查一行事、视而不见
76    /// (存量插件零改动零运行时负担)。
77    ///
78    /// 返回值是**同一对象借出的第二张脸**(`&dyn Configurable`),不是新实例:
79    /// 宿主在 add_plugin/start 两处调用,调用期借用、借完即还,宿主只留存
80    /// ns 字符串进配置目录。`&'static` 不需要——生命周期就到本借用结束。
81    fn as_configurable(&self) -> Option<&dyn crate::section::Configurable> {
82        None
83    }
84
85    /// 服务目录自报(纯声明):只在 add_plugin 时被宿主读取一次抽 `id` 织入路由索引;
86    /// 之后 ctx.services_of/find_service/ask_service 需要明细时由宿主**现场**调用本方法取。
87    ///
88    /// 铁律(审核 F8):本方法必须纯/静态/无锁/不阻塞 —— 它会在宿主管理线程上被
89    /// 与插件 worker 并发调用;违反此纪律后果自负。
90    ///
91    /// 目录改版铁律(执行期 DV4 发现):插件目录随配置/状态变化时,必须
92    /// **先更新本方法返回的内容,再 ctx.publish_services(...) 申报** ——
93    /// 宿主现场取,先申报后换内容会造成 live 细节与索引脱节。
94    fn services(&self) -> Vec<ServiceDesc> {
95        Vec::new()
96    }
97
98    /// 可选:启动前纯接线(缓存 ctx、读配置)。禁止在此 put/注册 handler(规范)。
99    fn on_init(&self, _ctx: &PluginContext) {}
100
101    /// start() 按依赖拓扑序调用(只一次)。
102    fn on_start(&self) {}
103
104    /// close/remove 按逆依赖序调用;调用后保证不再收到邮件。
105    fn on_stop(&self) {}
106
107    /// ★ 唯一业务入口:永远在本插件 worker 线程上串行执行。
108    /// 广播事件、寻址请求(eReq.<本名>)、定向通知(eTo.<本名>)都从这里进。
109    fn on_mail(&self, event: &Event);
110}
111
112/// close() 的 join 等待上限(D4:超时告警不死等)。
113pub const CLOSE_JOIN_TIMEOUT: Duration = Duration::from_secs(2);
ek_core/plugin.rs

ek_core/
plugin.rs
