maviola 0.3.0

//! # Maviola core errors
//!
//! These errors are returned by all `maviola` methods and functions.
//!
//! The top-level error is [`Error`]. Library API returns versions of this error possibly wrapping
//! other types of errors like [`FrameError`] or [`SpecError`].
//!
//! We also re-export errors from [`mavio::errors`](https://docs.rs/mavio/latest/mavio/errors/) and
//! wrap them as the corresponding variants of [`Error`]. All such low-level MAVLink abstractions
//! are available in [`crate::core`].

use std::fmt::{Debug, Formatter};
use std::sync::{mpsc, Arc, PoisonError};

use crate::protocol::MessageId;

/// <sup>[`mavio`](https://crates.io/crates/mavio)</sup>
/// Low-level error re-exported from Mavio. Maviola wraps all variants of [`CoreError`] with its own
/// [`Error`] and provides proper conversions with [`From`] trait.
///
/// You may use mavio fallible functions such as [`Frame::add_signature`](mavio::Frame::add_signature)
/// with Maviola [`Result`] by calling [`Error::from`].
///
/// For example:
///
/// ```rust
/// use maviola::error::{CoreError, Error, Result};
///
/// fn core_fallible() -> core::result::Result<(), CoreError> {
///     Ok(())
/// }
///
/// fn fallible() -> Result<()> {
///     core_fallible().map_err(Error::from)
/// }
///
/// fallible().unwrap();
/// ```
/// ---
///
#[doc(inline)]
pub use crate::error::Error as CoreError;
/// <sup>[`mavio`](https://crates.io/crates/mavio)</sup>
#[doc(inline)]
#[cfg(all(feature = "msrv-utils-mission", feature = "unstable"))]
pub use mavio::error::MissionError;
/// <sup>[`mavio`](https://crates.io/crates/mavio)</sup>
#[doc(inline)]
pub use mavio::error::{
    ChecksumError, FrameError, IncompatFlagsError, IoError, SignatureError, SpecError, VersionError,
};

/// Maviola result type.
pub type Result<T> = core::result::Result<T, Error>;

/// Result for sending parts of channels.
pub type SendResult<T> = core::result::Result<(), SendError<T>>;

/// Result of the blocking receive attempt.
pub type RecvResult<T> = core::result::Result<T, RecvError>;

/// Result of the blocking receive attempt with timeout.
pub type RecvTimeoutResult<T> = core::result::Result<T, RecvTimeoutError>;

/// Result of the non-blocking receive attempt.
pub type TryRecvResult<T> = core::result::Result<T, TryRecvError>;

/// <sup>[`serde ⍚`](https://serde.rs) | [`specta ⍚`](https://crates.io/crates/specta)</sup>
/// All errors generated by Maviola.
///
/// ## Caveats
///
/// We provide a limited support for [Serde](https://serde.rs) and
/// [Specta](https://crates.io/crates/specta). At the moment, the goal is simply to show something
/// meaningful. See [`IoError`], [`SerialError`], and [`NodeError`] for details.
///
/// This part of the API is considered unstable. Breaking changes may be introduced at any time.
///
/// To enable Serde or Specta for [`Error`], turn the `unstable` feature on.
///
/// ### Specta
///
/// The name of the exported type is `MaviolaError`.
#[cfg_attr(all(feature = "specta", feature = "unstable"), derive(specta::Type))]
#[cfg_attr(
    all(feature = "specta", feature = "unstable"),
    specta(rename = "MaviolaError")
)]
#[cfg_attr(
    all(feature = "serde", feature = "unstable"),
    derive(serde::Serialize, serde::Deserialize)
)]
#[derive(Clone, Debug, thiserror::Error)]
pub enum Error {
    /// [`std::io::Error`] wrapper.
    #[error("I/O error: {0:?}")]
    Io(IoError),

