opendal 0.1.8 → 0.1.9

data/core/core/src/types/error.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Errors that returned by OpenDAL
+//! OpenDAL error types.
 //!
 //! # Examples
 //!
@@ -42,10 +42,10 @@ use std::fmt::Display;
 use std::fmt::Formatter;
 use std::io;
 
-/// Result that is a wrapper of `Result<T, opendal::Error>`
+/// A specialized [`std::result::Result`] whose default error type is [`Error`].
 pub type Result<T, E = Error> = std::result::Result<T, E>;
 
-/// ErrorKind is all kinds of Error of opendal.
+/// OpenDAL error categories.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[non_exhaustive]
 pub enum ErrorKind {
@@ -55,7 +55,7 @@ pub enum ErrorKind {
     /// Underlying service doesn't support this operation.
     Unsupported,
 
-    /// The config for backend is invalid.
+    /// The config for this service is invalid.
     ConfigInvalid,
     /// The given path is not found.
     NotFound,
@@ -130,21 +130,26 @@ impl From<ErrorKind> for &'static str {
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 enum ErrorStatus {
-    /// Permanent means without external changes, the error never changes.
+    /// The error is stable and will not change without external changes.
     ///
-    /// For example, underlying services returns a not found error.
+    /// For example, a service returns a not found error.
     ///
     /// Users MUST never retry this operation.
     Permanent,
-    /// Temporary means this error is returned for temporary.
+
+    /// The error is temporary.
+    ///
+    /// For example:
     ///
-    /// For example, underlying services is rate limited or unavailable for temporary.
+    /// - A service rate-limits a request.
+    /// - A service is temporarily unavailable.
     ///
-    /// Users CAN retry the operation to resolve it.
+    /// Users MAY retry an operation to resolve this error.
     Temporary,
-    /// Persistent means this error used to be temporary but still failed after retry.
+
+    /// The error was temporary but persisted after retries.
     ///
-    /// For example, underlying services kept returning network errors.
+    /// For example, a service kept returning network errors.
     ///
     /// Users SHOULD NOT retry this operation, since it's highly possible to error again.
     Persistent,

data/core/core/src/types/execute/executors/mod.rs

@@ -17,9 +17,9 @@
 
 //! executors module provides implementations for the [`Execute`](crate::Execute) trait for widely used runtimes.
 //!
-//! Every executor will be hide behind the feature like `executors-xxx`. Users can switch or enable
-//! the executors they want by enabling the corresponding feature. Also, users can provide their
-//! own executor by implementing the [`Execute`](crate::Execute) trait directly.
+//! OpenDAL provides executor integrations through features such as `executors-xxx`.
+//! Enable the corresponding feature to select an executor. You can also provide
+//! your own executor by implementing the [`Execute`](crate::Execute) trait.
 
 #[cfg(feature = "executors-tokio")]
 mod tokio_executor;

data/core/core/src/types/http_transport/mod.rs

@@ -96,6 +96,12 @@ impl HttpTransporter {
     /// Install the process-wide default HTTP transport.
     ///
     /// The first installed transport wins. Later calls are ignored.
+    ///
+    /// The `opendal` facade calls this before `main` when
+    /// `auto-register-services` and a default HTTP transport feature are enabled.
+    /// Applications that need to install their own process-wide default should
+    /// disable `auto-register-services`. This does not affect transports
+    /// configured directly on an operator.
     pub fn install_default(transport: impl HttpTransport) {
         let _ = DEFAULT_HTTP_TRANSPORTER.set(Self::new(transport));
     }

data/core/core/src/types/list.rs

@@ -25,11 +25,10 @@ use futures::Stream;
 use crate::raw::*;
 use crate::*;
 
-/// Lister is designed to list entries at given path in an asynchronous
-/// manner.
+/// `Lister` lists entries at a given path asynchronously.
 ///
-/// - Lister implements `Stream<Item = Result<Entry>>`.
-/// - Lister will return `None` if there is no more entries or error has been returned.
+/// - `Lister` implements `Stream<Item = Result<Entry>>`.
+/// - `Lister` returns `None` after it yields all entries or encounters an error.
 pub struct Lister {
     lister: Option<oio::Lister>,
 
@@ -39,7 +38,7 @@ pub struct Lister {
 
 /// # Safety
 ///
-/// Lister will only be accessed by `&mut Self`
+/// All access to `Lister`'s internal state requires `&mut self`.
 unsafe impl Sync for Lister {}
 
 impl Lister {
@@ -65,7 +64,7 @@ impl Stream for Lister {
     type Item = Result<Entry>;
 
     fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
-        // Returns `None` if we have errored.
+        // Returns `None` if we encountered an error.
         if self.errored {
             return Poll::Ready(None);
         }

data/core/core/src/types/operator/info.rs

@@ -30,17 +30,19 @@ impl OperatorInfo {
         Self { info, capability }
     }
 
-    /// Scheme of operator.
+    /// Return the operator's scheme.
     pub fn scheme(&self) -> &'static str {
         self.info.scheme()
     }
 
-    /// Root of operator, will be in format like `/path/to/dir/`.
+    /// Return the operator's root in a format like `/path/to/dir/`.
     pub fn root(&self) -> String {
         self.info.root().to_string()
     }
 
-    /// Name of backend, could be empty if underlying backend doesn't have namespace concept.
+    /// Return the operator's name.
+    ///
+    /// The name can be empty if the service has no namespace concept.
     ///
     /// For example:
     ///
@@ -50,7 +52,7 @@ impl OperatorInfo {
         self.info.name().to_string()
     }
 
-    /// Get effective capability of operator.
+    /// Return the operator's effective capabilities.
     pub fn capability(&self) -> Capability {
         self.capability
     }

data/core/core/src/types/operator/mod.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Operator's API will be split into different mods.
+//! This module organizes the `Operator` API into several submodules.
 
 #[allow(clippy::module_inception)]
 mod operator;

data/core/core/src/types/operator/operator.rs

@@ -32,9 +32,37 @@ use crate::*;
 /// For more details about the `Operator`, refer to the concepts section in the
 /// crate documentation.
 ///
-/// `Operator` is immutable: methods that change layers, HTTP transport, or
+/// ## Immutability
+///
+/// `Operator` is immutable: methods that change layers, the HTTP transport, or the
 /// executor return a new operator. Existing clones and in-flight operations keep
-/// using the service stack and operation context they already hold.
+/// using the service stack and operation context they already hold. For example,
+/// a lister created before the operator is changed continues to use the previous
+/// configuration.
+///
+/// ### Example
+///
+/// ```
+/// use futures::TryStreamExt;
+/// use opendal_core::services::Memory;
+/// use opendal_core::{OperationContext, Operator, Result};
+///
+/// async fn example() -> Result<()> {
+///     let op = Operator::new(Memory::default())?;
+///     let mut lister = op.lister("/").await?;
+///
+///     // Replacing the context returns a new operator.
+///     let new_op = op.with_context(OperationContext::new());
+///     let _ = new_op.list("/").await?;
+///
+///     // The existing lister still uses the context it captured from `op`.
+///     while let Some(entry) = lister.try_next().await? {
+///         println!("{}", entry.path());
+///     }
+///
+///     Ok(())
+/// }
+/// ```
 ///
 /// Internally, an operator keeps base providers and composed dispatch state:
 ///
@@ -106,7 +134,8 @@ use crate::*;
 ///
 /// ## Operate
 ///
-/// After the operator is built and the layers are added, users can start operating the storage.
+/// After building an operator with the desired configuration and layers, users
+/// can start operating on storage.
 ///
 /// The operator is `Send`, `Sync`, and `Clone`. It holds immutable handles, and
 /// storage operation APIs only take a `&self` reference, making it safe to share
@@ -789,7 +818,8 @@ impl Operator {
     ///
     /// # Notes
     ///
-    /// Visit [`performance::concurrent_write`][crate::docs::performance::concurrent_write] for more details on concurrent writes.
+    /// Read the [concurrent write guide](https://github.com/apache/opendal/blob/main/core/core/src/docs/performance/concurrent_write.md)
+    /// for more details.
     ///
     /// ## Extra Options
     ///
@@ -830,7 +860,8 @@ impl Operator {
     ///
     /// # Notes
     ///
-    /// Visit [`performance::concurrent_write`][crate::docs::performance::concurrent_write] for more details on concurrent writes.
+    /// Read the [concurrent write guide](https://github.com/apache/opendal/blob/main/core/core/src/docs/performance/concurrent_write.md)
+    /// for more details.
     ///
     /// ## Streaming Write
     ///
@@ -885,7 +916,8 @@ impl Operator {
     ///
     /// # Notes
     ///
-    /// Visit [`performance::concurrent_write`][crate::docs::performance::concurrent_write] for more details on concurrent writes.
+    /// Read the [concurrent write guide](https://github.com/apache/opendal/blob/main/core/core/src/docs/performance/concurrent_write.md)
+    /// for more details.
     ///
     /// ## Streaming Write
     ///
@@ -1015,7 +1047,8 @@ impl Operator {
     /// [Capability](crate::types::Capability). However, you can override this by explicitly
     /// setting the `chunk` parameter.
     ///
-    /// Visit [`performance::concurrent_write`][crate::docs::performance::concurrent_write] for more details on concurrent writes.
+    /// Read the [concurrent write guide](https://github.com/apache/opendal/blob/main/core/core/src/docs/performance/concurrent_write.md)
+    /// for more details.
     ///
     /// # Examples
     ///
@@ -1069,7 +1102,8 @@ impl Operator {
     /// [Capability](crate::types::Capability). However, you can override this by explicitly
     /// setting the `chunk` parameter.
     ///
-    /// Visit [`performance::concurrent_write`][crate::docs::performance::concurrent_write] for more details on concurrent writes.
+    /// Read the [concurrent write guide](https://github.com/apache/opendal/blob/main/core/core/src/docs/performance/concurrent_write.md)
+    /// for more details.
     ///
     /// # Examples
     ///

data/core/core/src/types/operator/operator_futures.rs

@@ -26,14 +26,13 @@ use crate::raw::*;
 use crate::*;
 use futures::Future;
 
-/// OperatorFuture is the future generated by [`Operator`].
+/// [`Operator`] produces this future.
 ///
-/// The future will consume all the input to generate a future.
+/// The future consumes its inputs when it begins executing.
 ///
 /// # NOTES
 ///
-/// This struct is by design to keep in crate. We don't want
-/// users to use this struct directly.
+/// OpenDAL uses this type as an implementation detail. Users should not use it directly.
 pub struct OperatorFuture<I, O, F: Future<Output = Result<O>>> {
     /// The composed context used to execute operations.
     ctx: OperationContext,
@@ -50,8 +49,7 @@ pub struct OperatorFuture<I, O, F: Future<Output = Result<O>>> {
 impl<I, O, F: Future<Output = Result<O>>> OperatorFuture<I, O, F> {
     /// # NOTES
     ///
-    /// This struct is by design to keep in crate. We don't want
-    /// users to use this struct directly.
+    /// OpenDAL uses this type as an implementation detail. Users should not use it directly.
     pub(crate) fn new(
         ctx: OperationContext,
         srv: Servicer,
@@ -81,9 +79,9 @@ where
     }
 }
 
-/// Future that generated by [`Operator::stat_with`].
+/// [`Operator::stat_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureStat<F> = OperatorFuture<options::StatOptions, Metadata, F>;
 
 impl<F: Future<Output = Result<Metadata>>> FutureStat<F> {
@@ -128,9 +126,9 @@ impl<F: Future<Output = Result<Metadata>>> FutureStat<F> {
     }
 }
 
-/// Future that generated by [`Operator::presign_stat_with`].
+/// [`Operator::presign_stat_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FuturePresignStat<F> =
     OperatorFuture<(options::StatOptions, Duration), PresignedRequest, F>;
 
@@ -166,17 +164,17 @@ impl<F: Future<Output = Result<PresignedRequest>>> FuturePresignStat<F> {
     }
 }
 
-/// Future that generated by [`Operator::presign_delete_with`].
+/// [`Operator::presign_delete_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FuturePresignDelete<F> =
     OperatorFuture<(options::DeleteOptions, Duration), PresignedRequest, F>;
 
 impl<F: Future<Output = Result<PresignedRequest>>> FuturePresignDelete<F> {}
 
-/// Future that generated by [`Operator::presign_read_with`].
+/// [`Operator::presign_read_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FuturePresignRead<F> =
     OperatorFuture<(options::ReadOptions, Duration), PresignedRequest, F>;
 
@@ -212,9 +210,9 @@ impl<F: Future<Output = Result<PresignedRequest>>> FuturePresignRead<F> {
     }
 }
 
-/// Future that generated by [`Operator::presign_write_with`].
+/// [`Operator::presign_write_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FuturePresignWrite<F> =
     OperatorFuture<(options::WriteOptions, Duration), PresignedRequest, F>;
 
@@ -244,9 +242,9 @@ impl<F: Future<Output = Result<PresignedRequest>>> FuturePresignWrite<F> {
     }
 }
 
-/// Future that generated by [`Operator::read_with`].
+/// [`Operator::read_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureRead<F> = OperatorFuture<options::ReadOptions, Buffer, F>;
 
 impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
@@ -428,9 +426,9 @@ impl<F: Future<Output = Result<Buffer>>> FutureRead<F> {
     }
 }
 
-/// Future that generated by [`Operator::read_with`] or [`Operator::reader_with`].
+/// [`Operator::read_with`] and [`Operator::reader_with`] return this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 ///
 /// # Notes
 ///
@@ -628,9 +626,9 @@ impl<F: Future<Output = Result<Reader>>> FutureReader<F> {
     }
 }
 
-/// Future that generated by [`Operator::write_with`].
+/// [`Operator::write_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureWrite<F> = OperatorFuture<(options::WriteOptions, Buffer), Metadata, F>;
 
 impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
@@ -927,9 +925,9 @@ impl<F: Future<Output = Result<Metadata>>> FutureWrite<F> {
     }
 }
 
-/// Future that generated by [`Operator::writer_with`].
+/// [`Operator::writer_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureWriter<F> = OperatorFuture<options::WriteOptions, Writer, F>;
 
 impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
@@ -1266,9 +1264,9 @@ impl<F: Future<Output = Result<Writer>>> FutureWriter<F> {
     }
 }
 
-/// Future that generated by [`Operator::delete_with`].
+/// [`Operator::delete_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureDelete<F> = OperatorFuture<options::DeleteOptions, (), F>;
 
 impl<F: Future<Output = Result<()>>> FutureDelete<F> {
@@ -1285,14 +1283,14 @@ impl<F: Future<Output = Result<()>>> FutureDelete<F> {
     }
 }
 
-/// Future that generated by [`Operator::deleter_with`].
+/// This future creates a [`Deleter`].
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureDeleter<F> = OperatorFuture<OpDeleter, (), F>;
 
-/// Future that generated by [`Operator::list_with`] or [`Operator::lister_with`].
+/// [`Operator::list_with`] and [`Operator::lister_with`] return this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureList<F> = OperatorFuture<options::ListOptions, Vec<Entry>, F>;
 
 impl<F: Future<Output = Result<Vec<Entry>>>> FutureList<F> {
@@ -1351,9 +1349,9 @@ impl<F: Future<Output = Result<Vec<Entry>>>> FutureList<F> {
     }
 }
 
-/// Future that generated by [`Operator::list_with`] or [`Operator::lister_with`].
+/// [`Operator::list_with`] and [`Operator::lister_with`] return this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureLister<F> = OperatorFuture<options::ListOptions, Lister, F>;
 
 impl<F: Future<Output = Result<Lister>>> FutureLister<F> {
@@ -1412,9 +1410,9 @@ impl<F: Future<Output = Result<Lister>>> FutureLister<F> {
     }
 }
 
-/// Future that generated by [`Operator::copy_with`].
+/// [`Operator::copy_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureCopy<F> = OperatorFuture<(options::CopyOptions, String), Metadata, F>;
 
 impl<F: Future<Output = Result<Metadata>>> FutureCopy<F> {
@@ -1483,9 +1481,9 @@ impl<F: Future<Output = Result<Metadata>>> FutureCopy<F> {
     }
 }
 
-/// Future that generated by [`Operator::copier_with`].
+/// [`Operator::copier_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureCopier<F> = OperatorFuture<(options::CopyOptions, String), Copier, F>;
 
 impl<F: Future<Output = Result<Copier>>> FutureCopier<F> {
@@ -1539,9 +1537,9 @@ impl<F: Future<Output = Result<Copier>>> FutureCopier<F> {
     }
 }
 
-/// Future that generated by [`Operator::rename_with`].
+/// [`Operator::rename_with`] returns this future.
 ///
-/// Users can add more options by public functions provided by this struct.
+/// Use its methods to configure the operation before awaiting it.
 pub type FutureRename<F> = OperatorFuture<(options::RenameOptions, String), (), F>;
 
 impl<F: Future<Output = Result<()>>> FutureRename<F> {

data/core/core/src/types/operator/registry.rs

@@ -18,7 +18,7 @@
 use crate::types::builder::{Builder, Configurator};
 use crate::types::{IntoOperatorUri, OperatorUri};
 use crate::{Error, ErrorKind, Operator, Result};
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 use std::sync::{LazyLock, Mutex};
 
 /// Factory signature used to construct [`Operator`] from a URI and extra options.
@@ -35,10 +35,11 @@ impl OperatorRegistry {
     pub fn get() -> &'static Self {
         /// The global registry used by [`Operator::from_uri`].
         ///
-        /// `memory` is always registered here since it's used pervasively in unit tests
-        /// and as a zero-dependency backend.
+        /// OpenDAL always registers the `memory` service because OpenDAL uses it
+        /// extensively in unit tests and it has no dependencies.
         ///
-        /// Other optional service registrations are handled by the facade crate `opendal`.
+        /// The `opendal` facade crate registers other optional services. See
+        /// `core/src/lib.rs` in the facade crate for details.
         static OPERATOR_REGISTRY: LazyLock<OperatorRegistry> = LazyLock::new(|| {
             let factories = Mutex::new(HashMap::default());
             let registry = OperatorRegistry { factories };
@@ -59,21 +60,53 @@ impl OperatorRegistry {
         guard.insert(key, factory::<B::Config>);
     }
 
+    /// Return the set of schemes currently registered.
+    ///
+    /// For the global registry returned by [`OperatorRegistry::get`], this is
+    /// exactly the set of schemes that [`Operator::from_uri`] can construct, as
+    /// determined by the compiled-in `services-*` features.
+    ///
+    /// ```
+    /// use opendal_core::OperatorRegistry;
+    ///
+    /// let schemes = OperatorRegistry::get().schemes();
+    /// assert!(schemes.contains("memory"));
+    /// ```
+    pub fn schemes(&self) -> HashSet<String> {
+        self.factories
+            .lock()
+            .expect("operator registry mutex poisoned")
+            .keys()
+            .cloned()
+            .collect()
+    }
+
     /// Load an [`Operator`] via the factory registered for the URI's scheme.
     pub fn load(&self, uri: impl IntoOperatorUri) -> Result<Operator> {
         let parsed = uri.into_operator_uri()?;
         let scheme = parsed.scheme();
 
-        let factory = self
-            .factories
-            .lock()
-            .expect("operator registry mutex poisoned")
-            .get(scheme)
-            .copied()
-            .ok_or_else(|| {
-                Error::new(ErrorKind::Unsupported, "scheme is not registered")
-                    .with_context("scheme", scheme.to_string())
-            })?;
+        let factory = {
+            let guard = self
+                .factories
+                .lock()
+                .expect("operator registry mutex poisoned");
+
+            match guard.get(scheme).copied() {
+                Some(factory) => factory,
+                None => {
+                    // Collect the available schemes from the guard we already hold
+                    // to avoid re-locking the mutex (which would self-deadlock).
+                    let mut available: Vec<String> = guard.keys().cloned().collect();
+                    available.sort();
+                    return Err(
+                        Error::new(ErrorKind::Unsupported, "scheme is not registered")
+                            .with_context("scheme", scheme.to_string())
+                            .with_context("available", available.join(", ")),
+                    );
+                }
+            }
+        };
 
         factory(&parsed)
     }
@@ -84,3 +117,29 @@ fn factory<C: Configurator>(uri: &OperatorUri) -> Result<Operator> {
     let cfg = C::from_uri(uri)?;
     Operator::from_config(cfg)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn global_registry_exposes_memory_scheme() {
+        let schemes = OperatorRegistry::get().schemes();
+        assert!(schemes.contains("memory"));
+    }
+
+    #[test]
+    fn unregistered_scheme_error_lists_available_schemes() {
+        let err = OperatorRegistry::get()
+            .load("no-such-scheme://bucket/path")
+            .unwrap_err();
+
+        assert_eq!(err.kind(), ErrorKind::Unsupported);
+
+        let msg = err.to_string();
+        assert!(msg.contains("scheme is not registered"));
+        assert!(msg.contains("no-such-scheme"));
+        assert!(msg.contains("available"));
+        assert!(msg.contains("memory"));
+    }
+}