opendal 0.1.8 → 0.1.9

data/core/core/src/raw/ops.rs

@@ -25,7 +25,7 @@ use crate::raw::*;
 
 use std::collections::HashMap;
 
-/// Args for `create` operation.
+/// Arguments for `create` operation.
 ///
 /// The path must be normalized.
 #[derive(Debug, Clone, Default)]
@@ -38,12 +38,15 @@ impl OpCreateDir {
     }
 }
 
-/// Args for `delete` operation.
+/// Arguments for `delete` operation.
 ///
 /// The path must be normalized.
 #[derive(Debug, Clone, Default, Eq, Hash, PartialEq)]
 pub struct OpDelete {
+    /// The version of the object to delete.
     version: Option<String>,
+
+    /// Whether a `delete` is recursive.
     recursive: bool,
 }
 
@@ -55,7 +58,7 @@ impl OpDelete {
 }
 
 impl OpDelete {
-    /// Change the version of this delete operation.
+    /// Set the version of the object to delete.
     pub fn with_version(mut self, version: &str) -> Self {
         self.version = Some(version.into());
         self
@@ -67,7 +70,7 @@ impl OpDelete {
         self
     }
 
-    /// Get the version of this delete operation.
+    /// Return the version of the object to delete.
     pub fn version(&self) -> Option<&str> {
         self.version.as_deref()
     }
@@ -87,7 +90,7 @@ impl From<options::DeleteOptions> for OpDelete {
     }
 }
 
-/// Args for `delete` operation.
+/// Arguments for `delete` operation.
 ///
 /// The path must be normalized.
 #[derive(Debug, Clone, Default)]
@@ -100,39 +103,43 @@ impl OpDeleter {
     }
 }
 
-/// Args for `list` operation.
+/// Arguments for `list` operation.
 #[derive(Debug, Clone, Default)]
 pub struct OpList {
-    /// The limit passed to underlying service to specify the max results
-    /// that could return per-request.
+    /// The maximum number of results that the service should return per request.
     ///
-    /// Users could use this to control the memory usage of list operation.
+    /// This can be used to control the memory consumption of a list operation.
     limit: Option<usize>,
-    /// The start_after passes to underlying service to specify the specified key
-    /// to start listing from.
+
+    /// The key after which the service should start listing.
     start_after: Option<String>,
-    /// The recursive is used to control whether the list operation is recursive.
+
+    /// 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.
+    /// - If `false`, the operation lists only the immediate children of the given
+    ///   path.
+    /// - If `true`, the operation lists all entries whose paths start with the
+    ///   given path.
     ///
-    /// Default to `false`.
+    /// Defaults to `false`.
     recursive: bool,
-    /// The version is used to control whether the object versions should be returned.
+
+    /// Whether to return object versions.
     ///
-    /// - 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
+    /// - If `false`, the operation does not return object versions.
+    /// - If `true`, the operation returns object versions when the service
+    ///   supports versioning.
     ///
-    /// Default to `false`
+    /// Defaults to `false`.
     versions: bool,
-    /// The deleted is used to control whether the deleted objects should be returned.
+
+    /// Whether to return deleted objects.
     ///
-    /// - 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
+    /// - If `false`, the operation does not return deleted objects.
+    /// - If `true`, the operation returns deleted objects when the service
+    ///   supports versioning.
     ///
-    /// Default to `false`
+    /// Defaults to `false`.
     deleted: bool,
 }
 
@@ -142,40 +149,42 @@ impl OpList {
         Self::default()
     }
 
-    /// Change the limit of this list operation.
+    /// Set the maximum number of results per request.
     pub fn with_limit(mut self, limit: usize) -> Self {
         self.limit = Some(limit);
         self
     }
 
-    /// Get the limit of list operation.
+    /// Return the maximum number of results per request.
     pub fn limit(&self) -> Option<usize> {
         self.limit
     }
 
-    /// Change the start_after of this list operation.
+    /// Set the key after which listing should start.
     pub fn with_start_after(mut self, start_after: &str) -> Self {
         self.start_after = Some(start_after.into());
         self
     }
 
-    /// Get the start_after of list operation.
+    /// Return the key after which listing should start.
     pub fn start_after(&self) -> Option<&str> {
         self.start_after.as_deref()
     }
 
