vortex_error/

lib.rs

// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright the Vortex contributors

#![deny(missing_docs)]

//! This crate defines error & result types for Vortex.
//! It also contains a variety of useful macros for error handling.

use std::backtrace::Backtrace;
use std::backtrace::BacktraceStatus;
use std::borrow::Cow;
use std::convert::Infallible;
use std::env;
use std::error::Error;
use std::fmt;
use std::fmt::Debug;
use std::fmt::Display;
use std::fmt::Formatter;
use std::io;
use std::num::TryFromIntError;
use std::ops::Deref;
use std::sync::Arc;
use std::sync::LazyLock;

/// A string that can be used as an error message.
#[derive(Debug)]
pub struct ErrString(Cow<'static, str>);

#[expect(
    clippy::fallible_impl_from,
    reason = "intentionally panic in debug mode when VORTEX_PANIC_ON_ERR is set"
)]
impl<T> From<T> for ErrString
where
    T: Into<Cow<'static, str>>,
{
    #[expect(
        clippy::panic,
        reason = "intentionally panic in debug mode when VORTEX_PANIC_ON_ERR is set"
    )]
    fn from(msg: T) -> Self {
        if panic_on_err() {
            panic!("{}\nBacktrace:\n{}", msg.into(), Backtrace::capture());
        } else {
            Self(msg.into())
        }
    }
}

fn panic_on_err() -> bool {
    static PANIC_ON_ERR: LazyLock<bool> =
        LazyLock::new(|| env::var("VORTEX_PANIC_ON_ERR").is_ok_and(|v| v == "1"));
    *PANIC_ON_ERR
}

