Skip to main content

qubit_fs/metadata/
file_metadata.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 metadata model.
9
10use std::time::SystemTime;
11
12use crate::metadata::Checksum;
13use crate::metadata::FileKind;
14use crate::metadata::NonSensitiveMetadata;
15use crate::metadata::ResourceVersion;
16use crate::metadata::UserMetadata;
17
18/// Stable and extensible metadata for one filesystem resource.
19///
20/// # Examples
21///
22/// ```rust
23/// use qubit_fs::metadata::{FileKind, FileMetadata};
24///
25/// let metadata = FileMetadata::new(FileKind::File).with_len(Some(42));
26/// assert_eq!(Some(42), metadata.len());
27/// ```
28#[non_exhaustive]
29#[derive(Clone, Debug, PartialEq)]
30pub struct FileMetadata {
31    /// Provider-neutral resource kind.
32    kind: FileKind,
33    /// Byte length when known.
34    len: Option<u64>,
35    /// Last modification time when known.
36    modified_at: Option<SystemTime>,
37    /// Creation time when known.
38    created_at: Option<SystemTime>,
39    /// Last access time when known.
40    accessed_at: Option<SystemTime>,
41    /// Provider version or HTTP-style ETag when known.
42    etag: Option<ResourceVersion>,
43    /// Content type when known.
44    content_type: Option<String>,
45    /// Content checksum when known.
46    checksum: Option<Checksum>,
47    /// User-defined metadata with validated non-sensitive structural keys.
48    user_metadata: NonSensitiveMetadata,
49    /// Provider-native metadata with validated non-sensitive structural keys.
50    provider_metadata: NonSensitiveMetadata,
51}
52
53impl FileMetadata {
54    /// Creates metadata with only a file kind.
55    ///
56    /// # Parameters
57    /// - `kind`: Provider-neutral resource kind.
58    ///
59    /// # Returns
60    /// Metadata value with unknown optional fields.
61    #[inline]
62    #[must_use]
63    pub fn new(kind: FileKind) -> Self {
64        Self {
65            kind,
66            len: None,
67            modified_at: None,
68            created_at: None,
69            accessed_at: None,
70            etag: None,
71            content_type: None,
72            checksum: None,
73            user_metadata: NonSensitiveMetadata::new(),
74            provider_metadata: NonSensitiveMetadata::new(),
75        }
76    }
77
78    /// Returns the provider-neutral resource kind.
79    ///
80    /// # Returns
81    /// The resource kind borrowed from this metadata snapshot.
82    #[inline]
83    #[must_use]
84    pub const fn kind(&self) -> &FileKind {
85        &self.kind
86    }
87
88    /// Returns the known byte length, if any.
89    ///
90    /// # Returns
91    /// `Some` with the byte length when known, or `None` otherwise.
92    #[inline]
93    pub const fn len(&self) -> Option<u64> {
94        self.len
95    }
96
97    /// Returns whether the known byte length is zero.
98    ///
99    /// # Returns
100    /// `true` when the known byte length is zero.
101    #[inline]
102    #[must_use]
103    pub const fn is_empty(&self) -> bool {
104        matches!(self.len, Some(0))
105    }
106
107    /// Returns the last modification time, if known.
108    ///
109    /// # Returns
110    /// `Some` with the modification time when known, or `None` otherwise.
111    #[inline]
112    pub const fn modified_at(&self) -> Option<SystemTime> {
113        self.modified_at
114    }
115
116    /// Returns the creation time, if known.
117    ///
118    /// # Returns
119    /// `Some` with the creation time when known, or `None` otherwise.
120    #[inline]
121    pub const fn created_at(&self) -> Option<SystemTime> {
122        self.created_at
123    }
124
125    /// Returns the last access time, if known.
126    ///
127    /// # Returns
128    /// `Some` with the access time when known, or `None` otherwise.
129    #[inline]
130    pub const fn accessed_at(&self) -> Option<SystemTime> {
131        self.accessed_at
132    }
133
134    /// Returns the provider version or ETag, if known.
135    ///
136    /// # Returns
137    /// `Some` with the version borrowed from this snapshot, or `None` when the
138    /// provider did not report one.
139    #[inline]
140    pub const fn etag(&self) -> Option<&ResourceVersion> {
141        self.etag.as_ref()
142    }
143
144    /// Returns the content type, if known.
145    ///
146    /// # Returns
147    /// `Some` with the content type borrowed from this snapshot, or `None` when
148    /// the provider did not report one.
149    #[inline]
150    pub fn content_type(&self) -> Option<&str> {
151        self.content_type.as_deref()
152    }
153
154    /// Returns the content checksum, if known.
155    ///
156    /// # Returns
157    /// `Some` with the checksum borrowed from this snapshot, or `None` when the
158    /// provider did not report one.
159    #[inline]
160    pub const fn checksum(&self) -> Option<&Checksum> {
161        self.checksum.as_ref()
162    }
163
164    /// Returns validated user-defined metadata.
165    ///
166    /// # Returns
167    /// The validated metadata borrowed from this snapshot.
168    #[inline]
169    #[must_use]
170    pub const fn user_metadata(&self) -> &NonSensitiveMetadata {
171        &self.user_metadata
172    }
173
174    /// Returns validated provider-native metadata.
175    ///
176    /// # Returns
177    /// The validated metadata borrowed from this snapshot.
178    #[inline]
179    #[must_use]
180    pub const fn provider_metadata(&self) -> &NonSensitiveMetadata {
181        &self.provider_metadata
182    }
183
184    /// Tells whether this metadata describes a directory-like resource.
185    ///
186    /// # Returns
187    /// `true` for directories and prefixes.
188    #[inline]
189    #[must_use]
190    pub fn is_directory_like(&self) -> bool {
191        matches!(self.kind, FileKind::Directory | FileKind::Prefix)
192    }
193
194    /// Tells whether this metadata describes a file-like resource.
195    ///
196    /// # Returns
197    /// `true` for regular files and object-store objects.
198    #[inline]
199    #[must_use]
200    pub fn is_file_like(&self) -> bool {
201        matches!(self.kind, FileKind::File | FileKind::Object)
202    }
203
204    /// Replaces the resource kind.
205    ///
206    /// # Parameters
207    /// - `kind`: Provider-neutral resource kind to store.
208    ///
209    /// # Returns
210    /// This metadata snapshot with the replacement kind.
211    #[inline]
212    #[must_use]
213    pub fn with_kind(mut self, kind: FileKind) -> Self {
214        self.kind = kind;
215        self
216    }
217
218    /// Replaces the known byte length.
219    ///
220    /// # Parameters
221    /// - `len`: Known byte length, or `None` when it is unknown.
222    ///
223    /// # Returns
224    /// This metadata snapshot with the replacement length.
225    #[inline]
226    #[must_use]
227    pub fn with_len(mut self, len: Option<u64>) -> Self {
228        self.len = len;
229        self
230    }
231
232    /// Replaces the last modification time.
233    ///
234    /// # Parameters
235    /// - `value`: Modification time, or `None` when it is unknown.
236    ///
237    /// # Returns
238    /// This metadata snapshot with the replacement modification time.
239    #[inline]
240    #[must_use]
241    pub fn with_modified_at(mut self, value: Option<SystemTime>) -> Self {
242        self.modified_at = value;
243        self
244    }
245
246    /// Replaces the creation time.
247    ///
248    /// # Parameters
249    /// - `value`: Creation time, or `None` when it is unknown.
250    ///
251    /// # Returns
252    /// This metadata snapshot with the replacement creation time.
253    #[inline]
254    #[must_use]
255    pub fn with_created_at(mut self, value: Option<SystemTime>) -> Self {
256        self.created_at = value;
257        self
258    }
259
260    /// Replaces the last access time.
261    ///
262    /// # Parameters
263    /// - `value`: Access time, or `None` when it is unknown.
264    ///
265    /// # Returns
266    /// This metadata snapshot with the replacement access time.
267    #[inline]
268    #[must_use]
269    pub fn with_accessed_at(mut self, value: Option<SystemTime>) -> Self {
270        self.accessed_at = value;
271        self
272    }
273
274    /// Replaces the provider version or ETag.
275    ///
276    /// # Parameters
277    /// - `value`: Provider version, or `None` when it is unknown.
278    ///
279    /// # Returns
280    /// This metadata snapshot with the replacement version.
281    #[inline]
282    #[must_use]
283    pub fn with_etag(mut self, value: Option<ResourceVersion>) -> Self {
284        self.etag = value;
285        self
286    }
287
288    /// Replaces the content type.
289    ///
290    /// # Parameters
291    /// - `value`: Content type, or `None` when it is unknown.
292    ///
293    /// # Returns
294    /// This metadata snapshot with the replacement content type.
295    #[inline]
296    #[must_use]
297    pub fn with_content_type(mut self, value: Option<String>) -> Self {
298        self.content_type = value;
299        self
300    }
301
302    /// Replaces the content checksum.
303    ///
304    /// # Parameters
305    /// - `value`: Content checksum, or `None` when it is unknown.
306    ///
307    /// # Returns
308    /// This metadata snapshot with the replacement checksum.
309    #[inline]
310    #[must_use]
311    pub fn with_checksum(mut self, value: Option<Checksum>) -> Self {
312        self.checksum = value;
313        self
314    }
315
316    /// Replaces user-defined metadata that has already passed key validation.
317    ///
318    /// # Parameters
319    /// - `metadata`: User metadata to retain after validation.
320    ///
321    /// # Returns
322    /// This metadata snapshot with the replacement user metadata.
323    #[inline]
324    #[must_use]
325    pub fn with_user_metadata(mut self, metadata: UserMetadata) -> Self {
326        self.user_metadata = NonSensitiveMetadata::from(metadata);
327        self
328    }
329
330    /// Replaces provider-native metadata that has already passed key
331    /// validation.
332    ///
333    /// # Parameters
334    /// - `metadata`: Provider-native metadata to retain after validation.
335    ///
336    /// # Returns
337    /// This metadata snapshot with the replacement provider metadata.
338    #[inline]
339    #[must_use]
340    pub fn with_provider_metadata(mut self, metadata: UserMetadata) -> Self {
341        self.provider_metadata = NonSensitiveMetadata::from(metadata);
342        self
343    }
344}