hadris-fat 2.2.0

//! Read operations for FAT filesystems.

io_transform! {

#[cfg(feature = "alloc")]
use core::ops::DerefMut;

#[cfg(feature = "alloc")]
use alloc::vec::Vec;

use crate::error::{Error, Result};
#[cfg(feature = "write")]
use crate::file::ShortFileName;
use super::{
    fs::FatVolume, dir::FileEntry,
    io::{Cluster, ClusterLike, ErrorKind, Read, Seek, SeekFrom},
};

/// A reader for file content in a FAT filesystem.
///
/// This struct provides a `Read` implementation that follows the cluster chain
/// to read file contents.
///
/// # Buffering
///
/// When the `alloc` feature is enabled, the reader can optionally buffer data
/// to reduce the number of seek and read operations:
///
/// - [`with_buffer`](Self::with_buffer): Enable cluster-level buffering. Each cluster
///   is read entirely into memory and subsequent reads are served from the buffer.
///
/// - [`with_cached_chain`](Self::with_cached_chain): Pre-cache the entire cluster chain.
///   This is useful for small files where you want to avoid repeated FAT lookups.
pub struct FileReader<'a, DATA: Read + Seek> {
    fs: &'a FatVolume<DATA>,
    /// First cluster of the file, as recorded in the directory entry.
    first_cluster: Cluster<usize>,
    cluster: Cluster<usize>,
    /// Offset within the current cluster
    offset_in_cluster: usize,
    /// Current logical position in the file
    position: u64,
    /// Total size of the file
    size: usize,
    /// Cluster transitions taken so far. Bounded by `Fat::max_cluster()` so a
    /// corrupt looping chain surfaces as `Error::ClusterLoop` instead of
    /// hanging the reader.
    cluster_steps: u32,
    /// Optional cluster buffer for reduced I/O
    #[cfg(feature = "alloc")]
    cluster_buffer: Option<Vec<u8>>,
    /// Pre-cached cluster chain (optional)
    #[cfg(feature = "alloc")]
    cached_chain: Option<Vec<u32>>,
    /// Current index in the cached chain
    #[cfg(feature = "alloc")]
    chain_index: usize,
    /// Directory-slot coordinates captured at open, used to revalidate that the
    /// file has not been deleted (and its clusters reused) before serving reads.
    /// Only meaningful with `write`: a read-only volume can never mutate an
    /// entry, so a reader can never become stale.
    #[cfg(feature = "write")]
    entry_parent: Cluster<usize>,
    #[cfg(feature = "write")]
    entry_offset: usize,
    #[cfg(feature = "write")]
    entry_short_name: ShortFileName,
    /// Creation timestamp captured at open, revalidated alongside the name.
    #[cfg(feature = "write")]
    entry_created: crate::time::FatDateTime,
}

impl<'a, DATA: Read + Seek> FileReader<'a, DATA> {
    /// Create a new FileReader for a file entry.
    ///
    /// Returns an error if the entry is a directory.
    pub fn new(fs: &'a FatVolume<DATA>, entry: &FileEntry) -> Result<Self> {
        if entry.is_directory() {
            return Err(Error::NotAFile);
        }

        Ok(Self {
            fs,
            first_cluster: entry.cluster(),
            cluster: entry.cluster(),
            offset_in_cluster: 0,
            position: 0,
            size: entry.len() as usize,
            cluster_steps: 0,
            #[cfg(feature = "alloc")]
            cluster_buffer: None,
            #[cfg(feature = "alloc")]
            cached_chain: None,
            #[cfg(feature = "alloc")]
            chain_index: 0,
            #[cfg(feature = "write")]
            entry_parent: entry.parent_clus,
            #[cfg(feature = "write")]
            entry_offset: entry.offset_within_cluster,
            #[cfg(feature = "write")]
            entry_short_name: entry.short_name,
            #[cfg(feature = "write")]
            entry_created: entry.created,
        })
    }

    /// Returns the total size of the file in bytes.
    pub fn size(&self) -> usize {
        self.size
    }

    /// Returns the current logical position in the file.
    pub fn position(&self) -> u64 {
        self.position
    }

    /// Returns the number of bytes remaining to be read.
    pub fn remaining(&self) -> usize {
        (self.size as u64).saturating_sub(self.position) as usize
    }

