1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
//! Installing, updating and uninstalling a plugin.
//!
//! These are the only calls that take the install lock and touch the install directory:
//! `install` refuses a crate that is already present, `update` replaces it either way,
//! and `uninstall` deletes it — but not while this process has its library loaded, since
//! a `dlopen`ed library cannot always be removed.
use std::path::Path;
use crate::cache::{Index, InstallSource};
use crate::error::{KitError, KitResult};
use crate::install::{self, build_host, prebuilt, Installed};
use crate::manifest::PluginManifest;
use super::CratePluginKit;
impl<T> CratePluginKit<T> {
/// Installs a plugin.
///
/// `name` may be a short name (`"cargo"`, to which [`crate::KitConfig::crate_prefix`]
/// is prepended) or a full crate name. With `version` set to `None`, the latest
/// version is looked up on crates.io.
///
/// # Errors
///
/// - [`KitError::AlreadyInstalled`]: it is already installed. Use [`Self::update`]
/// to replace it.
pub fn install(&self, name: &str, version: Option<&str>) -> KitResult<Installed> {
let crate_name = self.cfg.normalize_crate_name(name);
let _lock = self.lock()?;
let dir = self.paths.plugin_dir(&crate_name);
if dir.is_dir() {
return Err(KitError::AlreadyInstalled {
name: crate_name,
path: dir,
});
}
let version = self.resolve_version(&crate_name, version)?;
let installed = self.install_locked(&crate_name, &version)?;
self.record(&installed)?;
Ok(installed)
}
/// Installs a plugin from a checkout on this machine.
///
/// The checkout is an ordinary plugin crate: a plain rlib with its manifest beside its
/// `Cargo.toml`. It is built exactly the way a published one is — through the same
/// generated wrapper, landing the same two files — so nothing downstream (loading,
/// listing, uninstalling) can tell the two apart. What differs is only where the source
/// comes from.
///
/// This is the development loop: build and install what you are working on without
/// publishing it first. [`Self::update`] on such a plugin rebuilds from the same
/// directory, and the prebuilt download is skipped (there is no release to download).
///
/// # Errors
///
/// - [`KitError::NoManifest`]: the directory has no `Cargo.toml`.
/// - [`KitError::ManifestRead`]: it has no readable `<id>-plugin.toml` beside it.
/// - [`KitError::AlreadyInstalled`]: that plugin is already installed. Use
/// [`Self::update`] to replace it.
pub fn install_from_path(&self, plugin_dir: impl AsRef<Path>) -> KitResult<Installed> {
let dir = plugin_dir.as_ref().canonicalize()?;
let _lock = self.lock()?;
// Checked before the build rather than after it: a checkout that cannot be installed
// should say so in a second, not after a `cargo build`.
if !dir.join("Cargo.toml").is_file() {
return Err(KitError::NoManifest { dir });
}
let manifest = PluginManifest::read(&dir.join(&self.cfg.manifest_name))?;
let crate_name = self.cfg.normalize_crate_name(&manifest.plugin.name);
let dir_installed = self.paths.plugin_dir(&crate_name);
if dir_installed.is_dir() {
return Err(KitError::AlreadyInstalled {
name: crate_name,
path: dir_installed,
});
}
let installed = build_host::install_from_path(
self.config(),
self.paths(),
&crate_name,
&manifest.plugin.version,
&dir,
)?;
self.record(&installed)?;
Ok(installed)
}
/// Updates (or reinstalls) a plugin. Replaces it if present, installs it if not.
///
/// A plugin that was installed from a checkout is rebuilt from that checkout: the
/// registry has nothing to say about a version that was never published, and rebuilding
/// the directory is what updating it means.
pub fn update(&self, name: &str, version: Option<&str>) -> KitResult<Installed> {
let crate_name = self.cfg.normalize_crate_name(name);
let _lock = self.lock()?;
// The recorded source decides, not the argument: a `version` has no meaning for a
// checkout.
let recorded = Index::load(&self.paths.index_file)
.get(&crate_name)
.map(|entry| entry.source.clone());
if let Some(InstallSource::Local { path }) = recorded {
let manifest = PluginManifest::read(&path.join(&self.cfg.manifest_name))?;
let installed = build_host::install_from_path(
self.config(),
self.paths(),
&crate_name,
&manifest.plugin.version,
&path,
)?;
self.record(&installed)?;
return Ok(installed);
}
let version = self.resolve_version(&crate_name, version)?;
let installed = self.install_locked(&crate_name, &version)?;
self.record(&installed)?;
Ok(installed)
}
/// Uninstalls a plugin.
///
/// # Errors
///
/// - [`KitError::NotInstalled`]: it was not installed in the first place.
/// - [`KitError::PluginInUse`]: this process has loaded its library. A `.dll`
/// that is currently `dlopen`ed cannot be deleted on Windows; on Linux the
/// removal succeeds but the disk space is not reclaimed. Rather than gamble on
/// it, ask the user to retry from a clean process.
pub fn uninstall(&self, name: &str) -> KitResult<()> {
let crate_name = self.cfg.normalize_crate_name(name);
let _lock = self.lock()?;
let dir = self.paths.plugin_dir(&crate_name);
if !dir.is_dir() {
return Err(KitError::NotInstalled { name: crate_name });
}
if self.loaded.borrow().contains(&crate_name) {
return Err(KitError::PluginInUse {
name: crate_name.clone(),
});
}
std::fs::remove_dir_all(&dir)?;
let mut idx = Index::load(&self.paths.index_file);
idx.remove(&crate_name);
idx.save(&self.paths.index_file)?;
Ok(())
}
/// The actual install. The caller must already hold the lock.
fn install_locked(&self, crate_name: &str, version: &str) -> KitResult<Installed> {
// Clear the old directory first (the update path)
install::remove_dir_if_exists(&self.paths.plugin_dir(crate_name))?;
if self.cfg.prefer_prebuilt {
match prebuilt::try_install(
self.config(),
self.paths(),
self.registry(),
crate_name,
version,
) {
Ok(Some(installed)) => return Ok(installed),
// No prebuilt asset — this is exactly the signal to fall back to
// build-host
Ok(None) => {}
// Broken network or a corrupt asset: fall back as well. build-host
// goes through cargo, which is a different route from GitHub and may
// well work.
Err(_) => {}
}
}
build_host::install(self.config(), self.paths(), crate_name, version)
}
}
#[cfg(test)]
mod tests {
use super::super::tests::{kit, place_plugin};
use super::*;
#[test]
fn uninstall_reports_a_plugin_that_is_not_installed() {
let tmp = tempfile::tempdir().unwrap();
let k = kit(&tmp.path().join("store"));
assert!(matches!(
k.uninstall("nope"),
Err(KitError::NotInstalled { .. })
));
}
#[test]
fn uninstall_removes_the_directory() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path().join("store");
let k = kit(&root);
let dir = place_plugin(&root, "myapp-plugin-foo");
assert!(dir.is_dir());
k.uninstall("foo").expect("should uninstall");
assert!(!dir.exists(), "the directory should have been deleted");
assert!(k.list().unwrap().is_empty());
}
/// A directory that is not a plugin crate is refused before anything is built.
#[test]
fn install_from_path_needs_a_cargo_manifest() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path().join("store");
let k = kit(&root);
let checkout = tmp.path().join("checkout");
std::fs::create_dir_all(&checkout).unwrap();
match k.install_from_path(&checkout) {
Err(KitError::NoManifest { dir }) => {
assert!(dir.ends_with("checkout"), "{dir:?}")
}
other => panic!("expected NoManifest, got {other:?}"),
}
}
/// A crate without the manifest beside it is refused too — and again before the
/// compile, which is the point of checking up front.
#[test]
fn install_from_path_needs_the_manifest() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path().join("store");
let k = kit(&root);
let checkout = tmp.path().join("checkout");
std::fs::create_dir_all(checkout.join("src")).unwrap();
std::fs::write(
checkout.join("Cargo.toml"),
"[package]\nname = \"myapp-plugin-foo\"\nversion = \"0.1.0\"\nedition = \"2021\"\n",
)
.unwrap();
assert!(
k.install_from_path(&checkout).is_err(),
"a crate with no manifest is not a plugin checkout"
);
}
/// The same refusal an install from crates.io gives: one plugin name, one directory.
#[test]
fn install_from_path_refuses_when_already_installed() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path().join("store");
let k = kit(&root);
place_plugin(&root, "myapp-plugin-foo");
let checkout = tmp.path().join("checkout");
std::fs::create_dir_all(checkout.join("src")).unwrap();
std::fs::write(
checkout.join("Cargo.toml"),
"[package]\nname = \"myapp-plugin-foo\"\nversion = \"0.1.0\"\nedition = \"2021\"\n",
)
.unwrap();
std::fs::write(
checkout.join("myapp-plugin.toml"),
super::super::tests::MANIFEST,
)
.unwrap();
match k.install_from_path(&checkout) {
Err(KitError::AlreadyInstalled { name, .. }) => {
assert_eq!(name, "myapp-plugin-foo")
}
other => panic!("expected AlreadyInstalled, got {other:?}"),
}
}
/// `install` does not overwrite an existing installation — use `update` to
/// replace it.
///
/// The check happens after the lock is taken and before any network or compile
/// work, so the test needs no network access.
#[test]
fn install_refuses_when_already_installed() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path().join("store");
let k = kit(&root);
place_plugin(&root, "myapp-plugin-foo");
match k.install("foo", Some("0.1.0")) {
Err(KitError::AlreadyInstalled { name, .. }) => {
assert_eq!(name, "myapp-plugin-foo")
}
other => panic!("expected AlreadyInstalled, got {other:?}"),
}
}
}