impl AsRef<str> for ErrString {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl Deref for ErrString {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl Display for ErrString {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        Display::fmt(&self.0, f)
    }
}

impl From<Infallible> for VortexError {
    fn from(_: Infallible) -> Self {
        unreachable!()
    }
}

const _: () = assert!(size_of::<VortexError>() < 128);

/// The top-level error type for Vortex.
#[non_exhaustive]
pub enum VortexError {
    /// A catch-all error variant
    Other(ErrString, Box<Backtrace>),
    /// A wrapped external error
    External(Box<dyn Error + Send + Sync + 'static>, Box<Backtrace>),
    /// An index is out of bounds.
    OutOfBounds(usize, usize, usize, Box<Backtrace>),
    /// An error occurred while executing a compute kernel.
    Compute(ErrString, Box<Backtrace>),
    /// An invalid argument was provided.
    InvalidArgument(ErrString, Box<Backtrace>),
    /// An error occurred while serializing or deserializing.
    Serde(ErrString, Box<Backtrace>),
    /// An unimplemented function was called.
    NotImplemented(ErrString, ErrString, Box<Backtrace>),
    /// A type mismatch occurred.
    MismatchedTypes(ErrString, ErrString, Box<Backtrace>),
    /// An assertion failed.
    AssertionFailed(ErrString, Box<Backtrace>),
    /// A wrapper for other errors, carrying additional context.
    Context(ErrString, Box<VortexError>),
    /// A wrapper for shared errors that require cloning.
    Shared(Arc<VortexError>),
    /// A wrapper for errors from the Arrow library.
    Arrow(arrow_schema::ArrowError, Box<Backtrace>),
    /// A wrapper for errors from the FlatBuffers library.
    #[cfg(feature = "flatbuffers")]
    FlatBuffers(flatbuffers::InvalidFlatbuffer, Box<Backtrace>),
    /// A wrapper for formatting errors.
    Fmt(fmt::Error, Box<Backtrace>),
    /// A wrapper for IO errors.
    Io(io::Error, Box<Backtrace>),
    /// A wrapper for errors from the Object Store library.
    #[cfg(feature = "object_store")]
    ObjectStore(object_store::Error, Box<Backtrace>),
    /// A wrapper for errors from the Jiff library.
    Jiff(jiff::Error, Box<Backtrace>),
    /// A wrapper for Tokio join error.
    #[cfg(feature = "tokio")]
    Join(tokio::task::JoinError, Box<Backtrace>),
    /// Wrap errors for fallible integer casting.
    TryFromInt(TryFromIntError, Box<Backtrace>),
    /// Wrap protobuf-related errors
    Prost(Box<dyn Error + Send + Sync + 'static>, Box<Backtrace>),
}

impl VortexError {
    /// Adds additional context to an error.
    pub fn with_context<T: Into<ErrString>>(self, msg: T) -> Self {
        VortexError::Context(msg.into(), Box::new(self))
    }

    /// Error prefix by variant
    fn variant_prefix(&self) -> &'static str {
        use VortexError::*;

        match self {
            Other(..) => "Other error: ",
            External(..) => "External error: ",
            OutOfBounds(..) => "Out of bounds error: ",
            Compute(..) => "Compute error: ",
            InvalidArgument(..) => "Invalid argument error: ",
            Serde(..) => "Serde error: ",
            NotImplemented(..) => "Not implemented error: ",
            MismatchedTypes(..) => "Mismatched types error: ",
            AssertionFailed(..) => "Assertion failed error: ",
            Context(..) | Shared(..) => "", // basically delegate to the underlying one
            Arrow(..) => "Arrow error: ",
            #[cfg(feature = "flatbuffers")]
            FlatBuffers(..) => "Flat buffers error: ",
            Fmt(..) => "Fmt: ",
            Io(..) => "Io: ",
            #[cfg(feature = "object_store")]
            ObjectStore(..) => "Object store error: ",
            Jiff(..) => "Jiff error: ",
            #[cfg(feature = "tokio")]
            Join(..) => "Tokio join error:",
            TryFromInt(..) => "Try from int error:",
            Prost(..) => "Prost error:",
        }
    }

    fn backtrace(&self) -> Option<&Backtrace> {
        use VortexError::*;

        match self {
            Other(.., bt) => Some(bt.as_ref()),
            External(.., bt) => Some(bt.as_ref()),
            OutOfBounds(.., bt) => Some(bt.as_ref()),
            Compute(.., bt) => Some(bt.as_ref()),
            InvalidArgument(.., bt) => Some(bt.as_ref()),
            Serde(.., bt) => Some(bt.as_ref()),
            NotImplemented(.., bt) => Some(bt.as_ref()),
            MismatchedTypes(.., bt) => Some(bt.as_ref()),
            AssertionFailed(.., bt) => Some(bt.as_ref()),
            Arrow(.., bt) => Some(bt.as_ref()),
            #[cfg(feature = "flatbuffers")]
            FlatBuffers(.., bt) => Some(bt.as_ref()),
            Fmt(.., bt) => Some(bt.as_ref()),
            Io(.., bt) => Some(bt.as_ref()),
            #[cfg(feature = "object_store")]
            ObjectStore(.., bt) => Some(bt.as_ref()),
            Jiff(.., bt) => Some(bt.as_ref()),
            #[cfg(feature = "tokio")]
            Join(.., bt) => Some(bt.as_ref()),
            TryFromInt(.., bt) => Some(bt.as_ref()),
            Prost(.., bt) => Some(bt.as_ref()),
            Context(_, inner) => inner.backtrace(),
            Shared(inner) => inner.backtrace(),
        }
    }

    fn message(&self) -> String {
        use VortexError::*;

        match self {
            Other(msg, _) => msg.to_string(),
            External(err, _) => err.to_string(),
            OutOfBounds(idx, start, stop, _) => {
                format!("index {idx} out of bounds from {start} to {stop}")
            }
            Compute(msg, _) | InvalidArgument(msg, _) | Serde(msg, _) | AssertionFailed(msg, _) => {
                format!("{msg}")
            }
            NotImplemented(func, by_whom, _) => {
                format!("function {func} not implemented for {by_whom}")
            }
            MismatchedTypes(expected, actual, _) => {
                format!("expected type: {expected} but instead got {actual}")
            }
            Context(msg, inner) => {
                format!("{msg}:\n  {inner}")
            }
            Shared(inner) => inner.message(),
            Arrow(err, _) => {
                format!("{err}")
            }
            #[cfg(feature = "flatbuffers")]
            FlatBuffers(err, _) => {
                format!("{err}")
            }
            Fmt(err, _) => {
                format!("{err}")
            }
            Io(err, _) => {
                format!("{err}")
            }
            #[cfg(feature = "object_store")]
            ObjectStore(err, _) => {
                format!("{err}")
            }
            Jiff(err, _) => {
                format!("{err}")
            }
            #[cfg(feature = "tokio")]
            Join(err, _) => {
                format!("{err}")
            }
            TryFromInt(err, _) => {
                format!("{err}")
            }
            Prost(err, _) => {
                format!("{err}")
            }
        }
    }
}

impl Display for VortexError {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.variant_prefix())?;
        write!(f, "{}", self.message())?;
        if let Some(backtrace) = self.backtrace()
            && backtrace.status() == BacktraceStatus::Captured
        {
            write!(f, "\nBacktrace:\n{backtrace}")?;
        }

