opendal 0.1.8 → 0.1.9

data/core/http-transports/reqwest/README.md

@@ -60,18 +60,46 @@ Most users depend on the `opendal` facade crate:
 ```toml
 [dependencies]
 # Default: reqwest transport with rustls.
-opendal = { version = "0.57" }
+opendal = { version = "0.58" }
 ```
 
 To select one transport TLS feature explicitly, disable default features:
 
 ```toml
 [dependencies]
-opendal = { version = "0.57", default-features = false, features = [
+opendal = { version = "0.58", default-features = false, features = [
     "http-transport-reqwest-rustls",
 ] }
 ```
 
+## Use with `opendal-core`
+
+Applications that use the split crates can attach reqwest to an operator
+without installing a process-wide default transport:
+
+```shell
+cargo add opendal-core opendal-http-transport-reqwest
+```
+
+```rust
+use opendal_core::Builder;
+use opendal_core::HttpTransporter;
+use opendal_core::OperationContext;
+use opendal_core::Operator;
+use opendal_core::Result;
+use opendal_http_transport_reqwest::ReqwestTransport;
+
+fn build_operator<B: Builder>(builder: B) -> Result<Operator> {
+    let transport = HttpTransporter::new(ReqwestTransport::default());
+    let context = OperationContext::new().with_http_transport(transport);
+
+    Ok(Operator::new(builder)?.with_context(context))
+}
+```
+
+Pass a configured service builder to `build_operator`. The resulting operator
+uses this reqwest transport for HTTP-backed services.
+
 ## Build different TLS backends
 
 ### Rustls
@@ -80,7 +108,7 @@ Use reqwest's Rustls backend explicitly when you build the client:
 
 ```toml
 [dependencies]
-opendal = { version = "0.57", default-features = false, features = [
+opendal = { version = "0.58", default-features = false, features = [
     "http-transport-reqwest-rustls",
 ] }
 reqwest = { version = "0.13.4", default-features = false, features = [
@@ -89,7 +117,7 @@ reqwest = { version = "0.13.4", default-features = false, features = [
 ] }
 ```
 
-```rust
+```rust,ignore
 use std::time::Duration;
 
 use opendal::HttpTransporter;
@@ -111,7 +139,7 @@ Use `native-tls` when you want reqwest to delegate TLS to the platform stack:
 
 ```toml
 [dependencies]
-opendal = { version = "0.57", default-features = false, features = [
+opendal = { version = "0.58", default-features = false, features = [
     "http-transport-reqwest-native-tls",
 ] }
 reqwest = { version = "0.13.4", default-features = false, features = [
@@ -120,7 +148,7 @@ reqwest = { version = "0.13.4", default-features = false, features = [
 ] }
 ```
 
-```rust
+```rust,ignore
 use opendal::HttpTransporter;
 use opendal::ReqwestTransport;
 
@@ -144,7 +172,7 @@ startup.
 
 ```toml
 [dependencies]
-opendal = { version = "0.57", default-features = false, features = [
+opendal = { version = "0.58", default-features = false, features = [
     "http-transport-reqwest-rustls-no-provider",
 ] }
 reqwest = { version = "0.13.4", default-features = false, features = [
@@ -155,7 +183,7 @@ rustls = { version = "0.23", default-features = false, features = ["std"] }
 webpki-roots = "1"
 ```
 
-```rust
+```rust,ignore
 use opendal::HttpTransporter;
 use opendal::ReqwestTransport;
 
@@ -191,6 +219,6 @@ for the target-specific limitations.
 
 ## License and Trademarks
 
-Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
+Licensed under the Apache License, Version 2.0: <http://www.apache.org/licenses/LICENSE-2.0>
 
 Apache OpenDAL, OpenDAL, and Apache are either registered trademarks or trademarks of the Apache Software Foundation.

data/core/http-transports/reqwest/src/lib.rs

