Skip to main content

appstruct_ir/
compatibility.rs

1use 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
50/// Parse current IR or migrate a supported legacy representation in memory.
51///
52/// # Errors
53///
54/// Returns an explicit compatibility error for missing, future, or semantically unsafe legacy
55/// versions. Callers should recompile the source App Spec when migration is unsafe.
56pub 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}