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 [`BlockingOperator`]. 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 [`BlockingOperator`]. Please pick the one that fits your use case.
92//!
93//! Every Operator API follows the same pattern, take `read` as an example:
94//!
95//! - `read`: Execute a read operation.
96//! - `read_with`: Execute a read operation with additional options, like `range` and `if_match`.
97//! - `reader`: Create a reader for streaming data, enabling flexible access.
98//! - `reader_with`: Create a reader with advanced options.
99//!
100//! ```no_run
101//! use opendal::layers::LoggingLayer;
102//! use opendal::services;
103//! use opendal::Operator;
104//! use opendal::Result;
105//!
106//! #[tokio::main]
107//! async fn main() -> Result<()> {
108//!     // Pick a builder and configure it.
109//!     let mut builder = services::S3::default().bucket("test");
110//!
111//!     // Init an operator
112//!     let op = Operator::new(builder)?
113//!         // Init with logging layer enabled.
114//!         .layer(LoggingLayer::default())
115//!         .finish();
116//!
117//!     // Fetch this file's metadata
118//!     let meta = op.stat("hello.txt").await?;
119//!     let length = meta.content_length();
120//!
121//!     // Read data from `hello.txt` with range `0..1024`.
122//!     let bs = op.read_with("hello.txt").range(0..1024).await?;
123//!
124//!     Ok(())
125//! }
126//! ```
127//!
128//! # Useful Links
129//!
130//! - [Concept][crate::docs::concepts]
131//! - [Internals][crate::docs::internals]
132//! - [Performance Guide][crate::docs::performance]
133
134// Make sure all our public APIs have docs.
135#![warn(missing_docs)]
136
137// Private module with public types, they will be accessed via `opendal::Xxxx`
138mod types;
139pub use types::*;
140
141// Public modules, they will be accessed like `opendal::layers::Xxxx`
142#[cfg(docsrs)]
143pub mod docs;
144pub mod layers;
145pub mod raw;
146pub mod services;
147
148#[cfg(test)]
149mod tests {
150    use std::mem::size_of;
151
152    use super::*;
153    /// This is not a real test case.
154    ///
155    /// We assert our public structs here to make sure we don't introduce
156    /// unexpected struct/enum size change.
157    #[cfg(target_pointer_width = "64")]
158    #[test]
159    fn assert_size() {
160        assert_eq!(16, size_of::<Operator>());
161        assert_eq!(320, size_of::<Entry>());
162        assert_eq!(296, size_of::<Metadata>());
163        assert_eq!(1, size_of::<EntryMode>());
164        assert_eq!(24, size_of::<Scheme>());
165    }
166
167    trait AssertSendSync: Send + Sync {}
168    impl AssertSendSync for Entry {}
169    impl AssertSendSync for Capability {}
170    impl AssertSendSync for Error {}
171    impl AssertSendSync for Reader {}
172    impl AssertSendSync for Writer {}
173    impl AssertSendSync for Lister {}
174    impl AssertSendSync for Operator {}
175    impl AssertSendSync for BlockingReader {}
176    impl AssertSendSync for BlockingWriter {}
177    impl AssertSendSync for BlockingLister {}
178    impl AssertSendSync for BlockingOperator {}
179
180    /// This is used to make sure our public API implement Send + Sync
181    #[test]
182    fn test_trait() {
183        let _: Box<dyn AssertSendSync> = Box::new(Capability::default());
184    }
185}
opendal/lib.rs

opendal/
lib.rs
