bare_types/sys/

kernel_version.rs

//! Kernel version type for system information.
//!
//! This module provides a type-safe abstraction for kernel versions,
//! ensuring valid version number parsing and comparison.
//!
//! Kernel versions typically follow semantic versioning (major.minor.patch)
//! with an optional release/build string.
//!
//! # Examples
//!
//! ```rust
//! use bare_types::sys::KernelVersion;
//!
//! // Parse from string
//! let version: KernelVersion = "6.8.0-40-generic".parse()?;
//!
//! // Access components
//! assert_eq!(version.major(), 6);
//! assert_eq!(version.minor(), 8);
//! assert_eq!(version.patch(), 0);
//!
//! // Get release string
//! assert_eq!(version.release(), Some("40-generic"));
//!
//! // Compare versions
//! assert!(version >= KernelVersion::new(6, 0, 0));
//! # Ok::<(), bare_types::sys::KernelVersionError>(())
//! ```
use core::fmt;
use core::str::FromStr;

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

/// Error type for kernel version parsing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum KernelVersionError {
    /// Empty version string
    ///
    /// The provided string is empty. Kernel version strings must contain at least
    /// major and a minor version number (e.g., "6.8").
    Empty,
    /// Invalid major version number
    ///
    /// The major version component could not be parsed as a valid u16 number.
    /// Kernel version numbers must be non-negative integers.
    InvalidMajor,
    /// Invalid minor version number
    ///
    /// The minor version component could not be parsed as a valid u16 number.
    /// Kernel version numbers must be non-negative integers.
    InvalidMinor,
    /// Invalid patch version number
    ///
    /// The patch version component could not be parsed as a valid u16 number.
    /// Kernel version numbers must be non-negative integers.
    InvalidPatch,
    /// Too many numeric components (max 3)
    ///
    /// Kernel version strings can have at most 3 numeric components:
    /// major.minor.patch. More than 3 components are not supported.
    TooManyComponents,
    /// Not enough numeric components (need at least 2)
    ///
    /// Kernel version strings must contain at least major and minor components.
    /// Only a patch number (e.g., "6") is not sufficient.
    NotEnoughComponents,
    /// Negative version number
    ///
    /// Kernel version numbers cannot be negative. This error may occur if parsing
    /// negative integers in version components.
    NegativeVersion,
}

impl fmt::Display for KernelVersionError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => write!(f, "kernel version string is empty"),
            Self::InvalidMajor => write!(f, "invalid major kernel version number"),
            Self::InvalidMinor => write!(f, "invalid minor kernel version number"),
            Self::InvalidPatch => write!(f, "invalid patch kernel version number"),
            Self::TooManyComponents => {
                write!(f, "kernel version has too many numeric components (max 3)")
            }
            Self::NotEnoughComponents => {
                write!(f, "kernel version needs at least 2 numeric components")
            }
            Self::NegativeVersion => write!(f, "kernel version numbers cannot be negative"),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for KernelVersionError {}

/// Kernel version.
///
/// This type provides type-safe kernel version numbers with three numeric
/// components (major, minor, patch) and an optional release string.
///
/// # Format
///
/// Kernel version format: `major.minor.patch[-release]`
///
/// - **Major**: Major version number (e.g., 6 for Linux 6.x)
/// - **Minor**: Minor version number (e.g., 8 for Linux 6.8)
/// - **Patch**: Patch level (e.g., 0 for Linux 6.8.0)
/// - **Release**: Optional release string (e.g., "40-generic" for Ubuntu)
///
/// # Invariants
///
/// - Major, minor, and patch versions are always present (u16)
/// - Release string is optional and must not contain leading '-'
/// - All version numbers are non-negative
///
/// # Examples
///
/// ```rust
/// use bare_types::sys::KernelVersion;
///
/// // Create from components
/// let version = KernelVersion::new(6, 8, 0);
///
/// // With release string
/// let version = KernelVersion::with_release(6, 8, 0, "40-generic");
///
/// // Parse from string
/// let version: KernelVersion = "6.8.0-40-generic".parse()?;
/// assert_eq!(version.major(), 6);
/// assert_eq!(version.release(), Some("40-generic"));
/// # Ok::<(), bare_types::sys::KernelVersionError>(())
/// ```
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct KernelVersion {
    /// The major version number
    major: u16,
    /// The minor version number
    minor: u16,
    /// The patch version number
    patch: u16,
    /// The optional release/build string
    release: Option<heapless::String<64>>,
}

