You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2025/05/23 07:43:29 UTC
(opendal) 01/01: feat(core): Expose xxx_options API
This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch impl-options
in repository https://gitbox.apache.org/repos/asf/opendal.git
commit 1c73e3fc9d24ecd18b829d28794a5ab3569df99b
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Fri May 23 15:42:56 2025 +0800
feat(core): Expose xxx_options API
Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
core/src/raw/ops.rs | 94 ++++-
core/src/types/mod.rs | 2 +
core/src/types/operator/operator.rs | 613 +++++++++++++--------------
core/src/types/operator/operator_futures.rs | 634 ++++++++--------------------
core/src/types/options.rs | 518 +++++++++++++++++++++++
5 files changed, 1070 insertions(+), 791 deletions(-)
diff --git a/core/src/raw/ops.rs b/core/src/raw/ops.rs
index 68dc5f1e4..978808f2b 100644
--- a/core/src/raw/ops.rs
+++ b/core/src/raw/ops.rs
@@ -19,7 +19,7 @@
//!
//! By using ops, users can add more context for operation.
-use crate::raw::*;
+use crate::{options, raw::*};
use chrono::{DateTime, Utc};
use std::collections::HashMap;
use std::time::Duration;
@@ -65,6 +65,14 @@ impl OpDelete {
}
}
+impl From<options::DeleteOptions> for OpDelete {
+ fn from(value: options::DeleteOptions) -> Self {
+ Self {
+ version: value.version,
+ }
+ }
+}
+
/// Args for `delete` operation.
///
/// The path must be normalized.
@@ -469,6 +477,54 @@ impl OpReader {
}
}
+impl From<options::ReadOptions> for (OpRead, OpReader) {
+ fn from(value: options::ReadOptions) -> Self {
+ (
+ OpRead {
+ range: value.range,
+ if_match: value.if_match,
+ if_none_match: value.if_none_match,
+ if_modified_since: value.if_modified_since,
+ if_unmodified_since: value.if_unmodified_since,
+ override_content_type: value.override_content_type,
+ override_cache_control: value.override_cache_control,
+ override_content_disposition: value.override_content_disposition,
+ version: value.version,
+ },
+ OpReader {
+ // Ensure concurrent is at least 1
+ concurrent: value.concurrent.max(1),
+ chunk: value.chunk,
+ gap: value.gap,
+ },
+ )
+ }
+}
+
+impl From<options::ReaderOptions> for (OpRead, OpReader) {
+ fn from(value: options::ReaderOptions) -> Self {
+ (
+ OpRead {
+ range: BytesRange::default(),
+ if_match: value.if_match,
+ if_none_match: value.if_none_match,
+ if_modified_since: value.if_modified_since,
+ if_unmodified_since: value.if_unmodified_since,
+ override_content_type: None,
+ override_cache_control: None,
+ override_content_disposition: None,
+ version: value.version,
+ },
+ OpReader {
+ // Ensure concurrent is at least 1
+ concurrent: value.concurrent.max(1),
+ chunk: value.chunk,
+ gap: value.gap,
+ },
+ )
+ }
+}
+
/// Args for `stat` operation.
#[derive(Debug, Clone, Default)]
pub struct OpStat {
@@ -578,6 +634,21 @@ impl OpStat {
}
}
+impl From<options::StatOptions> for OpStat {
+ fn from(value: options::StatOptions) -> Self {
+ Self {
+ if_match: value.if_match,
+ if_none_match: value.if_none_match,
+ if_modified_since: value.if_modified_since,
+ if_unmodified_since: value.if_unmodified_since,
+ override_content_type: value.override_content_type,
+ override_cache_control: value.override_cache_control,
+ override_content_disposition: value.override_content_disposition,
+ version: value.version,
+ }
+ }
+}
+
/// Args for `write` operation.
#[derive(Debug, Clone, Default)]
pub struct OpWrite {
@@ -754,6 +825,27 @@ impl OpWriter {
}
}
+impl From<options::WriteOptions> for (OpWrite, OpWriter) {
+ fn from(value: options::WriteOptions) -> Self {
+ (
+ OpWrite {
+ append: value.append,
+ // Ensure concurrent is at least 1
+ concurrent: value.concurrent.max(1),
+ content_type: value.content_type,
+ content_disposition: value.content_disposition,
+ content_encoding: value.content_encoding,
+ cache_control: value.cache_control,
+ if_match: value.if_match,
+ if_none_match: value.if_none_match,
+ if_not_exists: value.if_not_exists,
+ user_metadata: value.user_metadata,
+ },
+ OpWriter { chunk: value.chunk },
+ )
+ }
+}
+
/// Args for `copy` operation.
#[derive(Debug, Clone, Default)]
pub struct OpCopy {}
diff --git a/core/src/types/mod.rs b/core/src/types/mod.rs
index 3f7afc58f..f4bd6731c 100644
--- a/core/src/types/mod.rs
+++ b/core/src/types/mod.rs
@@ -72,5 +72,7 @@ pub use scheme::Scheme;
mod capability;
pub use capability::Capability;
+pub mod options;
+
mod context;
pub(crate) use context::*;
diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs
index ffe4b45f7..aabdab863 100644
--- a/core/src/types/operator/operator.rs
+++ b/core/src/types/operator/operator.rs
@@ -290,101 +290,7 @@ impl Operator {
///
/// # Options
///
- /// ## `if_match`
- ///
- /// Set `if_match` for this `stat` request.
- ///
- /// This feature can be used to check if the file's `ETag` matches the given `ETag`.
- ///
- /// If file exists, and it's etag doesn't match, an error with kind [`ErrorKind::ConditionNotMatch`]
- /// will be returned.
- ///
- /// ```
- /// # use opendal::Result;
- /// use opendal::Operator;
- ///
- /// # async fn test(op: Operator, etag: &str) -> Result<()> {
- /// let mut metadata = op.stat_with("path/to/file").if_match(etag).await?;
- /// # Ok(())
- /// # }
- /// ```
- ///
- /// ## `if_none_match`
- ///
- /// Set `if_none_match` for this `stat` request.
- ///
- /// This feature can be used to check if the file's `ETag` doesn't match the given `ETag`.
- ///
- /// If file exists, and it's etag match, an error with kind [`ErrorKind::ConditionNotMatch`]
- /// will be returned.
- ///
- /// ```
- /// # use opendal::Result;
- /// use opendal::Operator;
- ///
- /// # async fn test(op: Operator, etag: &str) -> Result<()> {
- /// let mut metadata = op.stat_with("path/to/file").if_none_match(etag).await?;
- /// # Ok(())
- /// # }
- /// ```
- ///
- /// ## `if_modified_since`
- ///
- /// set `if_modified_since` for this `stat` request.
- ///
- /// This feature can be used to check if the file has been modified since the given time.
- ///
- /// If file exists, and it's not modified after the given time, an error with kind [`ErrorKind::ConditionNotMatch`]
- /// will be returned.
- ///
- /// ```
- /// # use opendal::Result;
- /// use opendal::Operator;
- /// use chrono::Utc;
- ///
- /// # async fn test(op: Operator) -> Result<()> {
- /// let mut metadata = op.stat_with("path/to/file").if_modified_since(Utc::now()).await?;
- /// # Ok(())
- /// # }
- /// ```
- ///
- /// ## `if_unmodified_since`
- ///
- /// set `if_unmodified_since` for this `stat` request.
- ///
- /// This feature can be used to check if the file has NOT been modified since the given time.
- ///
- /// If file exists, and it's modified after the given time, an error with kind [`ErrorKind::ConditionNotMatch`]
- /// will be returned.
- ///
- /// ```
- /// # use opendal::Result;
- /// use opendal::Operator;
- /// use chrono::Utc;
- ///
- /// # async fn test(op: Operator) -> Result<()> {
- /// let mut metadata = op.stat_with("path/to/file").if_unmodified_since(Utc::now()).await?;
- /// # Ok(())
- /// # }
- /// ```
- ///
- /// ## `version`
- ///
- /// Set `version` for this `stat` request.
- ///
- /// This feature can be used to retrieve the metadata of a specific version of the given path
- ///
- /// If the version doesn't exist, an error with kind [`ErrorKind::NotFound`] will be returned.
- ///
- /// ```
- /// # use opendal::Result;
- /// # use opendal::Operator;
- ///
- /// # async fn test(op: Operator, version: &str) -> Result<()> {
- /// let mut metadata = op.stat_with("path/to/file").version(version).await?;
- /// # Ok(())
- /// # }
- /// ```
+ /// Check [`options::StatOptions`] for all available options.
///
/// # Examples
///
@@ -445,18 +351,29 @@ impl Operator {
/// we can do about this.
pub fn stat_with(&self, path: &str) -> FutureStat<impl Future<Output = Result<Metadata>>> {
let path = normalize_path(path);
-
OperatorFuture::new(
self.inner().clone(),
path,
- OpStat::default(),
- |inner, path, args| async move {
- let rp = inner.stat(&path, args).await?;
- Ok(rp.into_metadata())
- },
+ options::StatOptions::default(),
+ Self::stat_inner,
)
}
+ /// Get given path's metadata with extra options.
+ pub async fn stat_options(&self, path: &str, opts: options::StatOptions) -> Result<Metadata> {
+ let path = normalize_path(path);
+ Self::stat_inner(self.accessor.clone(), path, opts).await
+ }
+
+ async fn stat_inner(
+ acc: Accessor,
+ path: String,
+ opts: options::StatOptions,
+ ) -> Result<Metadata> {
+ let rp = acc.stat(&path, opts.into()).await?;
+ Ok(rp.into_metadata())
+ }
+
/// Check if this path exists or not.
///
/// # Example
@@ -594,16 +511,7 @@ impl Operator {
///
/// # Options
///
- /// Visit [`FutureRead`] for all available options.
- ///
- /// - [`range`](./operator_futures/type.FutureRead.html#method.version): Set `range` for the read.
- /// - [`concurrent`](./operator_futures/type.FutureRead.html#method.concurrent): Set `concurrent` for the read.
- /// - [`chunk`](./operator_futures/type.FutureRead.html#method.chunk): Set `chunk` for the read.
- /// - [`version`](./operator_futures/type.FutureRead.html#method.version): Set `version` for the read.
- /// - [`if_match`](./operator_futures/type.FutureRead.html#method.if_match): Set `if-match` for the read.
- /// - [`if_none_match`](./operator_futures/type.FutureRead.html#method.if_none_match): Set `if-none-match` for the read.
- /// - [`if_modified_since`](./operator_futures/type.FutureRead.html#method.if_modified_since): Set `if-modified-since` for the read.
- /// - [`if_unmodified_since`](./operator_futures/type.FutureRead.html#method.if_unmodified_since): Set `if-unmodified-since` for the read.
+ /// Visit [`options::ReadOptions`] for all available options.
///
/// # Examples
///
@@ -625,26 +533,35 @@ impl Operator {
OperatorFuture::new(
self.inner().clone(),
path,
- (OpRead::default(), OpReader::default()),
- |inner, path, (args, options)| async move {
- if !validate_path(&path, EntryMode::FILE) {
- return Err(
- Error::new(ErrorKind::IsADirectory, "read path is a directory")
- .with_operation("read")
- .with_context("service", inner.info().scheme())
- .with_context("path", &path),
- );
- }
-
- let range = args.range();
- let context = ReadContext::new(inner, path, args, options);
- let r = Reader::new(context);
- let buf = r.read(range.to_range()).await?;
- Ok(buf)
- },
+ options::ReadOptions::default(),
+ Self::read_inner,
)
}
+ /// Read the whole path into a bytes with extra options.
+ pub async fn read_options(&self, path: &str, opts: options::ReadOptions) -> Result<Buffer> {
+ let path = normalize_path(path);
+ Self::read_inner(self.inner().clone(), path, opts).await
+ }
+
+ async fn read_inner(acc: Accessor, path: String, opts: options::ReadOptions) -> Result<Buffer> {
+ if !validate_path(&path, EntryMode::FILE) {
+ return Err(
+ Error::new(ErrorKind::IsADirectory, "read path is a directory")
+ .with_operation("read")
+ .with_context("service", acc.info().scheme())
+ .with_context("path", &path),
+ );
+ }
+
+ let (args, opts) = opts.into();
+ let range = args.range();
+ let context = ReadContext::new(acc, path, args, opts);
+ let r = Reader::new(context);
+ let buf = r.read(range.to_range()).await?;
+ Ok(buf)
+ }
+
/// Create a new reader which can read the whole path.
///
/// # Notes
@@ -681,16 +598,7 @@ impl Operator {
///
/// # Options
///
- /// Visit [`FutureReader`] for all available options.
- ///
- /// - [`version`](./operator_futures/type.FutureReader.html#method.version): Set `version` for the reader.
- /// - [`concurrent`](./operator_futures/type.FutureReader.html#method.concurrent): Set `concurrent` for the reader.
- /// - [`chunk`](./operator_futures/type.FutureReader.html#method.chunk): Set `chunk` for the reader.
- /// - [`gap`](./operator_futures/type.FutureReader.html#method.gap): Set `gap` for the reader.
- /// - [`if_match`](./operator_futures/type.FutureReader.html#method.if_match): Set `if-match` for the reader.
- /// - [`if_none_match`](./operator_futures/type.FutureReader.html#method.if_none_match): Set `if-none-match` for the reader.
- /// - [`if_modified_since`](./operator_futures/type.FutureReader.html#method.if_modified_since): Set `if-modified-since` for the reader.
- /// - [`if_unmodified_since`](./operator_futures/type.FutureReader.html#method.if_unmodified_since): Set `if-unmodified-since` for the reader.
+ /// Visit [`options::ReaderOptions`] for all available options.
///
/// # Examples
///
@@ -709,23 +617,39 @@ impl Operator {
OperatorFuture::new(
self.inner().clone(),
path,
- (OpRead::default(), OpReader::default()),
- |inner, path, (args, options)| async move {
- if !validate_path(&path, EntryMode::FILE) {
- return Err(
- Error::new(ErrorKind::IsADirectory, "read path is a directory")
- .with_operation("Operator::reader")
- .with_context("service", inner.info().scheme())
- .with_context("path", path),
- );
- }
-
- let context = ReadContext::new(inner, path, args, options);
- Ok(Reader::new(context))
- },
+ options::ReaderOptions::default(),
+ Self::reader_inner,
)
}
+ /// Create a new reader with extra options
+ pub async fn reader_options(&self, path: &str, opts: options::ReaderOptions) -> Result<Reader> {
+ let path = normalize_path(path);
+ Self::reader_inner(self.inner().clone(), path, opts).await
+ }
+
+ /// Allow this unused async since we don't want
+ /// to change our public API.
+ #[allow(clippy::unused_async)]
+ async fn reader_inner(
+ acc: Accessor,
+ path: String,
+ options: options::ReaderOptions,
+ ) -> Result<Reader> {
+ if !validate_path(&path, EntryMode::FILE) {
+ return Err(
+ Error::new(ErrorKind::IsADirectory, "read path is a directory")
+ .with_operation("Operator::reader")
+ .with_context("service", acc.info().scheme())
+ .with_context("path", path),
+ );
+ }
+
+ let (args, opts) = options.into();
+ let context = ReadContext::new(acc, path, args, opts);
+ Ok(Reader::new(context))
+ }
+
/// Write bytes into path.
///
/// # Notes
@@ -765,119 +689,98 @@ impl Operator {
self.write_with(path, bs).await
}
- /// Copy a file from `from` to `to`.
+ /// Write data with extra options.
///
/// # Notes
///
- /// - `from` and `to` must be a file.
- /// - `to` will be overwritten if it exists.
- /// - If `from` and `to` are the same, an `IsSameFile` error will occur.
- /// - `copy` is idempotent. For same `from` and `to` input, the result will be the same.
+ /// ## Streaming Write
///
- /// # Examples
+ /// This method performs a single bulk write operation for all bytes. For finer-grained
+ /// memory control or lazy writing, consider using [`Operator::writer_with`] instead.
///
- /// ```
- /// # use opendal::Result;
- /// # use opendal::Operator;
+ /// ## Multipart Uploads
///
- /// # async fn test(op: Operator) -> Result<()> {
- /// op.copy("path/to/file", "path/to/file2").await?;
- /// # Ok(())
- /// # }
- /// ```
- pub async fn copy(&self, from: &str, to: &str) -> Result<()> {
- let from = normalize_path(from);
-
- if !validate_path(&from, EntryMode::FILE) {
- return Err(
- Error::new(ErrorKind::IsADirectory, "from path is a directory")
- .with_operation("Operator::copy")
- .with_context("service", self.info().scheme())
- .with_context("from", from),
- );
- }
-
- let to = normalize_path(to);
-
- if !validate_path(&to, EntryMode::FILE) {
- return Err(
- Error::new(ErrorKind::IsADirectory, "to path is a directory")
- .with_operation("Operator::copy")
- .with_context("service", self.info().scheme())
- .with_context("to", to),
- );
- }
-
- if from == to {
- return Err(
- Error::new(ErrorKind::IsSameFile, "from and to paths are same")
- .with_operation("Operator::copy")
- .with_context("service", self.info().scheme())
- .with_context("from", from)
- .with_context("to", to),
- );
- }
-
- self.inner().copy(&from, &to, OpCopy::new()).await?;
-
- Ok(())
- }
-
- /// Rename a file from `from` to `to`.
+ /// OpenDAL handles multipart uploads through the [`Writer`] abstraction, managing all
+ /// the upload details automatically. You can customize the upload behavior by configuring
+ /// `chunk` size and `concurrent` operations via [`Operator::writer_with`].
///
- /// # Notes
+ /// # Options
///
- /// - `from` and `to` must be a file.
- /// - `to` will be overwritten if it exists.
- /// - If `from` and `to` are the same, an `IsSameFile` error will occur.
+ /// Visit [`FutureWrite`] for all available options.
+ ///
+ /// - [`append`](./operator_futures/type.FutureWrite.html#method.append): Sets append mode for this write request.
+ /// - [`chunk`](./operator_futures/type.FutureWrite.html#method.chunk): Sets chunk size for buffered writes.
+ /// - [`concurrent`](./operator_futures/type.FutureWrite.html#method.concurrent): Sets concurrent write operations for this writer.
+ /// - [`cache_control`](./operator_futures/type.FutureWrite.html#method.cache_control): Sets cache control for this write request.
+ /// - [`content_type`](./operator_futures/type.FutureWrite.html#method.content_type): Sets content type for this write request.
+ /// - [`content_disposition`](./operator_futures/type.FutureWrite.html#method.content_disposition): Sets content disposition for this write request.
+ /// - [`content_encoding`](./operator_futures/type.FutureWrite.html#method.content_encoding): Sets content encoding for this write request.
+ /// - [`if_match`](./operator_futures/type.FutureWrite.html#method.if_match): Sets if-match for this write request.
+ /// - [`if_none_match`](./operator_futures/type.FutureWrite.html#method.if_none_match): Sets if-none-match for this write request.
+ /// - [`if_not_exist`](./operator_futures/type.FutureWrite.html#method.if_not_exist): Sets if-not-exist for this write request.
+ /// - [`user_metadata`](./operator_futures/type.FutureWrite.html#method.user_metadata): Sets user metadata for this write request.
///
/// # Examples
///
/// ```
/// # use opendal::Result;
/// # use opendal::Operator;
+ /// use bytes::Bytes;
///
/// # async fn test(op: Operator) -> Result<()> {
- /// op.rename("path/to/file", "path/to/file2").await?;
+ /// let _ = op.write_with("path/to/file", vec![0; 4096])
+ /// .if_not_exists(true)
+ /// .await?;
/// # Ok(())
/// # }
/// ```
- pub async fn rename(&self, from: &str, to: &str) -> Result<()> {
- let from = normalize_path(from);
-
- if !validate_path(&from, EntryMode::FILE) {
- return Err(
- Error::new(ErrorKind::IsADirectory, "from path is a directory")
- .with_operation("Operator::move_")
- .with_context("service", self.info().scheme())
- .with_context("from", from),
- );
- }
+ pub fn write_with(
+ &self,
+ path: &str,
+ bs: impl Into<Buffer>,
+ ) -> FutureWrite<impl Future<Output = Result<Metadata>>> {
+ let path = normalize_path(path);
+ let bs = bs.into();
- let to = normalize_path(to);
+ OperatorFuture::new(
+ self.inner().clone(),
+ path,
+ (options::WriteOptions::default(), bs),
+ |inner, path, (opts, bs)| Self::write_inner(inner, path, bs, opts),
+ )
+ }
- if !validate_path(&to, EntryMode::FILE) {
- return Err(
- Error::new(ErrorKind::IsADirectory, "to path is a directory")
- .with_operation("Operator::move_")
- .with_context("service", self.info().scheme())
- .with_context("to", to),
- );
- }
+ /// Write data with extra options.
+ pub async fn write_options(
+ &self,
+ path: &str,
+ bs: impl Into<Buffer>,
+ opts: options::WriteOptions,
+ ) -> Result<Metadata> {
+ let path = normalize_path(path);
+ Self::write_inner(self.inner().clone(), path, bs.into(), opts).await
+ }
- if from == to {
+ async fn write_inner(
+ acc: Accessor,
+ path: String,
+ bs: Buffer,
+ opts: options::WriteOptions,
+ ) -> Result<Metadata> {
+ if !validate_path(&path, EntryMode::FILE) {
return Err(
- Error::new(ErrorKind::IsSameFile, "from and to paths are same")
- .with_operation("Operator::move_")
- .with_context("service", self.info().scheme())
- .with_context("from", from)
- .with_context("to", to),
+ Error::new(ErrorKind::IsADirectory, "write path is a directory")
+ .with_operation("Operator::write")
+ .with_context("service", acc.info().scheme())
+ .with_context("path", &path),
);
}
- self.inner().rename(&from, &to, OpRename::new()).await?;
-
- Ok(())
+ let (args, opts) = opts.into();
+ let context = WriteContext::new(acc, path, args, opts);
+ let mut w = Writer::new(context).await?;
+ w.write(bs).await?;
+ w.close().await
}
/// Create a writer for streaming data to the given path.
@@ -932,19 +835,7 @@ impl Operator {
///
/// ## Options
///
- /// Visit [`FutureWriter`] for all available options.
- ///
- /// - [`append`](./operator_futures/type.FutureWriter.html#method.append): Sets append mode for this write request.
- /// - [`chunk`](./operator_futures/type.FutureWriter.html#method.chunk): Sets chunk size for buffered writes.
- /// - [`concurrent`](./operator_futures/type.FutureWriter.html#method.concurrent): Sets concurrent write operations for this writer.
- /// - [`cache_control`](./operator_futures/type.FutureWriter.html#method.cache_control): Sets cache control for this write request.
- /// - [`content_type`](./operator_futures/type.FutureWriter.html#method.content_type): Sets content type for this write request.
- /// - [`content_disposition`](./operator_futures/type.FutureWriter.html#method.content_disposition): Sets content disposition for this write request.
- /// - [`content_encoding`](./operator_futures/type.FutureWriter.html#method.content_encoding): Sets content encoding for this write request.
- /// - [`if_match`](./operator_futures/type.FutureWriter.html#method.if_match): Sets if-match for this write request.
- /// - [`if_none_match`](./operator_futures/type.FutureWriter.html#method.if_none_match): Sets if-none-match for this write request.
- /// - [`if_not_exist`](./operator_futures/type.FutureWriter.html#method.if_not_exist): Sets if-not-exist for this write request.
- /// - [`user_metadata`](./operator_futures/type.FutureWriter.html#method.user_metadata): Sets user metadata for this write request.
+ /// Visit [`options::WriteOptions`] for all available options.
///
/// ## Examples
///
@@ -970,97 +861,154 @@ impl Operator {
OperatorFuture::new(
self.inner().clone(),
path,
- (OpWrite::default(), OpWriter::default()),
- |inner, path, (args, options)| async move {
- if !validate_path(&path, EntryMode::FILE) {
- return Err(
- Error::new(ErrorKind::IsADirectory, "write path is a directory")
- .with_operation("Operator::writer")
- .with_context("service", inner.info().scheme().into_static())
- .with_context("path", &path),
- );
- }
-
- let context = WriteContext::new(inner, path, args, options);
- let w = Writer::new(context).await?;
- Ok(w)
- },
+ options::WriteOptions::default(),
+ Self::writer_inner,
)
}
- /// Write data with extra options.
+ /// Create a writer for streaming data to the given path with more options.
///
- /// # Notes
+ /// ## Options
///
- /// ## Streaming Write
+ /// Visit [`options::WriteOptions`] for all available options.
+ pub async fn writer_options(&self, path: &str, opts: options::WriteOptions) -> Result<Writer> {
+ let path = normalize_path(path);
+ Self::writer_inner(self.inner().clone(), path, opts).await
+ }
+
+ async fn writer_inner(
+ acc: Accessor,
+ path: String,
+ opts: options::WriteOptions,
+ ) -> Result<Writer> {
+ if !validate_path(&path, EntryMode::FILE) {
+ return Err(
+ Error::new(ErrorKind::IsADirectory, "write path is a directory")
+ .with_operation("Operator::writer")
+ .with_context("service", acc.info().scheme().into_static())
+ .with_context("path", &path),
+ );
+ }
+
+ let (args, opts) = opts.into();
+ let context = WriteContext::new(acc, path, args, opts);
+ let w = Writer::new(context).await?;
+ Ok(w)
+ }
+
+ /// Copy a file from `from` to `to`.
///
- /// This method performs a single bulk write operation for all bytes. For finer-grained
- /// memory control or lazy writing, consider using [`Operator::writer_with`] instead.
+ /// # Notes
///
- /// ## Multipart Uploads
+ /// - `from` and `to` must be a file.
+ /// - `to` will be overwritten if it exists.
+ /// - If `from` and `to` are the same, an `IsSameFile` error will occur.
+ /// - `copy` is idempotent. For same `from` and `to` input, the result will be the same.
///
- /// OpenDAL handles multipart uploads through the [`Writer`] abstraction, managing all
- /// the upload details automatically. You can customize the upload behavior by configuring
- /// `chunk` size and `concurrent` operations via [`Operator::writer_with`].
+ /// # Examples
///
- /// # Options
+ /// ```
+ /// # use opendal::Result;
+ /// # use opendal::Operator;
///
- /// Visit [`FutureWrite`] for all available options.
+ /// # async fn test(op: Operator) -> Result<()> {
+ /// op.copy("path/to/file", "path/to/file2").await?;
+ /// # Ok(())
+ /// # }
+ /// ```
+ pub async fn copy(&self, from: &str, to: &str) -> Result<()> {
+ let from = normalize_path(from);
+
+ if !validate_path(&from, EntryMode::FILE) {
+ return Err(
+ Error::new(ErrorKind::IsADirectory, "from path is a directory")
+ .with_operation("Operator::copy")
+ .with_context("service", self.info().scheme())
+ .with_context("from", from),
+ );
+ }
+
+ let to = normalize_path(to);
+
+ if !validate_path(&to, EntryMode::FILE) {
+ return Err(
+ Error::new(ErrorKind::IsADirectory, "to path is a directory")
+ .with_operation("Operator::copy")
+ .with_context("service", self.info().scheme())
+ .with_context("to", to),
+ );
+ }
+
+ if from == to {
+ return Err(
+ Error::new(ErrorKind::IsSameFile, "from and to paths are same")
+ .with_operation("Operator::copy")
+ .with_context("service", self.info().scheme())
+ .with_context("from", from)
+ .with_context("to", to),
+ );
+ }
+
+ self.inner().copy(&from, &to, OpCopy::new()).await?;
+
+ Ok(())
+ }
+
+ /// Rename a file from `from` to `to`.
///
- /// - [`append`](./operator_futures/type.FutureWrite.html#method.append): Sets append mode for this write request.
- /// - [`chunk`](./operator_futures/type.FutureWrite.html#method.chunk): Sets chunk size for buffered writes.
- /// - [`concurrent`](./operator_futures/type.FutureWrite.html#method.concurrent): Sets concurrent write operations for this writer.
- /// - [`cache_control`](./operator_futures/type.FutureWrite.html#method.cache_control): Sets cache control for this write request.
- /// - [`content_type`](./operator_futures/type.FutureWrite.html#method.content_type): Sets content type for this write request.
- /// - [`content_disposition`](./operator_futures/type.FutureWrite.html#method.content_disposition): Sets content disposition for this write request.
- /// - [`content_encoding`](./operator_futures/type.FutureWrite.html#method.content_encoding): Sets content encoding for this write request.
- /// - [`if_match`](./operator_futures/type.FutureWrite.html#method.if_match): Sets if-match for this write request.
- /// - [`if_none_match`](./operator_futures/type.FutureWrite.html#method.if_none_match): Sets if-none-match for this write request.
- /// - [`if_not_exist`](./operator_futures/type.FutureWrite.html#method.if_not_exist): Sets if-not-exist for this write request.
- /// - [`user_metadata`](./operator_futures/type.FutureWrite.html#method.user_metadata): Sets user metadata for this write request.
+ /// # Notes
+ ///
+ /// - `from` and `to` must be a file.
+ /// - `to` will be overwritten if it exists.
+ /// - If `from` and `to` are the same, an `IsSameFile` error will occur.
///
/// # Examples
///
/// ```
/// # use opendal::Result;
/// # use opendal::Operator;
- /// use bytes::Bytes;
///
/// # async fn test(op: Operator) -> Result<()> {
- /// let _ = op.write_with("path/to/file", vec![0; 4096])
- /// .if_not_exists(true)
- /// .await?;
+ /// op.rename("path/to/file", "path/to/file2").await?;
/// # Ok(())
/// # }
/// ```
- pub fn write_with(
- &self,
- path: &str,
- bs: impl Into<Buffer>,
- ) -> FutureWrite<impl Future<Output = Result<Metadata>>> {
- let path = normalize_path(path);
- let bs = bs.into();
+ pub async fn rename(&self, from: &str, to: &str) -> Result<()> {
+ let from = normalize_path(from);
- OperatorFuture::new(
- self.inner().clone(),
- path,
- (OpWrite::default(), OpWriter::default(), bs),
- |inner, path, (args, options, bs)| async move {
- if !validate_path(&path, EntryMode::FILE) {
- return Err(
- Error::new(ErrorKind::IsADirectory, "write path is a directory")
- .with_operation("Operator::write_with")
- .with_context("service", inner.info().scheme().into_static())
- .with_context("path", &path),
- );
- }
+ if !validate_path(&from, EntryMode::FILE) {
+ return Err(
+ Error::new(ErrorKind::IsADirectory, "from path is a directory")
+ .with_operation("Operator::move_")
+ .with_context("service", self.info().scheme())
+ .with_context("from", from),
+ );
+ }
- let context = WriteContext::new(inner, path, args, options);
- let mut w = Writer::new(context).await?;
- w.write(bs).await?;
- w.close().await
- },
- )
+ let to = normalize_path(to);
+
+ if !validate_path(&to, EntryMode::FILE) {
+ return Err(
+ Error::new(ErrorKind::IsADirectory, "to path is a directory")
+ .with_operation("Operator::move_")
+ .with_context("service", self.info().scheme())
+ .with_context("to", to),
+ );
+ }
+
+ if from == to {
+ return Err(
+ Error::new(ErrorKind::IsSameFile, "from and to paths are same")
+ .with_operation("Operator::move_")
+ .with_context("service", self.info().scheme())
+ .with_context("from", from)
+ .with_context("to", to),
+ );
+ }
+
+ self.inner().rename(&from, &to, OpRename::new()).await?;
+
+ Ok(())
}
/// Delete the given path.
@@ -1128,16 +1076,29 @@ impl Operator {
OperatorFuture::new(
self.inner().clone(),
path,
- OpDelete::default(),
- |inner, path, args| async move {
- let (_, mut deleter) = inner.delete_dyn().await?;
- deleter.delete_dyn(&path, args)?;
- deleter.flush_dyn().await?;
- Ok(())
- },
+ options::DeleteOptions::default(),
+ Self::delete_inner,
)
}
+ /// Delete the given path with extra options.
+ ///
+ /// ## Options
+ ///
+ /// Visit [`options::DeleteOptions`] for all available options.
+ pub async fn delete_options(&self, path: &str, opts: options::DeleteOptions) -> Result<()> {
+ let path = normalize_path(path);
+ Self::delete_inner(self.inner().clone(), path, opts).await
+ }
+
+ async fn delete_inner(acc: Accessor, path: String, opts: options::DeleteOptions) -> Result<()> {
+ let (_, mut deleter) = acc.delete_dyn().await?;
+ let args = opts.into();
+ deleter.delete_dyn(&path, args)?;
+ deleter.flush_dyn().await?;
+ Ok(())
+ }
+
/// Delete an infallible iterator of paths.
///
/// Also see:
diff --git a/core/src/types/operator/operator_futures.rs b/core/src/types/operator/operator_futures.rs
index 72ef6bd62..2e8a537d3 100644
--- a/core/src/types/operator/operator_futures.rs
+++ b/core/src/types/operator/operator_futures.rs
@@ -91,32 +91,47 @@ where
/// Future that generated by [`Operator::stat_with`].
///
/// Users can add more options by public functions provided by this struct.
-pub type FutureStat<F> = OperatorFuture<OpStat, Metadata, F>;
+pub type FutureStat<F> = OperatorFuture<options::StatOptions, Metadata, F>;
impl<F: Future<Output = Result<Metadata>>> FutureStat<F> {
/// Set the If-Match for this operation.
- pub fn if_match(self, v: &str) -> Self {
- self.map(|args| args.with_if_match(v))
+ ///
+ /// Refer to [`options::StatOptions::if_match`] for more details.
+ pub fn if_match(mut self, v: &str) -> Self {
+ self.args.if_match = Some(v.to_string());
+ self
}
/// Set the If-None-Match for this operation.
- pub fn if_none_match(self, v: &str) -> Self {
- self.map(|args| args.with_if_none_match(v))
+ ///
+ /// Refer to [`options::StatOptions::if_none_match`] for more details.
+ pub fn if_none_match(mut self, v: &str) -> Self {
+ self.args.if_none_match = Some(v.to_string());
+ self
}
/// Set the If-Modified-Since for this operation.
- pub fn if_modified_since(self, v: DateTime<Utc>) -> Self {
- self.map(|args| args.with_if_modified_since(v))
+ ///
+ /// Refer to [`options::StatOptions::if_modified_since`] for more details.
+ pub fn if_modified_since(mut self, v: DateTime<Utc>) -> Self {
+ self.args.if_modified_since = Some(v);
+ self
}
/// Set the If-Unmodified-Since for this operation.
- pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self {
- self.map(|args| args.with_if_unmodified_since(v))
+ ///
+ /// Refer to [`options::StatOptions::if_unmodified_since`] for more details.
+ pub fn if_unmodified_since(mut self, v: DateTime<Utc>) -> Self {
+ self.args.if_unmodified_since = Some(v);
+ self
}
/// Set the version for this operation.
- pub fn version(self, v: &str) -> Self {
- self.map(|args| args.with_version(v))
+ ///
+ /// Refer to [`options::StatOptions::version`] for more details.
+ pub fn version(mut self, v: &str) -> Self {
+ self.args.version = Some(v.to_string());
+ self
}
}
@@ -221,7 +236,7 @@ impl<F: Future<Output = Result<PresignedRequest>>> FuturePresignWrite<F> {
/// Future that generated by [`Operator::read_with`].
///
/// Users can add more options by public functions provided by this struct.
-pub type FutureRead<F> = OperatorFuture<(OpRead, OpReader), Buffer, F>;
+pub type FutureRead<F> = OperatorFuture<options::ReadOptions, Buffer, F>;
impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// Set `range` for this `read` request.
@@ -241,8 +256,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Ok(())
/// # }
/// ```
- pub fn range(self, range: impl RangeBounds<u64>) -> Self {
- self.map(|(args, op_reader)| (args.with_range(range.into()), op_reader))
+ pub fn range(mut self, range: impl RangeBounds<u64>) -> Self {
+ self.args.range = range.into();
+ self
}
/// Set `concurrent` for the reader.
@@ -263,8 +279,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Ok(())
/// # }
/// ```
- pub fn concurrent(self, concurrent: usize) -> Self {
- self.map(|(args, op_reader)| (args, op_reader.with_concurrent(concurrent)))
+ pub fn concurrent(mut self, concurrent: usize) -> Self {
+ self.args.concurrent = concurrent.max(1);
+ self
}
/// OpenDAL will use services' preferred chunk size by default. Users can set chunk based on their own needs.
@@ -280,8 +297,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Ok(())
/// # }
/// ```
- pub fn chunk(self, chunk_size: usize) -> Self {
- self.map(|(args, op_reader)| (args, op_reader.with_chunk(chunk_size)))
+ pub fn chunk(mut self, chunk_size: usize) -> Self {
+ self.args.chunk = Some(chunk_size);
+ self
}
/// Set `version` for this `read` request.
@@ -299,8 +317,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Ok(())
/// # }
/// ```
- pub fn version(self, v: &str) -> Self {
- self.map(|(args, op_reader)| (args.with_version(v), op_reader))
+ pub fn version(mut self, v: &str) -> Self {
+ self.args.version = Some(v.to_string());
+ self
}
/// Set `if_match` for this `read` request.
@@ -318,8 +337,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_match(self, v: &str) -> Self {
- self.map(|(args, op_reader)| (args.with_if_match(v), op_reader))
+ pub fn if_match(mut self, v: &str) -> Self {
+ self.args.if_match = Some(v.to_string());
+ self
}
/// Set `if_none_match` for this `read` request.
@@ -337,8 +357,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_none_match(self, v: &str) -> Self {
- self.map(|(args, op_reader)| (args.with_if_none_match(v), op_reader))
+ pub fn if_none_match(mut self, v: &str) -> Self {
+ self.args.if_none_match = Some(v.to_string());
+ self
}
/// ## `if_modified_since`
@@ -360,8 +381,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_modified_since(self, v: DateTime<Utc>) -> Self {
- self.map(|(args, op_reader)| (args.with_if_modified_since(v), op_reader))
+ pub fn if_modified_since(mut self, v: DateTime<Utc>) -> Self {
+ self.args.if_modified_since = Some(v);
+ self
}
/// Set `if_unmodified_since` for this `read` request.
@@ -381,8 +403,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self {
- self.map(|(args, op_reader)| (args.with_if_unmodified_since(v), op_reader))
+ pub fn if_unmodified_since(mut self, v: DateTime<Utc>) -> Self {
+ self.args.if_unmodified_since = Some(v);
+ self
}
}
@@ -393,7 +416,7 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
/// # Notes
///
/// `(OpRead, ())` is a trick to make sure `FutureReader` is different from `FutureRead`
-pub type FutureReader<F> = OperatorFuture<(OpRead, OpReader), Reader, F>;
+pub type FutureReader<F> = OperatorFuture<options::ReaderOptions, Reader, F>;
impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// Set `version` for this `reader`.
@@ -411,8 +434,9 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// # Ok(())
/// # }
/// ```
- pub fn version(self, v: &str) -> Self {
- self.map(|(op_read, op_reader)| (op_read.with_version(v), op_reader))
+ pub fn version(mut self, v: &str) -> Self {
+ self.args.version = Some(v.to_string());
+ self
}
/// Set `concurrent` for the reader.
@@ -433,8 +457,9 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// # Ok(())
/// # }
/// ```
- pub fn concurrent(self, concurrent: usize) -> Self {
- self.map(|(op_read, op_reader)| (op_read, op_reader.with_concurrent(concurrent)))
+ pub fn concurrent(mut self, concurrent: usize) -> Self {
+ self.args.concurrent = concurrent.max(1);
+ self
}
/// OpenDAL will use services' preferred chunk size by default. Users can set chunk based on their own needs.
@@ -453,8 +478,9 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// # Ok(())
/// # }
/// ```
- pub fn chunk(self, chunk_size: usize) -> Self {
- self.map(|(op_read, op_reader)| (op_read, op_reader.with_chunk(chunk_size)))
+ pub fn chunk(mut self, chunk_size: usize) -> Self {
+ self.args.chunk = Some(chunk_size);
+ self
}
/// Controls the optimization strategy for range reads in [`Reader::fetch`].
@@ -484,8 +510,9 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// # Ok(())
/// # }
/// ```
- pub fn gap(self, gap_size: usize) -> Self {
- self.map(|(op_read, op_reader)| (op_read, op_reader.with_gap(gap_size)))
+ pub fn gap(mut self, gap_size: usize) -> Self {
+ self.args.gap = Some(gap_size);
+ self
}
/// Set `if-match` for this `read` request.
@@ -503,8 +530,9 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_match(self, etag: &str) -> Self {
- self.map(|(op_read, op_reader)| (op_read.with_if_match(etag), op_reader))
+ pub fn if_match(mut self, etag: &str) -> Self {
+ self.args.if_match = Some(etag.to_string());
+ self
}
/// Set `if-none-match` for this `read` request.
@@ -522,8 +550,9 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_none_match(self, etag: &str) -> Self {
- self.map(|(op_read, op_reader)| (op_read.with_if_none_match(etag), op_reader))
+ pub fn if_none_match(mut self, etag: &str) -> Self {
+ self.args.if_none_match = Some(etag.to_string());
+ self
}
/// Set `if-modified-since` for this `read` request.
@@ -543,8 +572,9 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_modified_since(self, v: DateTime<Utc>) -> Self {
- self.map(|(op_read, op_reader)| (op_read.with_if_modified_since(v), op_reader))
+ pub fn if_modified_since(mut self, v: DateTime<Utc>) -> Self {
+ self.args.if_modified_since = Some(v);
+ self
}
/// Set `if-unmodified-since` for this `read` request.
@@ -564,32 +594,21 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self {
- self.map(|(op_read, op_reader)| (op_read.with_if_unmodified_since(v), op_reader))
+ pub fn if_unmodified_since(mut self, v: DateTime<Utc>) -> Self {
+ self.args.if_unmodified_since = Some(v);
+ self
}
}
/// Future that generated by [`Operator::write_with`].
///
/// Users can add more options by public functions provided by this struct.
-pub type FutureWrite<F> = OperatorFuture<(OpWrite, OpWriter, Buffer), Metadata, F>;
+pub type FutureWrite<F> = OperatorFuture<(options::WriteOptions, Buffer), Metadata, F>;
impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// Sets append mode for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_can_append`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - By default, write operations overwrite existing files
- /// - When append is set to true:
- /// - New data will be appended to the end of existing file
- /// - If file doesn't exist, it will be created
- /// - If not supported, will return an error
- ///
- /// This operation allows adding data to existing files instead of overwriting them.
+ /// Refer to [`options::WriteOptions::append`] for more details.
///
/// ### Example
///
@@ -605,35 +624,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn append(self, v: bool) -> Self {
- self.map(|(args, options, bs)| (args.with_append(v), options, bs))
+ pub fn append(mut self, v: bool) -> Self {
+ self.args.0.append = v;
+ self
}
/// Sets chunk size for buffered writes.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_multi_min_size`] and [`Capability::write_multi_max_size`] for size limits.
- ///
- /// ### Behavior
- ///
- /// - By default, OpenDAL sets optimal chunk size based on service capabilities
- /// - When chunk size is set:
- /// - Data will be buffered until reaching chunk size
- /// - One API call will be made per chunk
- /// - Last chunk may be smaller than chunk size
- /// - Important considerations:
- /// - Some services require minimum chunk sizes (e.g. S3's EntityTooSmall error)
- /// - Smaller chunks increase API calls and costs
- /// - Larger chunks increase memory usage, but improve performance and reduce costs
- ///
- /// ### Performance Impact
- ///
- /// Setting appropriate chunk size can:
- /// - Reduce number of API calls
- /// - Improve overall throughput
- /// - Lower operation costs
- /// - Better utilize network bandwidth
+ /// Refer to [`options::WriteOptions::chunk`] for more details.
///
/// ### Example
///
@@ -653,34 +651,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn chunk(self, v: usize) -> Self {
- self.map(|(args, options, bs)| (args, options.with_chunk(v), bs))
+ pub fn chunk(mut self, v: usize) -> Self {
+ self.args.0.chunk = Some(v);
+ self
}
/// Sets concurrent write operations for this writer.
///
- /// ## Behavior
- ///
- /// - By default, OpenDAL writes files sequentially
- /// - When concurrent is set:
- /// - Multiple write operations can execute in parallel
- /// - Write operations return immediately without waiting if tasks space are available
- /// - Close operation ensures all writes complete in order
- /// - Memory usage increases with concurrency level
- /// - If not supported, falls back to sequential writes
- ///
- /// This feature significantly improves performance when:
- /// - Writing large files
- /// - Network latency is high
- /// - Storage service supports concurrent uploads like multipart uploads
- ///
- /// ## Performance Impact
- ///
- /// Setting appropriate concurrency can:
- /// - Increase write throughput
- /// - Reduce total write time
- /// - Better utilize available bandwidth
- /// - Trade memory for performance
+ /// Refer to [`options::WriteOptions::concurrent`] for more details.
///
/// ## Example
///
@@ -697,30 +675,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn concurrent(self, v: usize) -> Self {
- self.map(|(args, options, bs)| (args.with_concurrent(v), options, bs))
+ pub fn concurrent(mut self, v: usize) -> Self {
+ self.args.0.concurrent = v.max(1);
+ self
}
/// Sets Cache-Control header for this write operation.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_cache_control`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, sets Cache-Control as system metadata on the target file
- /// - The value should follow HTTP Cache-Control header format
- /// - If not supported, the value will be ignored
- ///
- /// This operation allows controlling caching behavior for the written content.
- ///
- /// ### Use Cases
- ///
- /// - Setting browser cache duration
- /// - Configuring CDN behavior
- /// - Optimizing content delivery
- /// - Managing cache invalidation
+ /// Refer to [`options::WriteOptions::cache_control`] for more details.
///
/// ### Example
///
@@ -740,28 +702,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- ///
- /// ### References
- ///
- /// - [MDN Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
- /// - [RFC 7234 Section 5.2](https://tools.ietf.org/html/rfc7234#section-5.2)
- pub fn cache_control(self, v: &str) -> Self {
- self.map(|(args, options, bs)| (args.with_cache_control(v), options, bs))
+ pub fn cache_control(mut self, v: &str) -> Self {
+ self.args.0.cache_control = Some(v.to_string());
+ self
}
/// Sets `Content-Type` header for this write operation.
///
- /// ## Capability
- ///
- /// Check [`Capability::write_with_content_type`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, sets Content-Type as system metadata on the target file
- /// - The value should follow MIME type format (e.g. "text/plain", "image/jpeg")
- /// - If not supported, the value will be ignored
- ///
- /// This operation allows specifying the media type of the content being written.
+ /// Refer to [`options::WriteOptions::content_type`] for more details.
///
/// ## Example
///
@@ -779,29 +727,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn content_type(self, v: &str) -> Self {
- self.map(|(args, options, bs)| (args.with_content_type(v), options, bs))
+ pub fn content_type(mut self, v: &str) -> Self {
+ self.args.0.content_type = Some(v.to_string());
+ self
}
- /// ## `content_disposition`
- ///
/// Sets Content-Disposition header for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_content_disposition`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, sets Content-Disposition as system metadata on the target file
- /// - The value should follow HTTP Content-Disposition header format
- /// - Common values include:
- /// - `inline` - Content displayed within browser
- /// - `attachment` - Content downloaded as file
- /// - `attachment; filename="example.jpg"` - Downloaded with specified filename
- /// - If not supported, the value will be ignored
- ///
- /// This operation allows controlling how the content should be displayed or downloaded.
+ /// Refer to [`options::WriteOptions::content_disposition`] for more details.
///
/// ### Example
///
@@ -820,28 +753,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn content_disposition(self, v: &str) -> Self {
- self.map(|(args, options, bs)| (args.with_content_disposition(v), options, bs))
+ pub fn content_disposition(mut self, v: &str) -> Self {
+ self.args.0.content_disposition = Some(v.to_string());
+ self
}
/// Sets Content-Encoding header for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_content_encoding`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, sets Content-Encoding as system metadata on the target file
- /// - The value should follow HTTP Content-Encoding header format
- /// - Common values include:
- /// - `gzip` - Content encoded using gzip compression
- /// - `deflate` - Content encoded using deflate compression
- /// - `br` - Content encoded using Brotli compression
- /// - `identity` - No encoding applied (default value)
- /// - If not supported, the value will be ignored
- ///
- /// This operation allows specifying the encoding applied to the content being written.
+ /// Refer to [`options::WriteOptions::content_encoding`] for more details.
///
/// ### Example
///
@@ -860,27 +779,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn content_encoding(self, v: &str) -> Self {
- self.map(|(args, options, bs)| (args.with_content_encoding(v), options, bs))
+ pub fn content_encoding(mut self, v: &str) -> Self {
+ self.args.0.content_encoding = Some(v.to_string());
+ self
}
/// Sets If-Match header for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_if_match`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, the write operation will only succeed if the target's ETag matches the specified value
- /// - The value should be a valid ETag string
- /// - Common values include:
- /// - A specific ETag value like `"686897696a7c876b7e"`
- /// - `*` - Matches any existing resource
- /// - If not supported, the value will be ignored
- ///
- /// This operation provides conditional write functionality based on ETag matching,
- /// helping prevent unintended overwrites in concurrent scenarios.
+ /// Refer to [`options::WriteOptions::if_match`] for more details.
///
/// ### Example
///
@@ -899,30 +805,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_match(self, s: &str) -> Self {
- self.map(|(args, options, bs)| (args.with_if_match(s), options, bs))
+ pub fn if_match(mut self, s: &str) -> Self {
+ self.args.0.if_match = Some(s.to_string());
+ self
}
/// Sets If-None-Match header for this write request.
///
- /// Note: Certain services, like `s3`, support `if_not_exists` but not `if_none_match`.
- /// Use `if_not_exists` if you only want to check whether a file exists.
- ///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_if_none_match`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, the write operation will only succeed if the target's ETag does not match the specified value
- /// - The value should be a valid ETag string
- /// - Common values include:
- /// - A specific ETag value like `"686897696a7c876b7e"`
- /// - `*` - Matches if the resource does not exist
- /// - If not supported, the value will be ignored
- ///
- /// This operation provides conditional write functionality based on ETag non-matching,
- /// useful for preventing overwriting existing resources or ensuring unique writes.
+ /// Refer to [`options::WriteOptions::if_none_match`] for more details.
///
/// ### Example
///
@@ -941,24 +831,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_none_match(self, s: &str) -> Self {
- self.map(|(args, options, bs)| (args.with_if_none_match(s), options, bs))
+ pub fn if_none_match(mut self, s: &str) -> Self {
+ self.args.0.if_none_match = Some(s.to_string());
+ self
}
/// Sets the condition that write operation will succeed only if target does not exist.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_if_not_exists`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, the write operation will only succeed if the target path does not exist
- /// - Will return error if target already exists
- /// - If not supported, the value will be ignored
- ///
- /// This operation provides a way to ensure write operations only create new resources
- /// without overwriting existing ones, useful for implementing "create if not exists" logic.
+ /// Refer to [`options::WriteOptions::if_not_exists`] for more details.
///
/// ### Example
///
@@ -977,30 +857,14 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_not_exists(self, b: bool) -> Self {
- self.map(|(args, options, bs)| (args.with_if_not_exists(b), options, bs))
+ pub fn if_not_exists(mut self, b: bool) -> Self {
+ self.args.0.if_not_exists = b;
+ self
}
/// Sets user metadata for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_user_metadata`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, the user metadata will be attached to the object during write
- /// - Accepts key-value pairs where both key and value are strings
- /// - Keys are case-insensitive in most services
- /// - Services may have limitations for user metadata, for example:
- /// - Key length is typically limited (e.g., 1024 bytes)
- /// - Value length is typically limited (e.g., 4096 bytes)
- /// - Total metadata size might be limited
- /// - Some characters might be forbidden in keys
- /// - If not supported, the metadata will be ignored
- ///
- /// User metadata provides a way to attach custom metadata to objects during write operations.
- /// This metadata can be retrieved later when reading the object.
+ /// Refer to [`options::WriteOptions::user_metadata`] for more details.
///
/// ### Example
///
@@ -1022,38 +886,21 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
/// # Ok(())
/// # }
/// ```
- pub fn user_metadata(self, data: impl IntoIterator<Item = (String, String)>) -> Self {
- self.map(|(args, options, bs)| {
- (
- args.with_user_metadata(HashMap::from_iter(data)),
- options,
- bs,
- )
- })
+ pub fn user_metadata(mut self, data: impl IntoIterator<Item = (String, String)>) -> Self {
+ self.args.0.user_metadata = Some(HashMap::from_iter(data));
+ self
}
}
/// Future that generated by [`Operator::writer_with`].
///
/// Users can add more options by public functions provided by this struct.
-pub type FutureWriter<F> = OperatorFuture<(OpWrite, OpWriter), Writer, F>;
+pub type FutureWriter<F> = OperatorFuture<options::WriteOptions, Writer, F>;
impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// Sets append mode for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_can_append`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - By default, write operations overwrite existing files
- /// - When append is set to true:
- /// - New data will be appended to the end of existing file
- /// - If file doesn't exist, it will be created
- /// - If not supported, will return an error
- ///
- /// This operation allows adding data to existing files instead of overwriting them.
+ /// Refer to [`options::WriteOptions::append`] for more details.
///
/// ### Example
///
@@ -1072,35 +919,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn append(self, v: bool) -> Self {
- self.map(|(args, options)| (args.with_append(v), options))
+ pub fn append(mut self, v: bool) -> Self {
+ self.args.append = v;
+ self
}
/// Sets chunk size for buffered writes.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_multi_min_size`] and [`Capability::write_multi_max_size`] for size limits.
- ///
- /// ### Behavior
- ///
- /// - By default, OpenDAL sets optimal chunk size based on service capabilities
- /// - When chunk size is set:
- /// - Data will be buffered until reaching chunk size
- /// - One API call will be made per chunk
- /// - Last chunk may be smaller than chunk size
- /// - Important considerations:
- /// - Some services require minimum chunk sizes (e.g. S3's EntityTooSmall error)
- /// - Smaller chunks increase API calls and costs
- /// - Larger chunks increase memory usage, but improve performance and reduce costs
- ///
- /// ### Performance Impact
- ///
- /// Setting appropriate chunk size can:
- /// - Reduce number of API calls
- /// - Improve overall throughput
- /// - Lower operation costs
- /// - Better utilize network bandwidth
+ /// Refer to [`options::WriteOptions::chunk`] for more details.
///
/// ### Example
///
@@ -1123,34 +949,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn chunk(self, v: usize) -> Self {
- self.map(|(args, options)| (args, options.with_chunk(v)))
+ pub fn chunk(mut self, v: usize) -> Self {
+ self.args.chunk = Some(v);
+ self
}
/// Sets concurrent write operations for this writer.
///
- /// ## Behavior
- ///
- /// - By default, OpenDAL writes files sequentially
- /// - When concurrent is set:
- /// - Multiple write operations can execute in parallel
- /// - Write operations return immediately without waiting if tasks space are available
- /// - Close operation ensures all writes complete in order
- /// - Memory usage increases with concurrency level
- /// - If not supported, falls back to sequential writes
- ///
- /// This feature significantly improves performance when:
- /// - Writing large files
- /// - Network latency is high
- /// - Storage service supports concurrent uploads like multipart uploads
- ///
- /// ## Performance Impact
- ///
- /// Setting appropriate concurrency can:
- /// - Increase write throughput
- /// - Reduce total write time
- /// - Better utilize available bandwidth
- /// - Trade memory for performance
+ /// Refer to [`options::WriteOptions::concurrent`] for more details.
///
/// ## Example
///
@@ -1176,30 +982,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn concurrent(self, v: usize) -> Self {
- self.map(|(args, options)| (args.with_concurrent(v), options))
+ pub fn concurrent(mut self, v: usize) -> Self {
+ self.args.concurrent = v.max(1);
+ self
}
/// Sets Cache-Control header for this write operation.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_cache_control`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, sets Cache-Control as system metadata on the target file
- /// - The value should follow HTTP Cache-Control header format
- /// - If not supported, the value will be ignored
- ///
- /// This operation allows controlling caching behavior for the written content.
- ///
- /// ### Use Cases
- ///
- /// - Setting browser cache duration
- /// - Configuring CDN behavior
- /// - Optimizing content delivery
- /// - Managing cache invalidation
+ /// Refer to [`options::WriteOptions::cache_control`] for more details.
///
/// ### Example
///
@@ -1222,28 +1012,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- ///
- /// ### References
- ///
- /// - [MDN Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
- /// - [RFC 7234 Section 5.2](https://tools.ietf.org/html/rfc7234#section-5.2)
- pub fn cache_control(self, v: &str) -> Self {
- self.map(|(args, options)| (args.with_cache_control(v), options))
+ pub fn cache_control(mut self, v: &str) -> Self {
+ self.args.cache_control = Some(v.to_string());
+ self
}
/// Sets `Content-Type` header for this write operation.
///
- /// ## Capability
- ///
- /// Check [`Capability::write_with_content_type`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, sets Content-Type as system metadata on the target file
- /// - The value should follow MIME type format (e.g. "text/plain", "image/jpeg")
- /// - If not supported, the value will be ignored
- ///
- /// This operation allows specifying the media type of the content being written.
+ /// Refer to [`options::WriteOptions::content_type`] for more details.
///
/// ## Example
///
@@ -1264,29 +1040,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn content_type(self, v: &str) -> Self {
- self.map(|(args, options)| (args.with_content_type(v), options))
+ pub fn content_type(mut self, v: &str) -> Self {
+ self.args.content_type = Some(v.to_string());
+ self
}
- /// ## `content_disposition`
- ///
/// Sets Content-Disposition header for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_content_disposition`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, sets Content-Disposition as system metadata on the target file
- /// - The value should follow HTTP Content-Disposition header format
- /// - Common values include:
- /// - `inline` - Content displayed within browser
- /// - `attachment` - Content downloaded as file
- /// - `attachment; filename="example.jpg"` - Downloaded with specified filename
- /// - If not supported, the value will be ignored
- ///
- /// This operation allows controlling how the content should be displayed or downloaded.
+ /// Refer to [`options::WriteOptions::content_disposition`] for more details.
///
/// ### Example
///
@@ -1308,28 +1069,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn content_disposition(self, v: &str) -> Self {
- self.map(|(args, options)| (args.with_content_disposition(v), options))
+ pub fn content_disposition(mut self, v: &str) -> Self {
+ self.args.content_disposition = Some(v.to_string());
+ self
}
/// Sets Content-Encoding header for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_content_encoding`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, sets Content-Encoding as system metadata on the target file
- /// - The value should follow HTTP Content-Encoding header format
- /// - Common values include:
- /// - `gzip` - Content encoded using gzip compression
- /// - `deflate` - Content encoded using deflate compression
- /// - `br` - Content encoded using Brotli compression
- /// - `identity` - No encoding applied (default value)
- /// - If not supported, the value will be ignored
- ///
- /// This operation allows specifying the encoding applied to the content being written.
+ /// Refer to [`options::WriteOptions::content_encoding`] for more details.
///
/// ### Example
///
@@ -1351,15 +1098,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn content_encoding(self, v: &str) -> Self {
- self.map(|(args, options)| (args.with_content_encoding(v), options))
+ pub fn content_encoding(mut self, v: &str) -> Self {
+ self.args.content_encoding = Some(v.to_string());
+ self
}
/// Sets If-Match header for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_if_match`] before using this feature.
+ /// Refer to [`options::WriteOptions::if_match`] for more details.
///
/// ### Behavior
///
@@ -1393,30 +1139,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_match(self, s: &str) -> Self {
- self.map(|(args, options)| (args.with_if_match(s), options))
+ pub fn if_match(mut self, s: &str) -> Self {
+ self.args.if_match = Some(s.to_string());
+ self
}
/// Sets If-None-Match header for this write request.
///
- /// Note: Certain services, like `s3`, support `if_not_exists` but not `if_none_match`.
- /// Use `if_not_exists` if you only want to check whether a file exists.
- ///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_if_none_match`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, the write operation will only succeed if the target's ETag does not match the specified value
- /// - The value should be a valid ETag string
- /// - Common values include:
- /// - A specific ETag value like `"686897696a7c876b7e"`
- /// - `*` - Matches if the resource does not exist
- /// - If not supported, the value will be ignored
- ///
- /// This operation provides conditional write functionality based on ETag non-matching,
- /// useful for preventing overwriting existing resources or ensuring unique writes.
+ /// Refer to [`options::WriteOptions::if_none_match`] for more details.
///
/// ### Example
///
@@ -1438,24 +1168,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_none_match(self, s: &str) -> Self {
- self.map(|(args, options)| (args.with_if_none_match(s), options))
+ pub fn if_none_match(mut self, s: &str) -> Self {
+ self.args.if_none_match = Some(s.to_string());
+ self
}
/// Sets the condition that write operation will succeed only if target does not exist.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_if_not_exists`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, the write operation will only succeed if the target path does not exist
- /// - Will return error if target already exists
- /// - If not supported, the value will be ignored
- ///
- /// This operation provides a way to ensure write operations only create new resources
- /// without overwriting existing ones, useful for implementing "create if not exists" logic.
+ /// Refer to [`options::WriteOptions::if_not_exists`] for more details.
///
/// ### Example
///
@@ -1477,30 +1197,14 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn if_not_exists(self, b: bool) -> Self {
- self.map(|(args, options)| (args.with_if_not_exists(b), options))
+ pub fn if_not_exists(mut self, b: bool) -> Self {
+ self.args.if_not_exists = b;
+ self
}
/// Sets user metadata for this write request.
///
- /// ### Capability
- ///
- /// Check [`Capability::write_with_user_metadata`] before using this feature.
- ///
- /// ### Behavior
- ///
- /// - If supported, the user metadata will be attached to the object during write
- /// - Accepts key-value pairs where both key and value are strings
- /// - Keys are case-insensitive in most services
- /// - Services may have limitations for user metadata, for example:
- /// - Key length is typically limited (e.g., 1024 bytes)
- /// - Value length is typically limited (e.g., 4096 bytes)
- /// - Total metadata size might be limited
- /// - Some characters might be forbidden in keys
- /// - If not supported, the metadata will be ignored
- ///
- /// User metadata provides a way to attach custom metadata to objects during write operations.
- /// This metadata can be retrieved later when reading the object.
+ /// Refer to [`options::WriteOptions::user_metadata`] for more details.
///
/// ### Example
///
@@ -1524,20 +1228,22 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
/// # Ok(())
/// # }
/// ```
- pub fn user_metadata(self, data: impl IntoIterator<Item = (String, String)>) -> Self {
- self.map(|(args, options)| (args.with_user_metadata(HashMap::from_iter(data)), options))
+ pub fn user_metadata(mut self, data: impl IntoIterator<Item = (String, String)>) -> Self {
+ self.args.user_metadata = Some(HashMap::from_iter(data));
+ self
}
}
/// Future that generated by [`Operator::delete_with`].
///
/// Users can add more options by public functions provided by this struct.
-pub type FutureDelete<F> = OperatorFuture<OpDelete, (), F>;
+pub type FutureDelete<F> = OperatorFuture<options::DeleteOptions, (), F>;
impl<F: Future<Output = Result<()>>> FutureDelete<F> {
/// Change the version of this delete operation.
- pub fn version(self, v: &str) -> Self {
- self.map(|args| args.with_version(v))
+ pub fn version(mut self, v: &str) -> Self {
+ self.args.version = Some(v.to_string());
+ self
}
}
diff --git a/core/src/types/options.rs b/core/src/types/options.rs
new file mode 100644
index 000000000..a7b9d019a
--- /dev/null
+++ b/core/src/types/options.rs
@@ -0,0 +1,518 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Options module provides options definitions for operations.
+
+use std::collections::HashMap;
+
+use chrono::{DateTime, Utc};
+
+use crate::raw::BytesRange;
+
+/// Options for delete operations.
+#[non_exhaustive]
+#[derive(Debug, Clone, Default, Eq, PartialEq)]
+pub struct DeleteOptions {
+ /// The version of the file to delete.
+ pub version: Option<String>,
+}
+
+/// Options for list operations.
+#[non_exhaustive]
+#[derive(Debug, Clone, Default, Eq, PartialEq)]
+pub struct ListOptions {
+ /// The limit passed to underlying service to specify the max results
+ /// that could return per-request.
+ ///
+ /// Users could use this to control the memory usage of list operation.
+ pub limit: Option<usize>,
+ /// The start_after passes to underlying service to specify the specified key
+ /// to start listing from.
+ pub start_after: Option<String>,
+ /// The recursive is used to control whether the list operation is recursive.
+ ///
+ /// - If `false`, list operation will only list the entries under the given path.
+ /// - If `true`, list operation will list all entries that starts with given path.
+ ///
+ /// Default to `false`.
+ pub recursive: bool,
+ /// The version is used to control whether the object versions should be returned.
+ ///
+ /// - If `false`, list operation will not return with object versions
+ /// - If `true`, list operation will return with object versions if object versioning is supported
+ /// by the underlying service
+ ///
+ /// Default to `false`
+ pub versions: bool,
+ /// The deleted is used to control whether the deleted objects should be returned.
+ ///
+ /// - If `false`, list operation will not return with deleted objects
+ /// - If `true`, list operation will return with deleted objects if object versioning is supported
+ /// by the underlying service
+ ///
+ /// Default to `false`
+ pub deleted: bool,
+}
+
+/// Options for read operations.
+#[non_exhaustive]
+#[derive(Debug, Clone, Default, Eq, PartialEq)]
+pub struct ReadOptions {
+ /// Set `range` for this operation.
+ ///
+ /// If we have a file with size `n`.
+ ///
+ /// - `..` means read bytes in range `[0, n)` of file.
+ /// - `0..1024` and `..1024` means read bytes in range `[0, 1024)` of file
+ /// - `1024..` means read bytes in range `[1024, n)` of file
+ ///
+ /// The type implements `From<RangeBounds<u64>>`, so users can use `(1024..).into()` instead.
+ pub range: BytesRange,
+ /// Set `version` for this operation.
+ ///
+ /// This option can be used to retrieve the data of a specified version of the given path.
+ ///
+ /// If the version doesn't exist, an error with kind [`ErrorKind::NotFound`] will be returned.
+ pub version: Option<String>,
+
+ /// Set `if_match` for this operation.
+ ///
+ /// This option can be used to check if the file's `ETag` matches the given `ETag`.
+ ///
+ /// If file exists and it's etag doesn't match, an error with kind [`ErrorKind::ConditionNotMatch`]
+ /// will be returned.
+ pub if_match: Option<String>,
+ /// Set `if_none_match` for this operation.
+ ///
+ /// This option can be used to check if the file's `ETag` doesn't match the given `ETag`.
+ ///
+ /// If file exists and it's etag match, an error with kind [`ErrorKind::ConditionNotMatch`]
+ /// will be returned.
+ pub if_none_match: Option<String>,
+ /// Set `if_modified_since` for this operation.
+ ///
+ /// This option can be used to check if the file has been modified since the given timestamp.
+ ///
+ /// If file exists and it hasn't been modified since the specified time, an error with kind
+ /// [`ErrorKind::ConditionNotMatch`] will be returned.
+ pub if_modified_since: Option<DateTime<Utc>>,
+ /// Set `if_unmodified_since` for this operation.
+ ///
+ /// This feature can be used to check if the file hasn't been modified since the given timestamp.
+ ///
+ /// If file exists and it has been modified since the specified time, an error with kind
+ /// [`ErrorKind::ConditionNotMatch`] will be returned.
+ pub if_unmodified_since: Option<DateTime<Utc>>,
+
+ /// Set `concurrent` for the operation.
+ ///
+ /// OpenDAL by default to read file without concurrent. This is not efficient for cases when users
+ /// read large chunks of data. By setting `concurrent`, opendal will reading files concurrently
+ /// on support storage services.
+ ///
+ /// By setting `concurrent`, opendal will fetch chunks concurrently with
+ /// the give chunk size.
+ ///
+ /// Refer to [`crate::docs::performance`] for more details.
+ pub concurrent: usize,
+ /// Set `chunk` for the operation.
+ ///
+ /// OpenDAL will use services' preferred chunk size by default. Users can set chunk based on their own needs.
+ ///
+ /// Refer to [`crate::docs::performance`] for more details.
+ pub chunk: Option<usize>,
+ /// Controls the optimization strategy for range reads in [`Reader::fetch`].
+ ///
+ /// When performing range reads, if the gap between two requested ranges is smaller than
+ /// the configured `gap` size, OpenDAL will merge these ranges into a single read request
+ /// and discard the unrequested data in between. This helps reduce the number of API calls
+ /// to remote storage services.
+ ///
+ /// This optimization is particularly useful when performing multiple small range reads
+ /// that are close to each other, as it reduces the overhead of multiple network requests
+ /// at the cost of transferring some additional data.
+ ///
+ /// Refer to [`crate::docs::performance`] for more details.
+ pub gap: Option<usize>,
+
+ /// Specify the content-type header that should be sent back by the operation.
+ ///
+ /// This option is only meaningful when used along with presign.
+ pub override_content_type: Option<String>,
+ /// Specify the `cache-control` header that should be sent back by the operation.
+ ///
+ /// This option is only meaningful when used along with presign.
+ pub override_cache_control: Option<String>,
+ /// Specify the `content-disposition` header that should be sent back by the operation.
+ ///
+ /// This option is only meaningful when used along with presign.
+ pub override_content_disposition: Option<String>,
+}
+
+/// Options for reader operations.
+#[non_exhaustive]
+#[derive(Debug, Clone, Default, Eq, PartialEq)]
+pub struct ReaderOptions {
+ /// Set `version` for this operation.
+ ///
+ /// This option can be used to retrieve the data of a specified version of the given path.
+ ///
+ /// If the version doesn't exist, an error with kind [`ErrorKind::NotFound`] will be returned.
+ pub version: Option<String>,
+
+ /// Set `if_match` for this operation.
+ ///
+ /// This option can be used to check if the file's `ETag` matches the given `ETag`.
+ ///
+ /// If file exists and it's etag doesn't match, an error with kind [`ErrorKind::ConditionNotMatch`]
+ /// will be returned.
+ pub if_match: Option<String>,
+ /// Set `if_none_match` for this operation.
+ ///
+ /// This option can be used to check if the file's `ETag` doesn't match the given `ETag`.
+ ///
+ /// If file exists and it's etag match, an error with kind [`ErrorKind::ConditionNotMatch`]
+ /// will be returned.
+ pub if_none_match: Option<String>,
+ /// Set `if_modified_since` for this operation.
+ ///
+ /// This option can be used to check if the file has been modified since the given timestamp.
+ ///
+ /// If file exists and it hasn't been modified since the specified time, an error with kind
+ /// [`ErrorKind::ConditionNotMatch`] will be returned.
+ pub if_modified_since: Option<DateTime<Utc>>,
+ /// Set `if_unmodified_since` for this operation.
+ ///
+ /// This feature can be used to check if the file hasn't been modified since the given timestamp.
+ ///
+ /// If file exists and it has been modified since the specified time, an error with kind
+ /// [`ErrorKind::ConditionNotMatch`] will be returned.
+ pub if_unmodified_since: Option<DateTime<Utc>>,
+
+ /// Set `concurrent` for the operation.
+ ///
+ /// OpenDAL by default to read file without concurrent. This is not efficient for cases when users
+ /// read large chunks of data. By setting `concurrent`, opendal will reading files concurrently
+ /// on support storage services.
+ ///
+ /// By setting `concurrent`, opendal will fetch chunks concurrently with
+ /// the give chunk size.
+ ///
+ /// Refer to [`crate::docs::performance`] for more details.
+ pub concurrent: usize,
+ /// Set `chunk` for the operation.
+ ///
+ /// OpenDAL will use services' preferred chunk size by default. Users can set chunk based on their own needs.
+ ///
+ /// Refer to [`crate::docs::performance`] for more details.
+ pub chunk: Option<usize>,
+ /// Controls the optimization strategy for range reads in [`Reader::fetch`].
+ ///
+ /// When performing range reads, if the gap between two requested ranges is smaller than
+ /// the configured `gap` size, OpenDAL will merge these ranges into a single read request
+ /// and discard the unrequested data in between. This helps reduce the number of API calls
+ /// to remote storage services.
+ ///
+ /// This optimization is particularly useful when performing multiple small range reads
+ /// that are close to each other, as it reduces the overhead of multiple network requests
+ /// at the cost of transferring some additional data.
+ ///
+ /// Refer to [`crate::docs::performance`] for more details.
+ pub gap: Option<usize>,
+}
+
+/// Options for stat operations.
+#[non_exhaustive]
+#[derive(Debug, Clone, Default, Eq, PartialEq)]
+pub struct StatOptions {
+ /// Set `version` for this operation.
+ ///
+ /// This options can be used to retrieve the data of a specified version of the given path.
+ ///
+ /// If the version doesn't exist, an error with kind [`ErrorKind::NotFound`] will be returned.
+ pub version: Option<String>,
+
+ /// Set `if_match` for this operation.
+ ///
+ /// This option can be used to check if the file's `ETag` matches the given `ETag`.
+ ///
+ /// If file exists and it's etag doesn't match, an error with kind [`ErrorKind::ConditionNotMatch`]
+ /// will be returned.
+ pub if_match: Option<String>,
+ /// Set `if_none_match` for this operation.
+ ///
+ /// This option can be used to check if the file's `ETag` doesn't match the given `ETag`.
+ ///
+ /// If file exists and it's etag match, an error with kind [`ErrorKind::ConditionNotMatch`]
+ /// will be returned.
+ pub if_none_match: Option<String>,
+ /// Set `if_modified_since` for this operation.
+ ///
+ /// This option can be used to check if the file has been modified since the given timestamp.
+ ///
+ /// If file exists and it hasn't been modified since the specified time, an error with kind
+ /// [`ErrorKind::ConditionNotMatch`] will be returned.
+ pub if_modified_since: Option<DateTime<Utc>>,
+ /// Set `if_unmodified_since` for this operation.
+ ///
+ /// This feature can be used to check if the file hasn't been modified since the given timestamp.
+ ///
+ /// If file exists and it has been modified since the specified time, an error with kind
+ /// [`ErrorKind::ConditionNotMatch`] will be returned.
+ pub if_unmodified_since: Option<DateTime<Utc>>,
+
+ /// Specify the content-type header that should be sent back by the operation.
+ ///
+ /// This option is only meaningful when used along with presign.
+ pub override_content_type: Option<String>,
+ /// Specify the `cache-control` header that should be sent back by the operation.
+ ///
+ /// This option is only meaningful when used along with presign.
+ pub override_cache_control: Option<String>,
+ /// Specify the `content-disposition` header that should be sent back by the operation.
+ ///
+ /// This option is only meaningful when used along with presign.
+ pub override_content_disposition: Option<String>,
+}
+
+/// Options for write operations.
+#[non_exhaustive]
+#[derive(Debug, Clone, Default, Eq, PartialEq)]
+pub struct WriteOptions {
+ /// Sets append mode for this operation.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_can_append`] before using this option.
+ ///
+ /// ### Behavior
+ ///
+ /// - By default, write operations overwrite existing files
+ /// - When append is set to true:
+ /// - New data will be appended to the end of existing file
+ /// - If file doesn't exist, it will be created
+ /// - If not supported, will return an error
+ ///
+ /// This operation allows adding data to existing files instead of overwriting them.
+ pub append: bool,
+
+ /// Sets Cache-Control header for this write operation.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_with_cache_control`] before using this feature.
+ ///
+ /// ### Behavior
+ ///
+ /// - If supported, sets Cache-Control as system metadata on the target file
+ /// - The value should follow HTTP Cache-Control header format
+ /// - If not supported, the value will be ignored
+ ///
+ /// This operation allows controlling caching behavior for the written content.
+ ///
+ /// ### Use Cases
+ ///
+ /// - Setting browser cache duration
+ /// - Configuring CDN behavior
+ /// - Optimizing content delivery
+ /// - Managing cache invalidation
+ ///
+ /// ### References
+ ///
+ /// - [MDN Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
+ /// - [RFC 7234 Section 5.2](https://tools.ietf.org/html/rfc7234#section-5.2)
+ pub cache_control: Option<String>,
+ /// Sets `Content-Type` header for this write operation.
+ ///
+ /// ## Capability
+ ///
+ /// Check [`Capability::write_with_content_type`] before using this feature.
+ ///
+ /// ### Behavior
+ ///
+ /// - If supported, sets Content-Type as system metadata on the target file
+ /// - The value should follow MIME type format (e.g. "text/plain", "image/jpeg")
+ /// - If not supported, the value will be ignored
+ ///
+ /// This operation allows specifying the media type of the content being written.
+ pub content_type: Option<String>,
+ /// Sets Content-Disposition header for this write request.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_with_content_disposition`] before using this feature.
+ ///
+ /// ### Behavior
+ ///
+ /// - If supported, sets Content-Disposition as system metadata on the target file
+ /// - The value should follow HTTP Content-Disposition header format
+ /// - Common values include:
+ /// - `inline` - Content displayed within browser
+ /// - `attachment` - Content downloaded as file
+ /// - `attachment; filename="example.jpg"` - Downloaded with specified filename
+ /// - If not supported, the value will be ignored
+ ///
+ /// This operation allows controlling how the content should be displayed or downloaded.
+ pub content_disposition: Option<String>,
+ /// Sets Content-Encoding header for this write request.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_with_content_encoding`] before using this feature.
+ ///
+ /// ### Behavior
+ ///
+ /// - If supported, sets Content-Encoding as system metadata on the target file
+ /// - The value should follow HTTP Content-Encoding header format
+ /// - Common values include:
+ /// - `gzip` - Content encoded using gzip compression
+ /// - `deflate` - Content encoded using deflate compression
+ /// - `br` - Content encoded using Brotli compression
+ /// - `identity` - No encoding applied (default value)
+ /// - If not supported, the value will be ignored
+ ///
+ /// This operation allows specifying the encoding applied to the content being written.
+ pub content_encoding: Option<String>,
+ /// Sets user metadata for this write request.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_with_user_metadata`] before using this feature.
+ ///
+ /// ### Behavior
+ ///
+ /// - If supported, the user metadata will be attached to the object during write
+ /// - Accepts key-value pairs where both key and value are strings
+ /// - Keys are case-insensitive in most services
+ /// - Services may have limitations for user metadata, for example:
+ /// - Key length is typically limited (e.g., 1024 bytes)
+ /// - Value length is typically limited (e.g., 4096 bytes)
+ /// - Total metadata size might be limited
+ /// - Some characters might be forbidden in keys
+ /// - If not supported, the metadata will be ignored
+ ///
+ /// User metadata provides a way to attach custom metadata to objects during write operations.
+ /// This metadata can be retrieved later when reading the object.
+ pub user_metadata: Option<HashMap<String, String>>,
+
+ /// Sets If-Match header for this write request.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_with_if_match`] before using this feature.
+ ///
+ /// ### Behavior
+ ///
+ /// - If supported, the write operation will only succeed if the target's ETag matches the specified value
+ /// - The value should be a valid ETag string
+ /// - Common values include:
+ /// - A specific ETag value like `"686897696a7c876b7e"`
+ /// - `*` - Matches any existing resource
+ /// - If not supported, the value will be ignored
+ ///
+ /// This operation provides conditional write functionality based on ETag matching,
+ /// helping prevent unintended overwrites in concurrent scenarios.
+ pub if_match: Option<String>,
+ /// Sets If-None-Match header for this write request.
+ ///
+ /// Note: Certain services, like `s3`, support `if_not_exists` but not `if_none_match`.
+ /// Use `if_not_exists` if you only want to check whether a file exists.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_with_if_none_match`] before using this feature.
+ ///
+ /// ### Behavior
+ ///
+ /// - If supported, the write operation will only succeed if the target's ETag does not match the specified value
+ /// - The value should be a valid ETag string
+ /// - Common values include:
+ /// - A specific ETag value like `"686897696a7c876b7e"`
+ /// - `*` - Matches if the resource does not exist
+ /// - If not supported, the value will be ignored
+ ///
+ /// This operation provides conditional write functionality based on ETag non-matching,
+ /// useful for preventing overwriting existing resources or ensuring unique writes.
+ pub if_none_match: Option<String>,
+ /// Sets the condition that write operation will succeed only if target does not exist.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_with_if_not_exists`] before using this feature.
+ ///
+ /// ### Behavior
+ ///
+ /// - If supported, the write operation will only succeed if the target path does not exist
+ /// - Will return error if target already exists
+ /// - If not supported, the value will be ignored
+ ///
+ /// This operation provides a way to ensure write operations only create new resources
+ /// without overwriting existing ones, useful for implementing "create if not exists" logic.
+ pub if_not_exists: bool,
+
+ /// Sets concurrent write operations for this writer.
+ ///
+ /// ## Behavior
+ ///
+ /// - By default, OpenDAL writes files sequentially
+ /// - When concurrent is set:
+ /// - Multiple write operations can execute in parallel
+ /// - Write operations return immediately without waiting if tasks space are available
+ /// - Close operation ensures all writes complete in order
+ /// - Memory usage increases with concurrency level
+ /// - If not supported, falls back to sequential writes
+ ///
+ /// This feature significantly improves performance when:
+ /// - Writing large files
+ /// - Network latency is high
+ /// - Storage service supports concurrent uploads like multipart uploads
+ ///
+ /// ## Performance Impact
+ ///
+ /// Setting appropriate concurrency can:
+ /// - Increase write throughput
+ /// - Reduce total write time
+ /// - Better utilize available bandwidth
+ /// - Trade memory for performance
+ pub concurrent: usize,
+ /// Sets chunk size for buffered writes.
+ ///
+ /// ### Capability
+ ///
+ /// Check [`Capability::write_multi_min_size`] and [`Capability::write_multi_max_size`] for size limits.
+ ///
+ /// ### Behavior
+ ///
+ /// - By default, OpenDAL sets optimal chunk size based on service capabilities
+ /// - When chunk size is set:
+ /// - Data will be buffered until reaching chunk size
+ /// - One API call will be made per chunk
+ /// - Last chunk may be smaller than chunk size
+ /// - Important considerations:
+ /// - Some services require minimum chunk sizes (e.g. S3's EntityTooSmall error)
+ /// - Smaller chunks increase API calls and costs
+ /// - Larger chunks increase memory usage, but improve performance and reduce costs
+ ///
+ /// ### Performance Impact
+ ///
+ /// Setting appropriate chunk size can:
+ /// - Reduce number of API calls
+ /// - Improve overall throughput
+ /// - Lower operation costs
+ /// - Better utilize network bandwidth
+ pub chunk: Option<usize>,
+}