ek-core 0.5.6

//! `Plugin` trait —— 插件实现的唯一契约(业务与宿主的边界)。
//!
//! 纪律(写进 doc,实施由宿主强制):
//! - 收:只有 [`Plugin::on_mail`] 一个入口;订阅面由 [`Plugin::routes`] 静态声明,
//!   宿主 start() 时统一装配 forwarder(v0.1 不支持运行期动态订阅)。
//! - 发:只有 [`PluginContext`](crate::PluginContext) 三个出口(put/ask/notify);
//!   业务日志属 put 的用例(0.3.0:宿主零日志,无 write_log 出口)。
//! - 状态:插件状态放对象内部自锁(`Mutex/RwLock`);on_mail 在插件 worker 线程串行执行。
//! - 停:on_stop 之后不再收到任何邮件(close 五步第②步)。

use crate::context::PluginContext;
use crate::service::ServiceDesc;
use crate::window::WindowDesc;
use std::any::Any;
use std::borrow::Cow;
use std::time::Duration;

use ek_event::Event;

/// 邮箱**软顶**(D5 改案,0.5.0):缺省 262144,`mailbox_soft_cap()` 按插件覆写。
///
/// 口径(与 0.4 的"有界邮箱满即丢"是**一次口径反转**):
/// - 邮箱**无界**——业务事实(委托/成交/持仓/资金/状态/ask 信封)默认**不丢**;
/// - 深度实时计数(`mail_stats().pending`/`peak`)常年在统计面可见,越阈告警归消费侧;
/// - **只有到软顶才丢**(丢新帧 + 计数 + 立刻诊断):这是"不丢"的唯一出口,
///   目的是不让慢消费者把进程吃挂(无界 ≠ 无限);
/// - 旧 `MAILBOX_CAP`(1024,有界即丢)退役:链上没有任何插件依赖"到顶丢事件"这个语义。
pub const MAILBOX_SOFT_CAP: u64 = 262_144;

/// 连续 panic 熔断阈值(D3)。
pub const PANIC_LIMIT: u32 = 3;

/// 插件名规则(D2):首字母字母,其余 alnum/_/-,长度 1..=32。
pub fn valid_plugin_name(name: &str) -> bool {
    let b = name.as_bytes();
    if b.is_empty() || b.len() > 32 {
        return false;
    }
    if !b[0].is_ascii_alphabetic() {
        return false;
    }
    b[1..]
        .iter()
        .all(|c| c.is_ascii_alphanumeric() || *c == b'_' || *c == b'-')
}

pub trait Plugin: Any + Send + Sync {
    /// 注册键(D2 校验)。
    fn name(&self) -> &str;

    /// **模块名**(0.5.5,「插件界面 = 一模块一菜单」波)。
    ///
    /// 语义分工:
    /// - `name()` = **实例名**,唯一,如 `ctp_278153`(派生网关名);
    /// - `kind()` = **模块名**,同一模块的多个实例必须相同,如 `ctp`。
    ///
    /// 界面层按 `kind()` 归组:**一个模块一个菜单项、一扇窗**,该模块的所有实例交给
    /// 那扇窗自己呈现(表格 / tab / 分栏由模块决定)。缺省 = `name()`,即单实例插件
    /// (dm/oms/…)零改动仍是"自己一类";多实例插件(ctp/tq)覆写成固定模块名。
    ///
    /// ⚠ 纯/静态/无锁(与 [`Self::services`] 同纪律:宿主会在渲染线程上调用)。
    fn kind(&self) -> &str {
        self.name()
    }

    /// **模块窗自描述**(0.5.6,「菜单自动生成」波)。
    ///
    /// 覆写返回 `Some` = "本插件要一扇独立模块窗"。界面层扫描时据此建窗、
    /// 自动挂菜单项 —— 于是新增带界面的插件**不必再改界面层的静态模块表**。
    ///
    /// 缺省 `None` = "无模块窗":存量插件(纯后端件)零改动、零行为变化。
    ///
    /// ⚠ 纯/静态/无锁(与 [`Self::kind`]/[`Self::services`] 同纪律:界面层会在
    /// 渲染线程上、且在插件起停间隙调用)。返回 `always: true` 的模块必须
    /// 也能在**未装配**时被界面层兜住,见 [`WindowDesc::always`] 的说明。
    fn window(&self) -> Option<WindowDesc> {
        None
    }

    /// D1 显式依赖清单(宿主注册期校验存在性,start 期拓扑排序)。
    fn deps(&self) -> &[&str] {
        &[]
    }

