Skip to main content

quichash_core/database/
mod.rs

1//! QuicHash and hashdeep manifest formats.
2// Reads and writes plain text hash database files
3
4use std::collections::HashMap;
5use std::io::Write;
6use std::path::{Path, PathBuf};
7
8use crate::error::HashUtilityError;
9use crate::hash::Algorithm;
10use crate::manifest::Manifest;
11use crate::operation::FailurePolicy;
12
13pub(crate) mod checksum;
14pub(crate) mod compression;
15pub(crate) mod hashdeep;
16pub(crate) mod manifest_io;
17pub(crate) mod quichash;
18
19pub(crate) use hashdeep::HashdeepRecord;
20
21/// Database entry with metadata
22#[derive(Debug, Clone)]
23pub struct DatabaseEntry {
24    /// Lowercase hexadecimal digest.
25    pub hash: String,
26    /// Algorithm name recorded in the row.
27    pub algorithm: String,
28    /// Whether the digest was created with sampled hashing.
29    pub fast_mode: bool,
30}
31
32/// Database format type
33#[derive(Debug, Clone, Copy, PartialEq)]
34pub enum DatabaseFormat {
35    /// QuicHash format: hash  algorithm  fast_mode  filepath
36    Quichash,
37    /// Hashdeep format: size,hash1,hash2,...,filename
38    Hashdeep,
39}
40
41/// Malformed input line retained while reading with a continue policy.
42#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
43pub struct DatabaseIssue {
44    /// One-based source line number.
45    pub line: usize,
46    /// Explanation of why the line could not be parsed.
47    pub message: String,
48}
49
50/// Typed manifest and non-fatal parsing issues returned together.
51#[derive(Clone, Debug, serde::Serialize)]
52pub struct ManifestRead {
53    /// Successfully parsed and canonicalized manifest entries.
54    pub manifest: Manifest,
55    /// Malformed lines skipped under [`FailurePolicy::Continue`].
56    pub issues: Vec<DatabaseIssue>,
57}
58
59/// Handler for reading and writing hash database files
60pub struct DatabaseHandler;
61
62impl DatabaseHandler {
63    /// Infer a checksum algorithm from a path's file extension.
64    pub fn checksum_algorithm_from_path(path: &Path) -> Option<Algorithm> {
65        checksum::checksum_algorithm_from_path(path)
66    }
67
68    /// Check if a path corresponds to a supported checksum format for verification.
69    pub fn verification_checksum_algorithm(
70        path: &Path,
71    ) -> Result<Option<Algorithm>, HashUtilityError> {
72        checksum::verification_checksum_algorithm(path)
73    }
74
75    /// Read a conventional two-column checksum file for verification.
76    pub fn read_checksum_manifest(path: &Path) -> Result<Manifest, HashUtilityError> {
77        checksum::read_checksum_manifest(path)
78    }
79
80    /// Return the canonical output path for a database.
81    pub fn canonical_output_path(
82        requested_path: &Path,
83        format: DatabaseFormat,
84        compressed: bool,
85    ) -> Result<PathBuf, HashUtilityError> {
86        compression::canonical_output_path(requested_path, format, compressed)
87    }
88
89    /// Write a manifest to its canonical database path.
90    pub fn write_manifest_file(
91        requested_path: &Path,
92        manifest: &Manifest,
93        format: DatabaseFormat,
94        compressed: bool,
95    ) -> Result<PathBuf, HashUtilityError> {
96        manifest_io::write_manifest_file(requested_path, manifest, format, compressed)
97    }
98
99    /// Check if a path has .zst or .zstd extension (compressed database)
100    pub fn is_compressed(path: &Path) -> bool {
101        compression::is_compressed(path)
102    }
103
104    /// Compress a database file with Zstandard.
105    pub fn compress_database(input_path: &Path) -> Result<PathBuf, HashUtilityError> {
106        compression::compress_database(input_path)
107    }
108
109    /// Detect the format of a database file by reading its first few lines
110    pub fn detect_format(path: &Path) -> Result<DatabaseFormat, HashUtilityError> {
111        manifest_io::detect_format(path)
112    }
113
114    /// Write a single hash entry to the output writer
115    pub fn write_entry(
116        writer: &mut impl Write,
117        hash: &str,
118        algorithm: &str,
119        fast_mode: bool,
120        path: &Path,
121    ) -> std::io::Result<()> {
122        quichash::write_entry(writer, hash, algorithm, fast_mode, path)
123    }
124
125    /// Write hashdeep format header
126    pub fn write_hashdeep_header(
127        writer: &mut impl Write,
128        algorithms: &[String],
129    ) -> std::io::Result<()> {
130        hashdeep::write_hashdeep_header(writer, algorithms)
131    }
132
133    /// Write a single entry in hashdeep format
134    pub fn write_hashdeep_entry(
135        writer: &mut impl Write,
136        size: u64,
137        hashes: &[String],
138        path: &Path,
139    ) -> std::io::Result<()> {
140        hashdeep::write_hashdeep_entry(writer, size, hashes, path)
141    }
142
143    /// Read a hash database file and parse it into a HashMap
144    pub fn read_database(path: &Path) -> Result<HashMap<PathBuf, DatabaseEntry>, HashUtilityError> {
145        manifest_io::read_database(path)
146    }
147
148    /// Read every digest from a QuicHash or hashdeep manifest.
149    pub fn read_manifest(path: &Path) -> Result<Manifest, HashUtilityError> {
150        manifest_io::read_manifest(path)
151    }
152
153    /// Read a typed manifest, optionally retaining malformed-line issues.
154    pub fn read_manifest_with_policy(
155        path: &Path,
156        failure_policy: FailurePolicy,
157    ) -> Result<ManifestRead, HashUtilityError> {
158        manifest_io::read_manifest_with_policy(path, failure_policy)
159    }
160
161    /// Write every manifest digest in QuicHash or hashdeep format.
162    pub fn write_manifest(
163        writer: &mut impl Write,
164        manifest: &Manifest,
165        format: DatabaseFormat,
166    ) -> std::io::Result<()> {
167        manifest_io::write_manifest(writer, manifest, format)
168    }
169
170    /// Parse a single line from a QuicHash database file.
171    pub fn parse_line(line: &str) -> Option<(String, String, bool, PathBuf)> {
172        quichash::parse_line(line)
173    }
174
175    /// Parse a single line from a hashdeep database file.
176    pub fn parse_hashdeep_line(
177        line: &str,
178        algorithms: &[String],
179    ) -> Option<Vec<(PathBuf, DatabaseEntry)>> {
180        hashdeep::parse_hashdeep_line(line, algorithms)
181    }
182
183    pub(crate) fn parse_hashdeep_record(
184        line: &str,
185        expected_hash_count: Option<usize>,
186    ) -> Option<HashdeepRecord> {
187        hashdeep::parse_hashdeep_record(line, expected_hash_count)
188    }
189}