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 super::DEFAULT_SCHEME;
31use crate::raw::normalize_root;
32use crate::raw::Access;
33use crate::raw::AccessorInfo;
34use crate::raw::HttpClient;
35use crate::services::OnedriveConfig;
36use crate::Scheme;
37use crate::*;
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    type Config = OnedriveConfig;
141
142    fn build(self) -> Result<impl Access> {
143        let root = normalize_root(&self.config.root.unwrap_or_default());
144        debug!("backend use root {root}");
145
146        let info = AccessorInfo::default();
147        info.set_scheme(DEFAULT_SCHEME)
148            .set_root(&root)
149            .set_native_capability(Capability {
150                read: true,
151                read_with_if_none_match: true,
152
153                write: true,
154                write_with_if_match: true,
155                // OneDrive supports the file size up to 250GB
156                // Read more at https://support.microsoft.com/en-us/office/restrictions-and-limitations-in-onedrive-and-sharepoint-64883a5d-228e-48f5-b3d2-eb39e07630fa#individualfilesize
157                // However, we can't enable this, otherwise OpenDAL behavior tests will try to test creating huge
158                // file up to this size.
159                // write_total_max_size: Some(250 * 1024 * 1024 * 1024),
160                copy: true,
161                rename: true,
162
163                stat: true,
164                stat_with_if_none_match: true,
165                stat_with_version: self.config.enable_versioning,
166
167                delete: true,
168                create_dir: true,
169
170                list: true,
171                list_with_limit: true,
172                list_with_versions: self.config.enable_versioning,
173
174                shared: true,
175
176                ..Default::default()
177            });
178
179        // allow deprecated api here for compatibility
180        #[allow(deprecated)]
181        if let Some(client) = self.http_client {
182            info.update_http_client(|_| client);
183        }
184
185        let accessor_info = Arc::new(info);
186        let mut signer = OneDriveSigner::new(accessor_info.clone());
187
188        // Requires OAuth 2.0 tokens:
189        // - `access_token` (the short-lived token)
190        // - `refresh_token` flow (the long term token)
191        // to be mutually exclusive for setting up for implementation simplicity
192        match (self.config.access_token, self.config.refresh_token) {
193            (Some(access_token), None) => {
194                signer.access_token = access_token;
195                signer.expires_in = DateTime::<Utc>::MAX_UTC;
196            }
197            (None, Some(refresh_token)) => {
198                let client_id = self.config.client_id.ok_or_else(|| {
199                    Error::new(
200                        ErrorKind::ConfigInvalid,
201                        "client_id must be set when refresh_token is set",
202                    )
203                    .with_context("service", Scheme::Onedrive)
204                })?;
205
206                signer.refresh_token = refresh_token;
207                signer.client_id = client_id;
208                if let Some(client_secret) = self.config.client_secret {
209                    signer.client_secret = client_secret;
210                }
211            }
212            (Some(_), Some(_)) => {
213                return Err(Error::new(
214                    ErrorKind::ConfigInvalid,
215                    "access_token and refresh_token cannot be set at the same time",
216                )
217                .with_context("service", Scheme::Onedrive))
218            }
219            (None, None) => {
220                return Err(Error::new(
221                    ErrorKind::ConfigInvalid,
222                    "access_token or refresh_token must be set",
223                )
224                .with_context("service", Scheme::Onedrive))
225            }
226        };
227
228        let core = Arc::new(OneDriveCore {
229            info: accessor_info,
230            root,
231            signer: Arc::new(Mutex::new(signer)),
232        });
233
234        Ok(OnedriveBackend { core })
235    }
236}
opendal/services/onedrive/builder.rs

opendal/services/onedrive/
builder.rs
