Skip to main content

crate_plugin_kit/
error.rs

1//! 错误类型。
2//!
3//! 刻意**不**把 `anyhow::Error` 用在公开 API 上:这个 crate 会被宿主在靠近
4//! `dlopen` 边界的地方使用,一个可枚举、可匹配的错误类型比类型擦除的 error
5//! 更好排查。内部(`install` 模块)用 anyhow 图省事,出口处再收进来。
6
7use std::path::PathBuf;
8
9/// kit 的错误。
10///
11/// 变体分两类:
12///
13/// - **调用方能处理的**:[`KitError::NotInstalled`] / [`KitError::AlreadyInstalled`] /
14///   [`KitError::PluginInUse`] / [`KitError::CargoNotFound`] —— 调用方通常据此换一条路或提示用户;
15/// - **环境/数据坏了的**:其余。基本只能上报。
16#[derive(Debug, thiserror::Error)]
17pub enum KitError {
18    /// 要卸载/更新的插件没装。
19    #[error("插件 {name} 未安装")]
20    NotInstalled {
21        /// 完整 crate 名。
22        name: String,
23    },
24
25    /// 要安装的插件已经在了。
26    ///
27    /// 这是刻意的:`install` 不覆盖已有的安装,替换请走 `update`。
28    #[error("插件 {name} 的目录已存在:{path}")]
29    AlreadyInstalled {
30        /// 完整 crate 名。
31        name: String,
32        /// 已存在的目录。
33        path: PathBuf,
34    },
35
36    /// 插件的动态库仍在本进程里加载着,删不掉。
37    ///
38    /// Windows 上正在 `dlopen` 的 `.dll` 无法删除;Linux/macOS 上删得掉但空间不回收。
39    /// 与其赌,不如让用户换一个干净的进程。
40    #[error(
41        "插件 {name} 的动态库仍在本进程中加载,无法删除。\
42         请在一个新终端里重试(新进程不会加载它),或退出当前会话后再执行"
43    )]
44    PluginInUse {
45        /// 完整 crate 名。
46        name: String,
47    },
48
49    /// 读 manifest 文件失败。
50    #[error("读 manifest 失败({path}):{source}")]
51    ManifestRead {
52        /// manifest 路径。
53        path: PathBuf,
54        /// 底层 IO 错误。
55        #[source]
56        source: std::io::Error,
57    },
58
59    /// manifest 不是合法 TOML,或字段类型不对。
60    #[error("解析 manifest 失败({path}):{source}")]
61    ManifestParse {
62        /// manifest 路径。
63        path: PathBuf,
64        /// 底层 TOML 错误。
65        #[source]
66        source: Box<toml::de::Error>,
67    },
68
69    /// manifest 里某个必填字段缺失或为空。
70    #[error("manifest 缺少字段 `{field}`({path})")]
71    ManifestMissingField {
72        /// 字段名,例如 `plugin.name`。
73        field: String,
74        /// manifest 路径。
75        path: PathBuf,
76    },
77
78    /// 安装目录里找不到符合命名规则的动态库。
79    #[error("找不到插件 {name} 的动态库。试过:{tried}")]
80    LibraryNotFound {
81        /// 文件名主干。
82        name: String,
83        /// 尝试过的文件名,逗号分隔。
84        tried: String,
85    },
86
87    /// `dlopen` 本身失败(文件损坏、架构不符、缺依赖库)。
88    #[error("加载动态库失败({path}):{source}")]
89    LibraryLoad {
90        /// 动态库路径。
91        path: PathBuf,
92        /// 底层 libloading 错误。
93        #[source]
94        source: Box<libloading::Error>,
95    },
96
97    /// 动态库加载成功,但没有我们找的那个导出符号。
98    ///
99    /// 常见于"装错了东西"—— 比如把一个普通库放进了插件目录。
100    #[error("动态库里没有导出符号 `{symbol}`")]
101    SymbolMissing {
102        /// 缺失的符号名。
103        symbol: String,
104    },
105
106    /// 插件的入口函数返回了空指针。
107    #[error("插件的入口函数返回了空指针")]
108    NullEntry,
109
110    /// 等安装锁超时。
111    #[error("等待文件锁超时({path},等了 {secs} 秒)")]
112    LockTimeout {
113        /// 锁文件路径。
114        path: PathBuf,
115        /// 等待了多少秒。
116        secs: u64,
117    },
118
119    /// 锁文件本身操作失败。
120    #[error("文件锁操作失败({path}):{source}")]
121    LockIo {
122        /// 锁文件路径。
123        path: PathBuf,
124        /// 底层 IO 错误。
125        #[source]
126        source: std::io::Error,
127    },
128
129    /// `PATH` 里没有 `cargo`,build-host 装不了。
130    ///
131    /// 调用方可以据此提示用户"装个 Rust 工具链",或改走 prebuilt。
132    #[error("PATH 里找不到 `cargo`;build-host 安装需要 Rust 工具链")]
133    CargoNotFound,
134
135    /// `cargo build` 失败。stderr 已经透传给用户了(stdio 继承)。
136    #[error("build-host 编译失败(退出码 {code:?})")]
137    BuildFailed {
138        /// 进程退出码。被信号杀掉时为 `None`。
139        code: Option<i32>,
140    },
141
142    /// 编译成功了,但产物里找不到 cdylib。
143    #[error("编译产物里找不到 cdylib(找的是 {stem},目录 {dir})")]
144    BuildArtifactMissing {
145        /// 期望的文件名主干。
146        stem: String,
147        /// 找过的目录。
148        dir: String,
149    },
150
151    /// 网络请求失败。字符串里带 URL 与状态码。
152    #[error("网络请求失败:{0}")]
153    Http(String),
154
155    /// registry 返回了能拿到、但不符合预期的内容。
156    #[error("registry 返回了意外的响应:{0}")]
157    Registry(String),
158
159    /// 跨边界调用时插件 panic 了(宿主侧 `catch_unwind` 捕获)。
160    #[error("插件在 {what} 时 panic(已由 catch_unwind 捕获)")]
161    PluginPanicked {
162        /// 哪个调用点,例如 `"entry()"`。
163        what: String,
164    },
165
166    /// 既没有 HOME 也没有等价的系统目录,数据目录定不下来。
167    #[error("宿主应用的数据目录无法确定(既没有 HOME 也没有系统等价物)")]
168    NoDataDir,
169
170    /// IO 错误。
171    #[error(transparent)]
172    Io(#[from] std::io::Error),
173}
174
175/// 本 crate 的 `Result` 别名。
176pub type KitResult<T> = std::result::Result<T, KitError>;