    /// Frame encoding/decoding error.
    #[error("frame decoding/encoding error: {0:?}")]
    Frame(#[from] FrameError),

    /// Message encoding/decoding and specification discovery error.
    #[error("message decoding/encoding error: {0:?}")]
    Spec(SpecError),

    /// Node errors.
    #[error("node error: {0:?}")]
    #[cfg_attr(
        all(feature = "serde", feature = "unstable"),
        serde(skip_deserializing)
    )]
    Node(#[from] NodeError),

    /// Synchronisation errors.
    #[error("multi-threading error: {0:?}")]
    Sync(#[from] SyncError),

    /// Serial port error.
    #[error("serial port error: {0:?}")]
    Serial(#[from] SerialError),

    /// Mission-related errors.
    #[cfg(all(feature = "msrv-utils-mission", feature = "unstable"))]
    #[error("mission error: {0:?}")]
    Mission(#[from] MissionError),

    /// Other errors.
    #[error("error: {0}")]
    Other(String),
}

/// <sup>[`serde ⍚`](https://serde.rs) | [`specta ⍚`](https://crates.io/crates/specta)</sup>
/// Synchronisation errors.
#[cfg_attr(all(feature = "specta", feature = "unstable"), derive(specta::Type))]
#[cfg_attr(
    all(feature = "serde", feature = "unstable"),
    derive(serde::Serialize, serde::Deserialize)
)]
#[derive(Clone, Debug, thiserror::Error)]
pub enum SyncError {
    /// Error while joining threads.
    #[error("error during thread join: {0:?}")]
    ThreadJoin(String),

    /// Failed due to a poisoned mutex.
    #[error("poisoned mutex: {0}")]
    PoisonedMutex(String),

    /// Attempt to read from an empty MPSC/MPMC channel.
    #[error("channel is empty")]
    Empty,

    /// Attempt to read or write into a closed MPSC/MPMC channel.
    #[error("channel is closed")]
    Disconnected,

    /// The receiver lagged too far behind. Attempting to receive again will
    /// return the oldest message still retained by the channel.
    ///
    /// Includes the number of skipped messages.
    #[error("receiver is too far behind: {0}")]
    Lagged(u64),

    /// This **channel** is currently empty, but the **Sender**(s) have not yet
    /// disconnected, so data may yet become available.
    #[error("timed out")]
    Timeout,
}

/// <sup>[`serde ⍚`](https://serde.rs) | [`specta ⍚`](https://crates.io/crates/specta)</sup>
/// Node errors.
///
/// ## Caveats
///
/// The [`NodeError::NotInDialect`] variant is never deserialized by [Serde](https://serde.rs).
#[derive(Clone, Debug, thiserror::Error)]
#[cfg_attr(all(feature = "specta", feature = "unstable"), derive(specta::Type))]
#[cfg_attr(
    all(feature = "serde", feature = "unstable"),
    derive(serde::Serialize, serde::Deserialize)
)]
pub enum NodeError {
    /// Transport no longer active error.
    #[error("transport is no longer active")]
    Inactive,

    /// Attempt to use a frame with message ID that can't be recognised by a dialect.
    #[error("provided frame with ID = {0} can't be decoded in current dialect {1}")]
    NotInDialect(MessageId, &'static str),
}

/// <sup>[`serde ⍚`](https://serde.rs) | [`specta ⍚`](https://crates.io/crates/specta)</sup>
/// Serial port error.
///
/// This error heavily depends on a platform type and whether `sync` or `async` API is enabled.
///
/// ## Caveats
///
/// We provide a limited support for [Serde](https://serde.rs) and
/// [Specta](https://crates.io/crates/specta). At the moment, the goal is simply to show something
/// meaningful.
///
/// This part of the API is considered unstable. Breaking changes may be introduced at any time.
///
/// ### Serde
///
/// We provide a simplified serialization sufficient to display an error. The deserialized error is
/// always has a kind of [`serialport::ErrorKind::Unknown`] when serial support is available.
/// Otherwise, a simplified empty error will be returned. In future version the behavior may change.
///
/// ### Specta
///
/// We provide a simplified type definition:
///
/// ```rust,no_run
/// struct SerialError {
///     kind: String,
///     error: String,
/// }
/// ```
#[derive(Clone, Debug, thiserror::Error)]
#[error("{inner:?}")]
pub struct SerialError {
    #[cfg(feature = "sync")]
    #[cfg(any(windows, unix))]
    inner: Arc<serialport::Error>,
    #[cfg(all(feature = "async", not(feature = "sync")))]
    inner: Arc<tokio_serial::Error>,
    #[cfg(not(any(feature = "async", feature = "sync")))]
    inner: (),
    #[cfg(feature = "sync")]
    #[cfg(not(any(windows, unix)))]
    inner: (),
}

/// Error that happens, when caller attempts to send message to a closed channel.
///
/// The error wraps the value, that failed to be sent.
///
/// This error is returned by both synchronous and asynchronous channels.
pub struct SendError<T>(pub T);

/// Error that happens, when caller performs a blocking attempt to receive a message from a channel.
///
/// This error is returned by both synchronous and asynchronous channels.
#[derive(Clone, Copy, Debug, thiserror::Error)]
pub enum RecvError {
    /// Channel is disconnected, no messages will be received.
    #[error("channel is disconnected")]
    Disconnected,

