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