opendal/
lib.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18#![doc(html_logo_url = "https://opendal.apache.org/img/logo.svg")]
19#![doc = include_str!("../README.md")]
20#![cfg_attr(docsrs, feature(doc_cfg))]
21#![cfg_attr(docsrs, doc(auto_cfg))]
22#![deny(missing_docs)]
23
24pub use opendal_core::*;
25
26#[cfg(feature = "tests")]
27pub extern crate opendal_testkit as tests;
28
29/// Install the global defaults provided by the facade crate.
30///
31/// This function is safe to call multiple times. It registers enabled services
32/// and installs the default HTTP transport when the corresponding feature is
33/// enabled.
34///
35/// # Process-wide HTTP transport
36///
37/// When `auto-register-services` is enabled, a process constructor calls this
38/// function before `main`. If a default HTTP transport feature is also enabled,
39/// that transport occupies the process-wide default because
40/// [`HttpTransporter::install_default`] uses first-installed-wins semantics.
41///
42/// Applications that need to install their own process-wide transport should
43/// disable `auto-register-services`, call [`init_default_registry`] explicitly
44/// when URI-based construction is needed, and install the transport themselves.
45/// Per-operator transports can be configured regardless of this setting.
46pub fn install_default() {
47    init_default_registry();
48
49    #[cfg(any(
50        feature = "http-transport-reqwest",
51        feature = "http-transport-reqwest-native-tls",
52        feature = "http-transport-reqwest-rustls",
53        feature = "http-transport-reqwest-rustls-no-provider"
54    ))]
55    opendal_http_transport_reqwest::install_default();
56}
57
58/// Initialize the global [`OperatorRegistry`] with enabled services.
59///
60/// This function is safe to call multiple times and will only perform
61/// initialization once.
62///
63/// # Notes
64///
65/// Some bindings link `opendal` as a `staticlib`, where `#[ctor::ctor]`
66/// initializers may not be executed due to linker behavior. Those bindings
67/// should call this function explicitly before using `Operator::from_uri` or
68/// `Operator::via_iter`.
69pub fn init_default_registry() {
70    static DEFAULT_REGISTRY_INIT: std::sync::Once = std::sync::Once::new();
71    DEFAULT_REGISTRY_INIT.call_once(|| init_default_registry_inner(OperatorRegistry::get()));
72}
73
74fn init_default_registry_inner(registry: &OperatorRegistry) {
75    opendal_core::services::register_memory_service(registry);
76
77    #[cfg(feature = "services-aliyun-drive")]
78    opendal_service_aliyun_drive::register_aliyun_drive_service(registry);
79
80    #[cfg(feature = "services-alluxio")]
81    opendal_service_alluxio::register_alluxio_service(registry);
82
83    #[cfg(feature = "services-azblob")]
84    opendal_service_azblob::register_azblob_service(registry);
85
86    #[cfg(feature = "services-azdls")]
87    opendal_service_azdls::register_azdls_service(registry);
88
89    #[cfg(feature = "services-azfile")]
90    opendal_service_azfile::register_azfile_service(registry);
91
92    #[cfg(feature = "services-b2")]
93    opendal_service_b2::register_b2_service(registry);
94
95    #[cfg(feature = "services-cacache")]
96    opendal_service_cacache::register_cacache_service(registry);
97
98    #[cfg(feature = "services-cloudflare-kv")]
99    opendal_service_cloudflare_kv::register_cloudflare_kv_service(registry);
100
101    #[cfg(feature = "services-compfs")]
102    opendal_service_compfs::register_compfs_service(registry);
103
104    #[cfg(feature = "services-cos")]
105    opendal_service_cos::register_cos_service(registry);
106
107    #[cfg(feature = "services-d1")]
108    opendal_service_d1::register_d1_service(registry);
109
110    #[cfg(feature = "services-dashmap")]
111    opendal_service_dashmap::register_dashmap_service(registry);
112
113    #[cfg(feature = "services-dbfs")]
114    opendal_service_dbfs::register_dbfs_service(registry);
115
116    #[cfg(feature = "services-dropbox")]
117    opendal_service_dropbox::register_dropbox_service(registry);
118
119    #[cfg(feature = "services-etcd")]
120    opendal_service_etcd::register_etcd_service(registry);
121
122    #[cfg(feature = "services-foundationdb")]
123    opendal_service_foundationdb::register_foundationdb_service(registry);
124
125    #[cfg(feature = "services-foyer")]
126    opendal_service_foyer::register_foyer_service(registry);
127
128    #[cfg(feature = "services-fs")]
129    opendal_service_fs::register_fs_service(registry);
130
131    #[cfg(feature = "services-ftp")]
132    opendal_service_ftp::register_ftp_service(registry);
133
134    #[cfg(feature = "services-gcs")]
135    opendal_service_gcs::register_gcs_service(registry);
136
137    #[cfg(feature = "services-gcs-grpc")]
138    opendal_service_gcs_grpc::register_gcs_grpc_service(registry);
139
140    #[cfg(feature = "services-gdrive")]
141    opendal_service_gdrive::register_gdrive_service(registry);
142
143    #[cfg(feature = "services-ghac")]
144    opendal_service_ghac::register_ghac_service(registry);
145
146    #[cfg(feature = "services-git")]
147    opendal_service_git::register_git_service(registry);
148
149    #[cfg(feature = "services-github")]
150    opendal_service_github::register_github_service(registry);
151
152    #[cfg(feature = "services-goosefs")]
153    opendal_service_goosefs::register_goosefs_service(registry);
154
155    #[cfg(feature = "services-gridfs")]
156    opendal_service_gridfs::register_gridfs_service(registry);
157
158    #[cfg(feature = "services-hdfs")]
159    opendal_service_hdfs::register_hdfs_service(registry);
160
161    #[cfg(feature = "services-hdfs-native")]
162    opendal_service_hdfs_native::register_hdfs_native_service(registry);
163
164    #[cfg(feature = "services-http")]
165    opendal_service_http::register_http_service(registry);
166
167    #[cfg(feature = "services-hf")]
168    opendal_service_hf::register_hf_service(registry);
169
170    #[cfg(feature = "services-ipfs")]
171    opendal_service_ipfs::register_ipfs_service(registry);
172
173    #[cfg(feature = "services-ipmfs")]
174    opendal_service_ipmfs::register_ipmfs_service(registry);
175
176    #[cfg(feature = "services-koofr")]
177    opendal_service_koofr::register_koofr_service(registry);
178
179    #[cfg(feature = "services-lakefs")]
180    opendal_service_lakefs::register_lakefs_service(registry);
181
182    #[cfg(feature = "services-memcached")]
183    opendal_service_memcached::register_memcached_service(registry);
184
185    #[cfg(feature = "services-mini-moka")]
186    opendal_service_mini_moka::register_mini_moka_service(registry);
187
188    #[cfg(feature = "services-moka")]
189    opendal_service_moka::register_moka_service(registry);
190
191    #[cfg(feature = "services-mongodb")]
192    opendal_service_mongodb::register_mongodb_service(registry);
193
194    #[cfg(feature = "services-monoiofs")]
195    opendal_service_monoiofs::register_monoiofs_service(registry);
196
197    #[cfg(feature = "services-mysql")]
198    opendal_service_mysql::register_mysql_service(registry);
199
200    #[cfg(feature = "services-obs")]
201    opendal_service_obs::register_obs_service(registry);
202
203    #[cfg(feature = "services-onedrive")]
204    opendal_service_onedrive::register_onedrive_service(registry);
205
206    #[cfg(feature = "services-oss")]
207    opendal_service_oss::register_oss_service(registry);
208
209    #[cfg(feature = "services-pcloud")]
210    opendal_service_pcloud::register_pcloud_service(registry);
211
212    #[cfg(feature = "services-persy")]
213    opendal_service_persy::register_persy_service(registry);
214
215    #[cfg(feature = "services-postgresql")]
216    opendal_service_postgresql::register_postgresql_service(registry);
217
218    #[cfg(feature = "services-redb")]
219    opendal_service_redb::register_redb_service(registry);
220
221    #[cfg(feature = "services-rocksdb")]
222    opendal_service_rocksdb::register_rocksdb_service(registry);
223
224    #[cfg(feature = "services-s3")]
225    opendal_service_s3::register_s3_service(registry);
226
227    #[cfg(feature = "services-seafile")]
228    opendal_service_seafile::register_seafile_service(registry);
229
230    #[cfg(feature = "services-sftp")]
231    opendal_service_sftp::register_sftp_service(registry);
232
233    #[cfg(feature = "services-sled")]
234    opendal_service_sled::register_sled_service(registry);
235
236    #[cfg(feature = "services-smb")]
237    opendal_service_smb::register_smb_service(registry);
238
239    #[cfg(feature = "services-sqlite")]
240    opendal_service_sqlite::register_sqlite_service(registry);
241
242    #[cfg(feature = "services-surrealdb")]
243    opendal_service_surrealdb::register_surrealdb_service(registry);
244
245    #[cfg(feature = "services-swift")]
246    opendal_service_swift::register_swift_service(registry);
247
248    #[cfg(feature = "services-tikv")]
249    opendal_service_tikv::register_tikv_service(registry);
250
251    #[cfg(feature = "services-tos")]
252    opendal_service_tos::register_tos_service(registry);
253
254    #[cfg(feature = "services-upyun")]
255    opendal_service_upyun::register_upyun_service(registry);
256
257    #[cfg(feature = "services-vercel-artifacts")]
258    opendal_service_vercel_artifacts::register_vercel_artifacts_service(registry);
259
260    #[cfg(feature = "services-vercel-blob")]
261    opendal_service_vercel_blob::register_vercel_blob_service(registry);
262
263    #[cfg(feature = "services-webdav")]
264    opendal_service_webdav::register_webdav_service(registry);
265
266    #[cfg(feature = "services-webhdfs")]
267    opendal_service_webhdfs::register_webhdfs_service(registry);
268
269    #[cfg(feature = "services-yandex-disk")]
270    opendal_service_yandex_disk::register_yandex_disk_service(registry);
271
272    #[cfg(all(target_arch = "wasm32", feature = "services-opfs"))]
273    opendal_service_opfs::register_opfs_service(registry);
274
275    #[cfg(any(feature = "services-redis", feature = "services-redis-native-tls"))]
276    opendal_service_redis::register_redis_service(registry);
277}
278
279#[cfg(feature = "auto-register-services")]
280#[ctor::ctor(unsafe)]
281fn register_default_operator_registry() {
282    install_default();
283}
284
285/// Service builders enabled through `services-*` Cargo features.
286///
287/// [`Memory`](services::Memory) is always available. Other builders are
288/// re-exported when their matching facade feature is enabled; for example,
289/// `services-s3` enables [`S3`](services::S3).
290///
291/// Pass a configured builder to [`Operator::new`]. The facade automatically
292/// registers enabled services for [`Operator::from_uri`] and
293/// [`Operator::via_iter`] when the `auto-register-services` feature is enabled.
294pub mod services {
295    pub use opendal_core::services::*;
296    #[cfg(feature = "services-aliyun-drive")]
297    pub use opendal_service_aliyun_drive::*;
298    #[cfg(feature = "services-alluxio")]
299    pub use opendal_service_alluxio::*;
300    #[cfg(feature = "services-azblob")]
301    pub use opendal_service_azblob::*;
302    #[cfg(feature = "services-azdls")]
303    pub use opendal_service_azdls::*;
304    #[cfg(feature = "services-azfile")]
305    pub use opendal_service_azfile::*;
306    #[cfg(feature = "services-b2")]
307    pub use opendal_service_b2::*;
308    #[cfg(feature = "services-cacache")]
309    pub use opendal_service_cacache::*;
310    #[cfg(feature = "services-cloudflare-kv")]
311    pub use opendal_service_cloudflare_kv::*;
312    #[cfg(feature = "services-compfs")]
313    pub use opendal_service_compfs::*;
314    #[cfg(feature = "services-cos")]
315    pub use opendal_service_cos::*;
316    #[cfg(feature = "services-d1")]
317    pub use opendal_service_d1::*;
318    #[cfg(feature = "services-dashmap")]
319    pub use opendal_service_dashmap::*;
320    #[cfg(feature = "services-dbfs")]
321    pub use opendal_service_dbfs::*;
322    #[cfg(feature = "services-dropbox")]
323    pub use opendal_service_dropbox::*;
324    #[cfg(feature = "services-etcd")]
325    pub use opendal_service_etcd::*;
326    #[cfg(feature = "services-foundationdb")]
327    pub use opendal_service_foundationdb::*;
328    #[cfg(feature = "services-foyer")]
329    pub use opendal_service_foyer::*;
330    #[cfg(feature = "services-fs")]
331    pub use opendal_service_fs::*;
332    #[cfg(feature = "services-ftp")]
333    pub use opendal_service_ftp::*;
334    #[cfg(feature = "services-gcs")]
335    pub use opendal_service_gcs::*;
336    #[cfg(feature = "services-gcs-grpc")]
337    pub use opendal_service_gcs_grpc::*;
338    #[cfg(feature = "services-gdrive")]
339    pub use opendal_service_gdrive::*;
340    #[cfg(feature = "services-ghac")]
341    pub use opendal_service_ghac::*;
342    #[cfg(feature = "services-git")]
343    pub use opendal_service_git::*;
344    #[cfg(feature = "services-github")]
345    pub use opendal_service_github::*;
346    #[cfg(feature = "services-goosefs")]
347    pub use opendal_service_goosefs::*;
348    #[cfg(feature = "services-gridfs")]
349    pub use opendal_service_gridfs::*;
350    #[cfg(feature = "services-hdfs")]
351    pub use opendal_service_hdfs::*;
352    #[cfg(feature = "services-hdfs-native")]
353    pub use opendal_service_hdfs_native::*;
354    #[cfg(feature = "services-hf")]
355    pub use opendal_service_hf::*;
356    #[cfg(feature = "services-http")]
357    pub use opendal_service_http::*;
358    #[cfg(feature = "services-ipfs")]
359    pub use opendal_service_ipfs::*;
360    #[cfg(feature = "services-ipmfs")]
361    pub use opendal_service_ipmfs::*;
362    #[cfg(feature = "services-koofr")]
363    pub use opendal_service_koofr::*;
364    #[cfg(feature = "services-lakefs")]
365    pub use opendal_service_lakefs::*;
366    #[cfg(feature = "services-memcached")]
367    pub use opendal_service_memcached::*;
368    #[cfg(feature = "services-mini-moka")]
369    pub use opendal_service_mini_moka::*;
370    #[cfg(feature = "services-moka")]
371    pub use opendal_service_moka::*;
372    #[cfg(feature = "services-mongodb")]
373    pub use opendal_service_mongodb::*;
374    #[cfg(feature = "services-monoiofs")]
375    pub use opendal_service_monoiofs::*;
376    #[cfg(feature = "services-mysql")]
377    pub use opendal_service_mysql::*;
378    #[cfg(feature = "services-obs")]
379    pub use opendal_service_obs::*;
380    #[cfg(feature = "services-onedrive")]
381    pub use opendal_service_onedrive::*;
382    #[cfg(all(target_arch = "wasm32", feature = "services-opfs"))]
383    pub use opendal_service_opfs::*;
384    #[cfg(feature = "services-oss")]
385    pub use opendal_service_oss::*;
386    #[cfg(feature = "services-pcloud")]
387    pub use opendal_service_pcloud::*;
388    #[cfg(feature = "services-persy")]
389    pub use opendal_service_persy::*;
390    #[cfg(feature = "services-postgresql")]
391    pub use opendal_service_postgresql::*;
392    #[cfg(feature = "services-redb")]
393    pub use opendal_service_redb::*;
394    #[cfg(feature = "services-redis")]
395    pub use opendal_service_redis::*;
396    #[cfg(feature = "services-rocksdb")]
397    pub use opendal_service_rocksdb::*;
398    #[cfg(feature = "services-s3")]
399    pub use opendal_service_s3::*;
400    #[cfg(feature = "services-seafile")]
401    pub use opendal_service_seafile::*;
402    #[cfg(feature = "services-sftp")]
403    pub use opendal_service_sftp::*;
404    #[cfg(feature = "services-sled")]
405    pub use opendal_service_sled::*;
406    #[cfg(feature = "services-smb")]
407    pub use opendal_service_smb::*;
408    #[cfg(feature = "services-sqlite")]
409    pub use opendal_service_sqlite::*;
410    #[cfg(feature = "services-surrealdb")]
411    pub use opendal_service_surrealdb::*;
412    #[cfg(feature = "services-swift")]
413    pub use opendal_service_swift::*;
414    #[cfg(feature = "services-tikv")]
415    pub use opendal_service_tikv::*;
416    #[cfg(feature = "services-tos")]
417    pub use opendal_service_tos::*;
418    #[cfg(feature = "services-upyun")]
419    pub use opendal_service_upyun::*;
420    #[cfg(feature = "services-vercel-artifacts")]
421    pub use opendal_service_vercel_artifacts::*;
422    #[cfg(feature = "services-vercel-blob")]
423    pub use opendal_service_vercel_blob::*;
424    #[cfg(feature = "services-webdav")]
425    pub use opendal_service_webdav::*;
426    #[cfg(feature = "services-webhdfs")]
427    pub use opendal_service_webhdfs::*;
428    #[cfg(feature = "services-yandex-disk")]
429    pub use opendal_service_yandex_disk::*;
430}
431
432/// Layers enabled through `layers-*` Cargo features.
433///
434/// A layer adds cross-service behavior to an [`Operator`]. Enable the matching
435/// facade feature, construct the layer, and pass it to [`Operator::layer`].
436/// Layer order is observable, so review each layer's composition notes when
437/// combining retries, timeouts, caching, or observability.
438pub mod layers {
439    pub use opendal_core::layers::*;
440    #[cfg(feature = "layers-async-backtrace")]
441    pub use opendal_layer_async_backtrace::*;
442    #[cfg(feature = "layers-await-tree")]
443    pub use opendal_layer_await_tree::*;
444    #[cfg(feature = "layers-capability-check")]
445    pub use opendal_layer_capability_check::*;
446    #[cfg(feature = "layers-chaos")]
447    pub use opendal_layer_chaos::*;
448    #[cfg(feature = "layers-concurrent-limit")]
449    pub use opendal_layer_concurrent_limit::*;
450    #[cfg(all(target_os = "linux", feature = "layers-dtrace"))]
451    pub use opendal_layer_dtrace::*;
452    #[cfg(feature = "layers-fastmetrics")]
453    pub use opendal_layer_fastmetrics::*;
454    #[cfg(feature = "layers-fastrace")]
455    pub use opendal_layer_fastrace::*;
456    #[cfg(feature = "layers-foyer")]
457    pub use opendal_layer_foyer::*;
458    #[cfg(feature = "layers-hotpath")]
459    pub use opendal_layer_hotpath::*;
460    #[cfg(feature = "layers-immutable-index")]
461    pub use opendal_layer_immutable_index::*;
462    #[cfg(feature = "layers-logging")]
463    pub use opendal_layer_logging::*;
464    #[cfg(feature = "layers-metrics")]
465    pub use opendal_layer_metrics::*;
466    #[cfg(feature = "layers-mime-guess")]
467    pub use opendal_layer_mime_guess::*;
468    #[cfg(feature = "layers-otel-metrics")]
469    pub use opendal_layer_otelmetrics::*;
470    #[cfg(feature = "layers-otel-trace")]
471    pub use opendal_layer_oteltrace::*;
472    #[cfg(feature = "layers-prometheus")]
473    pub use opendal_layer_prometheus::*;
474    #[cfg(feature = "layers-prometheus-client")]
475    pub use opendal_layer_prometheus_client::*;
476    #[cfg(feature = "layers-retry")]
477    pub use opendal_layer_retry::*;
478    #[cfg(feature = "layers-route")]
479    pub use opendal_layer_route::*;
480    #[cfg(feature = "layers-tail-cut")]
481    pub use opendal_layer_tail_cut::*;
482    #[cfg(feature = "layers-throttle")]
483    pub use opendal_layer_throttle::*;
484    #[cfg(feature = "layers-timeout")]
485    pub use opendal_layer_timeout::*;
486    #[cfg(feature = "layers-tracing")]
487    pub use opendal_layer_tracing::*;
488}
opendal/lib.rs

opendal/
lib.rs
