Skip to main content

keystate_core/
version.rs

1//! Backend/schema version representation used to key manifests and reports.
2
3use std::{fmt, str::FromStr};
4
5use serde::{Deserialize, Serialize};
6
7use crate::error::{Error, Result};
8
9/// A simple `major.minor.patch` version.
10///
11/// Used to key [`FieldManifest`](crate::FieldManifest)s and
12/// [`VerificationReport`](crate::VerificationReport)s against the schema
13/// version actually detected at the source, so completeness claims are always
14/// tied to a concrete backend version.
15#[derive(
16    Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize, Default,
17)]
18pub struct Version {
19    /// Major schema version.
20    pub major: u64,
21    /// Minor schema version.
22    pub minor: u64,
23    /// Patch version.
24    pub patch: u64,
25}
26
27impl Version {
28    /// Construct a version from its three components.
29    pub const fn new(major: u64, minor: u64, patch: u64) -> Self {
30        Self {
31            major,
32            minor,
33            patch,
34        }
35    }
36}
37
38impl fmt::Display for Version {
39    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
40        write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
41    }
42}
43
44impl FromStr for Version {
45    type Err = Error;
46
47    fn from_str(input: &str) -> Result<Self> {
48        let parts: Vec<&str> = input.trim().split('.').collect();
49        if parts.len() != 3 {
50            return Err(Error::InvalidVersion {
51                input: input.to_string(),
52                reason: format!(
53                    "expected major.minor.patch, got {} component(s)",
54                    parts.len()
55                ),
56            });
57        }
58        let parse = |part: &str| -> Option<u64> { part.parse::<u64>().ok() };
59        let (major, minor, patch) = (parse(parts[0]), parse(parts[1]), parse(parts[2]));
60        let (Some(major), Some(minor), Some(patch)) = (major, minor, patch) else {
61            return Err(Error::InvalidVersion {
62                input: input.to_string(),
63                reason: "each component must be a non-negative integer".to_string(),
64            });
65        };
66        Ok(Version::new(major, minor, patch))
67    }
68}
69
70#[cfg(test)]
71mod tests {
72    use super::*;
73
74    #[test]
75    fn parses_three_part_versions() {
76        assert_eq!("26.0.4".parse::<Version>().unwrap(), Version::new(26, 0, 4));
77        assert_eq!("0.1.0".parse::<Version>().unwrap(), Version::new(0, 1, 0));
78        assert!("26.0".parse::<Version>().is_err());
79        assert!("26.0.beta".parse::<Version>().is_err());
80        assert!("".parse::<Version>().is_err());
81    }
82
83    #[test]
84    fn orders_lexically_by_component() {
85        assert!(Version::new(1, 10, 0) > Version::new(1, 9, 9));
86        assert!(Version::new(25, 0, 0) < Version::new(26, 0, 0));
87    }
88
89    #[test]
90    fn displays_and_roundtrips() {
91        let v = Version::new(24, 8, 1);
92        assert_eq!(v.to_string(), "24.8.1");
93        assert_eq!(v.to_string().parse::<Version>().unwrap(), v);
94    }
95}