rakata_formats/

section_reader.rs

//! Bounded, seekable windows over a shared source.
//!
//! Lazy archive indexes read entry bytes on demand rather than slurping a
//! whole file, so several of them need to read from one open handle at
//! independent positions. [`SectionReader`](crate::section_reader::SectionReader) is that primitive: a
//! `(start, len)` window that presents itself as a standalone stream
//! starting at zero.
//!
//! Two properties earn its place:
//!
//! - **Handles are shared through a `Mutex`, not `try_clone`.** Cloned file
//!   descriptors share one OS seek cursor, so two readers walking the same
//!   file would silently corrupt each other's positions. Each window keeps
//!   its own logical position and seeks the shared handle immediately before
//!   every read.
//! - **Windows nest.** [`SectionReader::section`](crate::section_reader::SectionReader::section) carves a sub-window out of
//!   an existing one against the same handle, which is what lets an archive
//!   index open a nested archive stored at an offset inside its parent. A
//!   save game is exactly this shape: per-module archives living at offsets
//!   inside `SAVEGAME.sav`.

use std::io::{self, Read, Seek, SeekFrom};
use std::sync::{Arc, Mutex};

/// A bounded window over a shared seekable source.
///
/// Offsets are window-relative: seeking to `0` lands on the window's first
/// byte, and reads stop at its last one regardless of how much data follows
/// in the underlying source. Cloning is cheap and yields an independent
/// cursor over the same window.
#[derive(Debug)]
pub struct SectionReader<R> {
    source: Arc<Mutex<R>>,
    start: u64,
    len: u64,
    pos: u64,
}

impl<R> Clone for SectionReader<R> {
    fn clone(&self) -> Self {
        Self {
            source: Arc::clone(&self.source),
            start: self.start,
            len: self.len,
            pos: self.pos,
        }
    }
}

impl<R> SectionReader<R> {
    /// Creates a window covering `len` bytes starting at `start` in `source`.
    ///
    /// The bounds are not validated against the source's actual length:
    /// a window past the end simply reads short, matching how the underlying
    /// reader behaves.
    pub fn new(source: Arc<Mutex<R>>, start: u64, len: u64) -> Self {
        Self {
            source,
            start,
            len,
            pos: 0,
        }
    }

    /// Wraps an entire source in a window, given its total length.
    pub fn whole(source: Arc<Mutex<R>>, len: u64) -> Self {
        Self::new(source, 0, len)
    }

    /// Carves a sub-window out of this one against the same shared source.
    ///
    /// `offset` is relative to this window's start. Returns `None` when the
    /// requested range would extend past this window's end, which for an
    /// archive index means the entry table pointed outside its own container.
    pub fn section(&self, offset: u64, len: u64) -> Option<Self> {
        let end = offset.checked_add(len)?;
        if end > self.len {
            return None;
        }
        Some(Self {
            source: Arc::clone(&self.source),
            start: self.start.checked_add(offset)?,
            len,
            pos: 0,
        })
    }

    /// Returns the window's length in bytes.
    pub fn len(&self) -> u64 {
        self.len
    }

    /// Returns whether the window covers zero bytes.
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    /// Returns the current window-relative position.
    pub fn position(&self) -> u64 {
        self.pos
    }
}

impl<R: Read + Seek> SectionReader<R> {
    /// Reads the window's entire contents into a new buffer.
    ///
    /// Independent of the current position: this always reads the whole
    /// window. Intended for the common archive case of pulling one complete
    /// entry out in a single locked pass.
    ///
    /// # Errors
    ///
    /// [`io::ErrorKind::InvalidData`] when the window's length exceeds
    /// addressable memory, and whatever the backing source reports otherwise.
    /// A short read is [`io::ErrorKind::UnexpectedEof`], since the window's
    /// length is what was asked for.
    pub fn read_all(&self) -> io::Result<Vec<u8>> {
        let capacity = usize::try_from(self.len).map_err(|_| {
            io::Error::new(
                io::ErrorKind::InvalidData,
                "section length exceeds addressable memory",
            )
        })?;
        let mut buf = vec![0u8; capacity];
        // A fresh cursor rather than `self.clone()`: cloning preserves the
        // current position, which would make this read short.
        let mut cursor = Self {
            source: Arc::clone(&self.source),
            start: self.start,
            len: self.len,
            pos: 0,
        };
        cursor.read_exact(&mut buf)?;
        Ok(buf)
    }
}

impl<R: Read + Seek> Read for SectionReader<R> {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        let remaining = self.len.saturating_sub(self.pos);
        if remaining == 0 || buf.is_empty() {
            return Ok(0);
        }

        // Clamp the request to what is left inside the window. usize::MAX is
        // a safe saturation point: buf can never be longer than that anyway.
        let cap = usize::try_from(remaining).unwrap_or(usize::MAX);
        let take = buf.len().min(cap);

