opendal_core/
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(
19    html_logo_url = "https://raw.githubusercontent.com/apache/opendal/main/website/static/img/logo.svg"
20)]
21#![cfg_attr(docsrs, feature(doc_cfg))]
22//! Apache OpenDAL™ is an Open Data Access Layer that enables seamless interaction with diverse storage services.
23//!
24//! OpenDAL's development is guided by its vision of **One Layer, All Storage** and its core principles: **Open Community**, **Solid Foundation**, **Fast Access**, **Object Storage First**, and **Extensible Architecture**. Read the explained vision at [OpenDAL Vision](https://opendal.apache.org/vision).
25//!
26//! # Quick Start
27//!
28//! OpenDAL's API entry points are [`Operator`] and [`blocking::Operator`]. All
29//! public APIs are accessible through the operator. To utilize OpenDAL, you
30//! need to:
31//!
32//! - [Init a service](#init-a-service)
33//! - [Compose layers](#compose-layers)
34//! - [Use operator](#use-operator)
35//!
36//! ## Init a service
37//!
38//! The first step is to pick a service and init it with a builder. All supported
39//! services could be found at [`services`].
40//!
41//! Let's take [`services::Memory`] as an example:
42//!
43//! ```no_run
44//! use opendal_core::services;
45//! use opendal_core::Operator;
46//! use opendal_core::Result;
47//!
48//! fn main() -> Result<()> {
49//!     // Pick a builder and configure it.
50//!     let builder = services::Memory::default();
51//!
52//!     // Init an operator
53//!     let op = Operator::new(builder)?.finish();
54//!     Ok(())
55//! }
56//! ```
57//!
58//! ## Compose layers
59//!
60//! The next setup is to compose layers. Layers are modules that provide extra
61//! features for every operation. All builtin layers could be found at [`layers`].
62//!
63//! Let's use [`layers::HttpClientLayer`] as an example; this layer allows
64//! customizing the HTTP client used by OpenDAL.
65//!
66//! ```no_run
67//! use opendal_core::layers::HttpClientLayer;
68//! use opendal_core::raw::HttpClient;
69//! use opendal_core::services;
70//! use opendal_core::Operator;
71//! use opendal_core::Result;
72//!
73//! #[tokio::main]
74//! async fn main() -> Result<()> {
75//!     // Pick a builder and configure it.
76//!     let builder = services::Memory::default();
77//!
78//!     // Init an operator
79//!     let client = HttpClient::new()?;
80//!     let op = Operator::new(builder)?
81//!         // Init with custom HTTP client.
82//!         .layer(HttpClientLayer::new(client))
83//!         .finish();
84//!
85//!     Ok(())
86//! }
87//! ```
88//!
89//! ## Use operator
90//!
91//! The final step is to use the operator. OpenDAL supports both async [`Operator`]
92//! and blocking [`blocking::Operator`]. Please pick the one that fits your use case.
93//!
94//! Every Operator API follows a consistent pattern. For example, consider the `read` operation:
95//!
96//! - [`Operator::read`]: Executes a read operation.
97//! - [`Operator::read_with`]: Executes a read operation with additional options using the builder pattern.
98//! - [`Operator::read_options`]: Executes a read operation with extra options provided via a [`options::ReadOptions`] struct.
99//! - [`Operator::reader`]: Creates a reader for streaming data, allowing for flexible access.
100//! - [`Operator::reader_with`]: Creates a reader with advanced options using the builder pattern.
101//! - [`Operator::reader_options`]: Creates a reader with extra options provided via a [`options::ReadOptions`] struct.
102//!
103//! The [`Reader`] created by [`Operator`] supports custom read control methods and can be converted
104//! into [`futures::AsyncRead`] or [`futures::Stream`] for broader ecosystem compatibility.
105//!
106//! ```no_run
107//! use opendal_core::layers::HttpClientLayer;
108//! use opendal_core::options;
109//! use opendal_core::raw::HttpClient;
110//! use opendal_core::services;
111//! use opendal_core::Operator;
112//! use opendal_core::Result;
113//!
114//! #[tokio::main]
115//! async fn main() -> Result<()> {
116//!     // Pick a builder and configure it.
117//!     let builder = services::Memory::default();
118//!
119//!     // Init an operator
120//!     let client = HttpClient::new()?;
121//!     let op = Operator::new(builder)?
122//!         // Init with custom HTTP client.
123//!         .layer(HttpClientLayer::new(client))
124//!         .finish();
125//!
126//!     // Fetch this file's metadata
127//!     let meta = op.stat("hello.txt").await?;
128//!     let length = meta.content_length();
129//!
130//!     // Read data from `hello.txt` with options.
131//!     let bs = op
132//!         .read_with("hello.txt")
133//!         .range(0..8 * 1024 * 1024)
134//!         .chunk(1024 * 1024)
135//!         .concurrent(4)
136//!         .await?;
137//!
138//!     // The same to:
139//!     let bs = op
140//!         .read_options("hello.txt", options::ReadOptions {
141//!             range: (0..8 * 1024 * 1024).into(),
142//!             chunk: Some(1024 * 1024),
143//!             concurrent: 4,
144//!             ..Default::default()
145//!         })
146//!         .await?;
147//!
148//!     Ok(())
149//! }
150//! ```
151//!
152//! # Useful Links
153//!
154//! - [Concept][crate::docs::concepts]
155//! - [Internals][crate::docs::internals]
156//! - [Performance Guide][crate::docs::performance]
157
158// Make sure all our public APIs have docs.
159#![deny(missing_docs)]
160
161// Private module with public types, they will be accessed via `opendal::Xxxx`
162mod types;
163pub use types::*;
164
165// Public modules, they will be accessed like `opendal::layers::Xxxx`
166#[cfg(feature = "blocking")]
167pub mod blocking;
168#[cfg(docsrs)]
169pub mod docs;
170pub mod layers;
171pub mod raw;
172pub mod services;
173
174#[cfg(test)]
175mod tests {
176    use std::mem::size_of;
177
178    use super::*;
179    /// This is not a real test case.
180    ///
181    /// We assert our public structs here to make sure we don't introduce
182    /// unexpected struct/enum size change.
183    #[cfg(target_pointer_width = "64")]
184    #[test]
185    fn assert_size() {
186        assert_eq!(16, size_of::<Operator>());
187        assert_eq!(360, size_of::<Entry>());
188        assert_eq!(336, size_of::<Metadata>());
189        assert_eq!(1, size_of::<EntryMode>());
190    }
191
192    trait AssertSendSync: Send + Sync {}
193    impl AssertSendSync for Entry {}
194    impl AssertSendSync for Capability {}
195    impl AssertSendSync for Error {}
196    impl AssertSendSync for Reader {}
197    impl AssertSendSync for Writer {}
198    impl AssertSendSync for Lister {}
199    impl AssertSendSync for Operator {}
200
201    /// This is used to make sure our public API implement Send + Sync
202    #[test]
203    fn test_trait() {
204        let _: Box<dyn AssertSendSync> = Box::new(Capability::default());
205    }
206}
opendal_core/lib.rs

opendal_core/
lib.rs