        Ok(())
    }
}

impl Debug for VortexError {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "{self}")
    }
}

impl Error for VortexError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        use VortexError::*;

        match self {
            External(err, _) => Some(err.as_ref()),
            Context(_, inner) => inner.source(),
            Shared(inner) => inner.source(),
            Arrow(err, _) => Some(err),
            #[cfg(feature = "flatbuffers")]
            FlatBuffers(err, _) => Some(err),
            Io(err, _) => Some(err),
            #[cfg(feature = "object_store")]
            ObjectStore(err, _) => Some(err),
            Jiff(err, _) => Some(err),
            #[cfg(feature = "tokio")]
            Join(err, _) => Some(err),
            Prost(err, _) => Some(err.as_ref()),
            _ => None,
        }
    }
}

/// A type alias for Results that return VortexErrors as their error type.
pub type VortexResult<T> = Result<T, VortexError>;

/// A vortex result that can be shared or cloned.
pub type SharedVortexResult<T> = Result<T, Arc<VortexError>>;

impl From<Arc<VortexError>> for VortexError {
    fn from(value: Arc<VortexError>) -> Self {
        Self::from(&value)
    }
}

impl From<&Arc<VortexError>> for VortexError {
    fn from(e: &Arc<VortexError>) -> Self {
        if let VortexError::Shared(e_inner) = e.as_ref() {
            // don't re-wrap
            VortexError::Shared(Arc::clone(e_inner))
        } else {
            VortexError::Shared(Arc::clone(e))
        }
    }
}

/// A trait for expect-ing a VortexResult or an Option.
pub trait VortexExpect {
    /// The type of the value being expected.
    type Output;

    /// Returns the value of the result if it is Ok, otherwise panics with the error.
    /// Should be called only in contexts where the error condition represents a bug (programmer error).
    ///
    /// # `&'static` message lifetime
    ///
    /// The panic string argument should be a string literal, hence the `&'static` lifetime. If
    /// you'd like to panic with a dynamic format string, consider using `unwrap_or_else` combined
    /// with the `vortex_panic!` macro instead.
    fn vortex_expect(self, msg: &'static str) -> Self::Output;
}

impl<T, E> VortexExpect for Result<T, E>
where
    E: Into<VortexError>,
{
    type Output = T;

    #[allow(clippy::inline_always)]
    #[inline(always)]
    fn vortex_expect(self, msg: &'static str) -> Self::Output {
        match self {
            Ok(value) => value,
            Err(err) => __private::result_expect_failed(err, msg),
        }
    }
}

impl<T> VortexExpect for Option<T> {
    type Output = T;

