pathrs 0.2.4

// 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 std::{
    cmp::{self, Ordering},
    fmt,
};

use once_cell::sync::Lazy;
use rustix::system as rustix_system;

/// A representation of a Linux kernel version that can be mutually compared
/// against, usually to check if a kernel aught to have a particular feature.
///
/// Use [`parse_kernel_version`] to convert a kernel version string (such as
/// returned by `uname -r`) to a [`KernelVersion`].
///
/// # Comparisons #
///
/// Note that the system for comparing kernel versions is not very akin to
/// SemVer because Linux kernel versions can (in principle) have arbitrarily
/// many dot components. If both kernel versions have the same number of
/// components, then the comparison is done left-to-right per-component in a
/// manner identical to the way [`slice`]s are compared. If the kernel versions
/// have different numbers of components then the comparison is done as though
/// the shorter kernel version was right-padded with additional `0` components.
///
/// Thus, `3[.0.0] < 3.1[.0] < 3.1.18 < 4[.0.0]`.
#[derive(Clone, Debug)]
pub(crate) struct KernelVersion(pub(crate) Vec<u64>);

impl fmt::Display for KernelVersion {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(
            f,
            "linux-{}",
            self.0
                .iter()
                .map(ToString::to_string)
                .collect::<Vec<_>>()
                .join(".")
        )
    }
}

impl Ord for KernelVersion {
    fn cmp(&self, other: &Self) -> Ordering {
        // In contrast to regular slices, when comparing kernel versions we
        // effectively zero-extend the trailing part of the shorter kernel
        // version specification (so 3.1.2 > 3.1[.0] > 3[.0.0]).
        let common_len = cmp::min(self.0.len(), other.0.len());
        match self.0[..common_len].cmp(&other.0[..common_len]) {
            // We only need to deal with the annoying trailing end case if the
            // common part is equal.
            Ordering::Equal => match (
                self.0[common_len..].iter().any(|&n| n > 0),
                other.0[common_len..].iter().any(|&n| n > 0),
            ) {
                (false, false) => Ordering::Equal, // all zeros or equal lengths
                (true, false) => Ordering::Greater, // self tail > 0
                (false, true) => Ordering::Less, // other tail > 0
                (true, true) => unreachable!("both KernelVersion slices cannot have non-zero tails because one must be empty"),
            },
            cmp => cmp,
        }
    }
}

impl PartialOrd for KernelVersion {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

impl PartialEq for KernelVersion {
    fn eq(&self, other: &Self) -> bool {
        self.cmp(other) == Ordering::Equal
    }
}

impl Eq for KernelVersion {}

/// Parse a kernel version string like `"4.10.23-1-default"` into a
/// [`KernelVersion`] that can be used for comparisons.
fn parse_kernel_version(kver_str: &str) -> Option<KernelVersion> {
    // Strip off any of the non-version suffixes from the kver string.
    let kver_str = &kver_str[..kver_str
        .find(|ch: char| !ch.is_ascii_digit() && ch != '.')
        .unwrap_or(kver_str.len())];

    let kver = kver_str
        .split('.')
        .map(|num| match num {
            "" => None,            // version components must be non-empty
            _ => num.parse().ok(), // version components must be valid numbers
        })
        .collect::<Option<Vec<_>>>()
        .map(KernelVersion);

    match kver {
        // Versions must have >= 2 components (actually, in practice it's >= 3).
        Some(KernelVersion(ref v)) if v.len() >= 2 => kver,
        _ => None,
    }
}

// MSRV(1.80): Use LazyLock.
pub(crate) static HOST_KERNEL_VERSION: Lazy<KernelVersion> = Lazy::new(host_kernel_version);

pub(crate) fn host_kernel_version() -> KernelVersion {
    parse_kernel_version(&rustix_system::uname().release().to_string_lossy())
        .expect("uname kernel release must be a valid KernelVersion string")
}

/// Returns the result of comparing the kernel version of the running system
/// against the specified kernel version using the specified comparator.
/// `is_kver!(>= 1,2,3)` is equivalent to `is_gte!(1, 2, 3)`.
macro_rules! is_kver {
    ($cmp:tt $($part:literal),+) => {
        {
            $(
                const _: u64 = $part;
            )+

            // Some of our tests rely on using personality(2) to fake older
            // (2.6-era) kernel versions, so we cannot use the cached kernel
            // version when in test builds. However, to make sure that we still
            // test that HOST_KERNEL_VERSION doesn't do anything silly (like
            // crash) we still compute it in our tests.
            let cached_host_kver = &*$crate::utils::kernel_version::HOST_KERNEL_VERSION;
            #[cfg(test)]
            let host_kver = &$crate::utils::kernel_version::host_kernel_version();
            #[cfg(not(test))]
            let host_kver = cached_host_kver;

            #[cfg(test)]
            eprintln!("cached host kernel is {cached_host_kver} but using {host_kver} for test");

            let cmp_kver = &$crate::utils::kernel_version::KernelVersion(vec![$($part),+]);

            host_kver $cmp cmp_kver
        }
    };
}
pub(crate) use is_kver;

/// Returns whether the kernel version of the running system is at least as new
/// as the kernel version specified. See the documentation of [`KernelVersion`]
/// for more information on how kernel versions are compared.
macro_rules! is_gte {
    ($($part:literal),+) => {
        $crate::utils::kernel_version::is_kver!{>= $($part),*}
    };
}
pub(crate) use is_gte;

/// Returns whether the kernel version of the running system is older than the
/// kernel version specified. See the documentation of [`KernelVersion`] for
/// more information on how kernel versions are compared.
macro_rules! is_lt {
    ($($part:literal),+) => {
        $crate::utils::kernel_version::is_kver!{< $($part),*}
    };
}
pub(crate) use is_lt;

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

