Skip to main content

oscyl_core/
native.rs

1//! Oscyl's own library file, `.oscyllib`: a ZIP holding `oscyl.json`
2//! (format version, driver id, per-program metadata), the program bytes in
3//! the driver's native layout, and the driver's extras verbatim. See
4//! `docs/reference/oscyllib-format.md`.
5
6use std::collections::BTreeMap;
7use std::io::{Read, Seek, Write};
8
9use oscyl_driver::{LibProgram, LibraryData};
10use serde::{Deserialize, Serialize};
11use zip::write::SimpleFileOptions;
12use zip::{ZipArchive, ZipWriter};
13
14/// File extension of a native library.
15pub const EXT: &str = "oscyllib";
16/// The format this version writes and the newest it reads.
17pub const FORMAT: u32 = 1;
18
19const MANIFEST: &str = "oscyl.json";
20const PROGRAMS: &str = "programs/";
21const EXTRAS: &str = "extras/";
22
23#[derive(Debug, thiserror::Error)]
24pub enum NativeError {
25    #[error("library archive error: {0}")]
26    Archive(String),
27    #[error("not an Oscyl library: {0}")]
28    NotNative(String),
29    #[error("this library was made by a newer version of Oscyl (format {0})")]
30    Newer(u32),
31}
32
33#[derive(Serialize, Deserialize)]
34struct Manifest {
35    format: u32,
36    driver: String,
37    programs: Vec<Meta>,
38}
39
40#[derive(Serialize, Deserialize)]
41struct Meta {
42    #[serde(default)]
43    author: String,
44    #[serde(default)]
45    comment: String,
46}
47
48fn archive(e: impl std::fmt::Display) -> NativeError {
49    NativeError::Archive(e.to_string())
50}
51
52fn program_name(i: usize) -> String {
53    format!("{PROGRAMS}{i:04}.bin")
54}
55
56/// Write `lib`, made with driver `driver`.
57pub fn write(w: impl Write + Seek, driver: &str, lib: &LibraryData) -> Result<(), NativeError> {
58    let manifest = Manifest {
59        format: FORMAT,
60        driver: driver.to_string(),
61        programs: lib
62            .programs
63            .iter()
64            .map(|p| Meta {
65                author: p.author.clone(),
66                comment: p.comment.clone(),
67            })
68            .collect(),
69    };
70    let json = serde_json::to_vec_pretty(&manifest).map_err(archive)?;
71    let mut zip = ZipWriter::new(w);
72    // The same bytes on every host: without this the archive says which
73    // system wrote it.
74    let opts = SimpleFileOptions::default().system(zip::System::Unix);
75    let mut member = |name: &str, data: &[u8]| -> Result<(), NativeError> {
76        zip.start_file(name, opts).map_err(archive)?;
77        zip.write_all(data).map_err(archive)
78    };
79    member(MANIFEST, &json)?;
80    for (i, p) in lib.programs.iter().enumerate() {
81        member(&program_name(i), &p.data)?;
82    }
83    for (name, data) in &lib.extras {
84        member(&format!("{EXTRAS}{name}"), data)?;
85    }
86    zip.finish().map_err(archive)?;
87    Ok(())
88}
89
90/// Read a native library: its driver id and contents.
91pub fn read(r: impl Read + Seek) -> Result<(String, LibraryData), NativeError> {
92    let mut zip = ZipArchive::new(r).map_err(|e| NativeError::NotNative(e.to_string()))?;
93    let mut files = BTreeMap::new();
94    for i in 0..zip.len() {
95        let mut f = zip.by_index(i).map_err(archive)?;
96        if f.is_dir() {
97            continue;
98        }
99        let mut data = Vec::new();
100        f.read_to_end(&mut data).map_err(archive)?;
101        files.insert(f.name().map_err(archive)?.into_owned(), data);
102    }
103    let json = files
104        .remove(MANIFEST)
105        .ok_or_else(|| NativeError::NotNative(format!("missing {MANIFEST}")))?;
106    let version: serde_json::Value =
107        serde_json::from_slice(&json).map_err(|e| NativeError::NotNative(e.to_string()))?;
108    match version.get("format").and_then(serde_json::Value::as_u64) {
109        Some(f) if f > FORMAT as u64 => return Err(NativeError::Newer(f as u32)),
110        Some(_) => {}
111        None => return Err(NativeError::NotNative("no format version".into())),
112    }
113    let m: Manifest =
114        serde_json::from_value(version).map_err(|e| NativeError::NotNative(e.to_string()))?;
115    let programs = m
116        .programs
117        .into_iter()
118        .enumerate()
119        .map(|(i, meta)| {
120            let data = files
121                .remove(&program_name(i))
122                .ok_or_else(|| NativeError::NotNative(format!("missing {}", program_name(i))))?;
123            Ok(LibProgram {
124                data,
125                author: meta.author,
126                comment: meta.comment,
127            })
128        })
129        .collect::<Result<Vec<_>, NativeError>>()?;
130    let extras = files
131        .into_iter()
132        .filter_map(|(n, d)| Some((n.strip_prefix(EXTRAS)?.to_string(), d)))
133        .collect();
134    Ok((m.driver, LibraryData { programs, extras }))
135}
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140    use oscyl_driver::{LibProgram, LibraryData};
141    use std::io::{Cursor, Write};
142    use zip::write::SimpleFileOptions;
143
144    fn sample() -> LibraryData {
145        let mut lib = LibraryData::default();
146        for (i, a) in ["Ann", "Bob"].iter().enumerate() {
147            lib.programs.push(LibProgram {
148                data: vec![i as u8; 4],
149                author: a.to_string(),
150                comment: format!("c{i} <&>"),
151            });
152        }
153        lib.extras
154            .insert("FileInformation.xml".into(), b"<x/>".to_vec());
155        lib.extras
156            .insert("deep/nested/member.bin".into(), vec![0, 255]);
157        lib
158    }
159
160    fn zip_with(members: &[(&str, &[u8])]) -> Vec<u8> {
161        let mut z = zip::ZipWriter::new(Cursor::new(Vec::new()));
162        for (name, data) in members {
163            z.start_file(*name, SimpleFileOptions::default()).unwrap();
164            z.write_all(data).unwrap();
165        }
166        z.finish().unwrap().into_inner()
167    }
168
169    #[test]
170    fn round_trip() {
171        let mut out = Cursor::new(Vec::new());
172        write(&mut out, "korg-minilogue-xd", &sample()).unwrap();
173        out.set_position(0);
174        let (driver, lib) = read(out).unwrap();
175        assert_eq!(driver, "korg-minilogue-xd");
176        assert_eq!(lib, sample());
177    }
178
179    #[test]
180    fn newer_format_is_refused() {
181        let z = zip_with(&[(MANIFEST, br#"{"format":2,"driver":"x","programs":[]}"#)]);
182        assert!(matches!(read(Cursor::new(z)), Err(NativeError::Newer(2))));
183    }
184
185    #[test]
186    fn missing_manifest_is_not_native() {
187        let z = zip_with(&[("other.txt", b"hi")]);
188        assert!(matches!(
189            read(Cursor::new(z)),
190            Err(NativeError::NotNative(_))
191        ));
192    }
193
194    #[test]
195    fn program_count_mismatch_is_rejected() {
196        let z = zip_with(&[
197            (
198                MANIFEST,
199                br#"{"format":1,"driver":"x","programs":[{"author":"","comment":""},{"author":"","comment":""}]}"#,
200            ),
201            ("programs/0000.bin", &[1]),
202        ]);
203        assert!(matches!(
204            read(Cursor::new(z)),
205            Err(NativeError::NotNative(_))
206        ));
207    }
208}