1use crate::error::SettingsError;
2
3pub 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
10pub 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
51pub 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
85pub 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
134pub 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}