    use pretty_assertions::assert_eq;

    macro_rules! kver {
        ($($part:literal),+) => {
            KernelVersion(vec![$($part),+])
        };
    }

    #[test]
    fn parse_kernel_version_bad() {
        assert_eq!(parse_kernel_version(""), None);
        assert_eq!(parse_kernel_version("."), None);
        assert_eq!(parse_kernel_version(".."), None);
        assert_eq!(parse_kernel_version(".-foo"), None);
        assert_eq!(parse_kernel_version("1..3"), None);
        assert_eq!(parse_kernel_version("4...2"), None);

        assert_eq!(parse_kernel_version("a.a.a"), None);
        assert_eq!(parse_kernel_version("invalid"), None);
        assert_eq!(parse_kernel_version("foo"), None);
        assert_eq!(parse_kernel_version("foo.1.3.4"), None);

        assert_eq!(parse_kernel_version("-1.2"), None);
        assert_eq!(parse_kernel_version("+1.2"), None);

        assert_eq!(parse_kernel_version("3a"), None);

        assert_eq!(parse_kernel_version(".1"), None);
        assert_eq!(parse_kernel_version(".1.2"), None);

        assert_eq!(parse_kernel_version("3.foo"), None);
        assert_eq!(parse_kernel_version("42.12."), None);
        assert_eq!(parse_kernel_version("4.10.-default"), None);
        assert_eq!(parse_kernel_version("4.10.-default"), None);
    }

    #[test]
    fn parse_kernel_version_good() {
        assert_eq!(parse_kernel_version("3.7"), Some(kver![3, 7]));
        assert_eq!(parse_kernel_version("3.8"), Some(kver![3, 8]));
        assert_eq!(parse_kernel_version("3.8.0"), Some(kver![3, 8, 0]));
        assert_eq!(parse_kernel_version("3.8.12"), Some(kver![3, 8, 12]));
        assert_eq!(
            parse_kernel_version("3.8.12.10.0.2.5912"),
            Some(kver![3, 8, 12, 10, 0, 2, 5912])
        );
        assert_eq!(
            parse_kernel_version("42.12.1000"),
            Some(kver![42, 12, 1000])
        );
    }

    #[test]
    fn parse_kernel_version_with_suffix() {
        assert_eq!(
            parse_kernel_version("2.6.16.48foobar"),
            Some(kver![2, 6, 16, 48])
        );
        assert_eq!(parse_kernel_version("2.6.16f00b4r"), Some(kver![2, 6, 16]));
        assert_eq!(
            parse_kernel_version("2.6.16.13rc2"),
            Some(kver![2, 6, 16, 13])
        );
        assert_eq!(
            parse_kernel_version("2.6.16.13-rc2"),
            Some(kver![2, 6, 16, 13])
        );
        assert_eq!(
            parse_kernel_version("3.8.16-generic"),
            Some(kver![3, 8, 16])
        );
        assert_eq!(
            parse_kernel_version("6.12.49-1-default"),
            Some(kver![6, 12, 49])
        );
        assert_eq!(
            parse_kernel_version("4.9.27-default-foo.12.23"),
            Some(kver![4, 9, 27])
        );
        assert_eq!(parse_kernel_version("5.15.0+debug"), Some(kver![5, 15, 0]));
        assert_eq!(parse_kernel_version("6.1.0~beta1"), Some(kver![6, 1, 0]));
        assert_eq!(
            parse_kernel_version("5.4.0_custom.1.2"),
            Some(kver![5, 4, 0])
        );
        assert_eq!(parse_kernel_version("3.8-4"), Some(kver![3, 8]));
    }

