g_err/

gerr.rs

extern crate alloc;

use alloc::boxed::Box;
use alloc::format;
use alloc::string::{String, ToString};
use alloc::vec::Vec;

use crate::gerr_box::GErrBox;
use crate::gerr_source::DataSource;
use crate::gerr_source::GErrSource;
use crate::gerr_source::IdSource;
use crate::types::DefaultConfig;
use crate::types::NoData;

use core::{
    error::Error,
    fmt::{Debug, Display},
    panic::Location,
};

#[cfg(feature = "backtrace")]
use std::backtrace::Backtrace;

use alloc::borrow::Cow;

/// Error config.
pub trait Config {
    /// Error id.
    ///
    /// # Must be:
    /// - Implementing `Display` & `Debug`.
    /// - Implementing serde's Serialize and Deserialize for `serde` feature.
    type Id;

    /// Auto-generate error id.
    ///
    /// Defaults to `None`.
    #[inline]
    fn id() -> Option<Self::Id> {
        None
    }

    /// Error code.
    const CODE: Option<&'static str> = None;

    /// Error tags.
    const TAGS: Option<&'static [&'static str]> = None;

    /// Display error message.
    ///
    /// It will be invoked in `Display` implementation.
    ///
    /// Defaults to `[<id>][<code>] <message>`.
    #[inline]
    fn display<C: Config, D>(gerr: &GErr<C, D>) -> String
    where
        C::Id: Display,
        D: Debug,
    {
        match (gerr.id(), gerr.code()) {
            (Some(id), Some(code)) => format!("[{id}][{code}] {}", gerr.message()),
            (Some(id), None) => format!("[{id}][-] {}", gerr.message()),
            (None, Some(code)) => format!("[-][{code}] {}", gerr.message()),
            (None, None) => format!("[-][-] {}", gerr.message()),
        }
    }
}

/// Trait for upserting error data.
///
/// Self must implement `Default`.
pub trait SetField<K, V> {
    fn set_field(&mut self, key: K, value: V);
}

/// Alias for core's Result.
pub type Result<T, C = DefaultConfig, D = NoData> = core::result::Result<T, GErr<C, D>>;

/// GErr with default config(no id) and no data.
pub type GErrDefault = GErr<DefaultConfig, NoData>;

/// GErr's source
#[derive(Debug)]
pub enum Source {
    /// General error.
    Err(Box<dyn Error + Send + Sync + 'static>),

    // It's boxed to reduce error size.
    /// GErr error.
    GErr(Box<GErrSource>),
}

/// GErr - Structured Error Type.
///
/// It's generically configurable with id, code, data, etc.
///
/// Error location is automatically generated.
///
/// It contains stack-trace if `backtrace` feature is enabled.
///
/// It provides 2 type parameters `C` and `D`:
/// - `C` is for error config. It bounds with [`Config`] trait containing error type configuration.
/// - `D` is for error data.
///
/// GErr contains error as having these attributes:
/// - `id`: The error id. This is to identify the error. It can be autogenerated or from outside(e.g. request id).
/// - `code`: The error code. Acts as label/category/group of errors.
/// - `message`: The error message.
/// - `sources`: The sources of current error. Errors can be linked/chained from multiple errors, serial or parallel.
/// - `tags`: The error tags. Things related to the error. For easy querying.
/// - `data`: The error data. This is additional data about the error. It can be error kinds(enum), user data triggering the errors, etc.
/// - `help`: Hint about how to solve the error.
/// - `location`: Where the error happen.
/// - `backtrace`: The error stacktrace, feature-gated behind `backtrace`.
///
/// # Note
/// Set aside size of error ID and Data:
///
/// - `GErr<DefaultConfig, NoData>` is approximately 160 bytes.
/// - Enabling the `backtrace` feature increases this to approximately
///   208 bytes (+48 bytes from `Backtrace`).
///
/// Clippy's `result_large_err` lint is intentionally allowed for this crate.
/// Users requiring a smaller error representation may box `GErr` in their
/// own APIs or using provided [`GErrBox`].
pub struct GErr<C: Config = DefaultConfig, D = NoData> {
    id: Option<C::Id>,

    code: Option<Cow<'static, str>>,

    message: Cow<'static, str>,

    sources: Option<Vec<Source>>,

    tags: Option<Vec<Cow<'static, str>>>,

    data: Option<D>,

    help: Option<Cow<'static, str>>,

    location: ErrorLocation,