-    /// The recursive is used to control whether the list operation is recursive.
+    /// Set 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.
+    /// - If `false`, the operation lists only the immediate children of the given
+    ///   path.
+    /// - If `true`, the operation lists all entries whose paths start with the
+    ///   given path.
     ///
-    /// Default to `false`.
+    /// Defaults to `false`.
     pub fn with_recursive(mut self, recursive: bool) -> Self {
         self.recursive = recursive;
         self
     }
 
-    /// Get the current recursive.
+    /// Return whether the list operation is recursive.
     pub fn recursive(&self) -> bool {
         self.recursive
     }
@@ -195,24 +204,24 @@ impl OpList {
         0
     }
 
-    /// Change the version of this list operation
+    /// Set whether to return object versions.
     pub fn with_versions(mut self, versions: bool) -> Self {
         self.versions = versions;
         self
     }
 
-    /// Get the version of this list operation
+    /// Return whether the operation includes object versions.
     pub fn versions(&self) -> bool {
         self.versions
     }
 
-    /// Change the deleted of this list operation
+    /// Set whether to return deleted objects.
     pub fn with_deleted(mut self, deleted: bool) -> Self {
         self.deleted = deleted;
         self
     }
 
-    /// Get the deleted of this list operation
+    /// Return whether the operation includes deleted objects.
     pub fn deleted(&self) -> bool {
         self.deleted
     }
@@ -230,7 +239,7 @@ impl From<options::ListOptions> for OpList {
     }
 }
 
-/// Args for `presign` operation.
+/// Arguments for `presign` operation.
 ///
 /// The path must be normalized.
 #[derive(Debug, Clone)]
@@ -249,12 +258,12 @@ impl OpPresign {
         }
     }
 
-    /// Get operation from op.
+    /// Return the operation to presign.
     pub fn operation(&self) -> &PresignOperation {
         &self.op
     }
 
-    /// Get expire from op.
+    /// Return the request expiration duration.
     pub fn expire(&self) -> Duration {
         self.expire
     }
@@ -303,7 +312,7 @@ impl From<OpDelete> for PresignOperation {
     }
 }
 
-/// Args for `read` operation.
+/// Arguments for `read` operation.
 #[derive(Debug, Clone, Default)]
 pub struct OpRead {
     if_match: Option<String>,
@@ -385,7 +394,7 @@ impl OpRead {
         self
     }
 
-    /// Get If-Modified-Since from option
+    /// Return the If-Modified-Since condition.
     pub fn if_modified_since(&self) -> Option<Timestamp> {
         self.if_modified_since
     }
@@ -417,12 +426,12 @@ impl OpRead {
     }
 }
 
-/// Args for reader operation.
+/// Arguments for reader operation.
 #[derive(Debug, Clone)]
 pub struct OpReader {
-    /// The concurrent requests that reader can send.
+    /// The number of concurrent requests that reader can send.
     concurrent: usize,
-    /// The chunk size of each request.
+    /// Request chunk size.
     chunk: Option<usize>,
     /// The gap size of each request.
     gap: Option<usize>,
@@ -447,46 +456,46 @@ impl OpReader {
         Self::default()
     }
 
-    /// Set the concurrent of the option
+    /// Set the number of concurrent requests the reader can send.
     pub fn with_concurrent(mut self, concurrent: usize) -> Self {
         self.concurrent = concurrent.max(1);
         self
     }
 
-    /// Get concurrent from option
+    /// Return the number of concurrent requests.
     pub fn concurrent(&self) -> usize {
         self.concurrent
     }
 
-    /// Set the chunk of the option
+    /// Set the request chunk size.
     pub fn with_chunk(mut self, chunk: usize) -> Self {
         self.chunk = Some(chunk.max(1));
         self
     }
 
-    /// Get chunk from option
+    /// Return the request chunk size.
     pub fn chunk(&self) -> Option<usize> {
         self.chunk
     }
 
-    /// Set the gap of the option
+    /// Set the gap size.
     pub fn with_gap(mut self, gap: usize) -> Self {
         self.gap = Some(gap.max(1));
         self
     }
 
-    /// Get gap from option
+    /// Return the gap size.
     pub fn gap(&self) -> Option<usize> {
         self.gap
     }
 
-    /// Set the prefetch of the option
+    /// Set the number of prefetch requests.
     pub fn with_prefetch(mut self, prefetch: usize) -> Self {
         self.prefetch = prefetch;
         self
     }
 
-    /// Get prefetch from option
+    /// Return the number of prefetch requests.
     pub fn prefetch(&self) -> usize {
         self.prefetch
     }
@@ -543,7 +552,7 @@ impl From<options::ReaderOptions> for (OpRead, OpReader) {
     }
 }
 