    #[test]
    fn kernel_version_eq_same_length() {
        assert!(kver![3, 8] == kver![3, 8], "3.8 == 3.8");
        assert!(kver![3, 8, 12] == kver![3, 8, 12], "3.8.12 == 3.8.12");
        assert!(kver![0, 0] == kver![0, 0], "0.0 == 0.0");
        assert!(kver![6, 12, 49] == kver![6, 12, 49], "6.12.49 == 6.12.49");
    }

    #[test]
    fn kernel_version_ne() {
        assert!(kver![3, 8, 0] != kver![3, 8, 1], "3.8 != 3.8.1");
        assert!(kver![3, 8, 12] != kver![4, 8, 12], "3.8.12 != 4.8.12");
        assert!(
            kver![6, 12, 49] != kver![6, 12, 49, 1],
            "6.12.49 != 6.12.49.1"
        );
    }

    #[test]
    fn kernel_version_eq_trailing_zeros() {
        // Trailing zeros should be treated as equal.
        assert!(kver![3, 8] == kver![3, 8, 0], "3.8 == 3.8.0");
        assert!(kver![3, 8] == kver![3, 8, 0, 0], "3.8 == 3.8.0.0");
        assert!(kver![3, 8] == kver![3, 8, 0, 0, 0], "3.8 == 3.8.0.0.0");
        assert!(kver![3, 8, 0] == kver![3, 8, 0, 0], "3.8.0 == 3.8.0.0");
        assert!(kver![3, 8, 0] == kver![3, 8], "3.8.0 == 3.8");
        assert!(kver![5, 0, 0, 0] == kver![5, 0], "5.0.0.0 == 5.0");
    }

    #[test]
    fn kernel_version_lt_same_length() {
        assert!(kver![3, 7] < kver![3, 8], "3.7 < 3.8");
        assert!(kver![3, 8] < kver![4, 0], "3.8 < 4.0");
        assert!(kver![3, 8, 11] < kver![3, 8, 12], "3.8.11 < 3.8.12");
        assert!(kver![2, 6, 32] < kver![3, 0, 0], "2.6.32 < 3.0.0");
        assert!(kver![5, 9, 99] < kver![5, 10, 0], "5.9.99 < 5.10.0");
    }

    #[test]
    fn kernel_version_gt_same_length() {
        assert!(kver![3, 8] > kver![3, 7], "3.8 > 3.7");
        assert!(kver![4, 0] > kver![3, 8], "4.0 > 3.8");
        assert!(kver![3, 8, 12] > kver![3, 8, 11], "3.8.12 > 3.8.11");
        assert!(kver![6, 0, 0] > kver![5, 99, 99], "6.0.0 > 5.99.99");
    }

    #[test]
    fn kernel_version_lt_different_length() {
        // Shorter version is effectively zero-padded.
        assert!(kver![3, 1] < kver![3, 1, 1], "3.1[.0] < 3.1.1");
        assert!(kver![3, 1] < kver![3, 1, 18], "3.1[.0] < 3.1.18");
        assert!(kver![3, 0] < kver![3, 0, 0, 1], "3.0[.0.0] < 3.0.0.1");
        assert!(
            kver![5, 4] < kver![5, 4, 0, 0, 1],
            "5.4[.0.0.0] < 5.4.0.0.1"
        );
    }

    #[test]
    fn kernel_version_gt_different_length() {
        assert!(kver![3, 1, 1] > kver![3, 1], "3.1.1 > 3.1[.0]");
        assert!(kver![3, 1, 18] > kver![3, 1], "3.1.18 > 3.1[.0]");
        assert!(kver![3, 0, 0, 1] > kver![3, 0], "3.0.0.1 > 3.0[.0.0]");
        assert!(
            kver![5, 4, 0, 0, 1] > kver![5, 4],
            "5.4.0.0.1 > 5.4[.0.0.0]"
        );
    }

