appstruct_ir/
compatibility.rs1use crate::{AppIr, IR_VERSION};
2use serde_json::Value;
3use sha2::{Digest, Sha256};
4use std::error::Error;
5use std::fmt;
6
7const MIN_COMPATIBLE_IR_VERSION: u32 = appstruct_contracts::IR.minimum;
8
9#[derive(Debug)]
10pub enum IrCompatibilityError {
11 InvalidJson(serde_json::Error),
12 MissingVersion,
13 UnsupportedVersion { found: u64 },
14 LegacyModuleGraph,
15}
16
17impl fmt::Display for IrCompatibilityError {
18 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
19 match self {
20 Self::InvalidJson(error) => write!(formatter, "invalid IR JSON: {error}"),
21 Self::MissingVersion => formatter.write_str("IR JSON is missing integer `ir_version`"),
22 Self::UnsupportedVersion { found } => write!(
23 formatter,
24 "unsupported IR version {found}; supported versions are {MIN_COMPATIBLE_IR_VERSION} through {IR_VERSION}"
25 ),
26 Self::LegacyModuleGraph => formatter.write_str(
27 "IR v7 with resolved modules cannot be migrated safely; recompile the App Spec",
28 ),
29 }
30 }
31}
32
33impl Error for IrCompatibilityError {
34 fn source(&self) -> Option<&(dyn Error + 'static)> {
35 match self {
36 Self::InvalidJson(error) => Some(error),
37 Self::MissingVersion | Self::UnsupportedVersion { .. } | Self::LegacyModuleGraph => {
38 None
39 }
40 }
41 }
42}
43
44impl From<serde_json::Error> for IrCompatibilityError {
45 fn from(error: serde_json::Error) -> Self {
46 Self::InvalidJson(error)
47 }
48}
49
50pub fn from_compatible_json(source: &str) -> Result<AppIr, IrCompatibilityError> {
57 let mut value: Value = serde_json::from_str(source)?;
58 let version = value
59 .get("ir_version")
60 .and_then(Value::as_u64)
61 .ok_or(IrCompatibilityError::MissingVersion)?;
62 match u32::try_from(version) {
63 Ok(IR_VERSION) => {}
64 Ok(7) => {
65 migrate_v7(&mut value)?;
66 migrate_v10(&mut value)?;
67 }
68 Ok(8) => {
69 migrate_v8(&mut value)?;
70 migrate_v9(&mut value)?;
71 migrate_v10(&mut value)?;
72 }
73 Ok(9) => {
74 migrate_v9(&mut value)?;
75 migrate_v10(&mut value)?;
76 }
77 Ok(10) => migrate_v10(&mut value)?,
78 _ => return Err(IrCompatibilityError::UnsupportedVersion { found: version }),
79 }
80 serde_json::from_value(value).map_err(IrCompatibilityError::from)
81}
82
83fn migrate_v7(value: &mut Value) -> Result<(), IrCompatibilityError> {
84 let modules = value
85 .get("modules")
86 .and_then(Value::as_array)
87 .ok_or_else(|| invalid_shape("IR v7 is missing array `modules`"))?;
88 if !modules.is_empty() {
89 return Err(IrCompatibilityError::LegacyModuleGraph);
90 }
91 value["ir_version"] = Value::from(IR_VERSION);
92 Ok(())
93}
94
95fn migrate_v8(value: &mut Value) -> Result<(), IrCompatibilityError> {
96 let modules = value
97 .get_mut("modules")
98 .and_then(Value::as_array_mut)
99 .ok_or_else(|| invalid_shape("IR v8 is missing array `modules`"))?;
100 for module in modules {
101 let module = module
102 .as_object_mut()
103 .ok_or_else(|| invalid_shape("IR v8 `modules` entries must be objects"))?;
104 module.insert("origin".to_owned(), Value::String("official".to_owned()));
105 module.insert("artifacts".to_owned(), Value::Array(Vec::new()));
106 }
107 value["ir_version"] = Value::from(9);
108 Ok(())
109}
110
111fn migrate_v9(value: &mut Value) -> Result<(), IrCompatibilityError> {
112 let modules = value
113 .get_mut("modules")
114 .and_then(Value::as_array_mut)
115 .ok_or_else(|| invalid_shape("IR v9 is missing array `modules`"))?;
116 for module in modules {
117 let module = module
118 .as_object_mut()
119 .ok_or_else(|| invalid_shape("IR v9 `modules` entries must be objects"))?;
120 module.insert("manifest_path".to_owned(), Value::Null);
121 module.insert("content_sha256".to_owned(), Value::Null);
122 let artifacts = module
123 .get_mut("artifacts")
124 .and_then(Value::as_array_mut)
125 .ok_or_else(|| invalid_shape("IR v9 module is missing array `artifacts`"))?;
126 for artifact in artifacts {
127 let artifact = artifact
128 .as_object_mut()
129 .ok_or_else(|| invalid_shape("IR v9 `artifacts` entries must be objects"))?;
130 let content = artifact
131 .get("content")
132 .and_then(Value::as_str)
133 .ok_or_else(|| invalid_shape("IR v9 artifact is missing string `content`"))?;
134 let byte_len = u64::try_from(content.len())
135 .map_err(|_| invalid_shape("IR v9 artifact byte count overflowed"))?;
136 let sha256 = format!("sha256:{:x}", Sha256::digest(content.as_bytes()));
137 artifact.insert("source".to_owned(), Value::Null);
138 artifact.insert("sha256".to_owned(), Value::String(sha256));
139 artifact.insert("byte_len".to_owned(), Value::from(byte_len));
140 }
141 }
142 value["ir_version"] = Value::from(IR_VERSION);
143 Ok(())
144}
145
146fn migrate_v10(value: &mut Value) -> Result<(), IrCompatibilityError> {
147 let database = value
148 .get_mut("database")
149 .and_then(Value::as_object_mut)
150 .ok_or_else(|| invalid_shape("IR v10 is missing object `database`"))?;
151 database.insert(
152 "dev_migration".to_owned(),
153 Value::String("unmanaged".to_owned()),
154 );
155 value["ir_version"] = Value::from(IR_VERSION);
156 Ok(())
157}
158
159fn invalid_shape(message: &str) -> IrCompatibilityError {
160 IrCompatibilityError::InvalidJson(serde_json::Error::io(std::io::Error::new(
161 std::io::ErrorKind::InvalidData,
162 message,
163 )))
164}
165
166#[cfg(test)]
167mod tests {
168 use super::{IrCompatibilityError, from_compatible_json};
169 use crate::IR_VERSION;
170
171 #[test]
172 fn migrates_module_free_v7_ir() {
173 let mut value: serde_json::Value =
174 serde_json::from_str(include_str!("../../../tests/golden/m0-app-ir.json")).unwrap();
175 value["ir_version"] = 7.into();
176 value["modules"] = serde_json::json!([]);
177 let migrated = from_compatible_json(&serde_json::to_string(&value).unwrap()).unwrap();
178 assert_eq!(migrated.ir_version, IR_VERSION);
179 assert!(migrated.modules.is_empty());
180 }
181
182 #[test]
183 fn rejects_legacy_module_graph_and_future_versions() {
184 let source = include_str!("../../../tests/golden/m0-app-ir.json");
185 let legacy = source.replacen(
186 &format!("\"ir_version\": {IR_VERSION}"),
187 "\"ir_version\": 7",
188 1,
189 );
190 assert!(matches!(
191 from_compatible_json(&legacy),
192 Err(IrCompatibilityError::LegacyModuleGraph)
193 ));
194
195 let future = source.replacen(
196 &format!("\"ir_version\": {IR_VERSION}"),
197 "\"ir_version\": 999",
198 1,
199 );
200 assert!(matches!(
201 from_compatible_json(&future),
202 Err(IrCompatibilityError::UnsupportedVersion { found: 999 })
203 ));
204 }
205
206 #[test]
207 fn migrates_v8_official_modules() {
208 let source = include_str!("../../../tests/golden/m0-app-ir.json");
209 let mut value: serde_json::Value = serde_json::from_str(source).unwrap();
210 value["ir_version"] = 8.into();
211 for module in value["modules"].as_array_mut().unwrap() {
212 module.as_object_mut().unwrap().remove("origin");
213 module.as_object_mut().unwrap().remove("artifacts");
214 }
215
216 let migrated = from_compatible_json(&serde_json::to_string(&value).unwrap()).unwrap();
217 assert_eq!(migrated.ir_version, IR_VERSION);
218 assert!(migrated.modules.iter().all(|module| {
219 module.origin == crate::ModuleOrigin::Official
220 && module.manifest_path.is_none()
221 && module.content_sha256.is_none()
222 && module.artifacts.is_empty()
223 }));
224 }
225
226 #[test]
227 fn migrates_v9_artifact_integrity_without_inventing_source_provenance() {
228 let source = include_str!("../../../tests/golden/m0-app-ir.json");
229 let mut value: serde_json::Value = serde_json::from_str(source).unwrap();
230 value["ir_version"] = 9.into();
231 let module = value["modules"][0].as_object_mut().unwrap();
232 module.remove("manifest_path");
233 module.remove("content_sha256");
234 module.insert(
235 "artifacts".to_owned(),
236 serde_json::json!([{"path": "README.md", "content": "legacy\n"}]),
237 );
238 for module in value["modules"].as_array_mut().unwrap().iter_mut().skip(1) {
239 module.as_object_mut().unwrap().remove("manifest_path");
240 module.as_object_mut().unwrap().remove("content_sha256");
241 }
242
243 let migrated = from_compatible_json(&serde_json::to_string(&value).unwrap()).unwrap();
244 let artifact = &migrated.modules[0].artifacts[0];
245 assert_eq!(artifact.source, None);
246 assert_eq!(artifact.byte_len, 7);
247 assert_eq!(
248 artifact.sha256,
249 "sha256:777d90290a75129dbd33a5ac590f4633ec91d0eb381213761c728004961c3320"
250 );
251 }
252
253 #[test]
254 fn migrates_v10_database_policy_without_enabling_writes() {
255 let source = include_str!("../../../tests/golden/m0-app-ir.json");
256 let mut value: serde_json::Value = serde_json::from_str(source).unwrap();
257 value["ir_version"] = 10.into();
258 value["database"]
259 .as_object_mut()
260 .unwrap()
261 .remove("dev_migration");
262
263 let migrated = from_compatible_json(&serde_json::to_string(&value).unwrap()).unwrap();
264 assert_eq!(migrated.ir_version, IR_VERSION);
265 assert_eq!(
266 migrated.database.dev_migration,
267 crate::DatabaseMigrationPolicy::Unmanaged
268 );
269 }
270}