    #[allow(clippy::inline_always)]
    #[inline(always)]
    fn vortex_expect(self, msg: &'static str) -> Self::Output {
        match self {
            Some(value) => value,
            None => __private::option_expect_failed(msg),
        }
    }
}

/// A convenient macro for creating a VortexError.
#[macro_export]
macro_rules! vortex_err {
    (Other: $($tts:tt)*) => {
        $crate::__private::fmt_err($crate::VortexError::Other, &format_args!($($tts)*))
    };
    (AssertionFailed: $($tts:tt)*) => {
        $crate::__private::fmt_err($crate::VortexError::AssertionFailed, &format_args!($($tts)*))
    };
    (IOError: $($tts:tt)*) => {{
        use std::backtrace::Backtrace;
        $crate::__private::must_use(
            $crate::VortexError::IOError(err_string.into(), Box::new(Backtrace::capture()))
        )
    }};
    (OutOfBounds: $idx:expr, $start:expr, $stop:expr) => {
        $crate::__private::out_of_bounds($idx, $start, $stop)
    };
    (NotImplemented: $func:expr, $by_whom:expr) => {
        $crate::__private::not_implemented($func, &format_args!("{}", $by_whom))
    };
    (MismatchedTypes: $expected:expr, $actual:expr) => {
        $crate::__private::mismatched_types(&$expected, &$actual)
    };
    (Context: $msg:literal, $err:expr) => {
        $crate::__private::context($msg, $err)
    };
    (External: $err:expr) => {
        $crate::__private::external($err)
    };
    ($variant:ident: $fmt:literal $(, $arg:expr)* $(,)?) => {
        $crate::__private::fmt_err($crate::VortexError::$variant, &format_args!($fmt $(, $arg)*))
    };
    ($variant:ident: $err:expr $(,)?) => {
        $crate::__private::must_use(
            $crate::VortexError::$variant($err)
        )
    };
    ($fmt:literal $(, $arg:expr)* $(,)?) => {
        $crate::vortex_err!(Other: $fmt, $($arg),*)
    };
}

/// A convenience macro for returning a VortexError.
#[macro_export]
macro_rules! vortex_bail {
    ($($tt:tt)+) => {
        return Err($crate::vortex_err!($($tt)+))
    };
}

/// A macro that mirrors `assert!` but instead of panicking on a failed condition,
/// it will immediately return an erroneous `VortexResult` to the calling context.
#[macro_export]
macro_rules! vortex_ensure {
    ($cond:expr) => {
        $crate::vortex_ensure!($cond, AssertionFailed: "{}", stringify!($cond));
    };
    ($cond:expr, $($tt:tt)*) => {
        if !$cond {
            $crate::vortex_bail!($($tt)*);
        }
    };
}

/// A macro that mirrors `assert_eq!` but instead of panicking when `left != right`, it will
/// immediately return an erroneous `VortexResult` to the calling context.
///
/// Both values must implement [`PartialEq`] and [`Display`], and each is
/// evaluated exactly once. Use [`vortex_ensure!`] for values that do not implement `Display`.
///
/// By default this returns an [`AssertionFailed`](VortexError::AssertionFailed) error that
/// shows both expressions and their values, so most callers do not need a message:
///
/// ```
/// # use vortex_error::{VortexResult, vortex_ensure_eq};
/// fn check(len: usize) -> VortexResult<()> {
///     vortex_ensure_eq!(len, 2);
///     Ok(())
/// }
///
/// let err = check(3).unwrap_err().to_string();
/// assert!(err.starts_with("Assertion failed error: `len == 2`\n  left: 3\n right: 2"));
/// ```
///
/// A custom message, optionally prefixed with an error variant, replaces the expressions. The
/// values are still appended, so the message does not need to repeat them:
///
/// ```
/// # use vortex_error::{VortexResult, vortex_ensure_eq};
/// fn check(len: usize) -> VortexResult<()> {
///     vortex_ensure_eq!(len, 2, InvalidArgument: "map entries must have {} fields", 2);
///     Ok(())
/// }
///
/// let err = check(3).unwrap_err().to_string();
/// assert!(err.starts_with(
///     "Invalid argument error: map entries must have 2 fields\n  left: 3\n right: 2"
/// ));
/// ```
#[macro_export]
macro_rules! vortex_ensure_eq {
    ($left:expr, $right:expr $(,)?) => {
        match (&$left, &$right) {
            (left_val, right_val) => {
                if *left_val != *right_val {
                    $crate::vortex_bail!(
                        AssertionFailed: "`{} == {}`\n  left: {}\n right: {}",
                        stringify!($left),
                        stringify!($right),
                        left_val,
                        right_val
                    );
                }
            }
        }
    };
    ($left:expr, $right:expr, $variant:ident: $fmt:literal $(, $arg:expr)* $(,)?) => {
        match (&$left, &$right) {
            (left_val, right_val) => {
                if *left_val != *right_val {
                    $crate::vortex_bail!(
                        $variant: "{}\n  left: {}\n right: {}",
                        format_args!($fmt $(, $arg)*),
                        left_val,
                        right_val
                    );
                }
            }
        }
    };
    ($left:expr, $right:expr, $fmt:literal $(, $arg:expr)* $(,)?) => {
        $crate::vortex_ensure_eq!($left, $right, Other: $fmt $(, $arg)*)
    };
}

/// A convenient macro for panicking with a VortexError in the presence of a programmer error
/// (e.g., an invariant has been violated).
#[macro_export]
macro_rules! vortex_panic {
    (OutOfBounds: $idx:expr, $start:expr, $stop:expr) => {{
        $crate::vortex_panic!($crate::vortex_err!(OutOfBounds: $idx, $start, $stop))
    }};
    (NotImplemented: $func:expr, $for_whom:expr) => {{
        $crate::vortex_panic!($crate::vortex_err!(NotImplemented: $func, $for_whom))
    }};
    (MismatchedTypes: $expected:literal, $actual:expr) => {{
        $crate::vortex_panic!($crate::vortex_err!(MismatchedTypes: $expected, $actual))
    }};
    (MismatchedTypes: $expected:expr, $actual:expr) => {{
        $crate::vortex_panic!($crate::vortex_err!(MismatchedTypes: $expected, $actual))
    }};
    (Context: $msg:literal, $err:expr) => {{
        $crate::vortex_panic!($crate::vortex_err!(Context: $msg, $err))
    }};
    ($variant:ident: $fmt:literal $(, $arg:expr)* $(,)?) => {
        $crate::vortex_panic!($crate::vortex_err!($variant: $fmt, $($arg),*))
    };
    ($err:expr, $fmt:literal $(, $arg:expr)* $(,)?) => {
        $crate::__private::panic_err_ctx($err, &format_args!($fmt $(, $arg)*))
    };
    ($fmt:literal $(, $arg:expr)* $(,)?) => {
        $crate::__private::panic_fmt(&format_args!($fmt $(, $arg)*))
    };
    ($err:expr) => {
        $crate::__private::panic_err($err)
    };
}

impl From<arrow_schema::ArrowError> for VortexError {
    fn from(value: arrow_schema::ArrowError) -> Self {
        VortexError::Arrow(value, Box::new(Backtrace::capture()))
    }
}

#[cfg(feature = "flatbuffers")]
impl From<flatbuffers::InvalidFlatbuffer> for VortexError {
    fn from(value: flatbuffers::InvalidFlatbuffer) -> Self {
        VortexError::FlatBuffers(value, Box::new(Backtrace::capture()))
    }
}

impl From<io::Error> for VortexError {
    fn from(value: io::Error) -> Self {
        VortexError::Io(value, Box::new(Backtrace::capture()))
    }
}

#[cfg(feature = "object_store")]
impl From<object_store::Error> for VortexError {
    fn from(value: object_store::Error) -> Self {
        VortexError::ObjectStore(value, Box::new(Backtrace::capture()))
    }
}

impl From<jiff::Error> for VortexError {
    fn from(value: jiff::Error) -> Self {
        VortexError::Jiff(value, Box::new(Backtrace::capture()))
    }
}

#[cfg(feature = "tokio")]
impl From<tokio::task::JoinError> for VortexError {
    fn from(value: tokio::task::JoinError) -> Self {
        if value.is_panic() {
            std::panic::resume_unwind(value.into_panic())
        } else {
            VortexError::Join(value, Box::new(Backtrace::capture()))
        }
    }
}

impl From<TryFromIntError> for VortexError {
    fn from(value: TryFromIntError) -> Self {
        VortexError::TryFromInt(value, Box::new(Backtrace::capture()))
    }
}

impl From<prost::EncodeError> for VortexError {
    fn from(value: prost::EncodeError) -> Self {
        Self::Prost(Box::new(value), Box::new(Backtrace::capture()))
    }
}

impl From<prost::DecodeError> for VortexError {
    fn from(value: prost::DecodeError) -> Self {
        Self::Prost(Box::new(value), Box::new(Backtrace::capture()))
    }
}

impl From<prost::UnknownEnumValue> for VortexError {
    fn from(value: prost::UnknownEnumValue) -> Self {
        Self::Prost(Box::new(value), Box::new(Backtrace::capture()))
    }
}

/// We want our error handlers to be fast in the happy path, so we inline them.
/// However, if we inline them as is, the call site gets the cold branch with
/// panic! macros which gets expanded into backtrace collection and throwing.
/// LLVM inliner/vectoriser in turn doesn't vectorize some code.
/// So we inline only the happy path, the error path gets to a cold handler which
/// is never inlined and thus doesn't prevent vectorization.
#[doc(hidden)]
#[expect(
    clippy::panic,
    reason = "cold handlers for vortex_panic!/vortex_expect intentionally panic"
)]
pub mod __private {
    use std::backtrace::Backtrace;
    use std::error::Error;
    use std::fmt;
    use std::fmt::Arguments;

