pathrs 0.2.4

// SPDX-License-Identifier: MPL-2.0 OR LGPL-3.0-or-later
/*
 * libpathrs: safe path resolution on Linux
 * Copyright (C) 2019-2025 SUSE LLC
 * Copyright (C) 2026 Aleksa Sarai <cyphar@cyphar.com>
 *
 * == MPL-2.0 ==
 *
 *  This Source Code Form is subject to the terms of the Mozilla Public
 *  License, v. 2.0. If a copy of the MPL was not distributed with this
 *  file, You can obtain one at https://mozilla.org/MPL/2.0/.
 *
 * Alternatively, this Source Code Form may also (at your option) be used
 * under the terms of the GNU Lesser General Public License Version 3, as
 * described below:
 *
 * == LGPL-3.0-or-later ==
 *
 *  This program is free software: you can redistribute it and/or modify it
 *  under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or (at
 *  your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 * Public License  for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License
 *  along with this program. If not, see <https://www.gnu.org/licenses/>.
 */

#![forbid(unsafe_code)]

//! Error types for libpathrs.

// NOTE: This module is mostly a workaround until several issues have been
//       resolved:
//
//  * `std::error::Error::chain` is stabilised.
//  * I figure out a nice way to implement GlobalBacktrace...

use crate::{resolvers::opath::SymlinkStackError, syscalls::Error as SyscallError};

use std::{borrow::Cow, io::Error as IOError};

// TODO: Add a backtrace to Error. We would just need to add an automatic
//       Backtrace::capture() in From. But it's not clear whether we want to
//       export the crate types here without std::backtrace::Backtrace.
// MSRV(1.65): Use std::backtrace::Backtrace.

