opendal/types/metadata.rs
1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18use std::collections::HashMap;
19
20use chrono::prelude::*;
21
22use crate::raw::*;
23use crate::*;
24
25/// Metadata contains all the information related to a specific path.
26///
27/// Depending on the context of the requests, the metadata for the same path may vary. For example, two
28/// versions of the same path might have different content lengths. Keep in mind that metadata is always
29/// tied to the given context and is not a global state.
30///
31/// ## File Versions
32///
33/// In systems that support versioning, such as AWS S3, the metadata may represent a specific version
34/// of a file.
35///
36/// Users can access [`Metadata::version`] to retrieve the file's version, if available. They can also
37/// use [`Metadata::is_current`] and [`Metadata::is_deleted`] to determine whether the metadata
38/// corresponds to the latest version or a deleted one.
39///
40/// The all possible combinations of `is_current` and `is_deleted` are as follows:
41///
42/// | `is_current` | `is_deleted` | description |
43/// |---------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
44/// | `Some(true)` | `false` | **The metadata's associated version is the latest, current version.** This is the normal state, indicating that this version is the most up-to-date and accessible version. |
45/// | `Some(true)` | `true` | **The metadata's associated version is the latest, deleted version (Latest Delete Marker or Soft Deleted).** This is particularly important in object storage systems like S3. It signifies that this version is the **most recent delete marker**, indicating the object has been deleted. Subsequent GET requests will return 404 errors unless a specific version ID is provided. |
46/// | `Some(false)` | `false` | **The metadata's associated version is neither the latest version nor deleted.** This indicates that this version is a previous version, still accessible by specifying its version ID. |
47/// | `Some(false)` | `true` | **The metadata's associated version is not the latest version and is deleted.** This represents a historical version that has been marked for deletion. Users will need to specify the version ID to access it, and accessing it may be subject to specific delete marker behavior (e.g., in S3, it might not return actual data but a specific delete marker response). |
48/// | `None` | `false` | **The metadata's associated file is not deleted, but its version status is either unknown or it is not the latest version.** This likely indicates that versioning is not enabled for this file, or versioning information is unavailable. |
49/// | `None` | `true` | **The metadata's associated file is deleted, but its version status is either unknown or it is not the latest version.** This typically means the file was deleted without versioning enabled, or its versioning information is unavailable. This may represent an actual data deletion operation rather than an S3 delete marker. |
50#[derive(Debug, Clone, Eq, PartialEq, Default)]
51pub struct Metadata {
52 mode: EntryMode,
53
54 is_current: Option<bool>,
55 is_deleted: bool,
56
57 cache_control: Option<String>,
58 content_disposition: Option<String>,
59 content_length: Option<u64>,
60 content_md5: Option<String>,
61 content_range: Option<BytesContentRange>,
62 content_type: Option<String>,
63 content_encoding: Option<String>,
64 etag: Option<String>,
65 last_modified: Option<DateTime<Utc>>,
66 version: Option<String>,
67
68 user_metadata: Option<HashMap<String, String>>,
69}
70
71impl Metadata {
72 /// Create a new metadata
73 pub fn new(mode: EntryMode) -> Self {
74 Self {
75 mode,
76
77 is_current: None,
78 is_deleted: false,
79
80 cache_control: None,
81 content_length: None,
82 content_md5: None,
83 content_type: None,
84 content_encoding: None,
85 content_range: None,
86 last_modified: None,
87 etag: None,
88 content_disposition: None,
89 version: None,
90 user_metadata: None,
91 }
92 }
93
94 /// mode represent this entry's mode.
95 pub fn mode(&self) -> EntryMode {
96 self.mode
97 }
98
99 /// Set mode for entry.
100 pub fn set_mode(&mut self, v: EntryMode) -> &mut Self {
101 self.mode = v;
102 self
103 }
104
105 /// Set mode for entry.
106 pub fn with_mode(mut self, v: EntryMode) -> Self {
107 self.mode = v;
108 self
109 }
110
111 /// Returns `true` if this metadata is for a file.
112 pub fn is_file(&self) -> bool {
113 matches!(self.mode, EntryMode::FILE)
114 }
115
116 /// Returns `true` if this metadata is for a directory.
117 pub fn is_dir(&self) -> bool {
118 matches!(self.mode, EntryMode::DIR)
119 }
120
121 /// Checks whether the metadata corresponds to the most recent version of the file.
122 ///
123 /// This function is particularly useful when working with versioned objects,
124 /// such as those stored in systems like AWS S3 with versioning enabled. It helps
125 /// determine if the retrieved metadata represents the current state of the file
126 /// or an older version.
127 ///
128 /// Refer to docs in [`Metadata`] for more information about file versions.
129 ///
130 /// # Return Value
131 ///
132 /// The function returns an `Option<bool>` which can have the following values:
133 ///
134 /// - `Some(true)`: Indicates that the metadata **is** associated with the latest version of the file.
135 /// The metadata is current and reflects the most up-to-date state.
136 /// - `Some(false)`: Indicates that the metadata **is not** associated with the latest version of the file.
137 /// The metadata belongs to an older version, and there might be a more recent version available.
138 /// - `None`: Indicates that the currency of the metadata **cannot be determined**. This might occur if
139 /// versioning is not supported or enabled, or if there is insufficient information to ascertain the version status.
140 pub fn is_current(&self) -> Option<bool> {
141 self.is_current
142 }
143
144 /// Set the `is_current` status of this entry.
145 ///
146 /// By default, this value will be `None`. Please avoid using this API if it's unclear whether the entry is current.
147 /// Set it to `true` if it is known to be the latest; otherwise, set it to `false`.
148 pub fn set_is_current(&mut self, is_current: bool) -> &mut Self {
149 self.is_current = Some(is_current);
150 self
151 }
152
153 /// Set the `is_current` status of this entry.
154 ///
155 /// By default, this value will be `None`. Please avoid using this API if it's unclear whether the entry is current.
156 /// Set it to `true` if it is known to be the latest; otherwise, set it to `false`.
157 pub fn with_is_current(mut self, is_current: Option<bool>) -> Self {
158 self.is_current = is_current;
159 self
160 }
161
162 /// Checks if the file (or version) associated with this metadata has been deleted.
163 ///
164 /// This function returns `true` if the file represented by this metadata has been marked for
165 /// deletion or has been permanently deleted.
166 /// It returns `false` otherwise, indicating that the file (or version) is still present and accessible.
167 ///
168 /// Refer to docs in [`Metadata`] for more information about file versions.
169 ///
170 /// # Returns
171 ///
172 /// `bool`: `true` if the object is considered deleted, `false` otherwise.
173 pub fn is_deleted(&self) -> bool {
174 self.is_deleted
175 }
176
177 /// Set the deleted status of this entry.
178 pub fn set_is_deleted(&mut self, v: bool) -> &mut Self {
179 self.is_deleted = v;
180 self
181 }
182
183 /// Set the deleted status of this entry.
184 pub fn with_is_deleted(mut self, v: bool) -> Self {
185 self.is_deleted = v;
186 self
187 }
188
189 /// Cache control of this entry.
190 ///
191 /// Cache-Control is defined by [RFC 7234](https://httpwg.org/specs/rfc7234.html#header.cache-control)
192 /// Refer to [MDN Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for more information.
193 pub fn cache_control(&self) -> Option<&str> {
194 self.cache_control.as_deref()
195 }
196
197 /// Set cache control of this entry.
198 ///
199 /// Cache-Control is defined by [RFC 7234](https://httpwg.org/specs/rfc7234.html#header.cache-control)
200 /// Refer to [MDN Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for more information.
201 pub fn set_cache_control(&mut self, v: &str) -> &mut Self {
202 self.cache_control = Some(v.to_string());
203 self
204 }
205
206 /// Set cache control of this entry.
207 ///
208 /// Cache-Control is defined by [RFC 7234](https://httpwg.org/specs/rfc7234.html#header.cache-control)
209 /// Refer to [MDN Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for more information.
210 pub fn with_cache_control(mut self, v: String) -> Self {
211 self.cache_control = Some(v);
212 self
213 }
214
215 /// Content length of this entry.
216 ///
217 /// `Content-Length` is defined by [RFC 7230](https://httpwg.org/specs/rfc7230.html#header.content-length)
218 ///
219 /// Refer to [MDN Content-Length](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length) for more information.
220 ///
221 /// # Returns
222 ///
223 /// Content length of this entry. It will be `0` if the content length is not set by the storage services.
224 pub fn content_length(&self) -> u64 {
225 self.content_length.unwrap_or_default()
226 }
227
228 /// Set content length of this entry.
229 pub fn set_content_length(&mut self, v: u64) -> &mut Self {
230 self.content_length = Some(v);
231 self
232 }
233
234 /// Set content length of this entry.
235 pub fn with_content_length(mut self, v: u64) -> Self {
236 self.content_length = Some(v);
237 self
238 }
239
240 /// Content MD5 of this entry.
241 ///
242 /// Content MD5 is defined by [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
243 /// And removed by [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231).
244 ///
245 /// OpenDAL will try its best to set this value, but not guarantee this value is the md5 of content.
246 pub fn content_md5(&self) -> Option<&str> {
247 self.content_md5.as_deref()
248 }
249
250 /// Set content MD5 of this entry.
251 pub fn set_content_md5(&mut self, v: &str) -> &mut Self {
252 self.content_md5 = Some(v.to_string());
253 self
254 }
255
256 /// Set content MD5 of this entry.
257 pub fn with_content_md5(mut self, v: String) -> Self {
258 self.content_md5 = Some(v);
259 self
260 }
261
262 /// Content Type of this entry.
263 ///
264 /// Content Type is defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-type).
265 ///
266 /// Refer to [MDN Content-Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) for more information.
267 pub fn content_type(&self) -> Option<&str> {
268 self.content_type.as_deref()
269 }
270
271 /// Set Content Type of this entry.
272 pub fn set_content_type(&mut self, v: &str) -> &mut Self {
273 self.content_type = Some(v.to_string());
274 self
275 }
276
277 /// Set Content Type of this entry.
278 pub fn with_content_type(mut self, v: String) -> Self {
279 self.content_type = Some(v);
280 self
281 }
282
283 /// Content Encoding of this entry.
284 ///
285 /// Content Encoding is defined by [RFC 7231](https://httpwg.org/specs/rfc7231.html#header.content-encoding)
286 ///
287 /// Refer to [MDN Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) for more information.
288 pub fn content_encoding(&self) -> Option<&str> {
289 self.content_encoding.as_deref()
290 }
291
292 /// Set Content Encoding of this entry.
293 pub fn set_content_encoding(&mut self, v: &str) -> &mut Self {
294 self.content_encoding = Some(v.to_string());
295 self
296 }
297
298 /// Content Range of this entry.
299 ///
300 /// Content Range is defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-range).
301 ///
302 /// Refer to [MDN Content-Range](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range) for more information.
303 pub fn content_range(&self) -> Option<BytesContentRange> {
304 self.content_range
305 }
306
307 /// Set Content Range of this entry.
308 pub fn set_content_range(&mut self, v: BytesContentRange) -> &mut Self {
309 self.content_range = Some(v);
310 self
311 }
312
313 /// Set Content Range of this entry.
314 pub fn with_content_range(mut self, v: BytesContentRange) -> Self {
315 self.content_range = Some(v);
316 self
317 }
318
319 /// Last modified of this entry.
320 ///
321 /// `Last-Modified` is defined by [RFC 7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
322 ///
323 /// Refer to [MDN Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) for more information.
324 pub fn last_modified(&self) -> Option<DateTime<Utc>> {
325 self.last_modified
326 }
327
328 /// Set Last modified of this entry.
329 pub fn set_last_modified(&mut self, v: DateTime<Utc>) -> &mut Self {
330 self.last_modified = Some(v);
331 self
332 }
333
334 /// Set Last modified of this entry.
335 pub fn with_last_modified(mut self, v: DateTime<Utc>) -> Self {
336 self.last_modified = Some(v);
337 self
338 }
339
340 /// ETag of this entry.
341 ///
342 /// `ETag` is defined by [RFC 7232](https://httpwg.org/specs/rfc7232.html#header.etag)
343 ///
344 /// Refer to [MDN ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) for more information.
345 ///
346 /// OpenDAL will return this value AS-IS like the following:
347 ///
348 /// - `"33a64df551425fcc55e4d42a148795d9f25f89d4"`
349 /// - `W/"0815"`
350 ///
351 /// `"` is part of etag.
352 pub fn etag(&self) -> Option<&str> {
353 self.etag.as_deref()
354 }
355
356 /// Set ETag of this entry.
357 pub fn set_etag(&mut self, v: &str) -> &mut Self {
358 self.etag = Some(v.to_string());
359 self
360 }
361
362 /// Set ETag of this entry.
363 pub fn with_etag(mut self, v: String) -> Self {
364 self.etag = Some(v);
365 self
366 }
367
368 /// Content-Disposition of this entry
369 ///
370 /// `Content-Disposition` is defined by [RFC 2616](https://www.rfc-editor/rfcs/2616) and
371 /// clarified usage in [RFC 6266](https://www.rfc-editor/6266).
372 ///
373 /// Refer to [MDN Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) for more information.
374 ///
375 /// OpenDAL will return this value AS-IS like the following:
376 ///
377 /// - "inline"
378 /// - "attachment"
379 /// - "attachment; filename=\"filename.jpg\""
380 pub fn content_disposition(&self) -> Option<&str> {
381 self.content_disposition.as_deref()
382 }
383
384 /// Set Content-Disposition of this entry
385 pub fn set_content_disposition(&mut self, v: &str) -> &mut Self {
386 self.content_disposition = Some(v.to_string());
387 self
388 }
389
390 /// Set Content-Disposition of this entry
391 pub fn with_content_disposition(mut self, v: String) -> Self {
392 self.content_disposition = Some(v);
393 self
394 }
395
396 /// Retrieves the `version` of the file, if available.
397 ///
398 /// The version is typically used in systems that support object versioning, such as AWS S3.
399 ///
400 /// # Returns
401 ///
402 /// - `Some(&str)`: If the file has a version associated with it,
403 /// this function returns `Some` containing a reference to the version ID string.
404 /// - `None`: If the file does not have a version, or if versioning is
405 /// not supported or enabled for the underlying storage system, this function
406 /// returns `None`.
407 pub fn version(&self) -> Option<&str> {
408 self.version.as_deref()
409 }
410
411 /// Set the version of the file
412 pub fn set_version(&mut self, v: &str) -> &mut Self {
413 self.version = Some(v.to_string());
414 self
415 }
416
417 /// With the version of the file.
418 pub fn with_version(mut self, v: String) -> Self {
419 self.version = Some(v);
420 self
421 }
422
423 /// User defined metadata of this entry
424 ///
425 /// The prefix of the user defined metadata key(for example: in oss, it's x-oss-meta-)
426 /// is remove from the key
427 pub fn user_metadata(&self) -> Option<&HashMap<String, String>> {
428 self.user_metadata.as_ref()
429 }
430
431 /// Set user defined metadata of this entry
432 pub fn with_user_metadata(&mut self, data: HashMap<String, String>) -> &mut Self {
433 self.user_metadata = Some(data);
434 self
435 }
436}