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

opendal/
lib.rs