    /// The receiver is far beyond the queue. Next request attempt will return the earliest possible
    /// message.
    #[error("lagged: {0}")]
    Lagged(u64),
}

/// Error that happens, when caller performs attempts to receive a message from a channel within a
/// timeout.
///
/// This error is returned by both synchronous and asynchronous channels.
#[derive(Clone, Copy, Debug, thiserror::Error)]
pub enum RecvTimeoutError {
    /// Channel is disconnected, no messages will be received.
    #[error("channel is disconnected")]
    Disconnected,

    /// This **channel** is currently empty, but the **Sender**(s) have not yet
    /// disconnected, so data may yet become available.
    #[error("timed out")]
    Timeout,

    /// The receiver is far beyond the queue. Next request attempt will return the earliest possible
    /// message.
    #[error("lagged: {0}")]
    Lagged(u64),
}

/// Error that happens, when caller tries to receive a message from a channel.
///
/// This error is returned by both synchronous and asynchronous channels.
#[derive(Clone, Copy, Debug, thiserror::Error)]
pub enum TryRecvError {
    /// Channel is empty.
    #[error("channel is empty")]
    Empty,

    /// Channel is disconnected, no messages will be received.
    #[error("channel is disconnected")]
    Disconnected,

    /// The receiver is far beyond the queue. Next request attempt will return the earliest possible
    /// message.
    #[error("lagged: {0}")]
    Lagged(u64),
}

impl From<mavio::error::Error> for Error {
    fn from(value: mavio::error::Error) -> Self {
        match value {
            mavio::error::Error::Io(err) => Self::Io(err),
            mavio::error::Error::Frame(err) => Self::Frame(err),
            mavio::error::Error::Spec(err) => Self::Spec(err),
            #[cfg(all(feature = "msrv-utils-mission", feature = "unstable"))]
            mavio::error::Error::Mission(err) => Self::Mission(err),
        }
    }
}

impl From<SpecError> for Error {
    fn from(value: SpecError) -> Self {
        Error::Spec(value)
    }
}

impl<Guard> From<PoisonError<Guard>> for Error {
    fn from(value: PoisonError<Guard>) -> Self {
        Error::Sync(SyncError::PoisonedMutex(format!("{:?}", value)))
    }
}

impl From<std::io::Error> for Error {
    fn from(value: std::io::Error) -> Self {
        Self::Io(IoError::from(value))
    }
}

impl From<VersionError> for Error {
    fn from(value: VersionError) -> Self {
        FrameError::from(value).into()
    }
}

impl From<ChecksumError> for Error {
    fn from(value: ChecksumError) -> Self {
        FrameError::from(value).into()
    }
}

impl From<SignatureError> for Error {
    fn from(value: SignatureError) -> Self {
        FrameError::from(value).into()
    }
}

impl From<IncompatFlagsError> for Error {
    fn from(value: IncompatFlagsError) -> Self {
        FrameError::from(value).into()
    }
}

///////////////////////////////////////////////////////////////////////////////
//                                Recv/Send                                  //
///////////////////////////////////////////////////////////////////////////////

impl<T> Debug for SendError<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SendError").finish_non_exhaustive()
    }
}

impl<T> From<SendError<T>> for Error {
    fn from(_: SendError<T>) -> Self {
        SyncError::Disconnected.into()
    }
}

impl From<RecvError> for Error {
    fn from(value: RecvError) -> Self {
        match value {
            RecvError::Disconnected => SyncError::Disconnected,
            RecvError::Lagged(n) => SyncError::Lagged(n),
        }
        .into()
    }
}

impl From<RecvTimeoutError> for Error {
    fn from(value: RecvTimeoutError) -> Self {
        match value {
            RecvTimeoutError::Disconnected => SyncError::Disconnected,
            RecvTimeoutError::Timeout => SyncError::Timeout,
            RecvTimeoutError::Lagged(n) => SyncError::Lagged(n),
        }
        .into()
    }
}

impl From<TryRecvError> for Error {
    fn from(value: TryRecvError) -> Self {
        match value {
            TryRecvError::Empty => SyncError::Empty,
            TryRecvError::Disconnected => SyncError::Disconnected,
            TryRecvError::Lagged(n) => SyncError::Lagged(n),
        }
        .into()
    }
}