    /// 订阅的 type 集合:广播 type(如业务常量 "eTick.")、
    /// 自身的寻址 type(e_req_type(本名)/e_to_type(本名))。
    /// 宿主 start() 装配 forwarder → 邮箱 → on_mail。
    fn routes(&self) -> Vec<Cow<'static, str>> {
        Vec::new()
    }

    /// 邮箱软顶覆写(D5 改案:缺省 [`MAILBOX_SOFT_CAP`],按插件可大可小)。
    ///
    /// 语义是**软顶**(到顶才丢),不是容量(到顶必丢):默认无界不丢。
    /// 给小是为了让某个插件在洪峰下更早显形,不是为了省内存。
    fn mailbox_soft_cap(&self) -> u64 {
        MAILBOX_SOFT_CAP
    }

    /// 插件版本(约定填 crate 版本)。默认空串 = 「未知版本」。
    ///
    /// ⚠ 陷阱(审核 F6):默认实现无法用 `env!(CARGO_PKG_VERSION)`
    /// —— 该宏在 ek-core 定义处展开,填出的是 ek-core 的版本。
    /// 插件侧必须显式覆写:
    /// ```ignore
    /// fn version(&self) -> Cow<'static, str> {
    ///     Cow::Borrowed(env!("CARGO_PKG_VERSION"))
    /// }
    /// ```
    fn version(&self) -> Cow<'static, str> {
        Cow::Borrowed("")
    }

    /// 向下转型口(0.5.2,「插件即 App」波)。
    ///
    /// 宿主侧要按**具体插件类型**挂它自带的界面面(`ui_face::render`)或调它的
    /// 读数口,而 `Arc<dyn Plugin>` 不能直接 downcast —— trait 已含 `Any` 超弦,
    /// 这里补一条口。**默认 `None` = 不支持转型**(老插件零改动零炸);要挂面的
    /// 插件侧覆写成 `Some(self)`。转型口只给宿主挂面用,不是插件间通信口
    /// (插件间只走总线,老纪律不动)。
    fn as_any(&self) -> Option<&dyn std::any::Any> {
        None
    }

    /// 配置托底可选能力(ek-core 0.4.0,BD-CFG):有配置面的插件覆写返回
    /// `Some(self)`;缺省 `None` = 「无配置面」,宿主探查一行事、视而不见
    /// (存量插件零改动零运行时负担)。
    ///
    /// 返回值是**同一对象借出的第二张脸**(`&dyn Configurable`),不是新实例:
    /// 宿主在 add_plugin/start 两处调用,调用期借用、借完即还,宿主只留存
    /// ns 字符串进配置目录。`&'static` 不需要——生命周期就到本借用结束。
    fn as_configurable(&self) -> Option<&dyn crate::section::Configurable> {
        None
    }

    /// 服务目录自报(纯声明):只在 add_plugin 时被宿主读取一次抽 `id` 织入路由索引;
    /// 之后 ctx.services_of/find_service/ask_service 需要明细时由宿主**现场**调用本方法取。
    ///
    /// 铁律(审核 F8):本方法必须纯/静态/无锁/不阻塞 —— 它会在宿主管理线程上被
    /// 与插件 worker 并发调用;违反此纪律后果自负。
    ///
    /// 目录改版铁律(执行期 DV4 发现):插件目录随配置/状态变化时,必须
    /// **先更新本方法返回的内容,再 ctx.publish_services(...) 申报** ——
    /// 宿主现场取,先申报后换内容会造成 live 细节与索引脱节。
    fn services(&self) -> Vec<ServiceDesc> {
        Vec::new()
    }

    /// 可选:启动前纯接线(缓存 ctx、读配置)。禁止在此 put/注册 handler(规范)。
    fn on_init(&self, _ctx: &PluginContext) {}

    /// start() 按依赖拓扑序调用(只一次)。
    fn on_start(&self) {}

    /// close/remove 按逆依赖序调用;调用后保证不再收到邮件。
    fn on_stop(&self) {}

    /// ★ 唯一业务入口:永远在本插件 worker 线程上串行执行。
    /// 广播事件、寻址请求(eReq.<本名>)、定向通知(eTo.<本名>)都从这里进。
    fn on_mail(&self, event: &Event);
}

/// close() 的 join 等待上限(D4:超时告警不死等)。
pub const CLOSE_JOIN_TIMEOUT: Duration = Duration::from_secs(2);