Skip to main content

crate_plugin_kit/
store.rs

1//! [`CratePluginKit`]:本 crate 的门面。
2//!
3//! # 泛型参数 `T`
4//!
5//! `T` 是**宿主自己的 `#[repr(C)]` 入口结构体**。本 crate 不使用它的任何字段 ——
6//! 它只出现在 [`CratePluginKit::load`] 的返回类型里,用来把 `dlopen` 出来的符号
7//! 转成一个**瘦指针** `*const T`。
8//!
9//! 这样就没有"类型擦除 → 还原"那一层:不存在两个 vtable 之间的 `fat pointer` 互转,
10//! 也就没有那类 UB。
11//!
12//! # 线程安全
13//!
14//! [`CratePluginKit`] 内部有一个 `RefCell` 记录"本进程加载过哪些插件"(用于
15//! [`CratePluginKit::uninstall`] 拒绝删除正在使用的库)。因此它**不是 `Sync`** ——
16//! 一个进程里建一个、串行用即可(CLI 就是这种用法)。需要并发的话,把 kit 放在
17//! 各线程自己的作用域里。
18
19use std::cell::RefCell;
20use std::collections::BTreeSet;
21use std::marker::PhantomData;
22use std::path::{Path, PathBuf};
23
24use crate::cache::{now_unix, Index, IndexEntry, InstallSource};
25use crate::config::{KitConfig, KitPaths};
26use crate::error::{KitError, KitResult};
27use crate::install::{self, build_host, prebuilt, Installed};
28use crate::loader::{self, LoadedPlugin};
29use crate::lock::FileLock;
30use crate::manifest::PluginManifest;
31use crate::registry::{CrateInfo, CrateSummary, Registry};
32
33/// 一个已安装插件的概览。
34#[derive(Debug, Clone)]
35pub struct PluginInfo {
36    /// 插件自报名(manifest 的 `plugin.name`)。
37    pub name: String,
38    /// 完整 crate 名,如 `bmux-plugin-cargo`。
39    pub crate_name: String,
40    /// 版本。
41    pub version: String,
42    /// 生态分组(宿主自用字段,可能为空)。
43    pub family: Option<String>,
44    /// ABI 版本(宿主自用字段,可能为空)。
45    pub abi: Option<u32>,
46    /// 安装目录。
47    pub dir: PathBuf,
48    /// 怎么装进来的。
49    pub source: InstallSource,
50}
51
52/// 通用插件管理库。
53///
54/// 建一个、串行用。
55pub struct CratePluginKit<T> {
56    cfg: KitConfig,
57    paths: KitPaths,
58    registry: Registry,
59    /// 本进程已经 `dlopen` 过的 crate 名。`uninstall` 拿它挡"删正在用的库"。
60    loaded: RefCell<BTreeSet<String>>,
61    /// `fn() -> T` 而不是 `T`:不假装拥有 `T`,也不要求 `T: Send/Sync`。
62    _host: PhantomData<fn() -> T>,
63}
64
65impl<T> CratePluginKit<T> {
66    /// 按配置建一个 kit 实例。会创建数据目录。
67    pub fn new(cfg: KitConfig) -> KitResult<Self> {
68        let paths = cfg.paths()?;
69        std::fs::create_dir_all(&paths.plugins)?;
70        std::fs::create_dir_all(&paths.build)?;
71
72        let registry = Registry::new(&cfg);
73
74        Ok(Self {
75            cfg,
76            paths,
77            registry,
78            loaded: RefCell::new(BTreeSet::new()),
79            _host: PhantomData,
80        })
81    }
82
83    /// 配置。
84    pub fn config(&self) -> &KitConfig {
85        &self.cfg
86    }
87
88    /// 各项路径。
89    pub fn paths(&self) -> &KitPaths {
90        &self.paths
91    }
92
93    /// registry 客户端。
94    pub fn registry(&self) -> &Registry {
95        &self.registry
96    }
97
98    // ---- 安装 / 卸载 ------------------------------------------------------
99
100    /// 安装一个插件。
101    ///
102    /// `name` 可以写短名(`"cargo"`,会自动补 [`KitConfig::crate_prefix`]),
103    /// 也可以写完整 crate 名。`version` 给 `None` 就去 crates.io 查最新版。
104    ///
105    /// # Errors
106    ///
107    /// - [`KitError::AlreadyInstalled`]:已经装过了。用 [`Self::update`] 替换。
108    pub fn install(&self, name: &str, version: Option<&str>) -> KitResult<Installed> {
109        let crate_name = self.cfg.normalize_crate_name(name);
110
111        let _lock = self.lock()?;
112
113        let dir = self.paths.plugin_dir(&crate_name);
114        if dir.is_dir() {
115            return Err(KitError::AlreadyInstalled {
116                name: crate_name,
117                path: dir,
118            });
119        }
120
121        let version = self.resolve_version(&crate_name, version)?;
122        let installed = self.install_locked(&crate_name, &version)?;
123        self.record(&installed)?;
124        Ok(installed)
125    }
126
127    /// 更新(或重装)一个插件。已存在就替换,不存在就当安装。
128    pub fn update(&self, name: &str, version: Option<&str>) -> KitResult<Installed> {
129        let crate_name = self.cfg.normalize_crate_name(name);
130
131        let _lock = self.lock()?;
132
133        let version = self.resolve_version(&crate_name, version)?;
134        let installed = self.install_locked(&crate_name, &version)?;
135        self.record(&installed)?;
136        Ok(installed)
137    }
138
139    /// 卸载一个插件。
140    ///
141    /// # Errors
142    ///
143    /// - [`KitError::NotInstalled`]:本来就没装。
144    /// - [`KitError::PluginPanicked`] 之外的一个"正在使用"错误:本进程加载过它的库。
145    ///   Windows 上正在 `dlopen` 的 `.dll` 删不掉;Linux 上删得掉但空间不回收。
146    ///   与其赌,不如让用户换一个干净的进程。
147    pub fn uninstall(&self, name: &str) -> KitResult<()> {
148        let crate_name = self.cfg.normalize_crate_name(name);
149
150        let _lock = self.lock()?;
151
152        let dir = self.paths.plugin_dir(&crate_name);
153        if !dir.is_dir() {
154            return Err(KitError::NotInstalled { name: crate_name });
155        }
156
157        if self.loaded.borrow().contains(&crate_name) {
158            return Err(KitError::PluginInUse {
159                name: crate_name.clone(),
160            });
161        }
162
163        std::fs::remove_dir_all(&dir)?;
164
165        let mut idx = Index::load(&self.paths.index_file);
166        idx.remove(&crate_name);
167        idx.save(&self.paths.index_file)?;
168
169        Ok(())
170    }
171
172    // ---- 查询 ------------------------------------------------------------
173
174    /// 列出已安装的插件。
175    ///
176    /// **以磁盘上的 manifest 为准**,`.plugins.json` 只用来补充"来源 / 安装时间"
177    /// 这类 manifest 里没有的信息。所以缓存丢了也不会漏插件。
178    pub fn list(&self) -> KitResult<Vec<PluginInfo>> {
179        let idx = Index::load(&self.paths.index_file);
180        let mut out = Vec::new();
181
182        let entries = match std::fs::read_dir(&self.paths.plugins) {
183            Ok(e) => e,
184            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(out),
185            Err(e) => return Err(e.into()),
186        };
187
188        for entry in entries {
189            let entry = entry?;
190            if !entry.file_type()?.is_dir() {
191                continue;
192            }
193            let crate_name = entry.file_name().to_string_lossy().into_owned();
194
195            // 目录在但 manifest 没了/坏了 —— 跳过,不要因为一个坏插件让整个 list 失败
196            let manifest_path = entry.path().join(&self.cfg.manifest_name);
197            let Ok(manifest) = PluginManifest::read(&manifest_path) else {
198                continue;
199            };
200
201            let source = idx.get(&crate_name).map(|e| e.source).unwrap_or_default();
202
203            out.push(PluginInfo {
204                name: manifest.plugin.name.clone(),
205                crate_name,
206                version: manifest.plugin.version.clone(),
207                family: manifest.plugin.family.clone(),
208                abi: manifest.plugin.abi,
209                dir: entry.path(),
210                source,
211            });
212        }
213
214        out.sort_by(|a, b| a.crate_name.cmp(&b.crate_name));
215        Ok(out)
216    }
217
218    /// 读某个插件的 manifest。
219    pub fn manifest_of(&self, name: &str) -> KitResult<PluginManifest> {
220        let crate_name = self.cfg.normalize_crate_name(name);
221        let path = self
222            .paths
223            .manifest_path(&crate_name, &self.cfg.manifest_name);
224        PluginManifest::read(&path)
225    }
226
227    /// 把 `name` 下的相对路径解析成绝对路径。
228    pub fn resolve(&self, name: &str, relative: impl AsRef<Path>) -> PathBuf {
229        let crate_name = self.cfg.normalize_crate_name(name);
230        self.paths.plugin_dir(&crate_name).join(relative)
231    }
232
233    // ---- 加载 ------------------------------------------------------------
234
235    /// 加载插件,拿到 `*const T`。
236    ///
237    /// 加载过之后 [`Self::uninstall`] 会拒绝删除它,直到进程退出。
238    pub fn load(&self, name: &str) -> KitResult<LoadedPlugin<T>> {
239        let crate_name = self.cfg.normalize_crate_name(name);
240
241        let manifest = self.manifest_of(&crate_name)?;
242        let dir = self.paths.plugin_dir(&crate_name);
243        let stem = manifest.effective_lib_stem(&self.cfg, &crate_name);
244        let lib_path = loader::find_library(&dir, &stem)?;
245
246        // SAFETY: `lib_path` 是本 kit 装出来的;`T` 与它导出的结构体布局是否一致
247        // 由宿主的 abi_version 字段兜底 —— 那是宿主契约 crate 的职责,不是本 crate 的。
248        let plugin = unsafe { loader::open::<T>(&lib_path, &self.cfg.entry_symbol)? };
249
250        self.loaded.borrow_mut().insert(crate_name);
251        Ok(plugin)
252    }
253
254    // ---- registry --------------------------------------------------------
255
256    /// 搜 crate。
257    pub fn search(&self, keyword: &str, limit: usize) -> KitResult<Vec<CrateSummary>> {
258        self.registry.search(keyword, limit)
259    }
260
261    /// 按精确名查 crate。
262    pub fn view(&self, name: &str) -> KitResult<Option<CrateInfo>> {
263        let crate_name = self.cfg.normalize_crate_name(name);
264        self.registry.view(&crate_name)
265    }
266
267    // ---- 内部 ------------------------------------------------------------
268
269    fn lock(&self) -> KitResult<FileLock> {
270        FileLock::acquire(&self.paths.lock_file, self.cfg.lock_timeout)
271    }
272
273    /// 没给版本就查最新版。
274    fn resolve_version(&self, crate_name: &str, version: Option<&str>) -> KitResult<String> {
275        if let Some(v) = version {
276            return Ok(v.to_string());
277        }
278        match self.registry.view(crate_name)? {
279            Some(info) if !info.version.is_empty() => Ok(info.version),
280            Some(_) => Err(KitError::Registry(format!(
281                "{crate_name} 在 registry 上没有可用版本"
282            ))),
283            None => Err(KitError::Registry(format!(
284                "registry 上找不到 {crate_name}"
285            ))),
286        }
287    }
288
289    /// 真正的安装动作。调用方必须已经持锁。
290    fn install_locked(&self, crate_name: &str, version: &str) -> KitResult<Installed> {
291        // 先把旧目录清掉(update 路径)
292        install::remove_dir_if_exists(&self.paths.plugin_dir(crate_name))?;
293
294        if self.cfg.prefer_prebuilt {
295            match prebuilt::try_install(&self.cfg, &self.paths, &self.registry, crate_name, version)
296            {
297                Ok(Some(installed)) => return Ok(installed),
298                // 没有 prebuilt 资产 —— 这正是回落 build-host 的信号
299                Ok(None) => {}
300                // 网络坏 / 资产损坏:也回落。build-host 走的是 cargo,
301                // 跟 GitHub 是两条路,很可能反而能通。
302                Err(_) => {}
303            }
304        }
305
306        build_host::install(&self.cfg, &self.paths, crate_name, version)
307    }
308
309    fn record(&self, installed: &Installed) -> KitResult<()> {
310        let mut idx = Index::load(&self.paths.index_file);
311
312        let abi = PluginManifest::read(
313            &self
314                .paths
315                .manifest_path(&installed.crate_name, &self.cfg.manifest_name),
316        )
317        .ok()
318        .and_then(|m| m.plugin.abi);
319
320        idx.insert(
321            &installed.crate_name,
322            IndexEntry {
323                version: installed.version.clone(),
324                abi,
325                root: installed.dir.clone(),
326                source: installed.source,
327                installed_at: now_unix(),
328            },
329        );
330        idx.save(&self.paths.index_file)
331    }
332}
333
334#[cfg(test)]
335mod tests {
336    use super::*;
337    use std::time::Duration;
338
339    /// 测试用的宿主 ABI 结构体。
340    ///
341    /// 内容是任意的 —— 这个 crate 从不读 `T` 的字段,它只把符号 cast 成 `*const T`。
342    #[repr(C)]
343    struct FakeEntry {
344        abi_version: u32,
345    }
346
347    const MANIFEST: &str = r#"
348[plugin]
349name    = "foo"
350version = "0.1.0"
351abi     = 1
352family  = "node"
353
354[detect]
355strong = ["fake.lock"]
356"#;
357
358    fn kit(root: &Path) -> CratePluginKit<FakeEntry> {
359        let cfg = KitConfig::new("myapp")
360            .with_data_dir(root)
361            .with_lock_timeout(Duration::from_millis(500));
362        CratePluginKit::new(cfg).expect("应当能建起来")
363    }
364
365    /// 手工放一个"已安装"的插件目录,省掉编译步骤。
366    fn place_plugin(root: &Path, crate_name: &str) -> PathBuf {
367        let dir = root.join("plugins").join(crate_name);
368        std::fs::create_dir_all(&dir).unwrap();
369        std::fs::write(dir.join("myapp-plugin.toml"), MANIFEST).unwrap();
370        dir
371    }
372
373    #[test]
374    fn new_creates_the_data_directories() {
375        let tmp = tempfile::tempdir().unwrap();
376        let root = tmp.path().join("store");
377
378        let k = kit(&root);
379        assert!(k.paths().plugins.is_dir(), "plugins 目录应当被建出来");
380        assert!(k.paths().build.is_dir(), "build 目录应当被建出来");
381    }
382
383    #[test]
384    fn a_fresh_store_lists_nothing() {
385        let tmp = tempfile::tempdir().unwrap();
386        let k = kit(&tmp.path().join("store"));
387        assert!(k.list().unwrap().is_empty());
388    }
389
390    /// 目录根本不存在时,`list` 也该给空列表而不是报错。
391    #[test]
392    fn list_tolerates_a_missing_plugins_directory() {
393        let tmp = tempfile::tempdir().unwrap();
394        let root = tmp.path().join("store");
395        let k = kit(&root);
396
397        std::fs::remove_dir_all(&root).unwrap();
398        assert!(k.list().unwrap().is_empty());
399    }
400
401    /// **关键行为**:磁盘上的 manifest 才是事实来源,不是 `.plugins.json`。
402    /// 手工放进去的插件(缓存里没有记录)也必须被列出来。
403    #[test]
404    fn list_reads_manifests_from_disk_not_the_cache() {
405        let tmp = tempfile::tempdir().unwrap();
406        let root = tmp.path().join("store");
407        let k = kit(&root);
408
409        place_plugin(&root, "myapp-plugin-foo");
410
411        let all = k.list().unwrap();
412        assert_eq!(all.len(), 1, "缓存是空的,但磁盘上有插件");
413        let info = &all[0];
414        assert_eq!(info.name, "foo");
415        assert_eq!(info.crate_name, "myapp-plugin-foo");
416        assert_eq!(info.version, "0.1.0");
417        assert_eq!(info.abi, Some(1));
418        assert_eq!(info.family.as_deref(), Some("node"));
419        // 缓存里没有记录 → 落到默认来源
420        assert_eq!(info.source, InstallSource::BuildHost);
421    }
422
423    /// 坏掉的 manifest 不该让整个 `list()` 失败 —— 跳过它就好。
424    #[test]
425    fn list_skips_a_directory_with_a_broken_manifest() {
426        let tmp = tempfile::tempdir().unwrap();
427        let root = tmp.path().join("store");
428        let k = kit(&root);
429
430        place_plugin(&root, "myapp-plugin-good");
431        let bad = root.join("plugins").join("myapp-plugin-bad");
432        std::fs::create_dir_all(&bad).unwrap();
433        std::fs::write(bad.join("myapp-plugin.toml"), "this is not toml").unwrap();
434
435        // 连 manifest 都没有的目录
436        let empty = root.join("plugins").join("myapp-plugin-empty");
437        std::fs::create_dir_all(&empty).unwrap();
438
439        let all = k.list().unwrap();
440        assert_eq!(all.len(), 1, "只应当列出好的那个:{all:?}");
441        assert_eq!(all[0].crate_name, "myapp-plugin-good");
442    }
443
444    #[test]
445    fn list_is_sorted_by_crate_name() {
446        let tmp = tempfile::tempdir().unwrap();
447        let root = tmp.path().join("store");
448        let k = kit(&root);
449
450        for name in ["myapp-plugin-c", "myapp-plugin-a", "myapp-plugin-b"] {
451            place_plugin(&root, name);
452        }
453
454        let names: Vec<_> = k
455            .list()
456            .unwrap()
457            .into_iter()
458            .map(|i| i.crate_name)
459            .collect();
460        assert_eq!(
461            names,
462            vec!["myapp-plugin-a", "myapp-plugin-b", "myapp-plugin-c"]
463        );
464    }
465
466    #[test]
467    fn manifest_of_reads_the_plugin() {
468        let tmp = tempfile::tempdir().unwrap();
469        let root = tmp.path().join("store");
470        let k = kit(&root);
471        place_plugin(&root, "myapp-plugin-foo");
472
473        let m = k.manifest_of("foo").expect("短名应当也能用");
474        assert_eq!(m.plugin.name, "foo");
475        assert!(m.extra.contains_key("detect"), "宿主的段要保留");
476    }
477
478    #[test]
479    fn manifest_of_reports_a_missing_plugin() {
480        let tmp = tempfile::tempdir().unwrap();
481        let k = kit(&tmp.path().join("store"));
482        assert!(matches!(
483            k.manifest_of("nope"),
484            Err(KitError::ManifestRead { .. })
485        ));
486    }
487
488    #[test]
489    fn uninstall_reports_a_plugin_that_is_not_installed() {
490        let tmp = tempfile::tempdir().unwrap();
491        let k = kit(&tmp.path().join("store"));
492
493        assert!(matches!(
494            k.uninstall("nope"),
495            Err(KitError::NotInstalled { .. })
496        ));
497    }
498
499    #[test]
500    fn uninstall_removes_the_directory() {
501        let tmp = tempfile::tempdir().unwrap();
502        let root = tmp.path().join("store");
503        let k = kit(&root);
504        let dir = place_plugin(&root, "myapp-plugin-foo");
505
506        assert!(dir.is_dir());
507        k.uninstall("foo").expect("应当能卸掉");
508        assert!(!dir.exists(), "目录应当被删掉");
509        assert!(k.list().unwrap().is_empty());
510    }
511
512    /// `install` 不覆盖已有安装 —— 替换走 `update`。
513    ///
514    /// 这个检查发生在取锁之后、任何网络/编译之前,所以测试不需要联网。
515    #[test]
516    fn install_refuses_when_already_installed() {
517        let tmp = tempfile::tempdir().unwrap();
518        let root = tmp.path().join("store");
519        let k = kit(&root);
520        place_plugin(&root, "myapp-plugin-foo");
521
522        match k.install("foo", Some("0.1.0")) {
523            Err(KitError::AlreadyInstalled { name, .. }) => {
524                assert_eq!(name, "myapp-plugin-foo")
525            }
526            other => panic!("期望 AlreadyInstalled,得到 {other:?}"),
527        }
528    }
529
530    #[test]
531    fn resolve_points_into_the_plugin_directory() {
532        let tmp = tempfile::tempdir().unwrap();
533        let root = tmp.path().join("store");
534        let k = kit(&root);
535
536        assert_eq!(
537            k.resolve("foo", "extra.txt"),
538            root.join("plugins")
539                .join("myapp-plugin-foo")
540                .join("extra.txt")
541        );
542        // 短名与全名要落到同一个地方
543        assert_eq!(k.resolve("foo", "x"), k.resolve("myapp-plugin-foo", "x"));
544    }
545
546    #[test]
547    fn config_is_exposed() {
548        let tmp = tempfile::tempdir().unwrap();
549        let k = kit(&tmp.path().join("store"));
550        assert_eq!(k.config().id, "myapp");
551        assert_eq!(k.config().crate_prefix, "myapp-plugin-");
552    }
553}