///////////////////////////////////////////////////////////////////////////////
//                                   MPSC                                    //
///////////////////////////////////////////////////////////////////////////////

impl<T> From<mpsc::SendError<T>> for SendError<T> {
    fn from(value: mpsc::SendError<T>) -> Self {
        SendError(value.0)
    }
}

impl From<mpsc::RecvError> for RecvError {
    fn from(_: mpsc::RecvError) -> Self {
        RecvError::Disconnected
    }
}

impl From<mpsc::RecvTimeoutError> for RecvTimeoutError {
    fn from(value: mpsc::RecvTimeoutError) -> Self {
        match value {
            mpsc::RecvTimeoutError::Timeout => RecvTimeoutError::Timeout,
            mpsc::RecvTimeoutError::Disconnected => RecvTimeoutError::Disconnected,
        }
    }
}

impl From<mpsc::TryRecvError> for TryRecvError {
    fn from(value: mpsc::TryRecvError) -> Self {
        match value {
            mpsc::TryRecvError::Empty => TryRecvError::Empty,
            mpsc::TryRecvError::Disconnected => TryRecvError::Disconnected,
        }
    }
}

impl<T> From<mpsc::SendError<T>> for Error {
    fn from(_: mpsc::SendError<T>) -> Self {
        SyncError::Disconnected.into()
    }
}

impl From<mpsc::RecvError> for Error {
    fn from(_: mpsc::RecvError) -> Self {
        SyncError::Disconnected.into()
    }
}

impl From<mpsc::RecvTimeoutError> for Error {
    fn from(value: mpsc::RecvTimeoutError) -> Self {
        RecvTimeoutError::from(value).into()
    }
}

impl From<mpsc::TryRecvError> for Error {
    fn from(value: mpsc::TryRecvError) -> Self {
        TryRecvError::from(value).into()
    }
}

///////////////////////////////////////////////////////////////////////////////
//                              Tokio: Broadcast                             //
///////////////////////////////////////////////////////////////////////////////

#[cfg(feature = "async")]
impl<T> From<tokio::sync::broadcast::error::SendError<T>> for SendError<T> {
    fn from(value: tokio::sync::broadcast::error::SendError<T>) -> Self {
        Self(value.0)
    }
}

#[cfg(feature = "async")]
impl From<tokio::sync::broadcast::error::RecvError> for RecvError {
    fn from(value: tokio::sync::broadcast::error::RecvError) -> Self {
        match value {
            tokio::sync::broadcast::error::RecvError::Closed => RecvError::Disconnected,
            tokio::sync::broadcast::error::RecvError::Lagged(val) => RecvError::Lagged(val),
        }
    }
}

#[cfg(feature = "async")]
impl From<tokio::sync::broadcast::error::TryRecvError> for TryRecvError {
    fn from(value: tokio::sync::broadcast::error::TryRecvError) -> Self {
        match value {
            tokio::sync::broadcast::error::TryRecvError::Empty => TryRecvError::Empty,
            tokio::sync::broadcast::error::TryRecvError::Closed => TryRecvError::Disconnected,
            tokio::sync::broadcast::error::TryRecvError::Lagged(val) => TryRecvError::Lagged(val),
        }
    }
}

#[cfg(feature = "async")]
impl<T> From<tokio::sync::broadcast::error::SendError<T>> for Error {
    fn from(_: tokio::sync::broadcast::error::SendError<T>) -> Self {
        SyncError::Disconnected.into()
    }
}

#[cfg(feature = "async")]
impl From<tokio::sync::broadcast::error::RecvError> for Error {
    fn from(value: tokio::sync::broadcast::error::RecvError) -> Self {
        RecvError::from(value).into()
    }
}

#[cfg(feature = "async")]
impl From<tokio::sync::broadcast::error::TryRecvError> for Error {
    fn from(value: tokio::sync::broadcast::error::TryRecvError) -> Self {
        TryRecvError::from(value).into()
    }
}

///////////////////////////////////////////////////////////////////////////////
//                                Tokio: MPSC                                //
///////////////////////////////////////////////////////////////////////////////

#[cfg(feature = "async")]
impl<T> From<tokio::sync::mpsc::error::SendError<T>> for SendError<T> {
    fn from(value: tokio::sync::mpsc::error::SendError<T>) -> Self {
        SendError(value.0)
    }
}

#[cfg(feature = "async")]
impl<T> From<tokio::sync::mpsc::error::SendError<T>> for Error {
    fn from(value: tokio::sync::mpsc::error::SendError<T>) -> Self {
        SendError::from(value).into()
    }
}

