Skip to main content

paganel_plugin_sdk/
error.rs

1use serde::{Deserialize, Serialize};
2use std::fmt;
3
4/// Result type returned by plugin entry points.
5pub type PluginResult<T> = Result<T, PluginError>;
6
7/// A plugin-level error. Serialized to JSON and returned to the host.
8#[derive(Debug, Clone, Serialize, Deserialize)]
9pub struct PluginError {
10    pub code: PluginErrorCode,
11    pub message: String,
12    /// Whether the host should treat this as transient (retryable).
13    #[serde(default)]
14    pub transient: bool,
15}
16
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
18#[serde(rename_all = "snake_case")]
19pub enum PluginErrorCode {
20    /// Required input field missing or wrong type.
21    InvalidInput,
22    /// Plugin rejected the row (filter only).
23    FilterRejected,
24    /// Plugin tried to use a capability that wasn't granted.
25    CapabilityDenied,
26    /// External call (HTTP, KV) failed.
27    ExternalError,
28    /// Plugin-specific logic error.
29    Internal,
30    /// Plugin panicked; message contains the panic string.
31    Panic,
32}
33
34impl PluginError {
35    pub fn invalid_input(msg: impl Into<String>) -> Self {
36        Self {
37            code: PluginErrorCode::InvalidInput,
38            message: msg.into(),
39            transient: false,
40        }
41    }
42
43    pub fn internal(msg: impl Into<String>) -> Self {
44        Self {
45            code: PluginErrorCode::Internal,
46            message: msg.into(),
47            transient: false,
48        }
49    }
50
51    pub fn external(msg: impl Into<String>) -> Self {
52        Self {
53            code: PluginErrorCode::ExternalError,
54            message: msg.into(),
55            transient: true,
56        }
57    }
58
59    pub fn capability_denied(name: &str) -> Self {
60        Self {
61            code: PluginErrorCode::CapabilityDenied,
62            message: format!("capability '{}' not granted", name),
63            transient: false,
64        }
65    }
66
67    pub fn panic(msg: String) -> Self {
68        Self {
69            code: PluginErrorCode::Panic,
70            message: msg,
71            transient: false,
72        }
73    }
74
75    /// Mark an error as transient (retryable).
76    pub fn with_transient(mut self) -> Self {
77        self.transient = true;
78        self
79    }
80}
81
82impl fmt::Display for PluginError {
83    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
84        write!(f, "[{:?}] {}", self.code, self.message)
85    }
86}
87
88impl std::error::Error for PluginError {}
89
90impl From<serde_json::Error> for PluginError {
91    fn from(e: serde_json::Error) -> Self {
92        PluginError::internal(format!("json error: {}", e))
93    }
94}
95
96impl From<std::num::ParseIntError> for PluginError {
97    fn from(e: std::num::ParseIntError) -> Self {
98        PluginError::invalid_input(format!("int parse error: {}", e))
99    }
100}
101
102impl From<std::num::ParseFloatError> for PluginError {
103    fn from(e: std::num::ParseFloatError) -> Self {
104        PluginError::invalid_input(format!("float parse error: {}", e))
105    }
106}
107
108#[doc(hidden)]
109pub fn serialize_error(err: &PluginError) -> Vec<u8> {
110    serde_json::to_vec(&serde_json::json!({
111        "error": err.message,
112        "code": err.code,
113        "transient": err.transient,
114    }))
115    .unwrap_or_else(|_| b"{\"error\":\"error serialization failed\"}".to_vec())
116}