@@ -15,55 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Reqwest based HTTP transport for Apache OpenDAL.
-//!
-//! # TLS backends
-//!
-//! Enable one of the following Cargo features to compile reqwest TLS support.
-//! The `default` feature enables `rustls`.
-//!
-//! - **`native-tls`** — Platform TLS links against the OS TLS library:
-//!    - Windows: SChannel
-//!    - macOS: Secure Transport
-//!    - Linux: OpenSSL, requires system development packages
-//!
-//! - **`rustls`** — [Rustls](https://crates.io/crates/rustls) configured by
-//!   reqwest with its default crypto provider and platform certificate
-//!   verification. Pure-Rust TLS stack, no system TLS dependency.
-//!
-//! - **`rustls-no-provider`** — Rustls without a built-in crypto provider.
-//!   You must install a [`rustls::crypto::CryptoProvider`] before building a
-//!   client. Use this when you want to bring your own provider
-//!   (e.g., a FIPS-certified module).
-//!
-//! In application or language binding builds, prefer selecting a single backend
-//! feature. In workspace or `--all-features` builds, Cargo may enable multiple
-//! backend features via feature unification; build a [`reqwest::Client`] with
-//! reqwest's TLS configuration methods and pass it to [`ReqwestTransport::new`]
-//! to force the backend you want.
-//!
-//! On wasm targets, reqwest uses the Fetch API instead of hyper. TLS is provided
-//! by the host environment, so native TLS backend features do not select a TLS
-//! stack there.
-//!
-//! # Custom reqwest client
-//!
-//! ```
-//! use std::time::Duration;
-//!
-//! use opendal_core::HttpTransporter;
-//! use opendal_http_transport_reqwest::ReqwestTransport;
-//!
-//! # fn build() -> Result<(), Box<dyn std::error::Error>> {
-//! let client = reqwest::Client::builder()
-//!     .tls_backend_rustls()
-//!     .connect_timeout(Duration::from_secs(10))
-//!     .build()?;
-//! let transport = ReqwestTransport::new(client);
-//! let _transport = HttpTransporter::new(transport);
-//! # Ok(())
-//! # }
-//! ```
+#![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, doc(auto_cfg))]
+#![deny(missing_docs)]
 
 use std::fmt::{Debug, Formatter};
 use std::future;
@@ -78,11 +33,13 @@ use opendal_core::Error;
 use opendal_core::ErrorKind;
 use opendal_core::HttpBody;
 use opendal_core::HttpTransport;
+use opendal_core::HttpTransporter;
 use opendal_core::Result;
 use opendal_core::raw::parse_content_encoding;
 use opendal_core::raw::parse_content_length;
 
-static DEFAULT_REQWEST_CLIENT: LazyLock<reqwest::Client> = LazyLock::new(reqwest::Client::new);
+static DEFAULT_REQWEST_TRANSPORT: LazyLock<ReqwestTransport> =
+    LazyLock::new(|| ReqwestTransport::new(reqwest::Client::new()));
 
 /// A HTTP transport with [`reqwest::Client`].
 #[derive(Clone)]
@@ -98,7 +55,7 @@ impl Debug for ReqwestTransport {
 
 impl Default for ReqwestTransport {
     fn default() -> Self {
-        Self::new(DEFAULT_REQWEST_CLIENT.clone())
+        DEFAULT_REQWEST_TRANSPORT.clone()
     }
 }
 
@@ -206,6 +163,23 @@ impl HttpTransport for ReqwestTransport {
     }
 }
 
