pathrs 0.2.5

// SPDX-License-Identifier: MPL-2.0 OR LGPL-3.0-or-later
/*
 * libpathrs: safe path resolution on Linux
 * 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/>.
 */

use crate::capi::{ret::IntoCReturn, utils};

use std::{mem, ptr};

use bytemuck::{Pod, TransparentWrapper, Zeroable};
use libc::c_int;

#[derive(Debug, Clone, Copy, TransparentWrapper)]
#[repr(transparent)]
pub struct CStringPtr {
    ptr: *const u8,
}

// MSRV(1.88): Use #[derive(Default)].
impl Default for CStringPtr {
    fn default() -> Self {
        Self { ptr: ptr::null() }
    }
}

impl From<&'static str> for CStringPtr {
    fn from(s: &'static str) -> Self {
        s.as_ptr().into()
    }
}

impl From<*const u8> for CStringPtr {
    fn from(ptr: *const u8) -> Self {
        Self { ptr }
    }
}

// SAFETY: This pointer (which must be &'static) is serialised as a u64, which
// is safe to represent and parse. The ban on pointers is mostly about
// semantics, see <https://github.com/Lokathor/bytemuck/discussions/346>.
unsafe impl Zeroable for CStringPtr {}
unsafe impl Pod for CStringPtr {}

/// Represents the version information of the runtime libpathrs library.
#[derive(Debug, Clone, Copy, Default, Pod, Zeroable)]
#[repr(C)]
pub struct VersionInfo {
    /// Pointer to static version string containing the crate version.
    /// cbindgen:rename-all="const char *"
    version_string: CStringPtr,
}

const VERSION_STRING: &str = concat!(env!("CARGO_PKG_VERSION"), "\0");

impl VersionInfo {
    pub(crate) fn new() -> Self {
        Self {
            version_string: VERSION_STRING.into(),
        }
    }
}

/// Return the version information of the libpathrs library at runtime.
///
/// This API is designed to be extensible. The caller must pass a pointer to a
/// contiguous buffer `dst` that is large enough to store `dst_size` bytes. This
/// buffer is then filled with version information. If the library has less data
/// than the given buffer size, the trailing bytes are zero-filled. If the
/// library has more data than the given buffer size the data is truncated and
/// (if the truncated data contained non-zero values), the return value
/// indicates what buffer size is needed to contain all version data.
///
/// # Return Value
///
/// On success, this function returns `0` or (if the version data was truncated)
/// a positive integer that is the size of the buffer needed to store all data.
///
/// If an error occurs, this function will return a negative error code. To
/// retrieve information about the error (such as a string describing the error,
/// the system errno(7) value associated with the error, etc), use
/// pathrs_errorinfo().
#[no_mangle]
pub unsafe extern "C" fn pathrs_version(dst: *mut VersionInfo, dst_size: usize) -> c_int {
    {
        let v = VersionInfo::new();
        // SAFETY: C caller guarantees buffer is at least dst_size and can be
        // written to.
        unsafe { utils::copy_into_extensible_struct(dst, dst_size, &v) }.map(|truncated| {
            if truncated {
                mem::size_of::<VersionInfo>() as isize
            } else {
                0isize // not truncated, return 0
            }
        })
    }
    .into_c_return()
}
utils::symver! {
    fn pathrs_version <- (pathrs_version, version = "LIBPATHRS_0.2.5", default);
}

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

    use std::{mem, ptr};

    use bytemuck::TransparentWrapper;
    use pretty_assertions::assert_eq;

    #[test]
    fn version() {
        let mut info = VersionInfo::default();

        let ret = unsafe { pathrs_version(&mut info as *mut _, mem::size_of::<VersionInfo>()) };
        assert_eq!(
            ret, 0,
            "pathrs_version with sizeof(VersionInfo) should not indicate truncation",
        );
        assert_eq!(
            TransparentWrapper::peel_ref(&info.version_string),
            &VERSION_STRING.as_ptr(),
            "pathrs_version should set info.version_string to VERSION_STRING pointer",
        );
        // TODO: Parse CString and compare to CARGO_PKG_VERSION?
    }

    #[test]
    fn version_zerosize() {
        let mut info = VersionInfo::default();

        let ret = unsafe { pathrs_version(&mut info as *mut _, 0) };
        assert_eq!(
            ret,
            mem::size_of::<VersionInfo>() as i32,
            "pathrs_version with zero size should indicate truncation",
        );
        assert_eq!(
            TransparentWrapper::peel_ref(&info.version_string),
            &ptr::null(),
            "pathrs_version should not modify info.version_string with zero size",
        );
    }

    #[test]
    fn version_null() {
        let ret = unsafe { pathrs_version(ptr::null_mut(), 0) };
        assert_eq!(
            ret,
            mem::size_of::<VersionInfo>() as i32,
            "pathrs_version with NULL and zero size should indicate truncation",
        );
    }
}