qubit_fs/metadata/
opened_file_info.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! File information captured as part of opening a stream.
9
10use crate::metadata::FileMetadata;
11use crate::metadata::FileSystemId;
12use crate::path::Path;
13
14/// Stable file identity plus an optional metadata snapshot captured at open.
15///
16/// # Examples
17///
18/// ```rust
19/// use qubit_fs::metadata::{FileKind, FileMetadata, FileSystemId, OpenedFileInfo};
20/// use qubit_fs::path::Path;
21///
22/// let info = OpenedFileInfo::new(FileSystemId::new("doc")?, Path::parse("/report")?)
23///     .with_metadata(FileMetadata::new(FileKind::File));
24/// assert_eq!("/report", info.path().as_str());
25/// # Ok::<(), qubit_fs::FsError>(())
26/// ```
27#[derive(Clone, Debug, PartialEq)]
28pub struct OpenedFileInfo {
29    /// Stable identity of the filesystem that opened the handle.
30    filesystem_id: FileSystemId,
31    /// Logical resource path fixed at open time.
32    path: Path,
33    /// Optional metadata captured without an additional lookup.
34    metadata: Option<Box<FileMetadata>>,
35}
36
37impl OpenedFileInfo {
38    /// Creates opened-file information without an extra metadata lookup.
39    ///
40    /// # Parameters
41    /// - `filesystem_id`: Stable identity of the filesystem that opened the
42    ///   handle.
43    /// - `path`: Logical resource path fixed at open time.
44    ///
45    /// # Returns
46    /// Opened-file information with no metadata snapshot.
47    #[inline]
48    #[must_use]
49    pub fn new(filesystem_id: FileSystemId, path: Path) -> Self {
50        Self {
51            filesystem_id,
52            path,
53            metadata: None,
54        }
55    }
56
57    /// Attaches metadata already obtained while opening the file.
58    ///
59    /// Providers should not perform an extra remote `stat` only to populate
60    /// this optional snapshot.
61    ///
62    /// # Parameters
63    /// - `metadata`: Metadata observed during open.
64    ///
65    /// # Returns
66    /// Updated opened-file information.
67    #[inline]
68    #[must_use]
69    pub fn with_metadata(mut self, metadata: FileMetadata) -> Self {
70        self.metadata = Some(Box::new(metadata));
71        self
72    }
73
74    /// Returns the stable opened location.
75    ///
76    /// # Returns
77    /// The location captured at open time.
78    #[inline]
79    #[must_use]
80    pub const fn filesystem_id(&self) -> &FileSystemId {
81        &self.filesystem_id
82    }
83
84    /// Returns the logical path fixed when the provider opened the handle.
85    #[inline]
86    #[must_use]
87    pub const fn path(&self) -> &Path {
88        &self.path
89    }
90
91    /// Returns the optional metadata snapshot captured during open.
92    ///
93    /// This is not live metadata. Call [`crate::FileSystem::stat`] when a
94    /// current view is required.
95    ///
96    /// # Returns
97    /// The optional open-time snapshot.
98    #[inline]
99    #[must_use]
100    pub fn metadata(&self) -> Option<&FileMetadata> {
101        self.metadata.as_deref()
102    }
103}
qubit_fs/metadata/opened_file_info.rs

qubit_fs/metadata/
opened_file_info.rs
