wireshift-core 0.1.1

//! Error types for `wireshift`.

use std::borrow::Cow;
use std::io;

use thiserror::Error;

/// Convenience result alias used throughout the crate.
pub type Result<T> = std::result::Result<T, Error>;

/// Errors produced by ring setup, submission, and completion handling.
///
/// ```rust
/// use wireshift::Error;
///
/// let err = Error::invalid_config("queue_depth must be non-zero");
/// assert!(err.to_string().contains("Fix:"));
/// ```
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum Error {
    /// The supplied configuration is invalid.
    #[error("{message}. Fix: {fix}")]
    InvalidConfig {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// The selected backend is unavailable.
    #[error("{message}. Fix: {fix}")]
    BackendUnavailable {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// Submission could not be accepted.
    #[error("{message}. Fix: {fix}")]
    Submission {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// Completion routing failed internally.
    #[error("{message}. Fix: {fix}")]
    Completion {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// Resource exhaustion was hit.
    #[error("{message}. Fix: {fix}")]
    ResourceExhausted {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// The caller attempted an unsupported operation.
    #[error("{message}. Fix: {fix}")]
    Unsupported {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// A cancellation request succeeded.
    #[error("{message}. Fix: {fix}")]
    Canceled {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// The operation timed out.
    #[error("{message}. Fix: {fix}")]
    Timeout {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// Input validation failed.
    #[error("{message}. Fix: {fix}")]
    Validation {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// The current process state is incompatible with the backend.
    #[error("{message}. Fix: {fix}")]
    ProcessState {
        /// Error summary.
        message: Cow<'static, str>,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
    /// A wrapped I/O error.
    #[error("{message}: {source}. Fix: {fix}")]
    Io {
        /// Human-readable context.
        message: Cow<'static, str>,
        /// Source I/O error.
        #[source]
        source: io::Error,
        /// Suggested remediation.
        fix: Cow<'static, str>,
    },
}

impl Error {
    /// Creates an invalid configuration error with a standard fix hint.
    #[must_use]
    pub fn invalid_config(message: impl Into<Cow<'static, str>>) -> Self {
        Self::InvalidConfig {
            message: message.into(),
            fix: Cow::Borrowed("provide a non-zero queue depth and sensible batch sizes"),
        }
    }

    /// Creates an I/O-flavoured error.
    #[must_use]
    pub fn io(
        message: impl Into<Cow<'static, str>>,
        source: io::Error,
        fix: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self::Io {
            message: message.into(),
            source,
            fix: fix.into(),
        }
    }

    /// Creates a validation error.
    #[must_use]
    pub fn validation(
        message: impl Into<Cow<'static, str>>,
        fix: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self::Validation {
            message: message.into(),
            fix: fix.into(),
        }
    }

    /// Creates a submission error.
    #[must_use]
    pub fn submission(
        message: impl Into<Cow<'static, str>>,
        fix: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self::Submission {
            message: message.into(),
            fix: fix.into(),
        }
    }

    /// Creates a completion error.
    #[must_use]
    pub fn completion(
        message: impl Into<Cow<'static, str>>,
        fix: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self::Completion {
            message: message.into(),
            fix: fix.into(),
        }
    }

    /// Creates a resource exhaustion error.
    #[must_use]
    pub fn resource_exhausted(
        message: impl Into<Cow<'static, str>>,
        fix: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self::ResourceExhausted {
            message: message.into(),
            fix: fix.into(),
        }
    }

    /// Creates a backend unavailable error.
    #[must_use]
    pub fn backend_unavailable(
        message: impl Into<Cow<'static, str>>,
        fix: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self::BackendUnavailable {
            message: message.into(),
            fix: fix.into(),
        }
    }

    /// Creates a cancellation error.
    #[must_use]
    pub fn canceled(
        message: impl Into<Cow<'static, str>>,
        fix: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self::Canceled {
            message: message.into(),
            fix: fix.into(),
        }
    }

    /// Creates an unsupported-operation error.
    #[must_use]
    pub fn unsupported(message: impl Into<Cow<'static, str>>) -> Self {
        Self::Unsupported {
            message: message.into(),
            fix: Cow::Borrowed("use a supported backend, platform, or operation mode"),
        }
    }

    /// Creates a timeout error.
    #[must_use]
    pub fn timeout(
        message: impl Into<Cow<'static, str>>,
        fix: impl Into<Cow<'static, str>>,
    ) -> Self {
        Self::Timeout {
            message: message.into(),
            fix: fix.into(),
        }
    }
}