Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(core): Polish API docs for Metadata #5497

Merged
merged 1 commit into from
Jan 2, 2025
Merged

docs(core): Polish API docs for Metadata #5497

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 55 additions & 125 deletions core/src/types/metadata.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,17 +22,17 @@ use chrono::prelude::*;
use crate::raw::*;
use crate::*;

/// Metadata carries all metadata associated with a path.
/// Metadata contains all the information related to a specific path.
///
/// # Notes
///
/// mode and content_length are required metadata that all services
/// should provide during `stat` operation. But in `list` operation,
/// a.k.a., `Entry`'s content length could be `None`.
/// Depending on the context of the requests, the metadata for the same path may vary. For example, two
/// versions of the same path might have different content lengths. Keep in mind that metadata is always
/// tied to the given context and is not a global state.
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct Metadata {
mode: EntryMode,

is_current: Option<bool>,

cache_control: Option<String>,
content_disposition: Option<String>,
content_length: Option<u64>,
Expand All @@ -43,7 +43,6 @@ pub struct Metadata {
etag: Option<String>,
last_modified: Option<DateTime<Utc>>,
version: Option<String>,
is_current: Option<bool>,

user_metadata: Option<HashMap<String, String>>,
}
Expand All @@ -54,6 +53,8 @@ impl Metadata {
Self {
mode,

is_current: None,

cache_control: None,
content_length: None,
content_md5: None,
Expand All @@ -65,7 +66,6 @@ impl Metadata {
content_disposition: None,
version: None,
user_metadata: None,
is_current: None,
}
}

Expand Down Expand Up @@ -97,11 +97,9 @@ impl Metadata {
}

/// Cache control of this entry.
///
/// Cache-Control is defined by [RFC 7234](https://httpwg.org/specs/rfc7234.html#header.cache-control)
/// Refer to [MDN Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for more information.
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::CacheControl`], otherwise this method returns `None`.
pub fn cache_control(&self) -> Option<&str> {
self.cache_control.as_deref()
}
Expand All @@ -127,12 +125,8 @@ impl Metadata {
/// Content length of this entry.
///
/// `Content-Length` is defined by [RFC 7230](https://httpwg.org/specs/rfc7230.html#header.content-length)
/// Refer to [MDN Content-Length](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length) for more information.
///
/// # Panics
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::ContentLength`], otherwise it will panic.
/// Refer to [MDN Content-Length](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length) for more information.
pub fn content_length(&self) -> u64 {
self.content_length.unwrap_or_default()
}
Expand All @@ -155,26 +149,17 @@ impl Metadata {
/// And removed by [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231).
///
/// OpenDAL will try its best to set this value, but not guarantee this value is the md5 of content.
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::ContentMd5`], otherwise this method returns `None`.
pub fn content_md5(&self) -> Option<&str> {
self.content_md5.as_deref()
}

/// Set content MD5 of this entry.
///
/// Content MD5 is defined by [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
/// And removed by [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231).
pub fn set_content_md5(&mut self, v: &str) -> &mut Self {
self.content_md5 = Some(v.to_string());
self
}

/// Set content MD5 of this entry.
///
/// Content MD5 is defined by [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
/// And removed by [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231).
pub fn with_content_md5(mut self, v: String) -> Self {
self.content_md5 = Some(v);
self
Expand All @@ -184,29 +169,28 @@ impl Metadata {
///
/// Content Type is defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-type).
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::ContentType`], otherwise this method returns `None`.
/// Refer to [MDN Content-Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) for more information.
pub fn content_type(&self) -> Option<&str> {
self.content_type.as_deref()
}

/// Set Content Type of this entry.
///
/// Content Type is defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-type).
pub fn set_content_type(&mut self, v: &str) -> &mut Self {
self.content_type = Some(v.to_string());
self
}

/// Set Content Type of this entry.
///
/// Content Type is defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-type).
pub fn with_content_type(mut self, v: String) -> Self {
self.content_type = Some(v);
self
}

/// Content Encoding of this entry.
///
/// Content Encoding is defined by [RFC 7231](https://httpwg.org/specs/rfc7231.html#header.content-encoding)
///
/// Refer to [MDN Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) for more information.
pub fn content_encoding(&self) -> Option<&str> {
self.content_encoding.as_deref()
}
Expand All @@ -221,23 +205,18 @@ impl Metadata {
///
/// Content Range is defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-range).
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::ContentRange`], otherwise this method returns `None`.
/// Refer to [MDN Content-Range](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range) for more information.
pub fn content_range(&self) -> Option<BytesContentRange> {
self.content_range
}

/// Set Content Range of this entry.
///
/// Content Range is defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-range).
pub fn set_content_range(&mut self, v: BytesContentRange) -> &mut Self {
self.content_range = Some(v);
self
}

/// Set Content Range of this entry.
///
/// Content Range is defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-range).
pub fn with_content_range(mut self, v: BytesContentRange) -> Self {
self.content_range = Some(v);
self
Expand All @@ -246,29 +225,19 @@ impl Metadata {
/// Last modified of this entry.
///
/// `Last-Modified` is defined by [RFC 7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
/// Refer to [MDN Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) for more information.
///
/// OpenDAL parse the raw value into [`DateTime`] for convenient.
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::LastModified`], otherwise this method returns `None`.
/// Refer to [MDN Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) for more information.
pub fn last_modified(&self) -> Option<DateTime<Utc>> {
self.last_modified
}

/// Set Last modified of this entry.
///
/// `Last-Modified` is defined by [RFC 7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
/// Refer to [MDN Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) for more information.
pub fn set_last_modified(&mut self, v: DateTime<Utc>) -> &mut Self {
self.last_modified = Some(v);
self
}

/// Set Last modified of this entry.
///
/// `Last-Modified` is defined by [RFC 7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
/// Refer to [MDN Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) for more information.
pub fn with_last_modified(mut self, v: DateTime<Utc>) -> Self {
self.last_modified = Some(v);
self
Expand All @@ -277,6 +246,7 @@ impl Metadata {
/// ETag of this entry.
///
/// `ETag` is defined by [RFC 7232](https://httpwg.org/specs/rfc7232.html#header.etag)
///
/// Refer to [MDN ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) for more information.
///
/// OpenDAL will return this value AS-IS like the following:
Expand All @@ -285,40 +255,17 @@ impl Metadata {
/// - `W/"0815"`
///
/// `"` is part of etag.
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::Etag`], otherwise this method returns `None`.
pub fn etag(&self) -> Option<&str> {
self.etag.as_deref()
}

/// Set ETag of this entry.
///
/// `ETag` is defined by [RFC 7232](https://httpwg.org/specs/rfc7232.html#header.etag)
/// Refer to [MDN ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) for more information.
///
/// OpenDAL will return this value AS-IS like the following:
///
/// - `"33a64df551425fcc55e4d42a148795d9f25f89d4"`
/// - `W/"0815"`
///
/// `"` is part of etag, don't trim it before setting.
pub fn set_etag(&mut self, v: &str) -> &mut Self {
self.etag = Some(v.to_string());
self
}

/// Set ETag of this entry.
///
/// `ETag` is defined by [RFC 7232](https://httpwg.org/specs/rfc7232.html#header.etag)
/// Refer to [MDN ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) for more information.
///
/// OpenDAL will return this value AS-IS like the following:
///
/// - `"33a64df551425fcc55e4d42a148795d9f25f89d4"`
/// - `W/"0815"`
///
/// `"` is part of etag, don't trim it before setting.
pub fn with_etag(mut self, v: String) -> Self {
self.etag = Some(v);
self
Expand All @@ -328,91 +275,74 @@ impl Metadata {
///
/// `Content-Disposition` is defined by [RFC 2616](https://www.rfc-editor/rfcs/2616) and
/// clarified usage in [RFC 6266](https://www.rfc-editor/6266).
///
/// Refer to [MDN Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) for more information.
///
/// OpenDAL will return this value AS-IS like the following:
///
/// - "inline"
/// - "attachment"
/// - "attachment; filename=\"filename.jpg\""
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::ContentDisposition`], otherwise this method returns `None`.
pub fn content_disposition(&self) -> Option<&str> {
self.content_disposition.as_deref()
}

/// Set Content-Disposition of this entry
///
/// `Content-Disposition` is defined by [RFC 2616](https://www.rfc-editor/rfcs/2616) and
/// clarified usage in [RFC 6266](https://www.rfc-editor/6266).
/// Refer to [MDN Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) for more information.
///
/// OpenDAL will return this value AS-IS like the following:
///
/// - "inline"
/// - "attachment"
/// - "attachment; filename=\"filename.jpg\""
pub fn with_content_disposition(mut self, v: String) -> Self {
self.content_disposition = Some(v);
pub fn set_content_disposition(&mut self, v: &str) -> &mut Self {
self.content_disposition = Some(v.to_string());
self
}

/// Set Content-Disposition of this entry
///
/// `Content-Disposition` is defined by [RFC 2616](https://www.rfc-editor/rfcs/2616) and
/// clarified usage in [RFC 6266](https://www.rfc-editor/6266).
/// Refer to [MDN Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) for more information.
///
/// OpenDAL will return this value AS-IS like the following:
///
/// - "inline"
/// - "attachment"
/// - "attachment; filename=\"filename.jpg\""
pub fn set_content_disposition(&mut self, v: &str) -> &mut Self {
self.content_disposition = Some(v.to_string());
pub fn with_content_disposition(mut self, v: String) -> Self {
self.content_disposition = Some(v);
self
}

/// Version of this entry.
/// Retrieves the `version` of the file, if available.
///
/// Version is a string that can be used to identify the version of this entry.
/// The version is typically used in systems that support object versioning, such as AWS S3.
///
/// This field may come out from the version control system, like object versioning in AWS S3.
/// # Returns
///
/// This value is only available when calling on result of `stat` or `list` with
/// [`Metakey::Version`], otherwise this method returns `None`.
/// - `Some(&str)`: If the file has a version associated with it,
/// this function returns `Some` containing a reference to the version ID string.
/// - `None`: If the file does not have a version, or if versioning is
/// not supported or enabled for the underlying storage system, this function
/// returns `None`.
pub fn version(&self) -> Option<&str> {
self.version.as_deref()
}

/// Set version of this entry.
///
/// Version is a string that can be used to identify the version of this entry.
///
/// This field may come out from the version control system, like object versioning in AWS S3.
/// Set the version of the file
pub fn set_version(&mut self, v: &str) -> &mut Self {
self.version = Some(v.to_string());
self
}

/// With the version of the file.
pub fn with_version(mut self, v: String) -> Self {
self.version = Some(v);
self
}

/// Set version of this entry.
/// Checks whether the metadata corresponds to the most recent version of the file.
///
/// Version is a string that can be used to identify the version of this entry.
/// This function is particularly useful when working with versioned objects,
/// such as those stored in systems like AWS S3 with versioning enabled. It helps
/// determine if the retrieved metadata represents the current state of the file
/// or an older version.
///
/// This field may come out from the version control system, like object versioning in AWS S3.
pub fn set_version(&mut self, v: &str) -> &mut Self {
self.version = Some(v.to_string());
self
}

/// Determines if the provided metadata reflects the current status of the path.
/// # Return Value
///
/// - `Ok(true)` indicates it is the latest status.
/// - `Ok(false)` indicates it is an older version of the file.
/// - `None` indicates uncertainty about its status.
/// The function returns an `Option<bool>` which can have the following values:
///
/// This API allows users to verify if the version is up-to-date when listing with versions.
/// - `Some(true)`: Indicates that the metadata **is** associated with the latest version of the file.
/// The metadata is current and reflects the most up-to-date state.
/// - `Some(false)`: Indicates that the metadata **is not** associated with the latest version of the file.
/// The metadata belongs to an older version, and there might be a more recent version available.
/// - `None`: Indicates that the currency of the metadata **cannot be determined**. This might occur if
/// versioning is not supported or enabled, or if there is insufficient information to ascertain the version status.
pub fn is_current(&self) -> Option<bool> {
self.is_current
}
Expand All @@ -421,17 +351,17 @@ impl Metadata {
///
/// By default, this value will be `None`. Please avoid using this API if it's unclear whether the entry is current.
/// Set it to `true` if it is known to be the latest; otherwise, set it to `false`.
pub fn with_is_current(mut self, is_current: Option<bool>) -> Self {
self.is_current = is_current;
pub fn set_is_current(&mut self, is_current: bool) -> &mut Self {
self.is_current = Some(is_current);
self
}

/// Set the `is_current` status of this entry.
///
/// By default, this value will be `None`. Please avoid using this API if it's unclear whether the entry is current.
/// Set it to `true` if it is known to be the latest; otherwise, set it to `false`.
pub fn set_is_current(&mut self, is_current: bool) -> &mut Self {
self.is_current = Some(is_current);
pub fn with_is_current(mut self, is_current: Option<bool>) -> Self {
self.is_current = is_current;
self
}

Expand Down
Loading