Skip to main content

export_bundle/
manifest.rs

1//! `manifest.json`: what a bundle contains, so it can be checked later.
2//!
3//! A bundle is a directory of CSV files beside a manifest, and the manifest
4//! is how anyone downstream answers two questions without the exporter's
5//! help: which files were in it, and are these still those bytes. So every
6//! entry carries a name, a SHA-256 and a row count.
7//!
8//! The document is written as *canonical* JSON: object keys sorted at every
9//! depth, no whitespace outside a string. Two spellings of one document
10//! would hash differently, so the manifest fixes one spelling for itself.
11//!
12//! `created_at` is the one wall-clock value, and it is the caller's to
13//! supply: this crate never reads a clock. [`Manifest`] ignores it when
14//! compared, so two bundles of the same bytes made a month apart are equal —
15//! equality means "these files", never "this afternoon".
16//!
17//! The manifest also records, per file, which columns the allow-list left
18//! behind. The recipient can then see for themselves that the export was
19//! wider than the bundle, and by exactly which columns.
20
21use std::collections::BTreeMap;
22use std::fmt::Write as _;
23
24use serde::{Deserialize, Serialize};
25use serde_json::Value;
26use sha2::{Digest as _, Sha256};
27
28/// One file in a bundle.
29#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
30pub struct FileEntry {
31    /// The name the file has inside the bundle.
32    pub name: String,
33    /// SHA-256 of its bytes, lowercase hex.
34    pub sha256: String,
35    /// Data rows, header excluded.
36    pub rows: usize,
37    /// Columns the allow-list dropped, in the header's own order.
38    ///
39    /// Reported rather than silently removed: a file that carried more than
40    /// its allow-list is something the recipient should see.
41    #[serde(default)]
42    pub dropped: Vec<String>,
43}
44
45/// What one bundle contains.
46///
47/// The whole document is a calculation over values the caller already has,
48/// so two bundles of the same files compare equal whoever ran them. Only
49/// `created_at` is left out of the comparison: it says when, not what.
50#[derive(Debug, Clone, Serialize, Deserialize)]
51pub struct Manifest {
52    /// One entry per bundled file, in the order the bundle wrote them.
53    pub files: Vec<FileEntry>,
54    /// When the bundle was made, as the caller supplied it.
55    ///
56    /// The only wall-clock value in a bundle, and the only field that
57    /// comparison ignores.
58    pub created_at: String,
59    /// The version of the tool that wrote it.
60    pub tool_version: String,
61    /// Free-form facts the caller attached: a window, a label, anything.
62    pub meta: BTreeMap<String, String>,
63    /// Columns left behind, per file, for files that carried extras.
64    #[serde(default)]
65    pub dropped: BTreeMap<String, Vec<String>>,
66}
67
68impl PartialEq for Manifest {
69    fn eq(&self, other: &Self) -> bool {
70        self.files == other.files
71            && self.tool_version == other.tool_version
72            && self.meta == other.meta
73            && self.dropped == other.dropped
74    }
75}
76
77impl Eq for Manifest {}
78
79impl Manifest {
80    /// The manifest as one file's worth of canonical JSON. **Calculation.**
81    ///
82    /// # Errors
83    /// A [`serde_json::Error`] if the document cannot be encoded, which
84    /// cannot happen for a manifest built from ordinary strings.
85    pub fn to_json(&self) -> Result<String, serde_json::Error> {
86        Ok(canonical_json(&serde_json::to_value(self)?))
87    }
88
89    /// A manifest read back off disk. **Calculation.**
90    ///
91    /// # Errors
92    /// A [`serde_json::Error`] when the text is not a manifest this build
93    /// knows.
94    pub fn from_json(text: &str) -> Result<Self, serde_json::Error> {
95        serde_json::from_str(text)
96    }
97}
98
99/// The SHA-256 of some bytes, lowercase hex. **Calculation.**
100pub(crate) fn sha256_hex(bytes: &[u8]) -> String {
101    Sha256::digest(bytes)
102        .iter()
103        .fold(String::new(), |mut hex, byte| {
104            let _ = write!(hex, "{byte:02x}");
105            hex
106        })
107}
108
109/// One document, one spelling: object keys sorted at every depth, no
110/// whitespace outside a string, array order left alone. **Calculation.**
111pub(crate) fn canonical_json(value: &Value) -> String {
112    let mut out = String::new();
113    write_value(&mut out, value);
114    out
115}
116
117fn write_value(out: &mut String, value: &Value) {
118    match value {
119        Value::Null => out.push_str("null"),
120        Value::Bool(yes) => out.push_str(if *yes { "true" } else { "false" }),
121        Value::Number(number) => out.push_str(&number.to_string()),
122        Value::String(text) => write_string(out, text),
123        Value::Array(items) => {
124            out.push('[');
125            for (position, item) in items.iter().enumerate() {
126                if position > 0 {
127                    out.push(',');
128                }
129                write_value(out, item);
130            }
131            out.push(']');
132        }
133        Value::Object(members) => {
134            let sorted: BTreeMap<&str, &Value> = members
135                .iter()
136                .map(|(key, value)| (key.as_str(), value))
137                .collect();
138            out.push('{');
139            for (position, (key, value)) in sorted.into_iter().enumerate() {
140                if position > 0 {
141                    out.push(',');
142                }
143                write_string(out, key);
144                out.push(':');
145                write_value(out, value);
146            }
147            out.push('}');
148        }
149    }
150}
151
152/// A string, escaped as JSON escapes one.
153fn write_string(out: &mut String, text: &str) {
154    out.push_str(&Value::String(text.to_owned()).to_string());
155}
156
157#[cfg(test)]
158mod tests {
159    use super::*;
160
161    #[test]
162    fn sha256_of_abc_is_the_published_vector() {
163        assert_eq!(
164            sha256_hex(b"abc"),
165            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
166        );
167    }
168
169    #[test]
170    fn sha256_of_nothing_is_the_published_empty_vector() {
171        assert_eq!(
172            sha256_hex(b""),
173            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
174        );
175    }
176
177    #[test]
178    fn keys_are_sorted_at_every_depth_and_nothing_is_spaced() {
179        let document: Value =
180            serde_json::from_str(r#"{"b": {"z": 1, "a": 2}, "a": [3, 4]}"#).unwrap();
181
182        assert_eq!(
183            canonical_json(&document),
184            r#"{"a":[3,4],"b":{"a":2,"z":1}}"#
185        );
186    }
187
188    #[test]
189    fn strings_keep_the_escaping_json_requires() {
190        let document: Value = serde_json::from_str(r#"{"note": "a \"quoted\" line\n"}"#).unwrap();
191
192        assert_eq!(
193            canonical_json(&document),
194            r#"{"note":"a \"quoted\" line\n"}"#
195        );
196    }
197
198    #[test]
199    fn array_order_is_content_and_is_not_sorted() {
200        let one: Value = serde_json::from_str("[1, 2]").unwrap();
201        let other: Value = serde_json::from_str("[2, 1]").unwrap();
202
203        assert_ne!(canonical_json(&one), canonical_json(&other));
204    }
205
206    #[test]
207    fn a_manifest_is_written_canonical_with_keys_sorted() {
208        let manifest = Manifest {
209            files: vec![FileEntry {
210                name: "id.csv".to_owned(),
211                sha256: sha256_hex(b"abc"),
212                rows: 1,
213                dropped: vec!["email".to_owned()],
214            }],
215            created_at: "2026-01-01T00:00:00Z".to_owned(),
216            tool_version: "0.1.0".to_owned(),
217            meta: BTreeMap::from([("window".to_owned(), "24h".to_owned())]),
218            dropped: BTreeMap::from([("id.csv".to_owned(), vec!["email".to_owned()])]),
219        };
220
221        let text = manifest.to_json().unwrap();
222
223        assert_eq!(
224            text,
225            concat!(
226                r#"{"created_at":"2026-01-01T00:00:00Z","#,
227                r#""dropped":{"id.csv":["email"]},"#,
228                r#""files":[{"dropped":["email"],"name":"id.csv","rows":1,"sha256":"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"}],"#,
229                r#""meta":{"window":"24h"},"#,
230                r#""tool_version":"0.1.0"}"#,
231            )
232        );
233    }
234}