+/// Install the process-wide default reqwest transport.
+///
+/// The reqwest client is initialized when the transport handles its first
+/// request.
+#[doc(hidden)]
+pub fn install_default() {
+    HttpTransporter::install_default(LazyReqwestTransport);
+}
+
+struct LazyReqwestTransport;
+
+impl HttpTransport for LazyReqwestTransport {
+    async fn fetch(&self, req: Request<Buffer>) -> Result<Response<HttpBody>> {
+        DEFAULT_REQWEST_TRANSPORT.fetch(req).await
+    }
+}
+
 #[inline]
 fn is_temporary_error(err: &reqwest::Error) -> bool {
     // error sending request
@@ -247,6 +221,11 @@ impl http_body::Body for HttpBufferBody {
 mod tests {
     use super::*;
 
+    #[test]
+    fn test_install_default_is_lazy() {
+        install_default();
+    }
+
     #[cfg(any(feature = "rustls", feature = "native-tls"))]
     #[test]
     fn test_default_transport_succeeds() {

data/core/layers/async-backtrace/Cargo.toml

@@ -18,6 +18,7 @@
 [package]
 description = "Apache OpenDAL async-backtrace layer"
 name = "opendal-layer-async-backtrace"
+readme = "README.md"
 
 authors = { workspace = true }
 edition = { workspace = true }
@@ -32,7 +33,7 @@ all-features = true
 
 [dependencies]
 async-backtrace = "0.2.6"
-opendal-core = { path = "../../core", version = "0.58.0", default-features = false }
+opendal-core = { path = "../../core", version = "0.58.1", default-features = false }
 
 [dev-dependencies]
-opendal-core = { path = "../../core", version = "0.58.0" }
+opendal-core = { path = "../../core", version = "0.58.1" }

data/core/layers/async-backtrace/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed 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.

data/core/layers/async-backtrace/NOTICE

@@ -0,0 +1,5 @@
+Apache OpenDAL
+Copyright 2023-2026 The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).

data/core/layers/async-backtrace/README.md

@@ -0,0 +1,48 @@
+# Apache OpenDAL™ Async Backtrace Layer
+
+`opendal-layer-async-backtrace` records logical stack traces for asynchronous service
+operations with `async-backtrace`.
+
+## Use through `opendal`
+
+Applications should normally enable this layer through the `opendal` facade with the
+`layers-async-backtrace` feature:
+
+```shell
+cargo add opendal --features layers-async-backtrace
+```
+
+The layer is available as `opendal::layers::AsyncBacktraceLayer` and can be
+composed with an operator through `opendal::Operator::layer`.
+
+## Use with `opendal-core`
+
+Add the split crates directly:
+
+```shell
+cargo add opendal-core opendal-layer-async-backtrace
+```
+
+Pass a configured layer to `Operator::layer`:
+
+```rust
+use opendal_core::Operator;
+use opendal_layer_async_backtrace::AsyncBacktraceLayer;
+
+fn add_layer(operator: Operator, layer: AsyncBacktraceLayer) -> Operator {
+    operator.layer(layer)
+}
+```
+
+Construct and configure `layer` as described in the API documentation before
+composing it with an operator.
+
+## Documentation
+
+- [Rust API documentation](https://docs.rs/opendal-layer-async-backtrace)
+- [Apache OpenDAL production guide](https://opendal.apache.org/docs/core/production)
+- [Apache OpenDAL documentation](https://opendal.apache.org/docs/)
+
+## License
+
+Licensed under the Apache License, Version 2.0.

data/core/layers/async-backtrace/src/lib.rs

@@ -15,21 +15,21 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Async backtrace layer implementation for Apache OpenDAL.
-
+#![doc = include_str!("../README.md")]
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, doc(auto_cfg))]
 #![deny(missing_docs)]
-
 use std::sync::Arc;
 
 use opendal_core::raw::*;
 use opendal_core::*;
 
-/// Add Efficient, logical 'stack' traces of async functions for the underlying services.
+/// `AsyncBacktraceLayer` records efficient logical stack traces for asynchronous
+/// service operations.
 ///
 /// # Async Backtrace
 ///
-/// async-backtrace allows developers to get a stack trace of the async functions.
+/// `async-backtrace` lets developers inspect the stack traces of asynchronous functions.
 /// Read more about [async-backtrace](https://docs.rs/async-backtrace/latest/async_backtrace/)
 ///
 /// # Examples

data/core/layers/await-tree/Cargo.toml

@@ -18,6 +18,7 @@
 [package]
 description = "Apache OpenDAL await-tree layer"
 name = "opendal-layer-await-tree"
+readme = "README.md"
 
 authors = { workspace = true }
 edition = { workspace = true }
@@ -33,7 +34,7 @@ all-features = true
 [dependencies]
 await-tree = "0.3"
 futures = { workspace = true }
-opendal-core = { path = "../../core", version = "0.58.0", default-features = false }
+opendal-core = { path = "../../core", version = "0.58.1", default-features = false }
 
 [dev-dependencies]
-opendal-core = { path = "../../core", version = "0.58.0" }
+opendal-core = { path = "../../core", version = "0.58.1" }