rustduck-core 1.1.0

Safe typed TSDuck core bindings for rustduck
Documentation
use thiserror::Error;

/// The native exception category captured at the `rustduck-sys` boundary.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum NativeExceptionKind {
    /// A native `std::exception` was caught.
    Standard,
    /// A native exception outside the `std::exception` hierarchy was caught.
    Unknown,
}

/// Errors reported by the safe Rust facade.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum Error {
    /// A caller supplied a value outside this facade's valid contract.
    #[error("invalid value for {field}: {message}")]
    InvalidArgument {
        /// The validated argument name.
        field: &'static str,
        /// A controlled description of the violated constraint.
        message: String,
    },

    /// An operation is invalid for the object's current lifecycle state.
    #[error("{object} cannot {operation} while it is {state}")]
    InvalidState {
        /// The affected object type.
        object: &'static str,
        /// The requested operation.
        operation: &'static str,
        /// The object's current state.
        state: &'static str,
    },

    /// A native operation reported its documented normal failure result.
    #[error("native operation {operation} failed")]
    NativeFailure {
        /// Stable identifier for the failed operation.
        operation: &'static str,
    },

    /// A bounded internal resource has no space for another entry.
    #[error("resource exhausted: {resource}")]
    ResourceExhausted {
        /// Stable identifier for the exhausted resource.
        resource: &'static str,
    },

    /// A native operation threw an exception that was contained at the boundary.
    #[error("native operation {operation} raised {kind:?}")]
    NativeException {
        /// Stable identifier for the failed operation.
        operation: &'static str,
        /// The caught exception category.
        kind: NativeExceptionKind,
    },

    /// A memory endpoint was closed before accepting or producing data.
    #[error("{endpoint} is closed")]
    QueueClosed {
        /// Stable endpoint identifier.
        endpoint: &'static str,
    },

    /// A memory endpoint was aborted.
    #[error("{endpoint} was aborted")]
    QueueAborted {
        /// Stable endpoint identifier.
        endpoint: &'static str,
    },

    /// The private memory callback protocol was violated.
    #[error("memory callback protocol failed: {operation}")]
    CallbackProtocol {
        /// Stable protocol operation identifier.
        operation: &'static str,
    },
}

pub(crate) fn native_exception(operation: &'static str, error: cxx::Exception) -> Error {
    let kind = match error.what() {
        "rustduck:unknown-exception" => NativeExceptionKind::Unknown,
        _ => NativeExceptionKind::Standard,
    };
    Error::NativeException { operation, kind }
}