-/// Args for `stat` operation.
+/// Arguments for `stat` operation.
 #[derive(Debug, Clone, Default)]
 pub struct OpStat {
     if_match: Option<String>,
@@ -667,7 +676,7 @@ impl From<options::StatOptions> for OpStat {
     }
 }
 
-/// Args for `write` operation.
+/// Arguments for `write` operation.
 #[derive(Debug, Clone, Default)]
 pub struct OpWrite {
     append: bool,
@@ -703,7 +712,7 @@ impl OpWrite {
     ///
     /// # Notes
     ///
-    /// Service could return `Unsupported` if the underlying storage does not support append.
+    /// Service could return `Unsupported` if the storage does not support append.
     pub fn with_append(mut self, append: bool) -> Self {
         self.append = append;
         self
@@ -809,7 +818,7 @@ impl OpWrite {
     }
 }
 
-/// Args for `writer` operation.
+/// Arguments for `writer` operation.
 #[derive(Debug, Clone, Default)]
 pub struct OpWriter {
     chunk: Option<usize>,
@@ -864,7 +873,7 @@ impl From<options::WriteOptions> for (OpWrite, OpWriter) {
     }
 }
 
-/// Args for `copy` operation.
+/// Arguments for `copy` operation.
 #[derive(Debug, Clone, Default)]
 pub struct OpCopy {
     if_not_exists: bool,
@@ -920,7 +929,7 @@ impl OpCopy {
     }
 }
 
-/// Args for `copier` operation.
+/// Arguments for `copier` operation.
 #[derive(Debug, Clone, Default)]
 pub struct OpCopier {
     concurrent: usize,
@@ -985,9 +994,13 @@ impl From<options::CopyOptions> for (OpCopy, OpCopier) {
     }
 }
 
-/// Args for `rename` operation.
+/// Arguments for `rename` operation.
 #[derive(Debug, Clone, Default)]
 pub struct OpRename {
+    /// Whether the rename should fail when the destination already exists.
+    ///
+    /// If `true`, the rename succeeds only when the destination does not exist.
+    /// If `false`, the rename uses OpenDAL's default overwrite behavior.
     if_not_exists: bool,
 }
 
@@ -997,13 +1010,22 @@ impl OpRename {
         Self::default()
     }
 
-    /// Set the if_not_exists flag for the operation.
+    /// Set whether the rename should fail when the destination already exists.
+    ///
+    /// If `true`, the rename succeeds only when the destination does not exist.
+    /// If `false`, the rename uses OpenDAL's default overwrite behavior.
+    ///
+    /// ## Service Implementation
+    ///
+    /// Check [`crate::Capability::rename_with_if_not_exists`] before setting this to
+    /// `true`. A service might return `ErrorKind::Unsupported` if it cannot
+    /// enforce the condition.
     pub fn with_if_not_exists(mut self, if_not_exists: bool) -> Self {
         self.if_not_exists = if_not_exists;
         self
     }
 
-    /// Get if_not_exists flag.
+    /// Return whether the rename should fail when the destination already exists.
     pub fn if_not_exists(&self) -> bool {
         self.if_not_exists
     }

data/core/core/src/raw/std_io_util.rs

@@ -58,8 +58,40 @@ pub(crate) fn format_std_io_error(err: Error) -> io::Error {
     let kind = match err.kind() {
         ErrorKind::NotFound => io::ErrorKind::NotFound,
         ErrorKind::PermissionDenied => io::ErrorKind::PermissionDenied,
-        _ => io::ErrorKind::Interrupted,
+        _ => io::ErrorKind::Other,
     };
 
     io::Error::new(kind, err)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_read_to_end_stops_on_persistent_error() {
+        struct ErrorThenEof {
+            calls: usize,
+        }
+
+        impl io::Read for ErrorThenEof {
+            fn read(&mut self, _: &mut [u8]) -> io::Result<usize> {
+                self.calls += 1;
+                if self.calls == 1 {
+                    return Err(format_std_io_error(
+                        Error::new(ErrorKind::Unexpected, "retry exhausted").set_persistent(),
+                    ));
+                }
+                Ok(0)
+            }
+        }
+
+        let mut reader = ErrorThenEof { calls: 0 };
+        let mut buf = Vec::new();
+        assert!(
+            io::Read::read_to_end(&mut reader, &mut buf).is_err(),
+            "calls: {}",
+            reader.calls
+        );
+    }
+}

data/core/core/src/services/memory/backend.rs

@@ -79,7 +79,6 @@ impl MemoryBackend {
             stat: true,
             list: true,
             list_with_recursive: true,
-            shared: false,
             ..Default::default()
         };
 

data/core/core/src/services/memory/mod.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-/// Default scheme for memory service.
+/// URI scheme used for memory service registration and URI construction.
 pub const MEMORY_SCHEME: &str = "memory";
 
 mod backend;
@@ -28,7 +28,11 @@ mod writer;
 pub use backend::MemoryBuilder as Memory;
 pub use config::MemoryConfig;
 
-/// Register this service into the given registry.
+/// Register the memory URI scheme with an operator registry.
+///
+/// Registration enables scheme-driven construction through
+/// [`crate::Operator::from_uri`] and [`crate::Operator::via_iter`]. Direct
+/// construction through [`crate::Operator::new`] does not require registration.
 pub fn register_memory_service(registry: &crate::OperatorRegistry) {
     registry.register::<Memory>(MEMORY_SCHEME);
 }

data/core/core/src/services/mod.rs

@@ -15,9 +15,15 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Services will provide builders to build underlying backends.
+//! Built-in service support.
 //!
-//! More ongoing services support is tracked at [opendal#5](https://github.com/apache/opendal/issues/5). Please feel free to submit issues if there are services not covered.
+//! [`Memory`] is the only storage service implemented by `opendal-core`
+//! directly. Other services live in `opendal-service-*` crates and are
+//! re-exported by the `opendal` facade behind `services-*` Cargo features.
+//!
+//! Pass a builder directly to [`crate::Operator::new`]. Service registration is
+//! only required for scheme-driven construction through
+//! [`crate::Operator::from_uri`] or [`crate::Operator::via_iter`].
 
 mod memory;
 pub use self::memory::*;

data/core/core/src/types/buffer.rs

@@ -44,14 +44,14 @@ use crate::*;
 
 /// Buffer is a wrapper of contiguous `Bytes` and non-contiguous `[Bytes]`.
 ///
-/// We designed buffer to allow underlying storage to return non-contiguous bytes. For example,
-/// http based storage like s3 could generate non-contiguous bytes by stream.
+/// Buffer supports non-contiguous bytes that a storage service returns. For example,
+/// HTTP-based services such as S3 can produce non-contiguous bytes while streaming.
 ///
 /// ## Features
 ///
 /// - [`Buffer`] can be used as [`Buf`], [`Iterator`], [`Stream`] directly.
 /// - [`Buffer`] is cheap to clone like [`Bytes`], only update reference count, no allocation.
-/// - [`Buffer`] is vectorized write friendly, you can convert it to [`IoSlice`] for vectored write.
+/// - Convert [`Buffer`] to [`IoSlice`] for vectored writes.
 ///
 /// ## Examples
 ///
@@ -246,7 +246,7 @@ impl Buffer {
 
     /// Returns a slice of self for the provided range.
     ///
-    /// This will increment the reference count for the underlying memory and return a new Buffer handle set to the slice.
+    /// This increments the reference count for the underlying memory and returns a new Buffer handle for the slice.
     ///
     /// This operation is O(1).
     pub fn slice(&self, range: impl RangeBounds<usize>) -> Self {

data/core/core/src/types/builder.rs

@@ -24,23 +24,22 @@ use crate::raw::*;
 use crate::types::OperatorUri;
 use crate::*;
 
-/// Builder is used to set up underlying services.
+/// OpenDAL uses `Builder` to set up a service.
 ///
-/// This trait allows the developer to define a builder struct that can:
+/// A `Builder` allows developers to:
 ///
-/// - build a service via builder style API.
-/// - configure in-memory options like `customized_credential_load`.
+/// - Build a service through a builder-style API.
+/// - Configure in-memory options, such as `customized_credential_load`.
 ///
-/// Usually, users don't need to use or import this trait directly, they can use `Operator` API instead.
-///
-/// For example:
+/// Users can usually use the [`Operator`] API instead of importing and using
+/// `Builder` directly. For example:
 ///
 /// ```
 /// # use anyhow::Result;
 /// use opendal_core::services::Memory;
 /// use opendal_core::Operator;
 /// async fn test() -> Result<()> {
-///     // Create memory backend builder.
+///     // Create a memory backend builder.
 ///     let builder = Memory::default();
 ///
 ///     // Build an `Operator` to start operating the storage.
@@ -50,7 +49,7 @@ use crate::*;
 /// }
 /// ```
 pub trait Builder: Default + 'static {
-    /// Associated configuration for this builder.
+    /// Associated configuration.
     type Config: Configurator;
 
     /// Consume the builder to build a service.
@@ -66,16 +65,15 @@ impl Builder for () {
     }
 }
 
-/// Configurator is used to configure the underlying service.
+/// OpenDAL uses `Configurator` to configure a service.
 ///
 /// This trait allows the developer to define a configuration struct that can:
 ///
-/// - deserialize from an iterator like hashmap or vector.
-/// - convert into a service builder and finally build the underlying services.
-///
-/// Usually, users don't need to use or import this trait directly, they can use `Operator` API instead.
+/// - Deserialize from an iterator such as a hash map or vector.
+/// - Convert into a service builder and then build a concrete service.
 ///
-/// For example:
+/// Users can usually use the [`Operator`] API instead of importing and using
+/// `Configurator` directly. For example:
 ///
 /// ```
 /// # use anyhow::Result;
@@ -97,14 +95,14 @@ pub trait Configurator: Serialize + DeserializeOwned + Debug + 'static {
     /// Associated builder for this configuration.
     type Builder: Builder;
 
-    /// Build configuration from a parsed URI plus merged options.
+    /// Build configuration from a parsed URI with merged options.
     fn from_uri(_uri: &OperatorUri) -> Result<Self> {
         Err(Error::new(ErrorKind::Unsupported, "uri is not supported"))
     }
 
     /// Deserialize from an iterator.
     ///
-    /// This API is provided by opendal, developer should not implement it.
+    /// OpenDAL provides this method; service developers should not need to override it.
     fn from_iter(iter: impl IntoIterator<Item = (String, String)>) -> Result<Self> {
         let cfg = ConfigDeserializer::new(iter.into_iter().collect());
 

data/core/core/src/types/copy.rs

@@ -26,9 +26,9 @@ use futures::Stream;
 use crate::raw::*;
 use crate::*;
 
-/// Copier is designed to drive long-running copy operations.
+/// `Copier` drives a long-running copy operation one step at a time.
 ///
-/// - Copier implements `Stream<Item = Result<usize>>`.
+/// - `Copier` implements `Stream<Item = Result<usize>>`.
 /// - `Some(Ok(n))` means the copy operation made progress by `n` bytes.
 /// - `None` means the copy operation has completed.
 pub struct Copier {
@@ -74,7 +74,7 @@ impl Copier {
         })
     }
 
-    /// Drive the copy operation forward.
+    /// Advance the copy operation by one step.
     pub async fn next(&mut self) -> Result<Option<usize>> {
         if self.errored {
             return Ok(None);

data/core/core/src/types/entry.rs

@@ -18,7 +18,9 @@
 use crate::raw::*;
 use crate::*;
 
-/// Entry returned by [`Lister`] or [`BlockingLister`] to represent a path and it's relative metadata.
+/// `Entry` represents an entry's path and metadata.
+///
+/// [`Lister`] and [`crate::blocking::Lister`] return `Entry` values.
 #[derive(Clone, Debug)]
 pub struct Entry {
     /// Path of this entry.