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>;