Skip to main content

rip_settings/
migration.rs

1use crate::error::SettingsError;
2
3/// A single migration step.
4pub trait Migration: Send + Sync {
5    fn from_version(&self) -> u32;
6    fn to_version(&self) -> u32;
7    fn migrate(&self, value: &mut serde_json::Value) -> Result<(), SettingsError>;
8}
9
10/// Rename a key from one name to another.
11pub struct KeyRename {
12    pub from_ver: u32,
13    pub to_ver: u32,
14    pub old_key: String,
15    pub new_key: String,
16}
17
18impl KeyRename {
19    pub fn new(
20        from_ver: u32,
21        to_ver: u32,
22        old_key: impl Into<String>,
23        new_key: impl Into<String>,
24    ) -> Self {
25        Self {
26            from_ver,
27            to_ver,
28            old_key: old_key.into(),
29            new_key: new_key.into(),
30        }
31    }
32}
33
34impl Migration for KeyRename {
35    fn from_version(&self) -> u32 {
36        self.from_ver
37    }
38    fn to_version(&self) -> u32 {
39        self.to_ver
40    }
41    fn migrate(&self, value: &mut serde_json::Value) -> Result<(), SettingsError> {
42        if let Some(obj) = value.as_object_mut() {
43            if let Some(v) = obj.remove(&self.old_key) {
44                obj.insert(self.new_key.clone(), v);
45            }
46        }
47        Ok(())
48    }
49}
50
51/// Delete one or more keys.
52pub struct KeyDeletion {
53    pub from_ver: u32,
54    pub to_ver: u32,
55    pub keys: Vec<String>,
56}
57
58impl KeyDeletion {
59    pub fn new(from_ver: u32, to_ver: u32, keys: Vec<String>) -> Self {
60        Self {
61            from_ver,
62            to_ver,
63            keys,
64        }
65    }
66}
67
68impl Migration for KeyDeletion {
69    fn from_version(&self) -> u32 {
70        self.from_ver
71    }
72    fn to_version(&self) -> u32 {
73        self.to_ver
74    }
75    fn migrate(&self, value: &mut serde_json::Value) -> Result<(), SettingsError> {
76        if let Some(obj) = value.as_object_mut() {
77            for key in &self.keys {
78                obj.remove(key);
79            }
80        }
81        Ok(())
82    }
83}
84
85/// Custom migration with a closure.
86pub struct CustomMigration {
87    from_ver: u32,
88    to_ver: u32,
89    func: Box<dyn Fn(&mut serde_json::Value) -> Result<(), SettingsError> + Send + Sync>,
90}
91
92impl CustomMigration {
93    pub fn new(
94        from_ver: u32,
95        to_ver: u32,
96        func: impl Fn(&mut serde_json::Value) -> Result<(), SettingsError> + Send + Sync + 'static,
97    ) -> Self {
98        Self {
99            from_ver,
100            to_ver,
101            func: Box::new(func),
102        }
103    }
104}
105
106impl Migration for CustomMigration {
107    fn from_version(&self) -> u32 {
108        self.from_ver
109    }
110    fn to_version(&self) -> u32 {
111        self.to_ver
112    }
113    fn migrate(&self, value: &mut serde_json::Value) -> Result<(), SettingsError> {
114        (self.func)(value)
115    }
116}
117
118#[derive(Clone, Debug)]
119pub enum MigrationResult {
120    NoMigrationNeeded,
121    Success {
122        from_version: u32,
123        to_version: u32,
124        migrations_applied: usize,
125    },
126    PartialSuccess {
127        from_version: u32,
128        to_version: u32,
129        migrations_applied: usize,
130        errors: Vec<(u32, String)>,
131    },
132}
133
134/// Manages and applies migrations to raw settings data.
135pub struct MigrationManager {
136    current_version: u32,
137    migrations: Vec<Box<dyn Migration>>,
138}
139
140impl MigrationManager {
141    pub fn new(current_version: u32) -> Self {
142        Self {
143            current_version,
144            migrations: Vec::new(),
145        }
146    }
147
148    pub fn add(mut self, migration: impl Migration + 'static) -> Self {
149        if let Some(last) = self.migrations.last() {
150            assert!(
151                migration.from_version() >= last.to_version(),
152                "Migration chain broken: {}->{} doesn't follow {}->{}",
153                migration.from_version(),
154                migration.to_version(),
155                last.from_version(),
156                last.to_version()
157            );
158        }
159        self.migrations.push(Box::new(migration));
160        self
161    }
162
163    pub fn add_key_rename(
164        self,
165        from_ver: u32,
166        to_ver: u32,
167        old_key: impl Into<String>,
168        new_key: impl Into<String>,
169    ) -> Self {
170        self.add(KeyRename::new(from_ver, to_ver, old_key, new_key))
171    }
172
173    pub fn add_key_deletion(self, from_ver: u32, to_ver: u32, keys: Vec<String>) -> Self {
174        self.add(KeyDeletion::new(from_ver, to_ver, keys))
175    }
176
177    pub fn migrate(&self, data: &mut serde_json::Value) -> MigrationResult {
178        let stored_version = data
179            .get("__schema_version")
180            .and_then(|v| v.as_u64())
181            .unwrap_or(0) as u32;
182
183        if stored_version >= self.current_version {
184            return MigrationResult::NoMigrationNeeded;
185        }
186
187        let mut applicable: Vec<&dyn Migration> = self
188            .migrations
189            .iter()
190            .filter(|m| {
191                m.from_version() >= stored_version && m.to_version() <= self.current_version
192            })
193            .map(|m| m.as_ref())
194            .collect();
195
196        applicable.sort_by_key(|m| m.from_version());
197
198        if applicable.is_empty() {
199            if let Some(obj) = data.as_object_mut() {
200                obj.insert(
201                    "__schema_version".into(),
202                    serde_json::json!(self.current_version),
203                );
204            }
205            return MigrationResult::NoMigrationNeeded;
206        }
207
208        let mut applied = 0usize;
209        let mut errors = Vec::new();
210
211        for migration in &applicable {
212            match migration.migrate(data) {
213                Ok(()) => applied += 1,
214                Err(e) => errors.push((migration.to_version(), e.to_string())),
215            }
216        }
217
218        if let Some(obj) = data.as_object_mut() {
219            obj.insert(
220                "__schema_version".into(),
221                serde_json::json!(self.current_version),
222            );
223        }
224
225        if errors.is_empty() {
226            MigrationResult::Success {
227                from_version: stored_version,
228                to_version: self.current_version,
229                migrations_applied: applied,
230            }
231        } else {
232            MigrationResult::PartialSuccess {
233                from_version: stored_version,
234                to_version: self.current_version,
235                migrations_applied: applied,
236                errors,
237            }
238        }
239    }
240
241    pub fn stored_version(data: &serde_json::Value) -> u32 {
242        data.get("__schema_version")
243            .and_then(|v| v.as_u64())
244            .unwrap_or(0) as u32
245    }
246}
247
248#[cfg(test)]
249mod tests {
250    use super::*;
251
252    #[test]
253    fn test_key_rename() {
254        let mut data = serde_json::json!({"old_name": "hello", "other": 42});
255        let manager = MigrationManager::new(2).add_key_rename(0, 1, "old_name", "new_name");
256        let result = manager.migrate(&mut data);
257        assert!(matches!(result, MigrationResult::Success { .. }));
258        assert_eq!(data["new_name"], "hello");
259        assert!(data.get("old_name").is_none());
260    }
261
262    #[test]
263    fn test_key_deletion() {
264        let mut data =
265            serde_json::json!({"keep_me": true, "delete_me": "gone", "also_delete": 123});
266        let manager = MigrationManager::new(2).add_key_deletion(
267            0,
268            1,
269            vec!["delete_me".into(), "also_delete".into()],
270        );
271        manager.migrate(&mut data);
272        assert!(data.get("delete_me").is_none());
273        assert!(data.get("also_delete").is_none());
274        assert_eq!(data["keep_me"], true);
275    }
276
277    #[test]
278    fn test_custom_migration() {
279        let mut data = serde_json::json!({"font_size": 14});
280        let migration = CustomMigration::new(0, 1, |value| {
281            if let Some(obj) = value.as_object_mut() {
282                if let Some(size) = obj.get("font_size").and_then(|v| v.as_i64()) {
283                    obj.insert("font_size".into(), serde_json::json!(size * 2));
284                }
285            }
286            Ok(())
287        });
288        let manager = MigrationManager::new(1).add(migration);
289        manager.migrate(&mut data);
290        assert_eq!(data["font_size"], 28);
291    }
292
293    #[test]
294    #[should_panic(expected = "Migration chain broken")]
295    fn test_migration_chain_validation() {
296        let _manager = MigrationManager::new(3)
297            .add_key_rename(2, 3, "old", "new")
298            .add_key_rename(0, 1, "other", "other_new");
299    }
300}