    #[test]
    fn kernel_version_ordering_chain() {
        // Example from the doc comment.
        assert!(kver![3, 0, 0] < kver![3, 1, 0], "3.0.0 < 3.1.0");
        assert!(kver![3, 1, 0] < kver![3, 1, 18], "3.1.0 < 3.1.18");
        assert!(kver![3, 1, 18] < kver![4, 0, 0], "3.1.18 < 4.0.0");

        // Same example with implicit zeros.
        assert!(kver![3] < kver![3, 1], "3[.0] < 3.1");
        assert!(kver![3, 1] < kver![3, 1, 18], "3.1[.0] < 3.1.18");
        assert!(kver![3, 1, 18] < kver![4, 0], "3.1.18 < 4.0[.0]");
    }

    #[test]
    fn kernel_version_cmp_parsed() {
        // Test comparison through parsed strings, like real kernel versions.
        let v3_8 = parse_kernel_version("3.8.0-generic").expect("parse '3.8.0-generic'");
        let v4_10 = parse_kernel_version("4.10.23-1-default").expect("parse '4.10.23-1-default'");
        let v6_12 = parse_kernel_version("6.12.49-1-default").expect("parse '6.12.49-1-default'");

        assert!(v3_8 < v4_10, "3.8.0 < 4.10.23");
        assert!(v4_10 < v6_12, "4.10.23 < 6.12.49");
        assert!(v3_8 < v6_12, "3.8.0 < 6.12.49");

        // Parsed version with trailing zeros should equal shorter form.
        let v5_4_0 = parse_kernel_version("5.4.0").expect("parse '5.4.0'");
        let v5_4 = parse_kernel_version("5.4").expect("parse '5.4'");
        assert!(v5_4_0 == v5_4, "5.4.0 == 5.4");
    }

    #[test]
    fn kernel_version_gte() {
        let v3_8 = parse_kernel_version("3.8.0-ubuntu.22.04").expect("parse '3.8.0-ubuntu.22.04");

        assert!(kver![3, 8] >= v3_8, "3.8 >= 3.8.0-ubuntu.22.04");
        assert!(kver![3, 8, 1] >= v3_8, "3.8.1 >= 3.8.0-ubuntu.22.04");
        assert!(kver![3, 8, 0, 1] >= v3_8, "3.8.0.1 >= 3.8.0-ubuntu.22.04");
        assert!(kver![4] >= v3_8, "4 >= 3.8.0-ubuntu.22.04");
        assert!(kver![4, 0, 0, 0] >= v3_8, "4.0.0.0 >= 3.8.0-ubuntu.22.04");
        assert!(kver![3, 7, 999] < v3_8, "3.7.999 < 3.8.0-ubuntu.22.04");
    }

    #[test]
    fn kernel_version_display() {
        assert_eq!("linux-2", kver![2].to_string(), "Linux 2");
        assert_eq!(
            "linux-2.6.32.182",
            kver![2, 6, 32, 182].to_string(),
            "Linux 2.6.32.182"
        );
        assert_eq!("linux-3.0", kver![3, 0].to_string(), "Linux 3.0");
        assert_eq!(
            "linux-4.1.18.2",
            kver![4, 1, 18, 2].to_string(),
            "Linux 4.1.18.2"
        );
    }

    #[test]
    fn host_kernel_version_uname26() {
        // The UNAME26 personality lets us fake a pre-3.0 kernel version.
        let _persona_guard = syscalls::scoped_personality(syscalls::PER_UNAME26);

        let host_kver = host_kernel_version();
        assert!(
            kver![3, 0] > host_kver,
            "UNAME26 personality should always result in a <3.0 kernel version: got {host_kver:?}"
        );

        assert!(
            !is_gte!(3, 0),
            "UNAME26 personality should always result in a <3.0 kernel version: is_gte!(3, 0) succeeded"
        );

        assert!(
            is_lt!(3, 0),
            "UNAME26 personality should always result in a <3.0 kernel version: is_lt!(3, 0) failed"
        );

        assert!(
            is_kver!(!= 4, 0),
            "UNAME26 personality should always result in a <3.0 kernel version: is_kver!(!= 4, 0) failed"
        );
    }
}