    /// Enable cluster-level buffering.
    ///
    /// When enabled, each cluster is read entirely into memory on first access,
    /// and subsequent reads within that cluster are served from the buffer.
    /// This reduces the number of seek operations at the cost of memory usage.
    ///
    /// Memory usage: One cluster size (typically 4KB to 64KB).
    #[cfg(feature = "alloc")]
    pub fn with_buffer(mut self) -> Self {
        self.cluster_buffer = Some(Vec::new());
        self
    }

    /// Pre-cache the entire cluster chain.
    ///
    /// This reads the entire FAT chain for the file into memory, eliminating
    /// the need for FAT lookups during sequential reads. This is most beneficial
    /// for fragmented files or when performing many random seeks. The current
    /// logical position is preserved.
    ///
    /// Memory usage: 4 bytes per cluster in the file.
    #[cfg(feature = "alloc")]
    pub async fn with_cached_chain(mut self) -> Result<Self> {
        if self.first_cluster.0 < 2 {
            // Empty file, no chain to cache
            self.cached_chain = Some(Vec::new());
            return Ok(self);
        }

        let max_clusters = self.fs.info.max_cluster as usize;
        let mut data = self.fs.data.lock();
        let cluster_size = data.cluster_size;
        let chain = self
            .fs
            .fat
            .read_chain(
                data.deref_mut(),
                self.first_cluster.0 as u32,
                max_clusters,
            )
            .await?;
        drop(data);

        if self.position < self.size as u64 {
            let chain_index = self.position as usize / cluster_size;
            let cluster = chain
                .get(chain_index)
                .copied()
                .ok_or(Error::UnexpectedEndOfChain {
                    cluster: chain
                        .last()
                        .copied()
                        .unwrap_or(self.first_cluster.0 as u32),
                })?;
            self.cluster.0 = cluster as usize;
            self.offset_in_cluster = self.position as usize % cluster_size;
            self.chain_index = chain_index;
        }
        self.cached_chain = Some(chain);
        Ok(self)
    }

