rusteal_core/
error.rs

1// Error types for the Rusteal runtime.
2
3use std::fmt;
4
5use rusteal_ffi::RustealErrorCode;
6
7/// Rich error type for Rusteal operations.
8#[derive(Debug)]
9pub enum RustealError {
10    ObjectDestroyed,
11    InvalidCast,
12    PropertyNotFound(String),
13    FunctionNotFound(String),
14    TypeMismatch,
15    NullArgument,
16    IndexOutOfRange,
17    InvalidOperation(String),
18    Internal(String),
19    BufferTooSmall,
20}
21
22impl fmt::Display for RustealError {
23    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
24        match self {
25            RustealError::ObjectDestroyed => write!(f, "object has been destroyed"),
26            RustealError::InvalidCast => write!(f, "invalid cast"),
27            RustealError::PropertyNotFound(name) => write!(f, "property not found: {name}"),
28            RustealError::FunctionNotFound(name) => write!(f, "function not found: {name}"),
29            RustealError::TypeMismatch => write!(f, "type mismatch"),
30            RustealError::NullArgument => write!(f, "null argument"),
31            RustealError::IndexOutOfRange => write!(f, "index out of range"),
32            RustealError::InvalidOperation(msg) => write!(f, "invalid operation: {msg}"),
33            RustealError::Internal(msg) => write!(f, "internal error: {msg}"),
34            RustealError::BufferTooSmall => write!(f, "buffer too small"),
35        }
36    }
37}
38
39impl std::error::Error for RustealError {}
40
41/// Convenience alias used throughout the runtime and generated code.
42pub type RustealResult<T> = Result<T, RustealError>;
43
44/// Convert an FFI error code to a `RustealResult<()>`.
45/// `Ok` maps to `Ok(())`, all others map to the corresponding `RustealError`.
46pub fn check_ffi(code: RustealErrorCode) -> RustealResult<()> {
47    match code {
48        RustealErrorCode::Ok => Ok(()),
49        other => Err(RustealError::from(other)),
50    }
51}
52
53/// Like `check_ffi`, but enriches property/function errors with the given name.
54pub fn check_ffi_ctx(code: RustealErrorCode, context: &str) -> RustealResult<()> {
55    match code {
56        RustealErrorCode::Ok => Ok(()),
57        RustealErrorCode::PropertyNotFound => Err(RustealError::PropertyNotFound(context.into())),
58        RustealErrorCode::FunctionNotFound => Err(RustealError::FunctionNotFound(context.into())),
59        RustealErrorCode::InvalidOperation => Err(RustealError::InvalidOperation(context.into())),
60        other => Err(RustealError::from(other)),
61    }
62}
63
64/// Assert that an FFI call returned `Ok`. Used for codegen-generated methods
65/// where handle validation has already been performed and the C++ wrapper
66/// is expected to always succeed. Panics in debug builds if the code is not `Ok`.
67#[inline(always)]
68pub fn ffi_infallible(code: RustealErrorCode) {
69    debug_assert_eq!(
70        code,
71        RustealErrorCode::Ok,
72        "FFI call returned {:?} after pre-validation",
73        code
74    );
75}
76
77/// Like [`ffi_infallible`], but includes a context string in the panic message.
78#[inline(always)]
79pub fn ffi_infallible_ctx(code: RustealErrorCode, ctx: &str) {
80    debug_assert_eq!(
81        code,
82        RustealErrorCode::Ok,
83        "FFI '{}' returned {:?} after pre-validation",
84        ctx,
85        code
86    );
87}
88
89impl From<RustealErrorCode> for RustealError {
90    #[allow(clippy::match_same_arms)]
91    fn from(code: RustealErrorCode) -> Self {
92        match code {
93            RustealErrorCode::Ok => {
94                // Callers should not convert Ok into an error. If they do,
95                // treat it as an internal logic bug.
96                RustealError::Internal("unexpected Ok error code".into())
97            }
98            RustealErrorCode::ObjectDestroyed => RustealError::ObjectDestroyed,
99            RustealErrorCode::InvalidCast => RustealError::InvalidCast,
100            RustealErrorCode::PropertyNotFound => RustealError::PropertyNotFound(String::new()),
101            RustealErrorCode::FunctionNotFound => RustealError::FunctionNotFound(String::new()),
102            RustealErrorCode::TypeMismatch => RustealError::TypeMismatch,
103            RustealErrorCode::NullArgument => RustealError::NullArgument,
104            RustealErrorCode::IndexOutOfRange => RustealError::IndexOutOfRange,
105            RustealErrorCode::InvalidOperation => RustealError::InvalidOperation(String::new()),
106            RustealErrorCode::InternalError => RustealError::Internal(String::new()),
107            RustealErrorCode::BufferTooSmall => RustealError::BufferTooSmall,
108        }
109    }
110}
111
112#[cfg(test)]
113mod tests {
114    use super::*;
115
116    #[test]
117    fn check_ffi_ok_returns_ok() {
118        assert!(check_ffi(RustealErrorCode::Ok).is_ok());
119    }
120
121    #[test]
122    fn check_ffi_errors_map_correctly() {
123        let cases = [
124            (RustealErrorCode::ObjectDestroyed, "ObjectDestroyed"),
125            (RustealErrorCode::InvalidCast, "InvalidCast"),
126            (RustealErrorCode::PropertyNotFound, "PropertyNotFound"),
127            (RustealErrorCode::FunctionNotFound, "FunctionNotFound"),
128            (RustealErrorCode::TypeMismatch, "TypeMismatch"),
129            (RustealErrorCode::NullArgument, "NullArgument"),
130            (RustealErrorCode::IndexOutOfRange, "IndexOutOfRange"),
131            (RustealErrorCode::InvalidOperation, "InvalidOperation"),
132            (RustealErrorCode::InternalError, "Internal"),
133        ];
134        for (code, expected_variant) in cases {
135            let err = check_ffi(code).unwrap_err();
136            let debug = format!("{err:?}");
137            assert!(
138                debug.starts_with(expected_variant),
139                "expected {expected_variant}, got {debug}"
140            );
141        }
142    }
143
144    #[test]
145    fn display_formats_are_human_readable() {
146        let err = RustealError::PropertyNotFound("Health".into());
147        assert_eq!(err.to_string(), "property not found: Health");
148    }
149}
rusteal_core/error.rs

rusteal_core/
error.rs