    #[cfg(feature = "backtrace")]
    backtrace: Backtrace,
}

/// Location where error happen.
#[derive(Debug, PartialEq, Eq)]
pub struct ErrorLocation {
    /// Filename of where error happen.
    pub file: Cow<'static, str>,
    /// Line number of where error happen.
    pub line: u32,
    /// Column of where error happen.
    pub column: u32,
}

impl<C: Config, D> GErr<C, D> {
    /// Constructs new GErr with message and auto-generated id.
    #[track_caller]
    #[inline]
    pub fn new<M>(message: M) -> Self
    where
        M: Into<Cow<'static, str>>,
    {
        Self::new_untracked(message, Location::caller())
    }

    #[inline]
    pub(crate) fn new_untracked<M>(message: M, location: &'static Location<'static>) -> Self
    where
        M: Into<Cow<'static, str>>,
    {
        Self::new_with_id_untracked(C::id(), message.into(), location)
    }

    /// Constructs new GErr from any error implementing trait [`Error`]
    ///
    /// Id is auto-generated and only contains message, location and the error as source.
    #[track_caller]
    #[inline]
    pub fn from_error<E>(err: E) -> Self
    where
        E: Error + Send + Sync + 'static,
    {
        Self::new_untracked(err.to_string(), Location::caller()).add_source(err)
    }

    /// Constructs new GErr with id and message.
    ///
    /// This is to set error id manually.
    #[track_caller]
    #[inline]
    pub fn new_with_id<M>(id: C::Id, message: M) -> Self
    where
        M: Into<Cow<'static, str>>,
    {
        Self::new_with_id_untracked(Some(id), message, Location::caller())
    }

    #[inline]
    pub(crate) fn new_with_id_untracked<M>(
        id: Option<C::Id>,
        message: M,
        location: &'static Location<'static>,
    ) -> Self
    where
        M: Into<Cow<'static, str>>,
    {
        Self {
            id,

            code: C::CODE.map(Cow::Borrowed),

            message: message.into(),

            sources: None,

            tags: C::TAGS.map(|tags| {
                tags.iter()
                    .map(|tag| Cow::Borrowed(*tag))
                    .collect::<Vec<_>>()
            }),

            data: None,

            help: None,

            location: location.into(),

            #[cfg(feature = "backtrace")]
            backtrace: Backtrace::capture(),
        }
    }

    /// Constructs new GErr from any error implementing trait [`Error`]
    ///
    /// Id is manually-set and only contains message, location and the error as source.
    #[track_caller]
    #[inline]
    pub fn from_error_with_id<E>(id: C::Id, err: E) -> Self
    where
        E: Error + Send + Sync + 'static,
    {
        Self::new_with_id_untracked(Some(id), err.to_string(), Location::caller()).add_source(err)
    }

    #[track_caller]
    #[inline]
    pub fn from_gerr<E>(gerr: E) -> Self
    where
        E: Into<GErrSource> + Send + Sync + 'static,
    {
        Self::from_gerr_untracked(gerr, Location::caller())
    }

    #[inline]
    pub(crate) fn from_gerr_untracked<E>(gerr: E, location: &'static Location<'static>) -> Self
    where
        E: Into<GErrSource> + Send + Sync + 'static,
    {
        let gerr = gerr.into();
        Self {
            id: C::id(),
            code: C::CODE.map(Cow::Borrowed),
            message: gerr.message,
            sources: gerr.sources,
            tags: C::TAGS.map(|tags| {
                tags.iter()
                    .map(|tag| Cow::Borrowed(*tag))
                    .collect::<Vec<_>>()
            }),
            data: None,
            help: gerr.help,
            location: location.into(),
            #[cfg(feature = "backtrace")]
            backtrace: Backtrace::capture(),
        }
    }
}

impl<C: Config, D> GErr<C, D> {
    /// Set error id.
    #[must_use]
    #[inline]
    pub fn set_id(mut self, id: C::Id) -> Self {
        self.id = Some(id);
        self
    }

    /// set error code.
    #[must_use]
    #[inline]
    pub fn set_code<T>(mut self, code: T) -> Self
    where
        T: Into<Cow<'static, str>>,
    {
        self.code = Some(code.into());
        self
    }

    /// Set list of sources.
    #[must_use]
    #[inline]
    pub fn set_sources<I>(mut self, sources: I) -> Self
    where
        I: IntoIterator<Item = Source>,
    {
        self.sources = Some(sources.into_iter().collect());
        self
    }

    /// Add general error(non-gerr) into list of sources.
    #[must_use]
    #[inline]
    pub fn add_source<E>(mut self, source: E) -> Self
    where
        E: Error + Send + Sync + 'static,
    {
        self.sources
            .get_or_insert_default()
            .push(Source::Err(Box::new(source)));
        self
    }

