Skip to main content

export_bundle/
verify.rs

1//! Checking a bundle against its manifest.
2//!
3//! Verify is the recipient's half of the deal: read `manifest.json`, hash
4//! every file it lists, count its rows, and compare. The first thing that
5//! differs is named — a file the manifest lists but the bundle does not
6//! hold, a hash that does not match, or a row count that does not — so a
7//! tampered bundle is answered with the specific file, not a shrug.
8//!
9//! Everything here is a calculation over bytes already on disk: no network,
10//! no clock, no second copy of any rule the manifest did not state.
11
12use std::fs;
13use std::io;
14use std::path::Path;
15
16use thiserror::Error;
17
18use crate::bundle::MANIFEST;
19use crate::manifest::{sha256_hex, Manifest};
20
21/// Why a bundle did not verify.
22#[derive(Debug, Error)]
23pub enum VerifyError {
24    /// The manifest could not be read, so there is nothing to check
25    /// against.
26    #[error("{file}: the manifest could not be read: {source}")]
27    ManifestIo {
28        /// Where the manifest was expected.
29        file: std::path::PathBuf,
30        /// The underlying error.
31        source: io::Error,
32    },
33    /// The manifest text is not a manifest this build knows.
34    #[error("{file}: the manifest could not be read: {source}")]
35    ManifestDecode {
36        /// Where the manifest was expected.
37        file: std::path::PathBuf,
38        /// The underlying error.
39        source: serde_json::Error,
40    },
41    /// A file the manifest lists is not in the bundle.
42    #[error("{file}: the manifest lists it, the bundle does not have it")]
43    Missing {
44        /// The listed file that is not there.
45        file: String,
46    },
47    /// A bundled file's bytes differ from what the manifest recorded.
48    #[error("{file}: sha256 is {found}, the manifest says {listed}")]
49    Hash {
50        /// The file whose bytes differ.
51        file: String,
52        /// The hash the bundle actually holds.
53        found: String,
54        /// The hash the manifest recorded.
55        listed: String,
56    },
57    /// A bundled file's row count differs from what the manifest recorded.
58    #[error("{file}: {found} data rows, the manifest says {listed}")]
59    Rows {
60        /// The file whose row count differs.
61        file: String,
62        /// Data rows the bundle actually holds.
63        found: usize,
64        /// Data rows the manifest recorded.
65        listed: usize,
66    },
67}
68
69/// Recompute a bundle against its manifest. **Action.**
70///
71/// Reads `manifest.json` from `dir`, then for every entry re-hashes the
72/// file and recounts its rows. The first mismatch — a listed file that is
73/// missing, a different hash, or a different row count — is named and the
74/// check stops there.
75///
76/// # Errors
77/// A [`VerifyError`] naming the first mismatch, or the manifest itself if
78/// it cannot be read.
79pub fn verify(dir: &Path) -> Result<(), VerifyError> {
80    let path = dir.join(MANIFEST);
81    let text = fs::read_to_string(&path).map_err(|source| VerifyError::ManifestIo {
82        file: path.clone(),
83        source,
84    })?;
85    let manifest = Manifest::from_json(&text)
86        .map_err(|source| VerifyError::ManifestDecode { file: path, source })?;
87
88    for entry in &manifest.files {
89        fault(dir, entry)?;
90    }
91    Ok(())
92}
93
94/// What is wrong with one listed file, if anything. **Action.**
95fn fault(dir: &Path, entry: &crate::manifest::FileEntry) -> Result<(), VerifyError> {
96    let path = dir.join(&entry.name);
97    let bytes = fs::read(&path).map_err(|_| VerifyError::Missing {
98        file: entry.name.clone(),
99    })?;
100
101    let found = sha256_hex(&bytes);
102    if found != entry.sha256 {
103        return Err(VerifyError::Hash {
104            file: entry.name.clone(),
105            found,
106            listed: entry.sha256.clone(),
107        });
108    }
109    let counted = data_rows(&String::from_utf8_lossy(&bytes));
110    if counted != entry.rows {
111        return Err(VerifyError::Rows {
112            file: entry.name.clone(),
113            found: counted,
114            listed: entry.rows,
115        });
116    }
117    Ok(())
118}
119
120/// Data rows in a text file: every non-empty line after the header.
121/// **Calculation.**
122fn data_rows(text: &str) -> usize {
123    text.lines()
124        .skip(1)
125        .filter(|line| !line.trim().is_empty())
126        .count()
127}
128
129#[cfg(test)]
130mod tests {
131    use std::fs;
132
133    use super::*;
134
135    fn write_bundle(dir: &Path) {
136        fs::create_dir_all(dir).unwrap();
137        fs::write(dir.join("meters.csv"), "id,watts\n1,60\n").unwrap();
138        let spec = crate::FileSpec {
139            path: dir.join("meters.csv"),
140            keep_columns: vec!["id".to_owned(), "watts".to_owned()],
141        };
142        crate::bundle(
143            &[spec],
144            dir,
145            std::collections::BTreeMap::new(),
146            "2026-01-01T00:00:00Z",
147            &[],
148        )
149        .unwrap();
150    }
151
152    #[test]
153    fn a_bundle_the_way_it_was_written_verifies() {
154        let home = crate::bundle::unique_directory();
155
156        write_bundle(&home);
157
158        verify(&home).unwrap_or_else(|error| panic!("the bundle verifies: {error}"));
159    }
160
161    #[test]
162    fn a_tampered_byte_makes_verify_fail_naming_that_file() {
163        let home = crate::bundle::unique_directory();
164
165        write_bundle(&home);
166        let path = home.join("meters.csv");
167        let text = fs::read_to_string(&path).unwrap();
168        fs::write(&path, text.replace("60", "61")).unwrap();
169
170        let error = verify(&home).expect_err("the file's bytes changed");
171
172        assert!(
173            matches!(error, VerifyError::Hash { ref file, .. } if file == "meters.csv"),
174            "got {error}"
175        );
176        assert!(error.to_string().contains("meters.csv"), "got {error}");
177    }
178
179    #[test]
180    fn a_file_the_manifest_lists_but_the_bundle_does_not_hold_is_named() {
181        let home = crate::bundle::unique_directory();
182
183        write_bundle(&home);
184        fs::remove_file(home.join("meters.csv")).unwrap();
185
186        let error = verify(&home).expect_err("the file is gone");
187
188        assert!(
189            matches!(error, VerifyError::Missing { ref file } if file == "meters.csv"),
190            "got {error}"
191        );
192    }
193
194    #[test]
195    fn a_changed_row_count_is_named() {
196        let home = crate::bundle::unique_directory();
197
198        write_bundle(&home);
199        // Keep only the header, then rewrite the manifest's hash to match
200        // the shorter file, so the only remaining mismatch is the row count.
201        let path = home.join("meters.csv");
202        let header = fs::read_to_string(&path)
203            .unwrap()
204            .lines()
205            .next()
206            .unwrap()
207            .to_owned();
208        fs::write(&path, format!("{header}\n")).unwrap();
209        let manifest_path = home.join("manifest.json");
210        let manifest = fs::read_to_string(&manifest_path).unwrap();
211        let listed = recorded_sha(&manifest);
212        let found = crate::manifest::sha256_hex(&fs::read(&path).unwrap());
213        fs::write(&manifest_path, manifest.replace(&listed, &found)).unwrap();
214
215        let error = verify(&home).expect_err("the row count changed");
216
217        assert!(
218            matches!(error, VerifyError::Rows { ref file, found: 0, listed: 1 } if file == "meters.csv"),
219            "got {error}"
220        );
221    }
222
223    /// The one hash recorded in the test manifest.
224    fn recorded_sha(manifest: &str) -> String {
225        let start = manifest.find("\"sha256\":\"").unwrap() + "\"sha256\":\"".len();
226        let end = manifest[start..].find('"').unwrap() + start;
227        manifest[start..end].to_owned()
228    }
229
230    #[test]
231    fn data_rows_do_not_count_the_header_or_a_trailing_blank_line() {
232        assert_eq!(data_rows("id\n1\n2\n"), 2);
233        assert_eq!(data_rows("id\n"), 0);
234        assert_eq!(data_rows(""), 0);
235    }
236
237    #[test]
238    fn text_that_is_not_a_manifest_is_refused() {
239        let home = crate::bundle::unique_directory();
240        fs::create_dir_all(&home).unwrap();
241        fs::write(home.join("manifest.json"), "{}").unwrap();
242
243        let error = verify(&home).expect_err("an empty object is not a manifest");
244
245        assert!(
246            matches!(error, VerifyError::ManifestDecode { .. }),
247            "got {error}"
248        );
249    }
250
251    #[test]
252    fn a_missing_manifest_is_refused() {
253        let home = crate::bundle::unique_directory();
254        fs::create_dir_all(&home).unwrap();
255
256        let error = verify(&home).expect_err("there is no manifest");
257
258        assert!(
259            matches!(error, VerifyError::ManifestIo { .. }),
260            "got {error}"
261        );
262    }
263}