impl KernelVersion {
    /// Creates a new kernel version from components.
    ///
    /// # Arguments
    ///
    /// * `major` - The major version number
    /// * `minor` - The minor version number
    /// * `patch` - The patch version number
    ///
    /// To include a release string, use [`KernelVersion::with_release`].
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// // Simple version
    /// let version = KernelVersion::new(6, 8, 0);
    /// assert_eq!(version.major(), 6);
    /// assert_eq!(version.minor(), 8);
    /// assert_eq!(version.patch(), 0);
    /// assert_eq!(version.release(), None);
    ///
    /// // With release string
    /// let version = KernelVersion::with_release(6, 8, 0, "40-generic");
    /// assert_eq!(version.release(), Some("40-generic"));
    /// ```
    #[must_use]
    pub const fn new(major: u16, minor: u16, patch: u16) -> Self {
        Self {
            major,
            minor,
            patch,
            release: None,
        }
    }

    /// Creates a new kernel version with a release string.
    ///
    /// This is a convenience method for creating a kernel version with
    /// a release/build string. For versions without a release string,
    /// use [`KernelVersion::new`].
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::with_release(6, 8, 0, "40-generic");
    /// assert_eq!(version.release(), Some("40-generic"));
    /// ```
    #[must_use]
    pub fn with_release(major: u16, minor: u16, patch: u16, release: &str) -> Self {
        let mut rel_str: heapless::String<64> = heapless::String::new();
        // Ignore error, truncation is acceptable for release strings
        let _ = rel_str.push_str(release);

        Self {
            major,
            minor,
            patch,
            release: Some(rel_str),
        }
    }

    /// Returns the major version number.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::new(6, 8, 0);
    /// assert_eq!(version.major(), 6);
    /// ```
    #[must_use]
    #[inline]
    pub const fn major(&self) -> u16 {
        self.major
    }

    /// Returns the minor version number.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::new(6, 8, 0);
    /// assert_eq!(version.minor(), 8);
    /// ```
    #[must_use]
    #[inline]
    pub const fn minor(&self) -> u16 {
        self.minor
    }

    /// Returns the patch version number.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::new(6, 8, 0);
    /// assert_eq!(version.patch(), 0);
    /// ```
    #[must_use]
    #[inline]
    pub const fn patch(&self) -> u16 {
        self.patch
    }

    /// Returns the optional release string.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::with_release(6, 8, 0, "40-generic");
    /// assert_eq!(version.release(), Some("40-generic"));
    ///
    /// let version = KernelVersion::new(6, 8, 0);
    /// assert_eq!(version.release(), None);
    /// ```
    #[must_use]
    #[inline]
    pub fn release(&self) -> Option<&str> {
        self.release.as_deref()
    }

    /// Returns `true` if this is a development/pre-release kernel.
    ///
    /// A kernel is considered a development kernel if the minor version
    /// is odd (Linux convention: odd minor = development, even = stable).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// // Development kernels have odd minor versions
    /// assert!(KernelVersion::new(6, 7, 0).is_development());
    ///
    /// // Stable kernels have even minor versions
    /// assert!(!KernelVersion::new(6, 8, 0).is_development());
    /// ```
    #[must_use]
    pub const fn is_development(&self) -> bool {
        // Linux convention: odd minor = development, even = stable
        self.minor % 2 == 1
    }

    /// Returns `true` if this is a stable kernel.
    ///
    /// A kernel is considered stable if the minor version is even
    /// (Linux convention).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// assert!(KernelVersion::new(6, 8, 0).is_stable());
    /// assert!(!KernelVersion::new(6, 7, 0).is_stable());
    /// ```
    #[must_use]
    pub const fn is_stable(&self) -> bool {
        !self.is_development()
    }