    /// Add GErr as error source.
    ///
    /// Any errors implementing `Into<GErrSource>` pass.
    #[must_use]
    #[inline]
    pub fn add_source_gerr<E>(mut self, gerr: E) -> Self
    where
        E: Into<GErrSource> + Error + Send + Sync + 'static,
    {
        self.sources
            .get_or_insert_default()
            .push(Source::GErr(Box::new(gerr.into())));
        self
    }

    /// Add tag to GErr.
    #[must_use]
    #[inline]
    pub fn add_tag<T>(mut self, tag: T) -> Self
    where
        T: Into<Cow<'static, str>>,
    {
        self.tags.get_or_insert_default().push(tag.into());
        self
    }

    /// Add multiple tags at once to GErr.
    #[must_use]
    #[inline]
    pub fn add_tags<I, T>(mut self, tags: I) -> Self
    where
        I: IntoIterator<Item = T>,
        T: Into<Cow<'static, str>>,
    {
        let mut tags = tags.into_iter().peekable();
        if tags.peek().is_some() {
            self.tags
                .get_or_insert_default()
                .extend(tags.map(Into::into));
        }
        self
    }

    /// Set error data.
    #[must_use]
    #[inline]
    pub fn set_data(mut self, data: D) -> Self {
        self.data = Some(data);
        self
    }

    /// Set help.
    #[must_use]
    #[inline]
    pub fn set_help<H>(mut self, help: H) -> Self
    where
        H: Into<Cow<'static, str>>,
    {
        self.help = Some(help.into());
        self
    }

    /// Overwrite config type along with associated values.
    #[must_use]
    #[inline]
    pub fn with_config<T: Config>(self) -> GErr<T, D> {
        GErr {
            id: T::id(),
            code: T::CODE.map(Cow::Borrowed),
            message: self.message,
            sources: self.sources,
            tags: T::TAGS.map(|tags| {
                tags.iter()
                    .map(|tag| Cow::Borrowed(*tag))
                    .collect::<Vec<_>>()
            }),
            data: self.data,
            help: self.help,
            location: self.location,
            #[cfg(feature = "backtrace")]
            backtrace: self.backtrace,
        }
    }

    /// Override Data(D) type.
    #[must_use]
    #[inline]
    pub fn with_data_type<T>(self) -> GErr<C, T> {
        GErr {
            id: self.id,
            code: self.code,
            message: self.message,

            sources: self.sources,

            tags: self.tags,

            data: None,

            help: self.help,

            location: self.location,

            #[cfg(feature = "backtrace")]
            backtrace: self.backtrace,
        }
    }

    /// Override Data(D) value and type.
    ///
    /// This returns new GErr with different type of Data.
    #[must_use]
    #[inline]
    pub fn with_data<T>(self, data: T) -> GErr<C, T> {
        GErr {
            id: self.id,
            message: self.message,

            code: self.code,
            sources: self.sources,

            tags: self.tags,

            data: Some(data),

            help: self.help,

            location: self.location,

            #[cfg(feature = "backtrace")]
            backtrace: self.backtrace,
        }
    }

    #[allow(dead_code)]
    #[inline]
    pub(crate) fn set_location(mut self, loc: ErrorLocation) -> Self {
        self.location = loc;
        self
    }

    // --- getter ---

    /// Error id.
    #[inline]
    pub fn id(&self) -> Option<&C::Id> {
        self.id.as_ref()
    }

    /// Error message.
    #[inline]
    pub fn message(&self) -> &str {
        &self.message
    }

    /// Error code.
    #[inline]
    pub fn code(&self) -> Option<&str> {
        self.code.as_deref().or(C::CODE)
    }

    /// Error tags.
    #[inline]
    pub fn tags(&self) -> Option<&[Cow<'static, str>]> {
        self.tags.as_deref()
    }

    /// Error data.
    #[inline]
    pub fn data(&self) -> Option<&D> {
        self.data.as_ref()
    }

    /// Error sources.
    #[inline]
    pub fn sources(&self) -> Option<&[Source]> {
        self.sources.as_deref()
    }

    /// Error location.
    #[inline]
    pub fn location(&self) -> &ErrorLocation {
        &self.location
    }

    /// Error help hint.
    #[inline]
    pub fn help(&self) -> Option<&str> {
        self.help.as_deref()
    }

    /// Error stacktrace, if `backtrace` enabled.
    #[cfg(feature = "backtrace")]
    #[inline]
    pub fn backtrace(&self) -> &std::backtrace::Backtrace {
        &self.backtrace
    }

