Skip to main content

rosetta_squint/
lib.rs

1//! rosetta-squint — point at an image (path or bytes), get the same hash
2//! hex string as every other rosetta-squint port for the same input.
3//!
4//! # Examples
5//!
6//! ```no_run
7//! use rosetta_squint::{phash, phash_bytes};
8//!
9//! let h = phash("photo.jpg", 8).unwrap();
10//! println!("{}", h);
11//! ```
12
13use std::fs;
14use std::io::Read;
15use std::path::Path;
16
17use image::{DynamicImage, ImageBuffer, Rgb, Rgba};
18use rosetta_squint_decode::{decode as rid_decode, Channels, DecodeError, DecodedImage};
19use rosetta_squint_hash::ImageHashError;
20
21pub use rosetta_squint_hash::{
22    hex_to_flathash, hex_to_hash, hex_to_multihash, Hash, ImageMultiHash,
23};
24
25/// Reject path-based decode of files that are too large or are non-regular
26/// (e.g., `/dev/zero`, named pipes, character devices) BEFORE reading bytes.
27/// Callers that genuinely need to process images larger than this threshold
28/// should decode via rosetta-squint-decode directly after explicit validation.
29pub const MAX_FILE_SIZE: u64 = 256 * 1024 * 1024; // 256 MiB
30
31// ── Error type ──────────────────────────────────────────────────────────────
32
33#[derive(Debug, thiserror::Error)]
34pub enum RosettaError {
35    #[error("io: {0}")]
36    Io(#[from] std::io::Error),
37    #[error("decode: {0}")]
38    Decode(#[from] DecodeError),
39    #[error("hash: {0}")]
40    Hash(#[from] ImageHashError),
41    #[error("internal: failed to construct image from decoded buffer")]
42    BadBuffer,
43    #[error("not a regular file: {path}")]
44    NotRegularFile { path: String },
45    #[error("symlink not allowed: {path}")]
46    SymlinkNotAllowed { path: String },
47    #[error(
48        "input file too large: {size} bytes (max {max} bytes / 256 MiB). \
49         For images above this threshold, decode via rosetta-squint-decode \
50         directly after explicit validation."
51    )]
52    FileTooLarge { size: u64, max: u64 },
53}
54
55// ── DecodedImage → DynamicImage ─────────────────────────────────────────────
56
57fn decoded_to_dynamic(d: DecodedImage) -> Result<DynamicImage, RosettaError> {
58    let w = d.width as u32;
59    let h = d.height as u32;
60    match d.channels {
61        Channels::Rgb => {
62            let buf: ImageBuffer<Rgb<u8>, Vec<u8>> =
63                ImageBuffer::from_raw(w, h, d.data).ok_or(RosettaError::BadBuffer)?;
64            Ok(DynamicImage::ImageRgb8(buf))
65        }
66        Channels::Rgba => {
67            let buf: ImageBuffer<Rgba<u8>, Vec<u8>> =
68                ImageBuffer::from_raw(w, h, d.data).ok_or(RosettaError::BadBuffer)?;
69            Ok(DynamicImage::ImageRgba8(buf))
70        }
71    }
72}
73
74// ── Public decode helpers ────────────────────────────────────────────────────
75
76/// Decode raw image bytes via rosetta-squint-decode and return a `DynamicImage`.
77pub fn decode_to_image(bytes: &[u8]) -> Result<DynamicImage, RosettaError> {
78    let decoded = rid_decode(bytes)?;
79    decoded_to_dynamic(decoded)
80}
81
82/// Open `path` such that the open fails if the final path component is a
83/// symlink. On Unix this uses `O_NOFOLLOW`. On non-Unix targets there is
84/// no equivalent open flag, so we pre-check via `symlink_metadata().is_symlink()`
85/// before opening — there is a narrow TOCTOU window between the lstat and
86/// the open on those platforms, but it is much narrower than the symlink
87/// target itself being swapped.
88fn open_no_follow(p: &Path) -> Result<fs::File, RosettaError> {
89    #[cfg(unix)]
90    {
91        use std::os::unix::fs::OpenOptionsExt;
92        fs::OpenOptions::new()
93            .read(true)
94            .custom_flags(libc::O_NOFOLLOW)
95            .open(p)
96            .map_err(|e| {
97                // ELOOP is what O_NOFOLLOW raises when the final path
98                // component is a symlink. Translate to a clearer variant
99                // so callers can distinguish symlink rejection from a
100                // generic I/O error.
101                if e.raw_os_error() == Some(libc::ELOOP) {
102                    RosettaError::SymlinkNotAllowed {
103                        path: p.display().to_string(),
104                    }
105                } else {
106                    RosettaError::Io(e)
107                }
108            })
109    }
110    #[cfg(not(unix))]
111    {
112        match fs::symlink_metadata(p) {
113            Ok(meta) if meta.file_type().is_symlink() => {
114                Err(RosettaError::SymlinkNotAllowed {
115                    path: p.display().to_string(),
116                })
117            }
118            Ok(_) => Ok(fs::File::open(p)?),
119            Err(e) => Err(RosettaError::Io(e)),
120        }
121    }
122}
123
124/// Read a file from disk and decode it to a `DynamicImage`.
125///
126/// Refuses symlinks (via `O_NOFOLLOW` on Unix / `symlink_metadata` on
127/// non-Unix), non-regular files (FIFOs, `/dev/zero`, character devices,
128/// etc.) and files larger than [`MAX_FILE_SIZE`] BEFORE reading bytes —
129/// without these guards `fs::read("/dev/zero")` would loop until OOM and
130/// a 300 MiB sparse file would allocate 300 MiB even though it contains
131/// no image. Callers who genuinely want symlink resolution must do it
132/// explicitly (e.g. `std::fs::canonicalize`) before calling this function.
133///
134/// The file is opened once and both the regular-file and size checks run
135/// against `File::metadata()` (which queries the open fd, not the path),
136/// closing the obvious TOCTOU window between stat and read. The read uses
137/// a `MAX_FILE_SIZE + 1` `take` limiter so a concurrent writer that grows
138/// the file after the size check is still rejected rather than allowed to
139/// silently exceed the cap.
140pub fn decode_file<P: AsRef<Path>>(path: P) -> Result<DynamicImage, RosettaError> {
141    let p = path.as_ref();
142    let mut f = open_no_follow(p)?;
143    // `File::metadata()` calls fstat() on the open fd, not stat() on the
144    // path — this is what defeats the TOCTOU.
145    let metadata = f.metadata()?;
146    if !metadata.is_file() {
147        return Err(RosettaError::NotRegularFile {
148            path: p.display().to_string(),
149        });
150    }
151    if metadata.len() > MAX_FILE_SIZE {
152        return Err(RosettaError::FileTooLarge {
153            size: metadata.len(),
154            max: MAX_FILE_SIZE,
155        });
156    }
157    // Pre-size by min(metadata, MAX) to avoid re-allocations on the common
158    // path. `take(MAX+1)` ensures we detect post-stat growth: if more than
159    // MAX_FILE_SIZE bytes are read, error out.
160    let cap = std::cmp::min(metadata.len(), MAX_FILE_SIZE) as usize;
161    let mut bytes: Vec<u8> = Vec::with_capacity(cap);
162    f.by_ref()
163        .take(MAX_FILE_SIZE + 1)
164        .read_to_end(&mut bytes)?;
165    if bytes.len() as u64 > MAX_FILE_SIZE {
166        return Err(RosettaError::FileTooLarge {
167            size: bytes.len() as u64,
168            max: MAX_FILE_SIZE,
169        });
170    }
171    decode_to_image(&bytes)
172}
173
174// ── phash ────────────────────────────────────────────────────────────────────
175
176/// Compute phash from a file path.
177pub fn phash<P: AsRef<Path>>(path: P, hash_size: usize) -> Result<Hash, RosettaError> {
178    let img = decode_file(path)?;
179    Ok(rosetta_squint_hash::phash(&img, hash_size)?)
180}
181
182/// Compute phash from raw bytes.
183pub fn phash_bytes(bytes: &[u8], hash_size: usize) -> Result<Hash, RosettaError> {
184    let img = decode_to_image(bytes)?;
185    Ok(rosetta_squint_hash::phash(&img, hash_size)?)
186}
187
188// ── phash_simple ─────────────────────────────────────────────────────────────
189
190/// Compute phash_simple from a file path.
191pub fn phash_simple<P: AsRef<Path>>(path: P, hash_size: usize) -> Result<Hash, RosettaError> {
192    let img = decode_file(path)?;
193    Ok(rosetta_squint_hash::phash_simple(&img, hash_size)?)
194}
195
196/// Compute phash_simple from raw bytes.
197pub fn phash_simple_bytes(bytes: &[u8], hash_size: usize) -> Result<Hash, RosettaError> {
198    let img = decode_to_image(bytes)?;
199    Ok(rosetta_squint_hash::phash_simple(&img, hash_size)?)
200}
201
202// ── dhash ────────────────────────────────────────────────────────────────────
203
204/// Compute dhash from a file path.
205pub fn dhash<P: AsRef<Path>>(path: P, hash_size: usize) -> Result<Hash, RosettaError> {
206    let img = decode_file(path)?;
207    Ok(rosetta_squint_hash::dhash(&img, hash_size)?)
208}
209
210/// Compute dhash from raw bytes.
211pub fn dhash_bytes(bytes: &[u8], hash_size: usize) -> Result<Hash, RosettaError> {
212    let img = decode_to_image(bytes)?;
213    Ok(rosetta_squint_hash::dhash(&img, hash_size)?)
214}
215
216// ── dhash_vertical ───────────────────────────────────────────────────────────
217
218/// Compute dhash_vertical from a file path.
219pub fn dhash_vertical<P: AsRef<Path>>(path: P, hash_size: usize) -> Result<Hash, RosettaError> {
220    let img = decode_file(path)?;
221    Ok(rosetta_squint_hash::dhash_vertical(&img, hash_size)?)
222}
223
224/// Compute dhash_vertical from raw bytes.
225pub fn dhash_vertical_bytes(bytes: &[u8], hash_size: usize) -> Result<Hash, RosettaError> {
226    let img = decode_to_image(bytes)?;
227    Ok(rosetta_squint_hash::dhash_vertical(&img, hash_size)?)
228}
229
230// ── average_hash ─────────────────────────────────────────────────────────────
231
232/// Compute average_hash from a file path.
233pub fn average_hash<P: AsRef<Path>>(path: P, hash_size: usize) -> Result<Hash, RosettaError> {
234    let img = decode_file(path)?;
235    Ok(rosetta_squint_hash::average_hash(&img, hash_size)?)
236}
237
238/// Compute average_hash from raw bytes.
239pub fn average_hash_bytes(bytes: &[u8], hash_size: usize) -> Result<Hash, RosettaError> {
240    let img = decode_to_image(bytes)?;
241    Ok(rosetta_squint_hash::average_hash(&img, hash_size)?)
242}
243
244// ── whash_haar ───────────────────────────────────────────────────────────────
245
246/// Compute whash_haar from a file path.
247pub fn whash_haar<P: AsRef<Path>>(path: P, hash_size: usize) -> Result<Hash, RosettaError> {
248    let img = decode_file(path)?;
249    Ok(rosetta_squint_hash::whash_haar(&img, hash_size)?)
250}
251
252/// Compute whash_haar from raw bytes.
253pub fn whash_haar_bytes(bytes: &[u8], hash_size: usize) -> Result<Hash, RosettaError> {
254    let img = decode_to_image(bytes)?;
255    Ok(rosetta_squint_hash::whash_haar(&img, hash_size)?)
256}
257
258// ── whash_db4 ────────────────────────────────────────────────────────────────
259
260/// Compute whash_db4 from a file path.
261pub fn whash_db4<P: AsRef<Path>>(path: P, hash_size: usize) -> Result<Hash, RosettaError> {
262    let img = decode_file(path)?;
263    Ok(rosetta_squint_hash::whash_db4(&img, hash_size)?)
264}
265
266/// Compute whash_db4 from raw bytes.
267pub fn whash_db4_bytes(bytes: &[u8], hash_size: usize) -> Result<Hash, RosettaError> {
268    let img = decode_to_image(bytes)?;
269    Ok(rosetta_squint_hash::whash_db4(&img, hash_size)?)
270}
271
272// ── whash_db4_robust ─────────────────────────────────────────────────────────
273
274/// Compute whash_db4_robust from a file path.
275pub fn whash_db4_robust<P: AsRef<Path>>(path: P, hash_size: usize) -> Result<Hash, RosettaError> {
276    let img = decode_file(path)?;
277    Ok(rosetta_squint_hash::whash_db4_robust(&img, hash_size)?)
278}
279
280/// Compute whash_db4_robust from raw bytes.
281pub fn whash_db4_robust_bytes(bytes: &[u8], hash_size: usize) -> Result<Hash, RosettaError> {
282    let img = decode_to_image(bytes)?;
283    Ok(rosetta_squint_hash::whash_db4_robust(&img, hash_size)?)
284}
285
286// ── colorhash ────────────────────────────────────────────────────────────────
287
288/// Compute colorhash from a file path.
289///
290/// `binbits` controls the number of bits per histogram bin (default is 3 in Python).
291pub fn colorhash<P: AsRef<Path>>(path: P, binbits: usize) -> Result<Hash, RosettaError> {
292    let img = decode_file(path)?;
293    Ok(rosetta_squint_hash::colorhash(&img, binbits)?)
294}
295
296/// Compute colorhash from raw bytes.
297pub fn colorhash_bytes(bytes: &[u8], binbits: usize) -> Result<Hash, RosettaError> {
298    let img = decode_to_image(bytes)?;
299    Ok(rosetta_squint_hash::colorhash(&img, binbits)?)
300}
301
302// ── crop_resistant_hash ───────────────────────────────────────────────────────
303
304/// Compute crop_resistant_hash from a file path.
305///
306/// `limit_segments`: optional cap on the number of segments to keep
307/// (largest first). Pass `None` to keep all segments — matches Python's
308/// default `limit_segments=None`.
309pub fn crop_resistant_hash<P: AsRef<Path>>(
310    path: P,
311    limit_segments: Option<usize>,
312) -> Result<ImageMultiHash, RosettaError> {
313    let img = decode_file(path)?;
314    Ok(rosetta_squint_hash::crop_resistant_hash(&img, limit_segments)?)
315}
316
317/// Compute crop_resistant_hash from raw bytes.
318///
319/// See [`crop_resistant_hash`] for the `limit_segments` semantics.
320pub fn crop_resistant_hash_bytes(
321    bytes: &[u8],
322    limit_segments: Option<usize>,
323) -> Result<ImageMultiHash, RosettaError> {
324    let img = decode_to_image(bytes)?;
325    Ok(rosetta_squint_hash::crop_resistant_hash(&img, limit_segments)?)
326}