opendal/services/onedrive/
builder.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
18use std::fmt::Debug;
19use std::fmt::Formatter;
20use std::sync::Arc;
21
22use chrono::DateTime;
23use chrono::Utc;
24use log::debug;
25use services::onedrive::core::OneDriveCore;
26use services::onedrive::core::OneDriveSigner;
27use tokio::sync::Mutex;
28
29use super::backend::OnedriveBackend;
30use crate::raw::normalize_root;
31use crate::raw::Access;
32use crate::raw::AccessorInfo;
33use crate::raw::HttpClient;
34use crate::services::OnedriveConfig;
35use crate::Scheme;
36use crate::*;
37
38impl Configurator for OnedriveConfig {
39    type Builder = OnedriveBuilder;
40    fn into_builder(self) -> Self::Builder {
41        OnedriveBuilder {
42            config: self,
43            http_client: None,
44        }
45    }
46}
47
48/// Microsoft [OneDrive](https://onedrive.com) backend support.
49#[doc = include_str!("docs.md")]
50#[derive(Default)]
51pub struct OnedriveBuilder {
52    config: OnedriveConfig,
53    http_client: Option<HttpClient>,
54}
55
56impl Debug for OnedriveBuilder {
57    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
58        f.debug_struct("Backend")
59            .field("config", &self.config)
60            .finish()
61    }
62}
63
64impl OnedriveBuilder {
65    /// Set root path of OneDrive folder.
66    pub fn root(mut self, root: &str) -> Self {
67        self.config.root = if root.is_empty() {
68            None
69        } else {
70            Some(root.to_string())
71        };
72
73        self
74    }
75
76    /// Specify the http client that used by this service.
77    ///
78    /// # Notes
79    ///
80    /// This API is part of OpenDAL's Raw API. `HttpClient` could be changed
81    /// during minor updates.
82    #[deprecated(since = "0.53.0", note = "Use `Operator::update_http_client` instead")]
83    #[allow(deprecated)]
84    pub fn http_client(mut self, http_client: HttpClient) -> Self {
85        self.http_client = Some(http_client);
86        self
87    }
88
89    /// Set the access token for a time limited access to Microsoft Graph API (also OneDrive).
90    ///
91    /// Microsoft Graph API uses a typical OAuth 2.0 flow for authentication and authorization.
92    /// You can get a access token from [Microsoft Graph Explore](https://developer.microsoft.com/en-us/graph/graph-explorer).
93    ///
94    /// # Note
95    ///
96    /// - An access token is short-lived.
97    /// - Use a refresh_token if you want to use OneDrive API for an extended period of time.
98    pub fn access_token(mut self, access_token: &str) -> Self {
99        self.config.access_token = Some(access_token.to_string());
100        self
101    }
102
103    /// Set the refresh token for long term access to Microsoft Graph API.
104    ///
105    /// OpenDAL will use a refresh token to maintain a fresh access token automatically.
106    ///
107    /// # Note
108    ///
109    /// - A refresh token is available through a OAuth 2.0 flow, with an additional scope `offline_access`.
110    pub fn refresh_token(mut self, refresh_token: &str) -> Self {
111        self.config.refresh_token = Some(refresh_token.to_string());
112        self
113    }
114
115    /// Set the client_id for a Microsoft Graph API application (available though Azure's registration portal)
116    ///
117    /// Required when using the refresh token.
118    pub fn client_id(mut self, client_id: &str) -> Self {
119        self.config.client_id = Some(client_id.to_string());
120        self
121    }
122
123    /// Set the client_secret for a Microsoft Graph API application
124    ///
125    /// Required for Web app when using the refresh token.
126    /// Don't use a client secret when use in a native app since the native app can't store the secret reliably.
127    pub fn client_secret(mut self, client_secret: &str) -> Self {
128        self.config.client_secret = Some(client_secret.to_string());
129        self
130    }
131
132    /// Enable versioning support for OneDrive
133    pub fn enable_versioning(mut self, enabled: bool) -> Self {
134        self.config.enable_versioning = enabled;
135        self
136    }
137}
138
139impl Builder for OnedriveBuilder {
140    const SCHEME: Scheme = Scheme::Onedrive;
141    type Config = OnedriveConfig;
142
143    fn build(self) -> Result<impl Access> {
144        let root = normalize_root(&self.config.root.unwrap_or_default());
145        debug!("backend use root {root}");
146
147        let info = AccessorInfo::default();
148        info.set_scheme(Scheme::Onedrive)
149            .set_root(&root)
150            .set_native_capability(Capability {
151                read: true,
152                read_with_if_none_match: true,
153
154                write: true,
155                write_with_if_match: true,
156                // OneDrive supports the file size up to 250GB
157                // Read more at https://support.microsoft.com/en-us/office/restrictions-and-limitations-in-onedrive-and-sharepoint-64883a5d-228e-48f5-b3d2-eb39e07630fa#individualfilesize
158                // However, we can't enable this, otherwise OpenDAL behavior tests will try to test creating huge
159                // file up to this size.
160                // write_total_max_size: Some(250 * 1024 * 1024 * 1024),
161                copy: true,
162                rename: true,
163
164                stat: true,
165                stat_with_if_none_match: true,
166                stat_with_version: self.config.enable_versioning,
167
168                delete: true,
169                create_dir: true,
170
171                list: true,
172                list_with_limit: true,
173                list_with_versions: self.config.enable_versioning,
174
175                shared: true,
176
177                ..Default::default()
178            });
179
180        // allow deprecated api here for compatibility
181        #[allow(deprecated)]
182        if let Some(client) = self.http_client {
183            info.update_http_client(|_| client);
184        }
185
186        let accessor_info = Arc::new(info);
187        let mut signer = OneDriveSigner::new(accessor_info.clone());
188
189        // Requires OAuth 2.0 tokens:
190        // - `access_token` (the short-lived token)
191        // - `refresh_token` flow (the long term token)
192        // to be mutually exclusive for setting up for implementation simplicity
193        match (self.config.access_token, self.config.refresh_token) {
194            (Some(access_token), None) => {
195                signer.access_token = access_token;
196                signer.expires_in = DateTime::<Utc>::MAX_UTC;
197            }
198            (None, Some(refresh_token)) => {
199                let client_id = self.config.client_id.ok_or_else(|| {
200                    Error::new(
201                        ErrorKind::ConfigInvalid,
202                        "client_id must be set when refresh_token is set",
203                    )
204                    .with_context("service", Scheme::Onedrive)
205                })?;
206
207                signer.refresh_token = refresh_token;
208                signer.client_id = client_id;
209                if let Some(client_secret) = self.config.client_secret {
210                    signer.client_secret = client_secret;
211                }
212            }
213            (Some(_), Some(_)) => {
214                return Err(Error::new(
215                    ErrorKind::ConfigInvalid,
216                    "access_token and refresh_token cannot be set at the same time",
217                )
218                .with_context("service", Scheme::Onedrive))
219            }
220            (None, None) => {
221                return Err(Error::new(
222                    ErrorKind::ConfigInvalid,
223                    "access_token or refresh_token must be set",
224                )
225                .with_context("service", Scheme::Onedrive))
226            }
227        };
228
229        let core = Arc::new(OneDriveCore {
230            info: accessor_info,
231            root,
232            signer: Arc::new(Mutex::new(signer)),
233        });
234
235        Ok(OnedriveBackend { core })
236    }
237}
opendal/services/onedrive/builder.rs

opendal/services/onedrive/
builder.rs