        let offset = self
            .start
            .checked_add(self.pos)
            .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "section offset overflow"))?;

        // A poisoned lock means another thread panicked while holding it. The
        // handle itself is still usable here because every read seeks first,
        // so a stale cursor left behind by that panic cannot affect this read.
        let mut source = self
            .source
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        source.seek(SeekFrom::Start(offset))?;
        let read = source.read(&mut buf[..take])?;
        drop(source);

        self.pos = self.pos.saturating_add(
            u64::try_from(read)
                .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "read length overflow"))?,
        );
        Ok(read)
    }
}

impl<R: Read + Seek> Seek for SectionReader<R> {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        let target = match pos {
            SeekFrom::Start(offset) => i128::from(offset),
            SeekFrom::End(offset) => i128::from(self.len) + i128::from(offset),
            SeekFrom::Current(offset) => i128::from(self.pos) + i128::from(offset),
        };

        if target < 0 {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "cannot seek before the start of a section",
            ));
        }

        // Seeking past the end is legal and mirrors std's file behaviour:
        // the position moves, and subsequent reads return zero bytes.
        self.pos = u64::try_from(target)
            .map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, "seek position overflow"))?;
        Ok(self.pos)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Cursor;

    fn source(bytes: &[u8]) -> Arc<Mutex<Cursor<Vec<u8>>>> {
        Arc::new(Mutex::new(Cursor::new(bytes.to_vec())))
    }

    #[test]
    fn reads_only_within_the_window() {
        let src = source(b"0123456789");
        let mut window = SectionReader::new(src, 3, 4);

        let mut buf = Vec::new();
        window.read_to_end(&mut buf).expect("read within window");

        assert_eq!(buf, b"3456");
    }

    #[test]
    fn read_stops_at_the_window_end_not_the_source_end() {
        let src = source(b"0123456789");
        let window = SectionReader::new(src, 0, 4);

        let mut buf = [0u8; 10];
        let mut cursor = window;
        let read = cursor.read(&mut buf).expect("bounded read");

        assert_eq!(read, 4);
        assert_eq!(&buf[..4], b"0123");
    }

    #[test]
    fn positions_are_window_relative() {
        let src = source(b"0123456789");
        let mut window = SectionReader::new(src, 5, 5);

        assert_eq!(window.seek(SeekFrom::Start(0)).expect("seek start"), 0);
        let mut byte = [0u8; 1];
        window.read_exact(&mut byte).expect("read first byte");
        assert_eq!(&byte, b"5");

        assert_eq!(window.seek(SeekFrom::End(-1)).expect("seek end"), 4);
        window.read_exact(&mut byte).expect("read last byte");
        assert_eq!(&byte, b"9");
    }

    #[test]
    fn seeking_before_the_window_start_is_rejected() {
        let src = source(b"0123456789");
        let mut window = SectionReader::new(src, 5, 5);

        let err = window
            .seek(SeekFrom::Current(-1))
            .expect_err("negative seek");

        assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
    }

    #[test]
    fn seeking_past_the_end_reads_nothing() {
        let src = source(b"0123456789");
        let mut window = SectionReader::new(src, 0, 4);

        window.seek(SeekFrom::Start(99)).expect("seek past end");
        let mut buf = [0u8; 4];

        assert_eq!(window.read(&mut buf).expect("read past end"), 0);
    }

    #[test]
    fn sections_nest_against_the_same_source() {
        let src = source(b"0123456789");
        let outer = SectionReader::new(src, 2, 6);

        let inner = outer.section(1, 3).expect("nested window in bounds");

        assert_eq!(inner.read_all().expect("read nested"), b"345");
    }

    #[test]
    fn a_section_reaching_past_its_parent_is_rejected() {
        let src = source(b"0123456789");
        let outer = SectionReader::new(src, 2, 4);

        assert!(outer.section(2, 3).is_none());
        assert!(outer.section(0, 5).is_none());
        assert!(outer.section(u64::MAX, 1).is_none());
    }

    #[test]
    fn independent_cursors_share_one_handle_without_interfering() {
        // The reason this type exists: File::try_clone would share one OS
        // seek cursor and let these two reads corrupt each other.
        let src = source(b"0123456789");
        let mut first = SectionReader::new(Arc::clone(&src), 0, 5);
        let mut second = SectionReader::new(src, 5, 5);

        let mut a = [0u8; 2];
        let mut b = [0u8; 2];
        first.read_exact(&mut a).expect("first window read");
        second.read_exact(&mut b).expect("second window read");
        assert_eq!(&a, b"01");
        assert_eq!(&b, b"56");

        first.read_exact(&mut a).expect("first window resumes");
        second.read_exact(&mut b).expect("second window resumes");
        assert_eq!(&a, b"23");
        assert_eq!(&b, b"78");
    }

    #[test]
    fn read_all_ignores_the_current_position() {
        let src = source(b"0123456789");
        let mut window = SectionReader::new(src, 0, 4);
        window.seek(SeekFrom::Start(2)).expect("advance cursor");

        assert_eq!(window.read_all().expect("read all"), b"0123");
    }

    #[test]
    fn an_empty_window_reads_nothing() {
        let src = source(b"0123456789");
        let window = SectionReader::new(src, 4, 0);

        assert!(window.is_empty());
        assert_eq!(window.read_all().expect("read empty"), b"");
    }
}