feat(mft): add MftRecordIter for zero-copy iteration over MFT records

refactor(mft_file): improve entry size calculations and update size handling
refactor(mft_record): enhance deref implementation and add from_bytes_unchecked method

Author: TeamDman

src/mft/mft_file.rs

@@ -1,5 +1,6 @@
 use crate::mft::fast_fixup::FixupStats;
 use crate::mft::fast_fixup::apply_fixups_parallel;
+use crate::mft::mft_record_iter::MftRecordIter;
 use bytes::Bytes;
 use eyre::Context;
 use std::fmt::Debug;
@@ -10,8 +11,8 @@ use std::time::Instant;
 use thousands::Separable;
 use tracing::debug;
 use tracing::instrument;
-use uom::si::f64::Information;
 use uom::si::information::byte;
+use uom::si::usize::Information;
 
 pub struct MftFile {
     bytes: Bytes,
@@ -33,17 +34,18 @@ impl Deref for MftFile {
 }
 impl MftFile {
     pub fn size(&self) -> Information {
-        Information::new::<byte>(self.bytes.len() as f64)
+        Information::new::<byte>(self.bytes.len())
     }
     pub fn entry_size(&self) -> Information {
         if self.len() < 0x20 {
-            return Information::new::<byte>(1024.0);
+            return Information::new::<byte>(1024);
         }
-        let size = u32::from_le_bytes([self[0x1C], self[0x1D], self[0x1E], self[0x1F]]);
+        let size = u32::from_le_bytes([self[0x1C], self[0x1D], self[0x1E], self[0x1F]]) as usize;
         if size == 0 {
-            Information::new::<byte>(1024.0)
+            // Information::new::<byte>(1024)
+            panic!("MFT entry size field is zero (invalid/unknown)");
         } else {
-            Information::new::<byte>(size as f64)
+            Information::new::<byte>(size)
         }
     }
     pub fn entry_count(&self) -> usize {
@@ -64,20 +66,22 @@ impl MftFile {
         debug!("Opened MFT file: {}", mft_file_path.display());
 
         // Determine file size
-        let file_size_bytes = file
-            .metadata()
-            .wrap_err_with(|| format!("Failed to get metadata for {}", mft_file_path.display()))?
-            .len() as usize;
-        let mft_file_size = Information::new::<byte>(file_size_bytes as f64);
-        if file_size_bytes < 1024 {
+        let mft_file_size = Information::new::<byte>(
+            file.metadata()
+                .wrap_err_with(|| {
+                    format!("Failed to get metadata for {}", mft_file_path.display())
+                })?
+                .len() as usize,
+        );
+        if mft_file_size < Information::new::<byte>(1024) {
             eyre::bail!("MFT file too small: {}", mft_file_path.display());
         }
 
         // Read all bytes
         debug!("Reading cached bytes: {}", mft_file_size.get_human());
         let read_start = Instant::now();
         let bytes = {
-            let mut buf = Vec::with_capacity(file_size_bytes);
+            let mut buf = Vec::with_capacity(mft_file_size.get::<byte>());
             let mut reader = std::io::BufReader::new(&file);
             reader
                 .read_to_end(&mut buf)
@@ -133,4 +137,15 @@ impl MftFile {
             bytes: Bytes::from(raw),
         })
     }
+
+    /// Iterate over fixed-size records contained in this MFT file.
+    ///
+    /// This creates zero-copy `MftRecord` instances by slicing the shared
+    /// `Bytes` buffer. No signature validation is performed.
+    /// The caller is responsible for ensuring fixups were already applied
+    /// (handled by `MftFile::from_bytes`/`from_path`).
+    #[inline]
+    pub fn iter_records(&self) -> MftRecordIter {
+        MftRecordIter::new(self.bytes.clone(), self.entry_size())
+    }
 }

src/mft/mft_record.rs

@@ -1,11 +1,11 @@
 use crate::mft::mft_record_attribute_iter::MftRecordAttributeIter;
 use crate::mft::mft_record_location::MftRecordLocationOnDisk;
 use crate::mft::mft_record_number::MftRecordNumber;
+use bytes::Bytes;
 use eyre::bail;
+use std::ops::Deref;
 use teamy_windows::file::HandleReadExt;
 use uom::si::information::byte;
-use std::ops::Deref;
-use bytes::Bytes;
 
 /// https://digitalinvestigator.blogspot.com/2022/03/the-ntfs-master-file-table-mft.html?m=1
 /// "On a standard hard drive with 512-byte sectors, the MFT is structured as a series of 1,024-byte records,
@@ -22,8 +22,10 @@ pub struct MftRecord {
 }
 
 impl Deref for MftRecord {
-    type Target = [u8];
-    fn deref(&self) -> &Self::Target { self.data.as_ref() }
+    type Target = Bytes;
+    fn deref(&self) -> &Self::Target {
+        &self.data
+    }
 }
 
 impl std::fmt::Debug for MftRecord {
@@ -38,6 +40,15 @@ impl std::fmt::Debug for MftRecord {
 }
 
 impl MftRecord {
+    /// Construct a record without validating the signature.
+    ///
+    /// Use this when the caller already ensured the slice is a single MFT record
+    /// with fixups applied. This avoids redundant checks and copying.
+    #[inline]
+    pub fn from_bytes_unchecked(bytes: Bytes) -> Self {
+        Self { data: bytes }
+    }
+
     // ---- Raw field offset constants (for clarity & reuse) ----
     const OFFSET_FOR_SIGNATURE: usize = 0x00;
     const OFFSET_FOR_UPDATE_SEQUENCE_ARRAY_OFFSET: usize = 0x04; // u16
@@ -54,24 +65,28 @@ impl MftRecord {
     // 0x2A padding
     const OFFSET_FOR_RECORD_NUMBER: usize = 0x2C; // u32 on-disk
 
-
     /// Read a single MFT record from the given drive handle at the specified location.
     /// Validates the "FILE" signature.
-    /// 
+    ///
     /// Useful for reading the $MFT record itself (record 0) or other known record numbers.
     pub fn try_from_handle(
         drive_handle: impl HandleReadExt,
         mft_record_location: MftRecordLocationOnDisk,
     ) -> eyre::Result<Self> {
         let mut data = [0u8; MFT_RECORD_SIZE as usize];
-        drive_handle.try_read_exact(mft_record_location.get::<byte>() as i64, data.as_mut_slice())?;
+        drive_handle.try_read_exact(
+            mft_record_location.get::<byte>() as i64,
+            data.as_mut_slice(),
+        )?;
         if &data[0..4] != b"FILE" {
             bail!(
                 "Invalid MFT record signature: expected 'FILE', got {:?}",
                 String::from_utf8_lossy(&data[0..4])
             );
         }
-        Ok(Self { data: Bytes::from(data.to_vec()) })
+        Ok(Self {
+            data: Bytes::from(data.to_vec()),
+        })
     }
 
     /// Zero-copy access to the 4-byte signature.
@@ -175,5 +190,7 @@ impl MftRecord {
     }
 
     /// Iterate raw attribute slices (header + body) in this record.
-    pub fn iter_attributes(&self) -> MftRecordAttributeIter<'_> { MftRecordAttributeIter::new(self) }
+    pub fn iter_attributes(&self) -> MftRecordAttributeIter<'_> {
+        MftRecordAttributeIter::new(self)
+    }
 }

src/mft/mft_record_iter.rs

@@ -0,0 +1,74 @@
+use crate::mft::mft_record::MftRecord;
+use bytes::Bytes;
+use uom::ConstZero;
+use uom::si::information::byte;
+use uom::si::usize::Information;
+
+/// Zero-copy iterator over MFT records stored contiguously in a `Bytes` buffer.
+pub struct MftRecordIter {
+    bytes: Bytes,
+    entry_size: Information,
+    index: usize,
+    total: usize,
+}
+
+impl MftRecordIter {
+    pub fn new(bytes: Bytes, entry_size: Information) -> Self {
+        let total = if entry_size == Information::ZERO {
+            panic!("MFT entry size cannot be zero");
+        } else {
+            bytes.len() / entry_size.get::<byte>()
+        };
+        Self {
+            bytes,
+            entry_size,
+            index: 0,
+            total,
+        }
+    }
+}
+
+impl Iterator for MftRecordIter {
+    type Item = MftRecord;
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.index >= self.total {
+            return None;
+        }
+        let start = self.index * self.entry_size;
+        let end = start + self.entry_size;
+        self.index += 1;
+        Some(MftRecord::from_bytes_unchecked(
+            self.bytes.slice(start.get::<byte>()..end.get::<byte>()),
+        ))
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let remaining = self.total.saturating_sub(self.index);
+        (remaining, Some(remaining))
+    }
+}
+
+impl ExactSizeIterator for MftRecordIter {}
+impl core::iter::FusedIterator for MftRecordIter {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn iter_records_yields_zero_copy_records() {
+        const ENTRY_SIZE: usize = 1024;
+        let mut buf = vec![0u8; ENTRY_SIZE * 2];
+        // Write 'FILE' signature for both records
+        buf[0..4].copy_from_slice(b"FILE");
+        buf[ENTRY_SIZE..ENTRY_SIZE + 4].copy_from_slice(b"FILE");
+        let bytes = Bytes::from(buf);
+        let mut it = MftRecordIter::new(bytes.clone(), Information::new::<byte>(ENTRY_SIZE));
+        let r1 = it.next().expect("first record");
+        let r2 = it.next().expect("second record");
+        assert!(it.next().is_none());
+        assert_eq!(r1.get_signature(), b"FILE");
+        assert_eq!(r2.get_signature(), b"FILE");
+        assert_eq!(bytes.len(), ENTRY_SIZE * 2);
+    }
+}

src/mft/mod.rs

@@ -11,6 +11,7 @@ pub mod mft_record_reference;
 pub mod mft_sequence_number;
 pub mod mft_physical_read;
 pub mod mft_file;
+pub mod mft_record_iter;
 pub mod fast_fixup;
 pub mod fast_entry;
 pub mod path_resolve;

src/mft_process.rs

@@ -8,7 +8,6 @@ use std::time::Instant;
 use thousands::Separable;
 use tracing::debug;
 use tracing::info;
-use uom::si::f64::Information;
 use uom::si::f64::InformationRate;
 use uom::si::f64::Ratio;
 use uom::si::f64::Time;
@@ -37,7 +36,9 @@ pub fn process_mft_file(
     let file_names =
         fast_entry::par_collect_filenames(&mft_file, mft_file.entry_size().get::<byte>() as usize);
     let scan_elapsed = Time::new::<second>(scan_start.elapsed().as_secs_f64());
-    let scan_rate = InformationRate::from(mft_file.size() / scan_elapsed);
+    let scan_rate = InformationRate::from(
+        uom::si::f64::Information::new::<byte>(mft_file.size().get::<byte>() as f64) / scan_elapsed,
+    );
     debug!(
         drive_letter = &drive_letter,
         "Took {} ({}) entries_with_names={}",
@@ -53,13 +54,12 @@ pub fn process_mft_file(
         file_names.x30_count().separate_with_commas()
     );
     let path_resolve_start = Instant::now();
-    let multi =        path_resolve::resolve_paths_all_parallel(&file_names)?;
+    let multi = path_resolve::resolve_paths_all_parallel(&file_names)?;
     let path_resolve_elapsed = Time::new::<second>(path_resolve_start.elapsed().as_secs_f64());
     let total_paths = multi.total_paths();
     let resolved_entries = multi.0.iter().filter(|v| !v.is_empty()).count();
-    let resolve_rate = InformationRate::from(
-        Information::new::<byte>(resolved_entries as f64 * 256.0) / path_resolve_elapsed,
-    );
+    let resolved_size = uom::si::f64::Information::new::<byte>(resolved_entries as f64 * 256.0);
+    let resolve_rate = InformationRate::from(resolved_size / path_resolve_elapsed);
     debug!(
         drive_letter = &drive_letter,
         "Took {} ({}) entries_resolved={} total_paths={}",
@@ -84,7 +84,8 @@ pub fn process_mft_file(
 
     let elapsed = Time::new::<second>(start.elapsed().as_secs_f64());
     // aggregate performance statistics
-    let total_data_rate = InformationRate::from(mft_file.size() / elapsed); // overall throughput
+    let total_size = uom::si::f64::Information::new::<byte>(mft_file.size().get::<byte>() as f64);
+    let total_data_rate = InformationRate::from(total_size / elapsed); // overall throughput
     let entries_rate = Ratio::new::<ratio>(mft_file.entry_count() as f64) / elapsed;
     debug!(
         drive_letter = &drive_letter,