Skip to main content

release_version/
build_version.rs

1//! Release version type combining semver, build number, and build provenance.
2
3use std::cmp::Ordering;
4use std::fmt;
5
6use semver::Version;
7
8use crate::upgrade_decision::UpgradeDecision;
9
10/// A parsed release version combining semantic version, build number,
11/// and development-build provenance.
12///
13/// Equal semantic versions compare build numbers only when both values
14/// are releases. If either is a development build, an explicit override
15/// is required and [`UpgradeDecision::DevBuild`] is returned otherwise.
16#[derive(Debug, Clone)]
17pub struct BuildVersion {
18    semver: Version,
19    build_number: u64,
20    dev_build: bool,
21}
22
23impl BuildVersion {
24    /// Construct from parsed components.
25    #[must_use]
26    pub fn new(semver: Version, build_number: u64, dev_build: bool) -> Self {
27        Self {
28            semver,
29            build_number,
30            dev_build,
31        }
32    }
33
34    /// Parse a release manifest's version fields.
35    ///
36    /// Manifest builds are never development builds.
37    ///
38    /// # Errors
39    ///
40    /// Returns an error if `binary_version` is not valid semver.
41    pub fn from_manifest(binary_version: &str, build_number: u64) -> Result<Self, semver::Error> {
42        Ok(Self {
43            semver: Version::parse(binary_version)?,
44            build_number,
45            dev_build: false,
46        })
47    }
48
49    /// The semantic version component.
50    #[must_use]
51    pub fn semver(&self) -> &Version {
52        &self.semver
53    }
54
55    /// The build number.
56    #[must_use]
57    pub fn build_number(&self) -> u64 {
58        self.build_number
59    }
60
61    /// Whether this is a local development build.
62    #[must_use]
63    pub fn is_dev_build(&self) -> bool {
64        self.dev_build
65    }
66
67    /// Compare this version against an available release to determine
68    /// whether an upgrade should proceed.
69    ///
70    /// When `allow_override` is `true`, downgrades and development-build
71    /// overrides are allowed.
72    #[must_use]
73    pub fn compare_for_upgrade(&self, available: &Self, allow_override: bool) -> UpgradeDecision {
74        match self.semver.cmp(&available.semver) {
75            Ordering::Less => return UpgradeDecision::Upgrade,
76            Ordering::Greater => {
77                return if allow_override {
78                    UpgradeDecision::Upgrade
79                } else {
80                    UpgradeDecision::Downgrade
81                };
82            }
83            Ordering::Equal => {}
84        }
85
86        // Semver is equal — check build provenance and number.
87        if self.dev_build || available.dev_build {
88            return if allow_override {
89                UpgradeDecision::Upgrade
90            } else {
91                UpgradeDecision::DevBuild
92            };
93        }
94
95        // Both are release builds — compare build numbers numerically.
96        match self.build_number.cmp(&available.build_number) {
97            Ordering::Less => UpgradeDecision::Upgrade,
98            Ordering::Equal => UpgradeDecision::UpToDate,
99            Ordering::Greater => {
100                if allow_override {
101                    UpgradeDecision::Upgrade
102                } else {
103                    UpgradeDecision::Downgrade
104                }
105            }
106        }
107    }
108}
109
110impl fmt::Display for BuildVersion {
111    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
112        write!(f, "{}.{}", self.semver, self.build_number)
113    }
114}
115
116impl Default for BuildVersion {
117    /// A zero placeholder for applications that inject their current
118    /// release stamp at startup.
119    fn default() -> Self {
120        Self {
121            semver: Version::new(0, 0, 0),
122            build_number: 0,
123            dev_build: true,
124        }
125    }
126}
127
128#[cfg(test)]
129mod tests {
130    use super::*;
131
132    #[test]
133    fn display_format() {
134        let v = BuildVersion::new(Version::new(0, 11, 0), 207, false);
135        assert_eq!(v.to_string(), "0.11.0.207");
136    }
137
138    #[test]
139    fn from_manifest_valid() {
140        let v = BuildVersion::from_manifest("0.11.0", 207).expect("valid semver");
141        assert_eq!(v.semver(), &Version::new(0, 11, 0));
142        assert_eq!(v.build_number(), 207);
143        assert!(!v.is_dev_build());
144    }
145
146    #[test]
147    fn from_manifest_invalid_semver() {
148        assert!(BuildVersion::from_manifest("not.valid", 1).is_err());
149    }
150}