crate_plugin_kit/error.rs
1//! Error types.
2//!
3//! `anyhow::Error` is deliberately kept out of the public API: this crate is used
4//! by hosts right at the `dlopen` boundary, where an enumerable, matchable error
5//! type is far easier to diagnose than a type-erased one. The internals (the
6//! `install` module) use anyhow for convenience and convert at the exit points.
7
8use std::path::PathBuf;
9
10/// Errors produced by the kit.
11///
12/// The variants fall into two groups:
13///
14/// - Caller-actionable: [`KitError::NotInstalled`] / [`KitError::AlreadyInstalled`] /
15/// [`KitError::PluginInUse`] / [`KitError::CargoNotFound`] — the caller usually
16/// takes another route or prompts the user;
17/// - Broken environment or data: everything else. These can only be reported.
18#[derive(Debug, thiserror::Error)]
19pub enum KitError {
20 /// The plugin to uninstall or update is not installed.
21 #[error("plugin {name} is not installed")]
22 NotInstalled {
23 /// Full crate name.
24 name: String,
25 },
26
27 /// The plugin to install is already present.
28 ///
29 /// `install` never overwrites an existing installation; use `update` to replace it.
30 #[error("directory for plugin {name} already exists: {path}")]
31 AlreadyInstalled {
32 /// Full crate name.
33 name: String,
34 /// The existing directory.
35 path: PathBuf,
36 },
37
38 /// The plugin's dynamic library is still loaded in this process, so it cannot be deleted.
39 ///
40 /// A `.dll` that is currently `dlopen`ed cannot be removed on Windows; on
41 /// Linux/macOS the removal succeeds but the disk space is not reclaimed. Rather
42 /// than gamble on it, ask the user to retry from a clean process.
43 #[error(
44 "the dynamic library of plugin {name} is still loaded in this process and cannot be \
45 deleted. Retry in a new terminal (a new process does not load it), or exit the \
46 current session and try again"
47 )]
48 PluginInUse {
49 /// Full crate name.
50 name: String,
51 },
52
53 /// Reading the manifest file failed.
54 #[error("failed to read manifest ({path}): {source}")]
55 ManifestRead {
56 /// Manifest path.
57 path: PathBuf,
58 /// Underlying IO error.
59 #[source]
60 source: std::io::Error,
61 },
62
63 /// The manifest is not valid TOML, or a field has the wrong type.
64 #[error("failed to parse manifest ({path}): {source}")]
65 ManifestParse {
66 /// Manifest path.
67 path: PathBuf,
68 /// Underlying TOML error.
69 #[source]
70 source: Box<toml::de::Error>,
71 },
72
73 /// A required field in the manifest is missing or empty.
74 #[error("manifest is missing field `{field}` ({path})")]
75 ManifestMissingField {
76 /// Field name, e.g. `plugin.name`.
77 field: String,
78 /// Manifest path.
79 path: PathBuf,
80 },
81
82 /// No dynamic library matching the naming rules was found in the install dir.
83 #[error("could not find the dynamic library of plugin {name}; tried: {tried}")]
84 LibraryNotFound {
85 /// File name stem.
86 name: String,
87 /// The file names that were tried, comma-separated.
88 tried: String,
89 },
90
91 /// `dlopen` itself failed (corrupt file, wrong architecture, missing dependencies).
92 #[error("failed to load the dynamic library ({path}): {source}")]
93 LibraryLoad {
94 /// Dynamic library path.
95 path: PathBuf,
96 /// Underlying libloading error.
97 #[source]
98 source: Box<libloading::Error>,
99 },
100
101 /// The library loaded, but it does not export the symbol we look for.
102 ///
103 /// Usually means the wrong thing was installed — e.g. a plain library placed in
104 /// the plugin directory.
105 #[error("the dynamic library does not export symbol `{symbol}`")]
106 SymbolMissing {
107 /// The missing symbol name.
108 symbol: String,
109 },
110
111 /// The plugin's entry function returned a null pointer.
112 #[error("the plugin's entry function returned a null pointer")]
113 NullEntry,
114
115 /// Timed out waiting for the install lock.
116 #[error("timed out waiting for the file lock ({path}, waited {secs}s)")]
117 LockTimeout {
118 /// Lock file path.
119 path: PathBuf,
120 /// How many seconds were spent waiting.
121 secs: u64,
122 },
123
124 /// An operation on the lock file itself failed.
125 #[error("file lock operation failed ({path}): {source}")]
126 LockIo {
127 /// Lock file path.
128 path: PathBuf,
129 /// Underlying IO error.
130 #[source]
131 source: std::io::Error,
132 },
133
134 /// No `cargo` on `PATH`, so build-host installation is unavailable.
135 ///
136 /// The caller can use this to tell the user to install a Rust toolchain, or to
137 /// fall back to prebuilt.
138 #[error("could not find `cargo` on PATH; build-host installation needs a Rust toolchain")]
139 CargoNotFound,
140
141 /// `cargo build` failed. stderr has already been passed through to the user
142 /// (stdio is inherited).
143 #[error("build-host compilation failed ({})", describe_code(.code))]
144 BuildFailed {
145 /// Process exit code. `None` when the process was killed by a signal.
146 code: Option<i32>,
147 },
148
149 /// The build succeeded, but there is no cdylib among its artifacts.
150 #[error("no cdylib among the build artifacts (looked for {stem} in {dir})")]
151 BuildArtifactMissing {
152 /// Expected file name stem.
153 stem: String,
154 /// Directories that were searched.
155 dir: String,
156 },
157
158 /// The network request failed. The message carries the URL and status code.
159 #[error("network request failed: {0}")]
160 Http(String),
161
162 /// The registry returned content we could fetch but that is not what we expect.
163 #[error("registry returned an unexpected response: {0}")]
164 Registry(String),
165
166 /// A plugin panicked during a cross-boundary call (caught by `catch_unwind` on
167 /// the host side).
168 #[error("plugin panicked in {what} (caught by catch_unwind)")]
169 PluginPanicked {
170 /// Which call site, e.g. `"entry()"`.
171 what: String,
172 },
173
174 /// Neither HOME nor an equivalent system directory is available, so the data
175 /// dir cannot be determined.
176 #[error("cannot determine the host application's data dir (no HOME and no system equivalent)")]
177 NoDataDir,
178
179 /// IO error.
180 #[error(transparent)]
181 Io(#[from] std::io::Error),
182}
183
184/// This crate's `Result` alias.
185pub type KitResult<T> = std::result::Result<T, KitError>;
186
187/// Say what happened to the build process, rather than printing `Option`'s `Debug` output at
188/// the user -- `Some(101)` and `None` are implementation details, not an explanation.
189fn describe_code(code: &Option<i32>) -> String {
190 match code {
191 Some(code) => format!("exit code {code}"),
192 None => "killed by a signal".to_string(),
193 }
194}