helix_core/
error.rs

1//! # error.rs
2//!
3//! helix-core 的统一错误类型。
4//!
5//! - `CoreError`：ExecutionShell / ModuleHost 层错误
6//! - `PortError`：所有 port trait 的统一返回错误
7//!   - driver 在 ACL-2 用 thiserror `From<具体 crate 错误>` 翻译到此类型
8//!   - 统一返回 PortError 保证所有 port trait 对象安全（dyn-safe）
9
10use thiserror::Error;
11
12/// core 层（ExecutionShell / ModuleHost）的错误。
13#[derive(Debug, Error)]
14pub enum CoreError {
15    /// 无模块能处理该 Tick（Inbound / Command 路由未命中）
16    #[error("no module accepted tick: {0}")]
17    NoHandler(&'static str),
18
19    /// corr_map 中找不到该 Correlation（PortReply 到达时 corr 已过期或从未注册）
20    #[error("unknown correlation {0}")]
21    UnknownCorrelation(u64),
22
23    /// 某模块的 handle / on_start / on_stop 返回错误
24    #[error("module '{module}' error: {source}")]
25    ModuleError {
26        module: &'static str,
27        #[source]
28        source: Box<dyn std::error::Error + Send + Sync + 'static>,
29    },
30}
31
32/// 所有 port trait 的统一返回错误类型。
33///
34/// ## driver 实现约定（ACL-2）
35///
36/// 各 helix-driver-* 的具体 crate 错误（sqlx::Error / reqwest::Error / 等）
37/// 必须用 thiserror `From` 翻译到此类型，不得让具体 crate 类型穿透 port 边界。
38///
39/// ```rust,no_run
40/// // 示例：helix-driver-native/src/storage.rs（需在该 crate 中编译，helix-core 不依赖 sqlx）
41/// # mod example {
42/// # use helix_core::PortError;
43/// // impl From<sqlx::Error> for PortError {
44/// //     fn from(e: sqlx::Error) -> Self {
45/// //         PortError::Storage(e.to_string())
46/// //     }
47/// // }
48/// # }
49/// ```
50#[derive(Debug, Error)]
51pub enum PortError {
52    /// An optimistic write lost a race; its transaction rolled back and the store remains usable.
53    #[error("storage conflict")]
54    StorageConflict,
55
56    #[error("storage error: {0}")]
57    Storage(String),
58
59    #[error("transport error: {0}")]
60    Transport(String),
61
62    #[error("http error: {0}")]
63    Http(String),
64
65    #[error("clock error: {0}")]
66    Clock(String),
67
68    #[error("id source error: {0}")]
69    IdSource(String),
70
71    /// 通用端口错误（用于 driver 无法分类的情况）
72    #[error("port error: {0}")]
73    Other(String),
74}
helix_core/error.rs

helix_core/
error.rs
