Skip to main content

tauri_plugin_update_gate/
decide.rs

1//! The gate's decision is a pure function: given the document and the
2//! running version, there is no reason to touch the network or the
3//! filesystem. Keeping it pure is what lets the interesting logic be
4//! tested without a server.
5
6use std::collections::HashMap;
7
8use serde::{Deserialize, Serialize};
9
10/// The document as read from the update server, parsed loosely: every field
11/// is optional so a document the app doesn't fully recognise yet still opens
12/// the gate instead of failing to parse.
13#[derive(Debug, Default, Clone, Deserialize)]
14#[serde(rename_all = "camelCase", default)]
15pub struct Document {
16    pub min_version: Option<String>,
17    pub latest_version: Option<String>,
18    pub message: HashMap<String, String>,
19    pub url: HashMap<String, Option<String>>,
20    /// Versions one platform holds apart from the rest. The stores release on
21    /// different days: the floor can rise everywhere while iOS still waits in
22    /// review. A `null` entry is the same as none.
23    pub platforms: HashMap<String, Option<Override>>,
24}
25
26/// One platform's own versions. A field it leaves out comes from the top level.
27#[derive(Debug, Default, Clone, Deserialize)]
28#[serde(rename_all = "camelCase", default)]
29pub struct Override {
30    pub min_version: Option<String>,
31    pub latest_version: Option<String>,
32}
33
34/// Where the running copy stands relative to the document's versions.
35#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
36#[serde(rename_all = "lowercase")]
37pub enum State {
38    /// Runs the latest known version, or newer.
39    Ok,
40    /// Runs an older version, but not below `minVersion`.
41    Optional,
42    /// Runs a version below `minVersion`.
43    Forced,
44}
45
46/// The gate's verdict, shaped for direct serialisation to the app.
47#[derive(Debug, Serialize)]
48#[serde(rename_all = "camelCase")]
49pub struct Gate {
50    pub state: State,
51    pub latest_version: Option<String>,
52    pub message: Option<String>,
53    pub url: Option<String>,
54}
55
56/// Decides whether `running` may still play, against `doc`. Fails open: a
57/// document field that doesn't parse as a version is treated as if it were
58/// absent rather than as grounds to lock someone out, because a malformed
59/// document is a server mistake, not the running app's fault.
60#[must_use]
61pub fn decide(doc: &Document, running: &str, lang: &str, platform: &str) -> Gate {
62    let own = doc.platforms.get(platform).and_then(Option::as_ref);
63    let min_version = own
64        .and_then(|o| o.min_version.as_ref())
65        .or(doc.min_version.as_ref());
66    let latest_version = own
67        .and_then(|o| o.latest_version.as_ref())
68        .or(doc.latest_version.as_ref())
69        .cloned();
70
71    let parse = |v: Option<&String>| -> Result<Option<semver::Version>, semver::Error> {
72        v.map(|v| semver::Version::parse(v)).transpose()
73    };
74
75    let (Ok(running), Ok(min), Ok(latest)) = (
76        semver::Version::parse(running),
77        parse(min_version),
78        parse(latest_version.as_ref()),
79    ) else {
80        return Gate {
81            state: State::Ok,
82            latest_version,
83            message: None,
84            url: None,
85        };
86    };
87
88    let state = if min.is_some_and(|min| running < min) {
89        State::Forced
90    } else if latest.is_some_and(|latest| running < latest) {
91        State::Optional
92    } else {
93        State::Ok
94    };
95
96    let message = doc
97        .message
98        .get(lang)
99        .or_else(|| doc.message.get("en"))
100        .cloned();
101    let url = doc.url.get(platform).cloned().flatten();
102
103    Gate {
104        state,
105        latest_version,
106        message,
107        url,
108    }
109}
110
111#[cfg(test)]
112mod tests {
113    use super::{decide, Document, Gate, State};
114
115    fn doc(s: &str) -> Document {
116        serde_json::from_str(s).unwrap()
117    }
118
119    #[test]
120    fn below_min_is_forced() {
121        let g = decide(
122            &doc(r#"{"minVersion":"1.2.0","latestVersion":"1.4.0"}"#),
123            "1.1.9",
124            "vi",
125            "ios",
126        );
127        assert!(matches!(g.state, State::Forced));
128    }
129
130    #[test]
131    fn between_min_and_latest_is_optional() {
132        let g = decide(
133            &doc(r#"{"minVersion":"1.2.0","latestVersion":"1.4.0"}"#),
134            "1.3.0",
135            "vi",
136            "ios",
137        );
138        assert!(matches!(g.state, State::Optional));
139    }
140
141    #[test]
142    fn newest_is_ok() {
143        let g = decide(
144            &doc(r#"{"minVersion":"1.2.0","latestVersion":"1.4.0"}"#),
145            "1.4.0",
146            "vi",
147            "ios",
148        );
149        assert!(matches!(g.state, State::Ok));
150    }
151
152    #[test]
153    fn a_prerelease_is_older_than_its_release() {
154        let g = decide(
155            &doc(r#"{"minVersion":"1.2.0"}"#),
156            "1.2.0-alpha.1",
157            "vi",
158            "ios",
159        );
160        assert!(matches!(g.state, State::Forced));
161    }
162
163    #[test]
164    fn an_unreadable_version_opens_the_gate() {
165        let g = decide(
166            &doc(r#"{"minVersion":"not a version"}"#),
167            "1.0.0",
168            "vi",
169            "ios",
170        );
171        assert!(matches!(g.state, State::Ok));
172        let g = decide(&doc(r#"{"minVersion":"9.0.0"}"#), "nonsense", "vi", "ios");
173        assert!(matches!(g.state, State::Ok));
174    }
175
176    #[test]
177    fn an_empty_document_opens_the_gate() {
178        let g = decide(&doc("{}"), "1.0.0", "vi", "ios");
179        assert!(matches!(g.state, State::Ok));
180        assert!(g.message.is_none());
181    }
182
183    #[test]
184    fn it_picks_the_language_and_falls_back_to_english() {
185        let d = doc(r#"{"minVersion":"2.0.0","message":{"vi":"Cập nhật nha","en":"Update"}}"#);
186        assert_eq!(
187            decide(&d, "1.0.0", "vi", "ios").message.as_deref(),
188            Some("Cập nhật nha")
189        );
190        assert_eq!(
191            decide(&d, "1.0.0", "fr", "ios").message.as_deref(),
192            Some("Update")
193        );
194    }
195
196    #[test]
197    fn it_picks_the_url_for_this_platform_and_tolerates_null() {
198        let d = doc(
199            r#"{"minVersion":"2.0.0","url":{"ios":"https://apps.apple.com/x","android":null}}"#,
200        );
201        assert_eq!(
202            decide(&d, "1.0.0", "vi", "ios").url.as_deref(),
203            Some("https://apps.apple.com/x")
204        );
205        assert_eq!(decide(&d, "1.0.0", "vi", "android").url, None);
206        assert_eq!(decide(&d, "1.0.0", "vi", "macos").url, None);
207    }
208
209    #[test]
210    fn gate_serialises_to_camel_case_with_lowercase_state() {
211        let g = Gate {
212            state: State::Optional,
213            latest_version: Some("1.4.0".to_string()),
214            message: Some("Update".to_string()),
215            url: Some("https://example.com".to_string()),
216        };
217        let json = serde_json::to_value(&g).unwrap();
218        assert_eq!(
219            json,
220            serde_json::json!({
221                "state": "optional",
222                "latestVersion": "1.4.0",
223                "message": "Update",
224                "url": "https://example.com",
225            })
226        );
227    }
228
229    /// The top level raised to 1.3.0 everywhere, with iOS held at 1.2.0
230    /// while its build waits in review.
231    const HELD_BACK: &str = r#"{"minVersion":"1.3.0","latestVersion":"1.4.0",
232        "platforms":{"ios":{"minVersion":"1.2.0"}}}"#;
233
234    #[test]
235    fn a_platform_can_hold_its_floor_below_the_rest() {
236        let d = doc(HELD_BACK);
237        assert_eq!(decide(&d, "1.2.5", "vi", "ios").state, State::Optional);
238        assert_eq!(decide(&d, "1.2.5", "vi", "android").state, State::Forced);
239    }
240
241    #[test]
242    fn a_platform_can_hold_its_offer_back_and_reports_its_own_latest() {
243        let d = doc(r#"{"minVersion":"1.0.0","latestVersion":"1.4.0",
244                "platforms":{"ios":{"latestVersion":"1.3.0"}}}"#);
245        let ios = decide(&d, "1.3.0", "vi", "ios");
246        assert_eq!(ios.state, State::Ok);
247        assert_eq!(ios.latest_version.as_deref(), Some("1.3.0"));
248        let android = decide(&d, "1.3.0", "vi", "android");
249        assert_eq!(android.state, State::Optional);
250        assert_eq!(android.latest_version.as_deref(), Some("1.4.0"));
251    }
252
253    #[test]
254    fn an_override_leaves_the_field_it_does_not_name_to_the_top_level() {
255        let d = doc(HELD_BACK);
256        // iOS overrides only the floor, so the offer still comes from 1.4.0.
257        assert_eq!(decide(&d, "1.3.0", "vi", "ios").state, State::Optional);
258        assert_eq!(
259            decide(&d, "1.3.0", "vi", "ios").latest_version.as_deref(),
260            Some("1.4.0")
261        );
262    }
263
264    #[test]
265    fn a_null_or_empty_override_means_the_top_level() {
266        for platforms in [r#"{"ios":null}"#, r#"{"ios":{}}"#] {
267            let d = doc(&format!(
268                r#"{{"minVersion":"1.3.0","platforms":{platforms}}}"#
269            ));
270            assert_eq!(decide(&d, "1.2.0", "vi", "ios").state, State::Forced);
271        }
272    }
273
274    #[test]
275    fn an_unreadable_override_opens_the_gate_on_that_platform_only() {
276        let d = doc(r#"{"minVersion":"1.3.0",
277                "platforms":{"ios":{"minVersion":"soon"}}}"#);
278        assert_eq!(decide(&d, "1.2.0", "vi", "ios").state, State::Ok);
279        assert_eq!(decide(&d, "1.2.0", "vi", "android").state, State::Forced);
280    }
281}