Skip to main content

rustduck_core/
error.rs

1use thiserror::Error;
2
3/// The native exception category captured at the `rustduck-sys` boundary.
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5#[non_exhaustive]
6pub enum NativeExceptionKind {
7    /// A native `std::exception` was caught.
8    Standard,
9    /// A native exception outside the `std::exception` hierarchy was caught.
10    Unknown,
11}
12
13/// Errors reported by the safe Rust facade.
14#[derive(Debug, Error)]
15#[non_exhaustive]
16pub enum Error {
17    /// A caller supplied a value outside this facade's valid contract.
18    #[error("invalid value for {field}: {message}")]
19    InvalidArgument {
20        /// The validated argument name.
21        field: &'static str,
22        /// A controlled description of the violated constraint.
23        message: String,
24    },
25
26    /// An operation is invalid for the object's current lifecycle state.
27    #[error("{object} cannot {operation} while it is {state}")]
28    InvalidState {
29        /// The affected object type.
30        object: &'static str,
31        /// The requested operation.
32        operation: &'static str,
33        /// The object's current state.
34        state: &'static str,
35    },
36
37    /// A native operation reported its documented normal failure result.
38    #[error("native operation {operation} failed")]
39    NativeFailure {
40        /// Stable identifier for the failed operation.
41        operation: &'static str,
42    },
43
44    /// A bounded internal resource has no space for another entry.
45    #[error("resource exhausted: {resource}")]
46    ResourceExhausted {
47        /// Stable identifier for the exhausted resource.
48        resource: &'static str,
49    },
50
51    /// A native operation threw an exception that was contained at the boundary.
52    #[error("native operation {operation} raised {kind:?}")]
53    NativeException {
54        /// Stable identifier for the failed operation.
55        operation: &'static str,
56        /// The caught exception category.
57        kind: NativeExceptionKind,
58    },
59
60    /// A memory endpoint was closed before accepting or producing data.
61    #[error("{endpoint} is closed")]
62    QueueClosed {
63        /// Stable endpoint identifier.
64        endpoint: &'static str,
65    },
66
67    /// A memory endpoint was aborted.
68    #[error("{endpoint} was aborted")]
69    QueueAborted {
70        /// Stable endpoint identifier.
71        endpoint: &'static str,
72    },
73
74    /// The private memory callback protocol was violated.
75    #[error("memory callback protocol failed: {operation}")]
76    CallbackProtocol {
77        /// Stable protocol operation identifier.
78        operation: &'static str,
79    },
80}
81
82pub(crate) fn native_exception(operation: &'static str, error: cxx::Exception) -> Error {
83    let kind = match error.what() {
84        "rustduck:unknown-exception" => NativeExceptionKind::Unknown,
85        _ => NativeExceptionKind::Standard,
86    };
87    Error::NativeException { operation, kind }
88}