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}