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 2026/07/17 08:12:41 UTC
(opendal) branch main updated: docs: clarify default HTTP transport ownership (#7924)
This is an automated email from the ASF dual-hosted git repository.
Xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal.git
The following commit(s) were added to refs/heads/main by this push:
new fe971d79a docs: clarify default HTTP transport ownership (#7924)
fe971d79a is described below
commit fe971d79a086a282aa2b8fae3bd05ce416abb38f
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Fri Jul 17 16:12:36 2026 +0800
docs: clarify default HTTP transport ownership (#7924)
---
core/Cargo.toml | 4 +++-
core/core/src/docs/performance/http_optimization.md | 10 +++++++++-
core/core/src/docs/rfcs/7749_http_transporter.md | 14 +++++++++-----
core/core/src/types/http_transport/mod.rs | 6 ++++++
core/src/lib.rs | 12 ++++++++++++
5 files changed, 39 insertions(+), 7 deletions(-)
diff --git a/core/Cargo.toml b/core/Cargo.toml
index 23ce5d518..15fcaf3be 100644
--- a/core/Cargo.toml
+++ b/core/Cargo.toml
@@ -81,7 +81,9 @@ unused_async = "warn"
all-features = true
[features]
-# Register services enabled to the OperatorRegistry so that they can be used by `Operator::from_uri`.
+# Install facade defaults before `main`: register enabled services and, when
+# configured, install the default HTTP transport. Disable this feature when the
+# application needs to install its own process-wide HTTP transport.
auto-register-services = ["dep:ctor"]
blocking = ["opendal-core/blocking"]
default = [
diff --git a/core/core/src/docs/performance/http_optimization.md b/core/core/src/docs/performance/http_optimization.md
index 029f410d3..d3efd6301 100644
--- a/core/core/src/docs/performance/http_optimization.md
+++ b/core/core/src/docs/performance/http_optimization.md
@@ -1,6 +1,14 @@
# HTTP Optimization
-All OpenDAL HTTP-based storage services use the same [HttpTransporter][crate::HttpTransporter] abstraction. This design offers users a unified interface for configuring HTTP transports. The `opendal` facade installs [reqwest](https://crates.io/crates/reqwest) as the default HTTP transport when the `http-transport-reqwest` feature is enabled.
+All OpenDAL HTTP-based storage services use the same
+[HttpTransporter][crate::HttpTransporter] abstraction. This design offers users
+a unified interface for configuring HTTP transports. The `opendal` facade
+installs [reqwest](https://crates.io/crates/reqwest) as the default HTTP transport
+when `opendal::install_default()` is called with the `http-transport-reqwest`
+feature enabled. The default `auto-register-services` feature calls
+`install_default()` before `main`. Applications that need to install their own
+process-wide transport should disable `auto-register-services`; transports
+configured directly on an operator are unaffected.
Many of the services supported by OpenDAL are HTTP-based. This guide aims to provide optimization tips for using HTTP-based storage services. While these tips are also applicable to other HTTP clients, the configuration methods may vary.
diff --git a/core/core/src/docs/rfcs/7749_http_transporter.md b/core/core/src/docs/rfcs/7749_http_transporter.md
index a1663bc11..2fcfb73af 100644
--- a/core/core/src/docs/rfcs/7749_http_transporter.md
+++ b/core/core/src/docs/rfcs/7749_http_transporter.md
@@ -182,9 +182,12 @@ transport with `HttpTransporter::install_default(...)` or configure an operator
with `.http_transport(...)`.
`HttpTransporter::install_default` is first-wins, returns no error, and does not
-overwrite an already installed default. Users that need process-wide replacement
-must install before the facade default is installed; otherwise they should use
-operator-level `.http_transport(...)`.
+overwrite an already installed default. The facade installs its default before
+`main` when `auto-register-services` is enabled. Users that need process-wide
+replacement must disable `auto-register-services`, install their transport
+themselves, and call `init_default_registry()` explicitly when URI-based
+construction is needed. Otherwise, they should use operator-level
+`.http_transport(...)`.
The operator-registry-only public entry `init_default_registry()` remains for
compatibility. It does not install HTTP transport. The facade
@@ -207,8 +210,9 @@ published artifact. Release tooling must publish the transport crate before the
facade package that depends on it.
The process-wide default transport remains global state. The design keeps it
-minimal and first-wins, but users that need strict control must install their
-default before facade auto-installation or configure transports per operator.
+minimal and first-wins, but users that need strict control must disable facade
+auto-installation and own default initialization or configure transports per
+operator.
# Rationale and alternatives
diff --git a/core/core/src/types/http_transport/mod.rs b/core/core/src/types/http_transport/mod.rs
index 3ff6d846d..d97a57ed7 100644
--- a/core/core/src/types/http_transport/mod.rs
+++ b/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));
}
diff --git a/core/src/lib.rs b/core/src/lib.rs
index 2457fd2e1..177003c16 100644
--- a/core/src/lib.rs
+++ b/core/src/lib.rs
@@ -32,6 +32,18 @@ pub extern crate opendal_testkit as tests;
/// This function is safe to call multiple times. It registers enabled services
/// and installs the default HTTP transport when the corresponding feature is
/// enabled.
+///
+/// # Process-wide HTTP transport
+///
+/// When `auto-register-services` is enabled, a process constructor calls this
+/// function before `main`. If a default HTTP transport feature is also enabled,
+/// that transport occupies the process-wide default because
+/// [`HttpTransporter::install_default`] uses first-installed-wins semantics.
+///
+/// Applications that need to install their own process-wide transport should
+/// disable `auto-register-services`, call [`init_default_registry`] explicitly
+/// when URI-based construction is needed, and install the transport themselves.
+/// Per-operator transports can be configured regardless of this setting.
pub fn install_default() {
init_default_registry();