    /// Returns `true` if this is a long-term support (LTS) kernel.
    ///
    /// This checks if the release string contains "lts" (case-insensitive).
    /// Note: This is a heuristic and may not be accurate for all distros.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let lts = KernelVersion::with_release(6, 1, 0, "lts");
    /// assert!(lts.is_lts());
    ///
    /// let regular = KernelVersion::new(6, 8, 0);
    /// assert!(!regular.is_lts());
    /// ```
    #[must_use]
    #[inline]
    pub fn is_lts(&self) -> bool {
        self.release
            .as_ref()
            .is_some_and(|r| r.to_lowercase().contains("lts"))
    }

    /// Returns a tuple of (major, minor, patch) for comparison.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::new(6, 8, 0);
    /// assert_eq!(version.as_tuple(), (6, 8, 0));
    /// ```
    #[must_use]
    pub const fn as_tuple(&self) -> (u16, u16, u16) {
        (self.major, self.minor, self.patch)
    }

    /// Returns a new version with the patch level incremented.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::new(6, 8, 0);
    /// let bumped = version.bump_patch();
    /// assert_eq!(bumped.patch(), 1);
    /// ```
    #[must_use]
    pub const fn bump_patch(&self) -> Self {
        Self::new(self.major, self.minor, self.patch.saturating_add(1))
    }

    /// Returns a new version with the minor version incremented and patch reset.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::new(6, 8, 5);
    /// let bumped = version.bump_minor();
    /// assert_eq!(bumped.minor(), 9);
    /// assert_eq!(bumped.patch(), 0);
    /// ```
    #[must_use]
    pub const fn bump_minor(&self) -> Self {
        Self::new(self.major, self.minor.saturating_add(1), 0)
    }

    /// Returns a new version with the major version incremented and others reset.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::new(6, 8, 5);
    /// let bumped = version.bump_major();
    /// assert_eq!(bumped.major(), 7);
    /// assert_eq!(bumped.minor(), 0);
    /// assert_eq!(bumped.patch(), 0);
    /// ```
    #[must_use]
    pub const fn bump_major(&self) -> Self {
        Self::new(self.major.saturating_add(1), 0, 0)
    }

    /// Returns a version without the release string.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::KernelVersion;
    ///
    /// let version = KernelVersion::with_release(6, 8, 0, "40-generic");
    /// let without = version.without_release();
    /// assert_eq!(without.release(), None);
    /// assert_eq!(without.major(), 6);
    /// ```
    #[must_use]
    pub const fn without_release(&self) -> Self {
        Self::new(self.major, self.minor, self.patch)
    }
}

impl FromStr for KernelVersion {
    type Err = KernelVersionError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if s.is_empty() {
            return Err(KernelVersionError::Empty);
        }

        // Split on '-' to separate version from release
        let (version_part, release_part) = s
            .find('-')
            .map_or((s, None), |idx| (&s[..idx], Some(&s[idx + 1..])));

        let parts: Vec<&str> = version_part.split('.').collect();

        if parts.len() > 3 {
            return Err(KernelVersionError::TooManyComponents);
        }

        if parts.len() < 2 {
            return Err(KernelVersionError::NotEnoughComponents);
        }

        let major = parts[0]
            .parse::<u16>()
            .map_err(|_| KernelVersionError::InvalidMajor)?;

        let minor = parts[1]
            .parse::<u16>()
            .map_err(|_| KernelVersionError::InvalidMinor)?;

        let patch = if parts.len() > 2 {
            parts[2]
                .parse::<u16>()
                .map_err(|_| KernelVersionError::InvalidPatch)?
        } else {
            0
        };

        let release = release_part.map(|r| {
            let mut rel_str: heapless::String<64> = heapless::String::new();
            // Truncate if necessary, ignoring errors
            let _ = rel_str.push_str(r);
            rel_str
        });

        Ok(Self {
            major,
            minor,
            patch,
            release,
        })
    }
}

impl TryFrom<&str> for KernelVersion {
    type Error = KernelVersionError;

    fn try_from(s: &str) -> Result<Self, Self::Error> {
        s.parse()
    }
}

impl fmt::Display for KernelVersion {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}.{}.{}", self.major, self.minor, self.patch)?;
        if let Some(release) = &self.release {
            write!(f, "-{release}")?;
        }
        Ok(())
    }
}

