fidius_core/
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 the Fidius plugin framework.
16
17use serde::{Deserialize, Serialize};
18use std::fmt;
19
20/// Error returned by plugin method implementations to signal business logic failures.
21///
22/// Serialized as bincode across the FFI boundary. The host deserializes
23/// this from the output buffer when the FFI shim returns `STATUS_PLUGIN_ERROR`.
24///
25/// The `details` field is stored as a JSON string (not `serde_json::Value`)
26/// because bincode cannot deserialize a free-form `serde_json::Value`
27/// (it lacks `deserialize_any`). Storing it as a `String` keeps the error
28/// struct bincode-compatible.
29#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
30pub struct PluginError {
31    /// Machine-readable error code (e.g., `"INVALID_INPUT"`, `"NOT_FOUND"`).
32    pub code: String,
33    /// Human-readable error message.
34    pub message: String,
35    /// Optional structured details as a JSON string.
36    pub details: Option<String>,
37}
38
39impl PluginError {
40    /// Create a new `PluginError` without details.
41    pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
42        Self {
43            code: code.into(),
44            message: message.into(),
45            details: None,
46        }
47    }
48
49    /// Create a new `PluginError` with structured details.
50    ///
51    /// The `serde_json::Value` is serialized to a JSON string for storage.
52    pub fn with_details(
53        code: impl Into<String>,
54        message: impl Into<String>,
55        details: serde_json::Value,
56    ) -> Self {
57        Self {
58            code: code.into(),
59            message: message.into(),
60            details: Some(details.to_string()),
61        }
62    }
63
64    /// Parse the `details` field back into a `serde_json::Value`.
65    ///
66    /// Returns `None` if details is absent or fails to parse.
67    pub fn details_value(&self) -> Option<serde_json::Value> {
68        self.details
69            .as_deref()
70            .and_then(|s| serde_json::from_str(s).ok())
71    }
72}
73
74impl fmt::Display for PluginError {
75    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
76        write!(f, "[{}] {}", self.code, self.message)
77    }
78}
79
80impl std::error::Error for PluginError {}
fidius_core/error.rs

fidius_core/
error.rs