    use crate::ErrString;
    use crate::VortexError;

    #[doc(hidden)]
    #[inline]
    #[cold]
    #[must_use]
    pub const fn must_use(error: VortexError) -> VortexError {
        error
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    #[must_use]
    pub fn fmt_err(
        variant: fn(ErrString, Box<Backtrace>) -> VortexError,
        args: &Arguments<'_>,
    ) -> VortexError {
        variant(args.to_string().into(), Box::new(Backtrace::capture()))
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    #[must_use]
    pub fn out_of_bounds(idx: usize, start: usize, stop: usize) -> VortexError {
        VortexError::OutOfBounds(idx, start, stop, Box::new(Backtrace::capture()))
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    #[must_use]
    pub fn not_implemented(func: impl Into<ErrString>, by_whom: &Arguments<'_>) -> VortexError {
        VortexError::NotImplemented(
            func.into(),
            by_whom.to_string().into(),
            Box::new(Backtrace::capture()),
        )
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    #[must_use]
    pub fn mismatched_types(expected: &dyn fmt::Display, actual: &dyn fmt::Display) -> VortexError {
        VortexError::MismatchedTypes(
            expected.to_string().into(),
            actual.to_string().into(),
            Box::new(Backtrace::capture()),
        )
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    #[must_use]
    pub fn context(msg: &'static str, err: VortexError) -> VortexError {
        VortexError::Context(msg.into(), Box::new(err))
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    #[must_use]
    pub fn external(err: impl Into<Box<dyn Error + Send + Sync + 'static>>) -> VortexError {
        VortexError::External(err.into(), Box::new(Backtrace::capture()))
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    pub fn panic_err(err: VortexError) -> ! {
        panic!("{err}")
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    pub fn panic_fmt(args: &Arguments<'_>) -> ! {
        panic!(
            "{}",
            VortexError::Other(args.to_string().into(), Box::new(Backtrace::capture()))
        )
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    pub fn panic_err_ctx(err: VortexError, args: &Arguments<'_>) -> ! {
        panic!("{}", err.with_context(args.to_string()))
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    pub fn result_expect_failed(err: impl Into<VortexError>, msg: &'static str) -> ! {
        panic!("{}", err.into().with_context(msg))
    }

    #[doc(hidden)]
    #[cold]
    #[inline(never)]
    pub fn option_expect_failed(msg: &'static str) -> ! {
        panic!(
            "{}",
            VortexError::AssertionFailed(msg.into(), Box::new(Backtrace::capture()))
        )
    }
}