#[cfg(feature = "arbitrary")]
impl<'a> arbitrary::Arbitrary<'a> for KernelVersion {
    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
        let major = u16::arbitrary(u)?;
        let minor = u16::arbitrary(u)?;
        let patch = u16::arbitrary(u)?;
        let has_release = bool::arbitrary(u)?;

        let release = if has_release {
            // Generate a limited release string to avoid excessive allocations
            let len = u.int_in_range(0..=32usize)?;
            let mut s: heapless::String<64> = heapless::String::new();
            for _ in 0..len {
                let ch: char = char::arbitrary(u)?;
                if ch.is_ascii_alphanumeric() || ch == '-' || ch == '.' || ch == '_' {
                    let _ = s.push(ch);
                }
            }
            Some(s)
        } else {
            None
        };

        Ok(Self {
            major,
            minor,
            patch,
            release,
        })
    }
}

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

    #[test]
    fn test_new() {
        let version = KernelVersion::new(6, 8, 0);
        assert_eq!(version.major(), 6);
        assert_eq!(version.minor(), 8);
        assert_eq!(version.patch(), 0);
        assert_eq!(version.release(), None);
    }

    #[test]
    fn test_with_release() {
        let version = KernelVersion::with_release(6, 8, 0, "40-generic");
        assert_eq!(version.major(), 6);
        assert_eq!(version.minor(), 8);
        assert_eq!(version.patch(), 0);
        assert_eq!(version.release(), Some("40-generic"));
    }

    #[test]
    fn test_is_development() {
        // Odd minor = development
        assert!(KernelVersion::new(6, 7, 0).is_development());
        assert!(KernelVersion::new(6, 9, 0).is_development());

        // Even minor = stable
        assert!(!KernelVersion::new(6, 8, 0).is_development());
        assert!(!KernelVersion::new(6, 10, 0).is_development());
    }

    #[test]
    fn test_is_stable() {
        assert!(KernelVersion::new(6, 8, 0).is_stable());
        assert!(!KernelVersion::new(6, 7, 0).is_stable());
    }

    #[test]
    fn test_is_lts() {
        let lts = KernelVersion::with_release(6, 1, 0, "lts");
        assert!(lts.is_lts());

        let lts_upper = KernelVersion::with_release(6, 1, 0, "LTS");
        assert!(lts_upper.is_lts());

        let regular = KernelVersion::new(6, 8, 0);
        assert!(!regular.is_lts());

        let generic = KernelVersion::with_release(6, 8, 0, "40-generic");
        assert!(!generic.is_lts());
    }

    #[test]
    fn test_as_tuple() {
        let version = KernelVersion::new(6, 8, 5);
        assert_eq!(version.as_tuple(), (6, 8, 5));
    }

    #[test]
    fn test_bump_patch() {
        let version = KernelVersion::new(6, 8, 0);
        let bumped = version.bump_patch();
        assert_eq!(bumped.patch(), 1);
        assert_eq!(bumped.major(), 6);
        assert_eq!(bumped.minor(), 8);
    }

    #[test]
    fn test_bump_minor() {
        let version = KernelVersion::new(6, 8, 5);
        let bumped = version.bump_minor();
        assert_eq!(bumped.major(), 6);
        assert_eq!(bumped.minor(), 9);
        assert_eq!(bumped.patch(), 0);
    }

    #[test]
    fn test_bump_major() {
        let version = KernelVersion::new(6, 8, 5);
        let bumped = version.bump_major();
        assert_eq!(bumped.major(), 7);
        assert_eq!(bumped.minor(), 0);
        assert_eq!(bumped.patch(), 0);
    }

    #[test]
    fn test_without_release() {
        let version = KernelVersion::with_release(6, 8, 0, "40-generic");
        let without = version.without_release();
        assert_eq!(without.release(), None);
        assert_eq!(without.major(), 6);
        assert_eq!(without.minor(), 8);
        assert_eq!(without.patch(), 0);
    }

    #[test]
    fn test_from_str_simple() {
        let version: KernelVersion = "6.8.0".parse().unwrap();
        assert_eq!(version.major(), 6);
        assert_eq!(version.minor(), 8);
        assert_eq!(version.patch(), 0);
        assert_eq!(version.release(), None);
    }

    #[test]
    fn test_from_str_with_release() {
        let version: KernelVersion = "6.8.0-40-generic".parse().unwrap();
        assert_eq!(version.major(), 6);
        assert_eq!(version.minor(), 8);
        assert_eq!(version.patch(), 0);
        assert_eq!(version.release(), Some("40-generic"));
    }

    #[test]
    fn test_from_str_two_components() {
        let version: KernelVersion = "6.8".parse().unwrap();
        assert_eq!(version.major(), 6);
        assert_eq!(version.minor(), 8);
        assert_eq!(version.patch(), 0);
    }

    #[test]
    fn test_from_str_long_release() {
        let version: KernelVersion = "5.15.0-1052-aws".parse().unwrap();
        assert_eq!(version.major(), 5);
        assert_eq!(version.minor(), 15);
        assert_eq!(version.patch(), 0);
        assert_eq!(version.release(), Some("1052-aws"));
    }

    #[test]
    fn test_from_str_errors() {
        // Empty
        assert!(matches!(
            "".parse::<KernelVersion>(),
            Err(KernelVersionError::Empty)
        ));

        // Too many numeric components
        assert!(matches!(
            "1.2.3.4".parse::<KernelVersion>(),
            Err(KernelVersionError::TooManyComponents)
        ));

        // Not enough components
        assert!(matches!(
            "6".parse::<KernelVersion>(),
            Err(KernelVersionError::NotEnoughComponents)
        ));

        // Invalid numbers
        assert!("abc.def".parse::<KernelVersion>().is_err());
        assert!("6.abc".parse::<KernelVersion>().is_err());
        assert!("6.8.abc".parse::<KernelVersion>().is_err());
    }

    #[test]
    fn test_display() {
        let version = KernelVersion::new(6, 8, 0);
        assert_eq!(format!("{}", version), "6.8.0");

        let version = KernelVersion::with_release(6, 8, 0, "40-generic");
        assert_eq!(format!("{}", version), "6.8.0-40-generic");
    }

    #[test]
    fn test_equality() {
        let v1 = KernelVersion::new(6, 8, 0);
        let v2 = KernelVersion::new(6, 8, 0);
        let v3 = KernelVersion::with_release(6, 8, 0, "40-generic");

        assert_eq!(v1, v2);
        assert_ne!(v1, v3);
    }

    #[test]
    fn test_ordering() {
        let v1 = KernelVersion::new(6, 8, 0);
        let v2 = KernelVersion::new(6, 8, 1);
        let v3 = KernelVersion::new(6, 9, 0);
        let v4 = KernelVersion::new(7, 0, 0);

        assert!(v1 < v2);
        assert!(v2 < v3);
        assert!(v3 < v4);

        // Release string affects ordering because KernelVersion derives PartialOrd
        // Two versions with different release strings are not equal
        let with_release = KernelVersion::with_release(6, 8, 0, "40-generic");
        let without_release = KernelVersion::new(6, 8, 0);
        // Version numbers are the same, but release strings differ
        assert_ne!(with_release, without_release);
    }

    #[test]
    fn test_clone() {
        let version = KernelVersion::with_release(6, 8, 0, "40-generic");
        let version2 = version.clone();
        assert_eq!(version, version2);
    }

    #[test]
    fn test_common_kernel_versions() {
        // Linux kernel versions
        let linux_6_8: KernelVersion = "6.8.0".parse().unwrap();
        assert_eq!(linux_6_8.major(), 6);
        assert!(linux_6_8.is_stable());

        let linux_5_15: KernelVersion = "5.15.0".parse().unwrap();
        assert_eq!(linux_5_15.major(), 5);

        // Ubuntu kernel
        let ubuntu: KernelVersion = "6.8.0-40-generic".parse().unwrap();
        assert_eq!(ubuntu.major(), 6);
        assert_eq!(ubuntu.release(), Some("40-generic"));

        // AWS kernel
        let aws: KernelVersion = "5.15.0-1052-aws".parse().unwrap();
        assert_eq!(aws.major(), 5);
        assert_eq!(aws.release(), Some("1052-aws"));
    }
}