qubit-fs 0.3.2

Provider-neutral synchronous and asynchronous filesystem abstraction for Rust
Documentation
// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Provider-opened random-access reader envelope.
use super::RandomAccessReadSession;
use crate::metadata::OpenedFileInfo;

/// Opened object metadata and its bound random-access session.
///
/// The metadata must describe the same opened object as the session. In
/// particular, do not perform a second path lookup to fill in its length.
///
/// # Examples
///
/// ```
/// use qubit_fs::metadata::{FileKind, FileMetadata, FileSystemId, OpenedFileInfo};
/// use qubit_fs::path::Path;
/// use qubit_fs::spi::{OpenedRandomAccessReader, RandomAccessReadSession};
/// use qubit_fs::{FsResult, Path as FsPath};
///
/// struct Empty;
/// impl RandomAccessReadSession for Empty {
///     fn read_at(&mut self, _: u64, _: &mut [u8]) -> FsResult<usize> { Ok(0) }
/// }
/// let info = OpenedFileInfo::new(FileSystemId::new("fixture")?, FsPath::parse("/x")?)
///     .with_metadata(FileMetadata::new(FileKind::File).with_len(Some(0)));
/// let _opened = OpenedRandomAccessReader::new(info, Box::new(Empty));
/// # Ok::<(), qubit_fs::FsError>(())
/// ```
pub struct OpenedRandomAccessReader {
    /// Identity and open-time metadata for the same object held by `session`.
    info: OpenedFileInfo,
    /// Operations bound to the opened object or immutable version.
    session: Box<dyn RandomAccessReadSession>,
}
impl OpenedRandomAccessReader {
    /// Creates an envelope from metadata observed on the same opened object.
    ///
    /// # Parameters
    /// - `info`: Identity and metadata captured from the object that was
    ///   opened.
    /// - `session`: Session retaining that same object or immutable version.
    ///
    /// # Returns
    /// The provider envelope for facade validation.
    pub fn new(info: OpenedFileInfo, session: Box<dyn RandomAccessReadSession>) -> Self {
        Self { info, session }
    }
    /// Returns provider-reported identity and open-time metadata.
    pub fn info(&self) -> &OpenedFileInfo {
        &self.info
    }
    /// Transfers the metadata and session together for facade validation.
    ///
    /// The pair must remain associated because the metadata describes the
    /// object retained by the session.
    ///
    /// # Returns
    /// The opened-object metadata and its corresponding random-access session.
    pub(crate) fn into_parts(self) -> (OpenedFileInfo, Box<dyn RandomAccessReadSession>) {
        (self.info, self.session)
    }
}