wordval-core 1.0.8

Wordval framework core: app lifecycle, plugin system, error handling, unified response types
Documentation
//! 插件生命周期状态机
//!
//! 设计原则:**显式状态 + 显式触发器 + 穷举转移表**。
//! 任何非法转移返回错误而不是静默改写状态,杜绝「任意状态可跳到任意状态」的隐式约定。
//!
//! 状态流转总览(合法路径):
//!
//! ```text
//! Stopped ──Start──▶ Starting ──StartOk──▶ Running ──Stop──▶ Stopped
//!                      │                     │  ▲            │
//!                      │                Degrade  Resume     │
//!                      │                     ▼  │            │
//!                      │               Degrading Degraded  │
//!                      │                     │    │        │
//!                      │              DegradeOk   Resume   │
//!                      │                     ▼    ▼        │
//!                      │                 Degraded Running  │
//!                      │                                    │
//!                      └──StartFailed──▶ Faulted ◀──Fault───┘
//!                                        │       ▲
//!                                     Reset    Fault(幂等)
//!                                        ▼       │
//!                                     Stopped  Faulted
//! ```

use std::fmt;

/// 插件生命周期状态
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PluginState {
    /// 已注册未启动(初始态)
    Stopped,
    /// 启动中(`start` 钩子执行中)
    Starting,
    /// 运行中(完整服务能力)
    Running,
    /// 降级中(`on_degrade` 钩子执行中)
    Degrading,
    /// 已降级(存活但功能受限,可恢复)
    Degraded,
    /// 恢复中(`on_resume` 钩子执行中)
    Resuming,
    /// 已故障(不可用;`reset` 后可回到 Stopped 重新启动)
    Faulted,
}

/// 驱动状态转移的触发器(生命周期操作或其结果)
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PluginTrigger {
    /// 请求启动
    Start,
    /// 启动成功
    StartOk,
    /// 启动失败
    StartFailed,
    /// 请求停止
    Stop,
    /// 请求降级
    Degrade,
    /// 降级完成
    DegradeOk,
    /// 请求恢复
    Resume,
    /// 恢复完成
    ResumeOk,
    /// 故障转移(任何存活状态均可触发;对 Faulted 幂等)
    Fault,
    /// 故障重置(Faulted → Stopped,允许重新启动)
    Reset,
}

impl PluginState {
    /// 应用触发器,返回新状态
    ///
    /// 合法转移以穷举 `match` 定义(新增状态/触发器时漏配会编译期报错);
    /// 非法组合返回 `Err`,调用方不应静默吞掉——那是状态机设计失效的信号。
    pub fn transition(self, trigger: PluginTrigger) -> Result<Self, String> {
        use PluginState as S;
        use PluginTrigger as T;
        match (self, trigger) {
            // 启动路径
            (S::Stopped, T::Start) => Ok(S::Starting),
            (S::Starting, T::StartOk) => Ok(S::Running),
            (S::Starting, T::StartFailed | T::Fault) => Ok(S::Faulted),
            // 运行路径
            (S::Running, T::Stop) => Ok(S::Stopped),
            (S::Running, T::Degrade) => Ok(S::Degrading),
            // 降级 / 恢复路径
            (S::Degrading, T::DegradeOk) => Ok(S::Degraded),
            (S::Degraded, T::Resume) => Ok(S::Resuming),
            (S::Resuming, T::ResumeOk) => Ok(S::Running),
            // 停机兜底:Running / Degraded / Faulted / 未启动的 Stopped 均可关闭
            // (停机必须始终能清理,即使插件处于异常状态)
            (S::Stopped, T::Stop) => Ok(S::Stopped),
            (S::Degraded, T::Stop) => Ok(S::Stopped),
            (S::Faulted, T::Stop) => Ok(S::Stopped),
            // 故障路径:任何存活状态可 Fault;Faulted 幂等
            (S::Running, T::Fault) => Ok(S::Faulted),
            (S::Degrading, T::Fault) => Ok(S::Faulted),
            (S::Degraded, T::Fault) => Ok(S::Faulted),
            (S::Resuming, T::Fault) => Ok(S::Faulted),
            (S::Faulted, T::Fault) => Ok(S::Faulted),
            // 故障重置:回到初始态允许重启
            (S::Faulted, T::Reset) => Ok(S::Stopped),
            (state, trigger) => Err(format!("非法状态转移: {state:?} + {trigger:?}")),
        }
    }