    /// Returns GErr as `Result<T, GErr<ID, P, D>>`.
    #[inline]
    pub fn result<T>(self) -> Result<T, C, D> {
        Result::Err(self)
    }

    /// Box GErr
    #[inline]
    pub fn boxed(self) -> GErrBox<C, D> {
        Box::new(self)
    }
}

impl<C: Config, D> GErr<C, D> {
    /// Update error data's fields provided that the data implement `Default` and [`SetField`].
    ///
    /// [`SetField`] trait implementation is user-defined.
    #[must_use]
    #[inline]
    pub fn set_field<K, V>(mut self, key: K, value: V) -> Self
    where
        D: Default + SetField<K, V>,
    {
        let data = self.data.get_or_insert_with(Default::default);
        data.set_field(key, value);
        self
    }
}

impl<C: Config, D> Display for GErr<C, D>
where
    C::Id: Display,
    D: Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{}", C::display(self))
    }
}

impl<C: Config, D: Debug> Debug for GErr<C, D>
where
    C::Id: Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        let mut debug = f.debug_struct("GErr");

        debug
            .field("id", &self.id)
            .field("code", &self.code())
            .field("message", &self.message)
            .field("sources", &self.sources)
            .field("tags", &self.tags)
            .field("data", &self.data)
            .field("help", &self.help())
            .field("location", &self.location);

        #[cfg(feature = "backtrace")]
        debug.field("backtrace", &self.backtrace);

        debug.finish()
    }
}

impl<C: Config, D> Error for GErr<C, D>
where
    C::Id: Debug + Display,
    D: Debug,
{
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        if let Some(ref sources) = self.sources
            && !sources.is_empty()
        {
            return sources.first().map(|s| match s {
                Source::Err(e) => &**e as &(dyn Error + 'static),
                Source::GErr(e) => &**e as &(dyn Error + 'static),
            });
        }
        None
    }
}

#[cfg(not(feature = "serde"))]
impl<C: Config, D> From<GErr<C, D>> for GErrSource
where
    C::Id: IdSource + 'static,
    D: DataSource + 'static,
{
    fn from(gerr: GErr<C, D>) -> Self {
        GErrSource {
            id: gerr.id.map(|id| Box::new(id) as Box<dyn IdSource>),
            code: gerr.code,
            message: gerr.message,
            tags: gerr.tags,
            data: gerr.data.map(|d| Box::new(d) as Box<dyn DataSource>),
            help: gerr.help,
            location: Some(gerr.location),
            sources: gerr.sources,
        }
    }
}

#[cfg(not(feature = "serde"))]
impl<C: Config, D> GErr<C, D>
where
    C::Id: IdSource + 'static,
    D: DataSource + 'static,
{
    /// Converts GErr into [`GErrSource`].
    #[inline]
    pub fn into_gerr_source(self) -> GErrSource {
        self.into()
    }
}

#[cfg(feature = "serde")]
impl<C: Config, D> From<GErr<C, D>> for GErrSource
where
    C::Id: ::serde::Serialize + IdSource + 'static,
    D: ::serde::Serialize + DataSource + 'static,
{
    fn from(gerr: GErr<C, D>) -> Self {
        GErrSource {
            id_json: gerr
                .id()
                .map(|id| serde_json::to_value(id).unwrap_or_default()),
            id: gerr.id.map(|id| Box::new(id) as Box<dyn IdSource>),
            code: gerr.code,
            message: gerr.message,
            tags: gerr.tags,
            data_json: gerr
                .data
                .as_ref()
                .map(|d| serde_json::to_value(d).unwrap_or_default()),
            data: gerr.data.map(|d| Box::new(d) as Box<dyn DataSource>),
            help: gerr.help,
            location: Some(gerr.location),
            sources: gerr.sources,
        }
    }
}

#[cfg(feature = "serde")]
impl<C: Config, D> GErr<C, D>
where
    C::Id: ::serde::Serialize + IdSource + 'static,
    D: ::serde::Serialize + DataSource + 'static,
{
    /// Converts GErr into [`GErrSource`].
    #[inline]
    pub fn into_gerr_source(self) -> GErrSource {
        self.into()
    }
}

impl<T, C: Config, D> From<GErr<C, D>> for core::result::Result<T, GErr<C, D>> {
    #[inline]
    fn from(value: GErr<C, D>) -> Self {
        core::result::Result::Err(value)
    }
}

impl From<&'static core::panic::Location<'static>> for ErrorLocation {
    #[inline]
    fn from(location: &'static core::panic::Location<'static>) -> Self {
        Self {
            file: Cow::Borrowed(location.file()),
            line: location.line(),
            column: location.column(),
        }
    }
}