    /// Read data from the file.
    ///
    /// Reads up to `buf.len()` bytes, or fewer at end-of-file. Use a small `buf` to
    /// stream incrementally; a larger `buf` allows more bytes per call (including
    /// contiguous-cluster bulk I/O when the chain is cached). The underlying
    /// [`Read`](crate::io::Read) / [`Seek`](crate::io::Seek) implementation can enforce
    /// alignment or transfer sizes as needed. Optional per-cluster buffering applies when
    /// enabled.
    pub async fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
        // Cap by caller buffer and bytes left in the file; actual I/O may be one or many
        // steps inside read_to_buf (cached contiguous runs vs. read_one_chunk loop).
        let max = buf.len().min(self.remaining());
        if max == 0 {
            return Ok(0);
        }
        self.read_to_buf(&mut buf[..max]).await
    }

    /// Read into `buf` until the buffer is full or the end of the file is reached.
    ///
    /// At most `buf.len().min(self.remaining())` bytes are read. Returns the number of
    /// bytes written to the start of `buf`.
    ///
    /// When the cluster chain is cached (`with_cached_chain`), contiguous runs of
    /// clusters are read in one seek+read per run (one I/O per fragment) instead of
    /// one per cluster.
    async fn read_to_buf(&mut self, buf: &mut [u8]) -> Result<usize> {
        let max = buf.len().min(self.remaining());
        if max == 0 {
            return Ok(0);
        }
        // Before serving any bytes, confirm the file's directory slot still holds
        // this exact entry. If it was deleted (and its clusters possibly reused)
        // since the reader opened, revalidation returns `StaleEntry` rather than
        // disclosing an unrelated file's data. Only reachable with `write`; a
        // read-only volume can never mutate an entry out from under a reader.
        #[cfg(feature = "write")]
        self.fs
            .revalidate_slot(
                self.entry_parent,
                self.entry_offset,
                &self.entry_short_name,
                &self.entry_created,
            )
            .await?;
        let buf = &mut buf[..max];

        #[cfg(feature = "alloc")]
        {
            let mut data = self.fs.data.lock();
            let cluster_size = data.cluster_size;
            let data_start = self.fs.info.data_start;

            // Cached chain: coalesce physically consecutive clusters into one seek+read per run.
            if let Some(ref chain) = self.cached_chain {
                let buf_len = buf.len();
                // Fast path: one seek + one read per contiguous run of clusters
                let mut total = 0usize;
                let mut chain_index = self.chain_index;
                let mut offset_in_cluster = self.offset_in_cluster;

                while total < buf_len && chain_index < chain.len() {
                    let first_cluster = chain[chain_index] as usize;
                    // Count contiguous run: chain[chain_index], chain[chain_index+1], ... while consecutive
                    let mut run_len = 1usize;
                    while chain_index + run_len < chain.len()
                        && chain[chain_index + run_len] == chain[chain_index + run_len - 1] + 1
                    {
                        run_len += 1;
                    }

                    // Bytes we can read from this run (from current offset to end of run)
                    let bytes_from_first = cluster_size.saturating_sub(offset_in_cluster);
                    let bytes_from_run = bytes_from_first
                        .saturating_add(run_len.saturating_sub(1).saturating_mul(cluster_size));
                    let to_read = bytes_from_run.min(buf_len - total);

                    if to_read == 0 {
                        break;
                    }

                    let seek_pos = Cluster(first_cluster)
                        .to_bytes(data_start, cluster_size)
                        .saturating_add(offset_in_cluster);
                    data.seek(SeekFrom::Start(seek_pos as u64)).await?;
                    data.read_exact(&mut buf[total..total + to_read]).await?;

                    total += to_read;
                    self.position += to_read as u64;

                    // Advance by clusters we consumed
                    let new_offset = offset_in_cluster + to_read;
                    chain_index += new_offset / cluster_size;
                    offset_in_cluster = new_offset % cluster_size;
                }

                self.chain_index = chain_index;
                self.offset_in_cluster = offset_in_cluster;
                if chain_index < chain.len() {
                    self.cluster.0 = chain[chain_index] as usize;
                }
                drop(data);
                return Ok(total);
            }

            drop(data);
        }

        // No cached chain (or alloc off): walk the FAT one cluster-sized step at a time.
        let buf_len = buf.len();
        let mut total = 0usize;
        while total < buf_len {
            let n = self.read_one_chunk(&mut buf[total..]).await?;
            if n == 0 {
                break;
            }
            total += n;
        }
        Ok(total)
    }

    /// Read at most one contiguous span within the current cluster (or less if `buf` or the
    /// file ends sooner). Used by [`read_to_buf`](Self::read_to_buf) when the chain is not
    /// cached; advances to the next FAT cluster when the current one is exhausted.
    async fn read_one_chunk(&mut self, buf: &mut [u8]) -> Result<usize> {
        // End of logical file
        if self.position >= self.size as u64 {
            return Ok(0);
        }

        // A directory entry whose first cluster is 0 has no data allocated
        // (1 is reserved); report EOF instead of underflowing the
        // cluster-to-offset math.
        if self.cluster.0 < 2 {
            return Ok(0);
        }

        let mut data = self.fs.data.lock();
        let cluster_size = data.cluster_size;

        // Consumed the whole cluster: follow the chain to the next data cluster.
        if self.offset_in_cluster >= cluster_size {
            #[cfg(feature = "alloc")]
            {
                if let Some(ref chain) = self.cached_chain {
                    // Next cluster from the pre-read chain (no FAT table walk).
                    self.chain_index += 1;
                    if self.chain_index >= chain.len() {
                        return Ok(0); // End of file
                    }
                    self.cluster.0 = chain[self.chain_index] as usize;
                    self.offset_in_cluster = 0;
                    // Cluster buffer holds one cluster; must reload after moving.
                    if let Some(ref mut buffer) = self.cluster_buffer {
                        buffer.clear();
                    }
                } else {
                    // Resolve next cluster from the FAT on disk.
                    self.cluster_steps = self.cluster_steps.saturating_add(1);
                    if self.cluster_steps > self.fs.fat.max_cluster() {
                        return Err(Error::ClusterLoop {
                            cluster: self.cluster.0 as u32,
                        });
                    }
                    // Drop data lock so next_cluster_routed can acquire
                    // cache+data in canonical order; re-lock after.
                    drop(data);
                    let next = self.fs.next_cluster_routed(self.cluster.0).await?;
                    data = self.fs.data.lock();
                    match next {
                        Some(cluster) => {
                            self.cluster.0 = cluster as usize;
                            self.offset_in_cluster = 0;
                            if let Some(ref mut buffer) = self.cluster_buffer {
                                buffer.clear();
                            }
                        }
                        None => return Ok(0), // End of cluster chain
                    }
                }
            }

            #[cfg(not(feature = "alloc"))]
            {
                self.cluster_steps = self.cluster_steps.saturating_add(1);
                if self.cluster_steps > self.fs.fat.max_cluster() {
                    return Err(Error::ClusterLoop {
                        cluster: self.cluster.0 as u32,
                    });
                }
                // Drop data lock so next_cluster_routed can acquire
                // cache+data in canonical order; re-lock after.
                drop(data);
                let next = self.fs.next_cluster_routed(self.cluster.0).await?;
                data = self.fs.data.lock();
                match next {
                    Some(cluster) => {
                        self.cluster.0 = cluster as usize;
                        self.offset_in_cluster = 0;
                    }
                    None => return Ok(0), // End of cluster chain
                }
            }
        }

        // How much we can copy from the current cluster in this step.
        let bytes_left_in_cluster = cluster_size - self.offset_in_cluster;
        let bytes_left_in_file = (self.size as u64 - self.position) as usize;
        let read_max = buf.len().min(bytes_left_in_cluster).min(bytes_left_in_file);

        if read_max == 0 {
            return Ok(0);
        }

        #[cfg(feature = "alloc")]
        let bytes_read = if let Some(ref mut buffer) = self.cluster_buffer {
            // Load whole cluster once, then serve reads from RAM.
            if buffer.is_empty() {
                let cluster_start = self.cluster.to_bytes(self.fs.info.data_start, cluster_size);
                data.seek(SeekFrom::Start(cluster_start as u64)).await?;

                buffer.resize(cluster_size, 0);
                data.read_exact(buffer).await?;
            }

            let src = &buffer[self.offset_in_cluster..self.offset_in_cluster + read_max];
            buf[..read_max].copy_from_slice(src);
            read_max
        } else {
            // Direct read at file offset within this cluster.
            let seek_pos = self.cluster.to_bytes(self.fs.info.data_start, cluster_size)
                + self.offset_in_cluster;
            data.seek(SeekFrom::Start(seek_pos as u64)).await?;
            data.read(&mut buf[..read_max]).await?
        };

        #[cfg(not(feature = "alloc"))]
        let bytes_read = {
            let seek_pos = self.cluster.to_bytes(self.fs.info.data_start, cluster_size)
                + self.offset_in_cluster;
            data.seek(SeekFrom::Start(seek_pos as u64)).await?;
            data.read(&mut buf[..read_max]).await?
        };

        self.offset_in_cluster += bytes_read;
        self.position += bytes_read as u64;

        Ok(bytes_read)
    }

    /// Reposition the reader within the file.
    ///
    /// Follows `std::io::Seek` semantics: `Start`/`Current`/`End` are all
    /// supported, seeking beyond the end of the file is allowed (subsequent
    /// reads return 0), and seeking before the start is an error. Returns the
    /// new position from the start of the file.
    pub async fn seek(&mut self, pos: SeekFrom) -> Result<u64> {
        fn invalid(message: &'static str) -> Error {
            Error::Io(hadris_io::Error::new(ErrorKind::InvalidInput, message))
        }

        let target = match pos {
            SeekFrom::Start(position) => Some(position),
            SeekFrom::Current(offset) => self.position.checked_add_signed(offset),
            SeekFrom::End(offset) => (self.size as u64).checked_add_signed(offset),
        }
        .ok_or_else(|| invalid("invalid seek position"))?;

        if target >= self.size as u64 || self.first_cluster.0 < 2 {
            self.position = target;
            return Ok(target);
        }

        let target_usize = target as usize;
        let cluster_size = self.fs.data.lock().cluster_size;
        let target_cluster = target_usize / cluster_size;
        let target_offset = target_usize % cluster_size;

        #[cfg(feature = "alloc")]
        if let Some(ref chain) = self.cached_chain {
            let cluster = *chain
                .get(target_cluster)
                .ok_or(Error::UnexpectedEndOfChain {
                    cluster: chain.last().copied().unwrap_or(self.first_cluster.0 as u32),
                })?;
            if let Some(ref mut buffer) = self.cluster_buffer {
                buffer.clear();
            }
            self.chain_index = target_cluster;
            self.cluster.0 = cluster as usize;
            self.offset_in_cluster = target_offset;
            self.position = target;
            return Ok(target);
        }

        let current_cluster = (self.position as usize).saturating_sub(self.offset_in_cluster)
            / cluster_size;

        let (mut cluster, mut hops, mut cluster_steps) = if self.position >= self.size as u64 {
            (self.first_cluster.0, target_cluster, 0)
        } else if target_cluster >= current_cluster {
            (
                self.cluster.0,
                target_cluster - current_cluster,
                self.cluster_steps,
            )
        } else {
            (self.first_cluster.0, target_cluster, 0)
        };

        while hops > 0 {
            cluster_steps = cluster_steps.saturating_add(1);
            if cluster_steps > self.fs.fat.max_cluster() {
                return Err(Error::ClusterLoop {
                    cluster: cluster as u32,
                });
            }
            cluster = self
                .fs
                .next_cluster_routed(cluster)
                .await?
                .ok_or(Error::UnexpectedEndOfChain {
                    cluster: cluster as u32,
                })? as usize;
            hops -= 1;
        }

        #[cfg(feature = "alloc")]
        if let Some(ref mut buffer) = self.cluster_buffer {
            buffer.clear();
        }
        self.cluster_steps = cluster_steps;
        self.cluster.0 = cluster;
        self.offset_in_cluster = target_offset;
        self.position = target;

        Ok(target)
    }

    /// Read all bytes from the current read position through the end of the file.
    ///
    /// Data is read starting at this reader's current offset in the file (the same
    /// position the next [`read`](Self::read) would use—not necessarily offset 0). Bytes
    /// already consumed by earlier [`read`](Self::read) or `read_to_vec` calls are not read
    /// again. Bytes are read using the same internal bulk-read path as [`read`](Self::read).
    #[cfg(feature = "alloc")]
    pub async fn read_to_vec(&mut self) -> Result<Vec<u8>> {
        let remaining = self.remaining();
        // `size` derives from the untrusted directory-entry file size (u32, up to
        // ~4 GiB). A file cannot exceed the volume's cluster heap, so bound the
        // up-front allocation against it — otherwise a corrupt entry in a tiny
        // image could force a multi-gigabyte allocation (a DoS that aborts the
        // process on no-overcommit / embedded targets).
        let volume_capacity = self.fs.info.max_cluster as u64 * self.fs.info.cluster_size as u64;
        if remaining as u64 > volume_capacity {
            return Err(Error::CorruptFilesystem {
                context: "file size exceeds volume capacity",
            });
        }
        // The capacity check above is not sufficient on its own: a corrupt BPB
        // can also claim a huge volume (total_sectors), letting a ~4 GiB file
        // size through on a tiny image. So cap the up-front allocation and
        // grow only as actual data arrives — reads past the real data yield
        // short reads or I/O errors, not gigabytes of zeros.
        const MAX_PREALLOC: usize = 16 * 1024 * 1024;
        let mut buf = alloc::vec![0u8; remaining.min(MAX_PREALLOC)];
        let mut filled = 0;
        while filled < remaining {
            if filled == buf.len() {
                buf.resize((buf.len() * 2).min(remaining), 0);
            }
            let n = self.read_to_buf(&mut buf[filled..]).await?;
            if n == 0 {
                break;
            }
            filled += n;
        }
        buf.truncate(filled);
        Ok(buf)
    }
}

/// Extension trait for FatVolume to read files directly.
pub trait FatVolumeReadExt<DATA: Read + Seek> {
    /// Create a reader for a file entry.
    fn read_file<'a>(&'a self, entry: &FileEntry) -> Result<FileReader<'a, DATA>>;
}

impl<DATA: Read + Seek> FatVolumeReadExt<DATA> for FatVolume<DATA> {
    fn read_file<'a>(&'a self, entry: &FileEntry) -> Result<FileReader<'a, DATA>> {
        FileReader::new(self, entry)
    }
}

} // end io_transform!