///////////////////////////////////////////////////////////////////////////////
//                                Serial Port                                //
///////////////////////////////////////////////////////////////////////////////

#[cfg(feature = "sync")]
#[cfg(any(windows, unix))]
impl AsRef<serialport::Error> for SerialError {
    fn as_ref(&self) -> &serialport::Error {
        self.inner.as_ref()
    }
}

#[cfg(feature = "sync")]
#[cfg(any(windows, unix))]
impl From<serialport::Error> for SerialError {
    fn from(value: serialport::Error) -> Self {
        SerialError {
            inner: Arc::new(value),
        }
    }
}

#[cfg(all(feature = "async", not(feature = "sync")))]
impl AsRef<tokio_serial::Error> for SerialError {
    fn as_ref(&self) -> &tokio_serial::Error {
        self.inner.as_ref()
    }
}

#[cfg(all(feature = "async", not(feature = "sync")))]
impl From<tokio_serial::Error> for SerialError {
    fn from(value: tokio_serial::Error) -> Self {
        SerialError {
            inner: Arc::new(value),
        }
    }
}

#[cfg(feature = "sync")]
#[cfg(any(windows, unix))]
impl From<serialport::Error> for Error {
    fn from(value: serialport::Error) -> Self {
        match value.kind {
            serialport::ErrorKind::Io(kind) => {
                Self::Io(IoError::from(std::io::Error::new(kind, value.description)))
            }
            _ => Self::Serial(SerialError::from(value)),
        }
    }
}

#[cfg(all(feature = "async", not(feature = "sync")))]
impl From<tokio_serial::Error> for Error {
    fn from(value: tokio_serial::Error) -> Self {
        match value.kind {
            tokio_serial::ErrorKind::Io(kind) => {
                Self::Io(IoError::from(std::io::Error::new(kind, value.description)))
            }
            _ => Self::Serial(SerialError::from(value)),
        }
    }
}

#[cfg(all(feature = "serde", feature = "unstable"))]
impl serde::Serialize for SerialError {
    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        use serde::ser::SerializeStruct;
        let mut io_error = serializer.serialize_struct("SerialError", 2)?;

        #[cfg(feature = "sync")]
        #[cfg(any(windows, unix))]
        {
            io_error.serialize_field("kind", &format!("{:?}", self.as_ref().kind()))?;
            io_error.serialize_field("error", &self.as_ref().to_string())?;
        }

        #[cfg(all(feature = "async", not(feature = "sync")))]
        {
            io_error.serialize_field("kind", &format!("{:?}", self.as_ref().kind()))?;
            io_error.serialize_field("error", &self.as_ref().to_string())?;
        }

        #[cfg(not(all(feature = "async", feature = "sync")))]
        {
            io_error.serialize_field("kind", "Unknown")?;
            io_error.serialize_field("error", "Unknown")?;
        }

        #[cfg(feature = "sync")]
        #[cfg(not(any(windows, unix)))]
        {
            io_error.serialize_field("kind", "Unknown")?;
            io_error.serialize_field("error", "Unknown")?;
        }

        io_error.end()
    }
}

#[cfg(all(feature = "serde", feature = "unstable"))]
impl<'de> serde::Deserialize<'de> for SerialError {
    fn deserialize<D>(_: D) -> std::result::Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        #[cfg(feature = "sync")]
        #[cfg(any(windows, unix))]
        return Ok(SerialError::from(serialport::Error::new(
            serialport::ErrorKind::Unknown,
            "Foreign error",
        )));

        #[cfg(all(feature = "async", not(feature = "sync")))]
        return Ok(SerialError::from(tokio_serial::Error::new(
            tokio_serial::ErrorKind::Unknown,
            "Foreign error",
        )));

        #[cfg(not(any(feature = "async", feature = "sync")))]
        return Ok(SerialError { inner: () });

        #[cfg(feature = "sync")]
        #[cfg(not(any(windows, unix)))]
        return Ok(SerialError { inner: () });
    }
}

#[cfg(all(feature = "specta", feature = "unstable"))]
#[derive(specta::Type)]
#[allow(dead_code)]
struct SerialErrorStub {
    kind: String,
    error: String,
}

#[cfg(all(feature = "specta", feature = "unstable"))]
impl specta::Type for SerialError {
    fn inline(type_map: &mut specta::TypeMap, generics: specta::Generics) -> specta::DataType {
        specta::DataType::from(SerialErrorStub::inline(type_map, generics))
    }
}