    /// 是否正在完整服务
    pub fn is_running(self) -> bool {
        matches!(self, Self::Running)
    }

    /// 是否可用(运行或降级——降级仍提供受限服务)
    pub fn is_available(self) -> bool {
        matches!(self, Self::Running | Self::Degraded)
    }
}

impl fmt::Display for PluginState {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{self:?}")
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn legal_happy_path_transitions() {
        use PluginTrigger as T;
        use PluginState as S;
        // 完整生命周期:启动 → 降级 → 恢复 → 停止
        assert_eq!(S::Stopped.transition(T::Start), Ok(S::Starting));
        assert_eq!(S::Starting.transition(T::StartOk), Ok(S::Running));
        assert_eq!(S::Running.transition(T::Degrade), Ok(S::Degrading));
        assert_eq!(S::Degrading.transition(T::DegradeOk), Ok(S::Degraded));
        assert_eq!(S::Degraded.transition(T::Resume), Ok(S::Resuming));
        assert_eq!(S::Resuming.transition(T::ResumeOk), Ok(S::Running));
        assert_eq!(S::Running.transition(T::Stop), Ok(S::Stopped));
    }

    #[test]
    fn start_failure_goes_to_faulted() {
        use PluginTrigger as T;
        use PluginState as S;
        assert_eq!(
            S::Starting.transition(T::StartFailed),
            Ok(S::Faulted),
            "启动失败必须进入 Faulted 而不是静默回 Stopped"
        );
        // 故障后重置 → 可重新启动
        assert_eq!(S::Faulted.transition(T::Reset), Ok(S::Stopped));
    }

    #[test]
    fn fault_is_reachable_from_any_live_state_and_idempotent() {
        use PluginTrigger as T;
        use PluginState as S;
        for live in [S::Starting, S::Running, S::Degrading, S::Degraded, S::Resuming] {
            assert_eq!(live.transition(T::Fault), Ok(S::Faulted), "{live:?} 应可故障转移");
        }
        assert_eq!(S::Faulted.transition(T::Fault), Ok(S::Faulted), "Fault 幂等");
        // Stopped 不可故障转移(未启动无可清理)
        assert!(S::Stopped.transition(T::Fault).is_err());
    }

    #[test]
    fn stop_is_always_allowed_for_shutdown() {
        use PluginTrigger as T;
        use PluginState as S;
        // 停机兜底:Stopped(未启动,幂等)/ Degraded / Faulted 均可关闭
        assert_eq!(S::Stopped.transition(T::Stop), Ok(S::Stopped));
        assert_eq!(S::Degraded.transition(T::Stop), Ok(S::Stopped));
        assert_eq!(S::Faulted.transition(T::Stop), Ok(S::Stopped));
    }

    #[test]
    fn illegal_transitions_rejected() {
        use PluginTrigger as T;
        use PluginState as S;
        // 运行中不能重复启动、降级态不能直接降级、停止态不能恢复
        assert!(S::Running.transition(T::Start).is_err());
        assert!(S::Running.transition(T::StartOk).is_err());
        assert!(S::Degraded.transition(T::Degrade).is_err());
        assert!(S::Stopped.transition(T::Resume).is_err());
        assert!(S::Stopped.transition(T::Reset).is_err());
        assert!(S::Faulted.transition(T::Start).is_err(), "Faulted 必须先 Reset");
        assert!(S::Faulted.transition(T::Resume).is_err());
        // 瞬态状态不可直接停止(正在执行钩子中,并发操作由管理器门禁拒绝)
        assert!(S::Starting.transition(T::Stop).is_err());
        assert!(S::Degrading.transition(T::Stop).is_err());
        assert!(S::Resuming.transition(T::Stop).is_err());
    }

    #[test]
    fn availability_predicates() {
        use PluginState as S;
        assert!(S::Running.is_running());
        assert!(!S::Degraded.is_running());
        assert!(S::Degraded.is_available(), "降级仍提供受限服务");
        assert!(S::Running.is_available());
        assert!(!S::Faulted.is_available());
        assert!(!S::Stopped.is_available());
    }
}