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

opendal/
lib.rs
