fidius_host/
error.rs

1// Copyright 2026 Colliery, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Error types for fidius-host plugin loading and calling.
16
17use fidius_core::PluginError;
18
19/// Errors that can occur when loading a plugin.
20#[derive(Debug, thiserror::Error)]
21pub enum LoadError {
22    #[error("library not found: {path}")]
23    LibraryNotFound { path: String },
24
25    #[error("symbol 'fidius_get_registry' not found in {path}")]
26    SymbolNotFound { path: String },
27
28    #[error("invalid magic bytes (expected FIDIUS\\0\\0)")]
29    InvalidMagic,
30
31    #[error("incompatible registry version: got {got}, expected {expected}")]
32    IncompatibleRegistryVersion { got: u32, expected: u32 },
33
34    #[error("incompatible ABI version: got {got}, expected {expected}")]
35    IncompatibleAbiVersion { got: u32, expected: u32 },
36
37    #[error("interface hash mismatch: got {got:#x}, expected {expected:#x}")]
38    InterfaceHashMismatch { got: u64, expected: u64 },
39
40    #[error("buffer strategy mismatch: plugin uses {got}, host expects {expected}")]
41    BufferStrategyMismatch {
42        got: fidius_core::descriptor::BufferStrategyKind,
43        expected: fidius_core::descriptor::BufferStrategyKind,
44    },
45
46    #[error("architecture mismatch: expected {expected}, got {got}")]
47    ArchitectureMismatch { expected: String, got: String },
48
49    #[error("unknown buffer strategy discriminant: {value}")]
50    UnknownBufferStrategy { value: u8 },
51
52    #[error("signature verification failed for {path}")]
53    SignatureInvalid { path: String },
54
55    #[error("signature required but no .sig file found for {path}")]
56    SignatureRequired { path: String },
57
58    #[error("plugin '{name}' not found")]
59    PluginNotFound { name: String },
60
61    #[error("libloading error: {0}")]
62    LibLoading(#[from] libloading::Error),
63
64    #[error("io error: {0}")]
65    Io(#[from] std::io::Error),
66
67    /// Python loader failed (only produced with the `python` feature on).
68    /// Wraps `fidius_python::PythonLoadError` as a string to keep the
69    /// fidius-host public error enum type-clean across feature gates.
70    #[error("python load failed: {0}")]
71    PythonLoad(String),
72
73    /// WASM component loader failed (only produced with the `wasm` feature on).
74    /// Wraps wasmtime/instantiation errors as a string to keep the public enum
75    /// type-clean across feature gates.
76    #[error("wasm load failed: {0}")]
77    WasmLoad(String),
78}
79
80/// Errors that can occur when calling a plugin method.
81#[derive(Debug, thiserror::Error)]
82pub enum CallError {
83    #[error("serialization error: {0}")]
84    Serialization(String),
85
86    #[error("deserialization error: {0}")]
87    Deserialization(String),
88
89    #[error("plugin error: {0}")]
90    Plugin(PluginError),
91
92    #[error("plugin panicked: {0}")]
93    Panic(String),
94
95    #[error("buffer too small")]
96    BufferTooSmall,
97
98    /// Optional method is not implemented by this plugin — its capability bit is unset.
99    /// Returned when a method marked `#[optional]` is called on a plugin that chose not
100    /// to implement it. Not returned for out-of-range method indices; see `InvalidMethodIndex`.
101    #[error("method not implemented (capability bit {bit} not set)")]
102    NotImplemented { bit: u32 },
103
104    #[error("invalid method index {index} (plugin has {count} method(s))")]
105    InvalidMethodIndex { index: usize, count: u32 },
106
107    #[error("unknown FFI status code: {code}")]
108    UnknownStatus { code: i32 },
109
110    /// A method was dispatched through the wrong wire path — a `#[wire(raw)]`
111    /// method called via the typed path, or vice versa. Backend-agnostic: the
112    /// Python and (future) WASM executors both enforce the raw/typed split.
113    #[error(
114        "wire-mode mismatch on method '{method}': declared wire_raw={declared}, dispatcher used wire_raw={attempted}"
115    )]
116    WireModeMismatch {
117        method: String,
118        declared: bool,
119        attempted: bool,
120    },
121
122    /// A runtime-level fault originating inside an execution backend that is
123    /// *not* a plugin-raised [`PluginError`] — e.g. a future WASM trap
124    /// (unreachable, out-of-bounds) or an interpreter-level failure. Carries
125    /// the backend's runtime name and a message. Plugin-raised errors (Python
126    /// exceptions included) stay in [`CallError::Plugin`] so their structured
127    /// `code`/`message`/`details` (including tracebacks) round-trip.
128    #[error("{runtime} backend error: {message}")]
129    Backend { runtime: String, message: String },
130}
131
132/// Fold the Python backend's call error into the unified [`CallError`].
133///
134/// `fidius-python` deliberately does not depend on `fidius-host` (that would
135/// cycle — the host optionally depends on it), so the conversion lives here,
136/// behind the `python` feature, where both types are visible. Plugin-raised
137/// Python exceptions map to [`CallError::Plugin`] with the traceback preserved
138/// in `PluginError.details` (built by `fidius_python::pyerr_to_plugin_error`).
139#[cfg(feature = "python")]
140impl From<fidius_python::PythonCallError> for CallError {
141    fn from(e: fidius_python::PythonCallError) -> Self {
142        use fidius_python::PythonCallError as P;
143        match e {
144            P::InvalidMethodIndex { index, count } => CallError::InvalidMethodIndex {
145                index,
146                count: count as u32,
147            },
148            P::WireModeMismatch {
149                method,
150                declared,
151                attempted,
152            } => CallError::WireModeMismatch {
153                method: method.to_string(),
154                declared,
155                attempted,
156            },
157            P::InputDecode(msg) => CallError::Deserialization(msg),
158            P::OutputEncode(msg) => CallError::Serialization(msg),
159            P::Plugin(err) => CallError::Plugin(err),
160        }
161    }
162}
fidius_host/error.rs

fidius_host/
error.rs