/// Opaque error type for libpathrs.
///
/// If you wish to do non-trivial error handling with libpathrs errors, use
/// [`Error::kind`] to get an [`ErrorKind`] you can handle programmatically.
#[derive(thiserror::Error, Debug)]
#[error(transparent)]
pub struct Error(#[from] Box<ErrorImpl>);

impl<E: Into<ErrorImpl>> From<E> for Error {
    // TODO: Is there a way to make this not be exported at all?
    #[doc(hidden)]
    fn from(err: E) -> Self {
        Self(Box::new(err.into()))
    }
}

impl Error {
    /// Get the [`ErrorKind`] of this error.
    pub fn kind(&self) -> ErrorKind {
        self.0.kind()
    }

    /// Shorthand for [`.kind().can_retry()`](ErrorKind::can_retry).
    pub fn can_retry(&self) -> bool {
        self.0.kind().can_retry()
    }

    pub(crate) fn is_safety_violation(&self) -> bool {
        self.0.is_safety_violation()
    }

    #[cfg(test)]
    pub(crate) fn into_inner(self) -> ErrorImpl {
        *self.0
    }
}

#[derive(thiserror::Error, Debug)]
pub(crate) enum ErrorImpl {
    #[allow(dead_code)]
    #[error("feature {feature} is not implemented")]
    NotImplemented { feature: Cow<'static, str> },

    #[error("feature {feature} not supported by the system")]
    NotSupported { feature: Cow<'static, str> },

    #[error("invalid {name} argument: {description}")]
    InvalidArgument {
        name: Cow<'static, str>,
        description: Cow<'static, str>,
    },

    #[cfg(feature = "capi")]
    #[error("invalid {name} structure: extra non-zero trailing bytes found")]
    UnsupportedStructureData { name: Cow<'static, str> },

    #[error("violation of safety requirement: {description}")]
    SafetyViolation { description: Cow<'static, str> },

    #[error("broken symlink stack during iteration: {description}")]
    BadSymlinkStackError {
        description: Cow<'static, str>,
        source: SymlinkStackError,
    },

    #[error("{operation} failed")]
    OsError {
        operation: Cow<'static, str>,
        source: IOError,
    },

    #[error("{operation} failed")]
    RawOsError {
        operation: Cow<'static, str>,
        source: SyscallError,
    },

    #[cfg(feature = "capi")]
    #[error("error while parsing c struct: {description}")]
    BytemuckPodCastError {
        description: Cow<'static, str>,
        source: bytemuck::PodCastError,
    },

    #[error("integer parsing failed")]
    ParseIntError(#[from] std::num::ParseIntError),

    // This should never actually get constructed in practice, but is needed so
    // that you can have From<FromStr::Err> work for the no-op FromStr<String>,
    // which in turn is needed for our nice generic str::parse-wrapping APIs.
    #[error("impossible error: infallible error failed")]
    InfallibleError(#[from] std::convert::Infallible),

    #[error("{context}")]
    Wrapped {
        context: Cow<'static, str>,
        source: Box<ErrorImpl>,
    },
}

/// Underlying error class for libpathrs errors.
///
/// This is similar in concept to [`std::io::ErrorKind`]. Note that the
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
#[non_exhaustive]
pub enum ErrorKind {
    /// The requested feature is not implemented in libpathrs.
    NotImplemented,
    /// The requested feature is not supported by the system.
    NotSupported,
    /// The provided arguments to libpathrs were invalid.
    InvalidArgument,
    /// The provided extensible structure argument to the libpathrs C API
    /// contained trailing non-zero data which was not supported.
    #[cfg(feature = "capi")]
    UnsupportedStructureData,
    /// libpaths encountered a state where the safety of the operation could not
    /// be guaranteeed. This is usually the result of an attack by a malicious
    /// program.
    SafetyViolation,
    /// Some internal error occurred. For more information, see the string
    /// description of the original [`Error`].
    InternalError,
    /// The underlying error came from a system call. The provided
    /// [`std::io::RawOsError`] is the numerical value of the `errno` number, if
    /// available.
    // TODO: We might want to use Option<std::io::ErrorKind>?
    OsError(Option<i32>),
}

impl ErrorImpl {
    pub(crate) fn kind(&self) -> ErrorKind {
        match self {
            Self::NotImplemented { .. } => ErrorKind::NotImplemented,
            Self::NotSupported { .. } => ErrorKind::NotSupported,
            Self::InvalidArgument { .. } => ErrorKind::InvalidArgument,
            #[cfg(feature = "capi")]
            Self::UnsupportedStructureData { .. } => ErrorKind::UnsupportedStructureData,
            Self::SafetyViolation { .. } => ErrorKind::SafetyViolation,
            // Any syscall-related errors get mapped to an OsError, since the
            // distinction doesn't matter to users checking error values.
            Self::OsError { source, .. } => ErrorKind::OsError(source.raw_os_error()),
            Self::RawOsError { source, .. } => {
                ErrorKind::OsError(source.root_cause().raw_os_error())
            }
            // These errors are internal error types that we don't want to
            // expose outside of the crate. All that matters to users is that
            // there was some internal error.
            Self::BadSymlinkStackError { .. }
            | Self::ParseIntError(_)
            | Self::InfallibleError(_) => ErrorKind::InternalError,
            #[cfg(feature = "capi")]
            Self::BytemuckPodCastError { .. } => ErrorKind::InternalError,

            Self::Wrapped { source, .. } => source.kind(),
        }
    }

    pub(crate) fn is_safety_violation(&self) -> bool {
        self.kind().is_safety_violation()
    }
}

impl ErrorKind {
    /// Return a C-like errno for the [`ErrorKind`].
    ///
    /// Aside from fetching the errno represented by standard
    /// [`ErrorKind::OsError`] errors, pure-Rust errors are also mapped to C
    /// errno values where appropriate.
    pub(crate) fn errno(&self) -> Option<i32> {
        match self {
            ErrorKind::NotImplemented | ErrorKind::NotSupported => Some(libc::ENOSYS),
            ErrorKind::InvalidArgument => Some(libc::EINVAL),
            #[cfg(feature = "capi")]
            ErrorKind::UnsupportedStructureData => Some(libc::E2BIG),
            ErrorKind::SafetyViolation => Some(libc::EXDEV),
            ErrorKind::OsError(errno) => *errno,
            _ => None,
        }
    }

    /// Indicates whether an [`ErrorKind`] was associated with a transient error
    /// and that the operation might succeed if retried.
    ///
    /// Callers can make use of this if they wish to have custom retry logic.
    pub fn can_retry(&self) -> bool {
        matches!(self.errno(), Some(libc::EAGAIN) | Some(libc::EINTR))
    }

    pub(crate) fn is_safety_violation(&self) -> bool {
        self.errno() == Self::SafetyViolation.errno()
    }
}

// Private trait necessary to work around the "orphan trait" restriction.
pub(crate) trait ErrorExt: Sized {
    /// Wrap a `Result<..., Error>` with an additional context string.
    fn wrap<S: Into<String>>(self, context: S) -> Self {
        self.with_wrap(|| context.into())
    }

    /// Wrap a `Result<..., Error>` with an additional context string created by
    /// a closure.
    fn with_wrap<F>(self, context_fn: F) -> Self
    where
        F: FnOnce() -> String;
}

impl ErrorExt for ErrorImpl {
    fn with_wrap<F>(self, context_fn: F) -> Self
    where
        F: FnOnce() -> String,
    {
        Self::Wrapped {
            context: context_fn().into(),
            source: self.into(),
        }
    }
}

impl ErrorExt for Error {
    fn with_wrap<F>(self, context_fn: F) -> Self
    where
        F: FnOnce() -> String,
    {
        self.0.with_wrap(context_fn).into()
    }
}

impl<T, E: ErrorExt> ErrorExt for Result<T, E> {
    fn with_wrap<F>(self, context_fn: F) -> Self
    where
        F: FnOnce() -> String,
    {
        self.map_err(|err| err.with_wrap(context_fn))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    use pretty_assertions::assert_eq;

    #[test]
    fn error_kind_errno() {
        assert_eq!(
            ErrorKind::InvalidArgument.errno(),
            Some(libc::EINVAL),
            "ErrorKind::InvalidArgument is equivalent to EINVAL"
        );
        assert_eq!(
            ErrorKind::NotImplemented.errno(),
            Some(libc::ENOSYS),
            "ErrorKind::NotImplemented is equivalent to ENOSYS"
        );
        assert_eq!(
            ErrorKind::SafetyViolation.errno(),
            Some(libc::EXDEV),
            "ErrorKind::SafetyViolation is equivalent to EXDEV"
        );
        assert_eq!(
            ErrorKind::OsError(Some(libc::ENOANO)).errno(),
            Some(libc::ENOANO),
            "ErrorKind::OsError(...)::errno() returns the inner errno"
        );
    }
}