Skip to main content

coven_storage/providers/
connector.rs

1//! Provider construction from an explicit location and device credentials.
2
3use super::{
4    http_client::HttpClient, oauth_folders::OAuthFolders, DropboxStorage, OAuthSession,
5    OneDriveStorage, S3Storage, StorageFolder,
6};
7use crate::{
8    ProviderAuth, ProviderOps, S3Credentials, S3DetectionRun, S3DetectionRuns, StorageConfig,
9    StorageConnection, StorageCredentials, StorageError, StorageFailure,
10};
11use coven_foundation::{
12    clock::ClockRef,
13    id_source::{DeviceId, IdSourceRef, StoreId},
14};
15use std::sync::Arc;
16
17/// Constructs provider connections without committing settings or credentials.
18/// Tests replace the connection boundary with in-memory storage.
19#[async_trait::async_trait]
20pub trait StorageConnector: Send + Sync {
21    /// Read the signed-in account's display label before recording a member's location.
22    async fn account_label(
23        &self,
24        _auth: ProviderAuth,
25        _cooldown: Arc<dyn crate::Cooldown>,
26    ) -> Result<String, StorageError> {
27        Err(StorageFailure::ProviderUnavailable.into())
28    }
29
30    /// Read the signed-in account's provider id and primary address, before a
31    /// join keeps the sign-in (§13.2).
32    async fn signed_in_account(
33        &self,
34        _auth: ProviderAuth,
35        _cooldown: Arc<dyn crate::Cooldown>,
36    ) -> Result<crate::ProviderAccount, StorageError> {
37        Err(StorageFailure::ProviderUnavailable.into())
38    }
39
40    /// Read the signed-in OneDrive root.
41    async fn onedrive_root(
42        &self,
43        _auth: ProviderAuth,
44        _cooldown: Arc<dyn crate::Cooldown>,
45    ) -> Result<StorageFolder, StorageError> {
46        Err(StorageFailure::ProviderUnavailable.into())
47    }
48
49    /// Read all immediate OneDrive child folders.
50    async fn onedrive_folders(
51        &self,
52        _parent: &StorageConfig,
53        _auth: ProviderAuth,
54        _cooldown: Arc<dyn crate::Cooldown>,
55    ) -> Result<Vec<StorageFolder>, StorageError> {
56        Err(StorageFailure::ProviderUnavailable.into())
57    }
58
59    /// Create a OneDrive folder without renaming or replacing an occupied name.
60    async fn create_onedrive_folder(
61        &self,
62        _parent: &StorageConfig,
63        _name: &str,
64        _auth: ProviderAuth,
65        _cooldown: Arc<dyn crate::Cooldown>,
66    ) -> Result<StorageFolder, StorageError> {
67        Err(StorageFailure::ProviderUnavailable.into())
68    }
69
70    /// Read all shared Dropbox namespaces.
71    async fn dropbox_shared_folders(
72        &self,
73        _auth: ProviderAuth,
74        _cooldown: Arc<dyn crate::Cooldown>,
75    ) -> Result<Vec<StorageFolder>, StorageError> {
76        Err(StorageFailure::ProviderUnavailable.into())
77    }
78
79    /// Make a folder named `name` at the top of the signed-in Dropbox and
80    /// share it, refusing a name already taken.
81    async fn create_dropbox_shared_folder(
82        &self,
83        _name: &str,
84        _auth: ProviderAuth,
85        _cooldown: Arc<dyn crate::Cooldown>,
86    ) -> Result<StorageFolder, StorageError> {
87        Err(StorageFailure::ProviderUnavailable.into())
88    }
89
90    /// Create the owner's CloudKit location from the entitled container.
91    /// A connector without native CloudKit support refuses this capability.
92    async fn prepare_cloudkit(
93        &self,
94        _container: &str,
95        _store: StoreId,
96    ) -> Result<StorageConfig, StorageError> {
97        Err(StorageFailure::ProviderUnavailable.into())
98    }
99    /// Validate settings and wrap the selected native provider once. The caller
100    /// verifies the connection before publication. Every request waits for
101    /// the store's shared `cooldown`; a rejected OAuth token is refreshed in
102    /// the sign-in's custody (§20.2). A setup call makes its own
103    /// connection beside it (`StorageConnection::during_setup`) for its
104    /// requests to draw on its waits (§20.8).
105    /// The connection writes for `device`: what it stages sits in that
106    /// device's reserved folder (D10).
107    async fn connect(
108        &self,
109        config: StorageConfig,
110        auth: ProviderAuth,
111        device: DeviceId,
112        publications: Arc<dyn crate::PublicationGate>,
113        cooldown: Arc<dyn crate::Cooldown>,
114        transfers: Arc<crate::TransferBudget>,
115    ) -> Result<Arc<StorageConnection>, StorageError>;
116    /// Probe an S3 location's service (§20.7), writing only fresh objects under
117    /// the store's `.coven-check/<run>/` prefix for `runs.run` and deleting
118    /// them, also on failure, then removing what each of `runs.earlier`
119    /// left there. The caller recorded `runs.run` before calling; the answer
120    /// names the runs whose probes and uploads are confirmed gone.
121    /// A connector without native S3 refuses this capability.
122    /// A rate-limited probe is sent again while setup's `waits` allow (§20.8).
123    async fn detect_s3(
124        &self,
125        _config: StorageConfig,
126        _credentials: S3Credentials,
127        _store: StoreId,
128        runs: &S3DetectionRuns,
129        _waits: &crate::SetupWaits,
130    ) -> S3DetectionRun {
131        S3DetectionRun::unwritten(runs, Err(StorageFailure::ProviderUnavailable.into()))
132    }
133    /// Before a store's first setup at a location it needs to itself (a
134    /// Dropbox shared folder, a OneDrive folder, or an S3 bucket), refuse a
135    /// location whose root holds anything outside the store's folder or the
136    /// `coven-location` marker (§20.3).
137    /// Reads only. A connector without that provider refuses this capability.
138    /// A rate-limited listing is sent again while setup's `waits` allow.
139    async fn check_new_store(
140        &self,
141        _config: StorageConfig,
142        _auth: ProviderAuth,
143        _store: StoreId,
144        _waits: &crate::SetupWaits,
145    ) -> Result<(), StorageError> {
146        Err(StorageFailure::ProviderUnavailable.into())
147    }
148}
149
150/// The provider composition root retains the supplied clock and id source,
151/// and the one HTTP client every connection it makes sends through.
152pub struct ProviderConnector {
153    clock: ClockRef,
154    ids: IdSourceRef,
155    /// Building it fails only when TLS cannot be set up; each call needing it
156    /// then returns that failure.
157    http: Result<HttpClient, Arc<super::http_client::TlsSetupError>>,
158    #[cfg(any(test, feature = "test-utils"))]
159    folder_api: Option<String>,
160}
161impl ProviderConnector {
162    /// Retain the capabilities used to construct subsequent connections.
163    pub fn new(clock: ClockRef, ids: IdSourceRef) -> Self {
164        Self {
165            http: HttpClient::new(clock.clone()).map_err(Arc::new),
166            clock,
167            ids,
168            #[cfg(any(test, feature = "test-utils"))]
169            folder_api: None,
170        }
171    }
172    /// Send account and folder calls to an in-process provider API in application tests.
173    #[cfg(any(test, feature = "test-utils"))]
174    pub fn with_folder_api(mut self, api: String) -> Self {
175        self.folder_api = Some(api);
176        self
177    }
178    /// Delete every object and abort every unfinished upload in an S3
179    /// location's bucket, once its root shows it holds only stores, with
180    /// this connector's clock, ids and HTTP client (api.md E14). A
181    /// development tool outside the sync protocol.
182    #[cfg(feature = "dev-tools")]
183    pub async fn empty_s3_bucket(
184        &self,
185        config: StorageConfig,
186        credentials: S3Credentials,
187    ) -> Result<super::EmptiedS3Bucket, super::EmptyS3BucketError> {
188        let http = self
189            .http
190            .clone()
191            .map_err(|source| super::http_client::tls_failure(crate::CloudProvider::S3, source))
192            .map_err(super::EmptyS3BucketError::Storage)?;
193        super::empty_s3_bucket(config, credentials, self.clock.clone(), self.ids.clone(), http)
194            .await
195    }
196    async fn with_folders<T, F, Fut>(
197        &self,
198        auth: ProviderAuth,
199        cooldown: Arc<dyn crate::Cooldown>,
200        request: F,
201    ) -> Result<T, StorageError>
202    where
203        F: FnOnce(OAuthFolders) -> Fut,
204        Fut: std::future::Future<Output = Result<T, StorageError>>,
205    {
206        let ProviderAuth::OAuth { tokens, custody } = auth else {
207            return Err(StorageFailure::InvalidConfiguration
208                .with_source("account and folder requests require OAuth sign-in"));
209        };
210        let access = tokens.access;
211        let api = super::oauth_api(access.provider()).expect("an OAuth provider").to_owned();
212        #[cfg(any(test, feature = "test-utils"))]
213        let api = self.folder_api.clone().unwrap_or(api);
214        let session = OAuthSession::new(
215            access.provider(),
216            tokens,
217            custody,
218            self.clock.clone(),
219            self.http
220                .clone()
221                .map_err(|source| super::http_client::tls_failure(access.provider(), source))?,
222        )?;
223        request(OAuthFolders::new(session, access, api, cooldown)).await
224    }
225}
226
227#[async_trait::async_trait]
228impl StorageConnector for ProviderConnector {
229    async fn account_label(
230        &self,
231        auth: ProviderAuth,
232        cooldown: Arc<dyn crate::Cooldown>,
233    ) -> Result<String, StorageError> {
234        self.with_folders(auth, cooldown, |folders| async move { folders.account_label().await })
235            .await
236    }
237
238    async fn signed_in_account(
239        &self,
240        auth: ProviderAuth,
241        cooldown: Arc<dyn crate::Cooldown>,
242    ) -> Result<crate::ProviderAccount, StorageError> {
243        self.with_folders(auth, cooldown, |folders| async move { folders.account_identity().await })
244            .await
245    }
246
247    /// Read the signed-in OneDrive root.
248    async fn onedrive_root(
249        &self,
250        auth: ProviderAuth,
251        cooldown: Arc<dyn crate::Cooldown>,
252    ) -> Result<StorageFolder, StorageError> {
253        self.with_folders(auth, cooldown, |folders| async move { folders.onedrive_root().await })
254            .await
255    }
256
257    /// Read all immediate OneDrive child folders.
258    async fn onedrive_folders(
259        &self,
260        parent: &StorageConfig,
261        auth: ProviderAuth,
262        cooldown: Arc<dyn crate::Cooldown>,
263    ) -> Result<Vec<StorageFolder>, StorageError> {
264        self.with_folders(auth, cooldown, |folders| async move {
265            folders.onedrive_folders(parent).await
266        })
267        .await
268    }
269
270    /// Create a OneDrive folder without renaming or replacing an occupied name.
271    async fn create_onedrive_folder(
272        &self,
273        parent: &StorageConfig,
274        name: &str,
275        auth: ProviderAuth,
276        cooldown: Arc<dyn crate::Cooldown>,
277    ) -> Result<StorageFolder, StorageError> {
278        self.with_folders(auth, cooldown, |folders| async move {
279            folders.create_onedrive_folder(parent, name).await
280        })
281        .await
282    }
283
284    /// Read all shared Dropbox namespaces.
285    async fn dropbox_shared_folders(
286        &self,
287        auth: ProviderAuth,
288        cooldown: Arc<dyn crate::Cooldown>,
289    ) -> Result<Vec<StorageFolder>, StorageError> {
290        self.with_folders(auth, cooldown, |folders| async move {
291            folders.dropbox_shared_folders().await
292        })
293        .await
294    }
295
296    /// Make a folder named `name` at the top of the signed-in Dropbox and
297    /// share it, refusing a name already taken.
298    async fn create_dropbox_shared_folder(
299        &self,
300        name: &str,
301        auth: ProviderAuth,
302        cooldown: Arc<dyn crate::Cooldown>,
303    ) -> Result<StorageFolder, StorageError> {
304        self.with_folders(auth, cooldown, |folders| async move {
305            folders.create_dropbox_shared_folder(name).await
306        })
307        .await
308    }
309
310    async fn prepare_cloudkit(
311        &self,
312        container: &str,
313        store: StoreId,
314    ) -> Result<StorageConfig, StorageError> {
315        #[cfg(target_vendor = "apple")]
316        {
317            super::cloudkit::prepare(container, store).await
318        }
319        #[cfg(not(target_vendor = "apple"))]
320        {
321            let _ = (container, store);
322            Err(StorageFailure::ProviderUnavailable.into())
323        }
324    }
325    async fn connect(
326        &self,
327        config: StorageConfig,
328        auth: ProviderAuth,
329        device: DeviceId,
330        publications: Arc<dyn crate::PublicationGate>,
331        cooldown: Arc<dyn crate::Cooldown>,
332        transfers: Arc<crate::TransferBudget>,
333    ) -> Result<Arc<StorageConnection>, StorageError> {
334        crate::ConnectionCredentials { location: config.clone(), credentials: auth.credentials() }
335            .validate()?;
336        let provider = config.provider();
337        let http = self
338            .http
339            .clone()
340            .map_err(|source| super::http_client::tls_failure(provider, source))?;
341        let session = |tokens, custody| {
342            OAuthSession::new(provider, tokens, custody, self.clock.clone(), http.clone())
343        };
344        let provider: Arc<dyn ProviderOps> = match (&config, auth) {
345            (StorageConfig::S3 { .. }, ProviderAuth::S3(credentials)) => Arc::new(S3Storage::new(
346                config,
347                credentials,
348                self.clock.clone(),
349                self.ids.clone(),
350                cooldown.clone(),
351                http.clone(),
352            )?),
353            (StorageConfig::Dropbox { .. }, ProviderAuth::OAuth { tokens, custody }) => {
354                let session = session(tokens, custody)?;
355                Arc::new(DropboxStorage::new(config, session)?)
356            }
357            (StorageConfig::OneDrive { .. }, ProviderAuth::OAuth { tokens, custody }) => {
358                let session = session(tokens, custody)?;
359                Arc::new(OneDriveStorage::new(config, session, self.ids.clone())?)
360            }
361            (StorageConfig::CloudKit { .. }, ProviderAuth::CloudKit) => {
362                #[cfg(target_vendor = "apple")]
363                {
364                    Arc::new(super::CloudKitStorage::new(config, self.ids.clone()).await?)
365                }
366                #[cfg(not(target_vendor = "apple"))]
367                {
368                    return Err(StorageFailure::ProviderUnavailable.into());
369                }
370            }
371            _ => {
372                return Err(StorageFailure::InvalidConfiguration
373                    .with_source("credentials do not match the provider"))
374            }
375        };
376        let connection = StorageConnection::with_gate(
377            provider,
378            device,
379            publications,
380            cooldown,
381            transfers,
382            self.clock.clone(),
383        );
384        Ok(Arc::new(connection))
385    }
386    async fn detect_s3(
387        &self,
388        config: StorageConfig,
389        credentials: S3Credentials,
390        store: StoreId,
391        runs: &S3DetectionRuns,
392        waits: &crate::SetupWaits,
393    ) -> S3DetectionRun {
394        let valid = crate::ConnectionCredentials {
395            location: config.clone(),
396            credentials: StorageCredentials::S3(credentials.clone()),
397        }
398        .validate();
399        let http = self
400            .http
401            .clone()
402            .map_err(|source| super::http_client::tls_failure(crate::CloudProvider::S3, source));
403        let http = match valid.and(http) {
404            Ok(http) => http,
405            Err(error) => return S3DetectionRun::unwritten(runs, Err(error)),
406        };
407        super::detect_s3(
408            config,
409            credentials,
410            store,
411            runs,
412            self.clock.clone(),
413            self.ids.clone(),
414            http,
415            waits,
416        )
417        .await
418    }
419    async fn check_new_store(
420        &self,
421        config: StorageConfig,
422        auth: ProviderAuth,
423        store: StoreId,
424        waits: &crate::SetupWaits,
425    ) -> Result<(), StorageError> {
426        crate::ConnectionCredentials { location: config.clone(), credentials: auth.credentials() }
427            .validate()?;
428        if !config.holds_one_store() {
429            return Err(StorageFailure::InvalidConfiguration
430                .with_source("the location holds several stores, so nothing checks it"));
431        }
432        let provider = config.provider();
433        let http = self
434            .http
435            .clone()
436            .map_err(|source| super::http_client::tls_failure(provider, source))?;
437        let session = |tokens, custody| {
438            OAuthSession::new(provider, tokens, custody, self.clock.clone(), http.clone())
439        };
440        // Each page is one listing request: a rate-limited one stored nothing.
441        let clock = self.clock.as_ref();
442        let holds_only = match (&config, auth) {
443            (StorageConfig::S3 { .. }, ProviderAuth::S3(credentials)) => {
444                return super::check_new_s3_store(
445                    config,
446                    credentials,
447                    store,
448                    self.clock.clone(),
449                    self.ids.clone(),
450                    http,
451                    waits,
452                )
453                .await
454            }
455            (StorageConfig::Dropbox { .. }, ProviderAuth::OAuth { tokens, custody }) => {
456                let dropbox = DropboxStorage::new(config, session(tokens, custody)?)?;
457                waits.resend(clock, || dropbox.holds_only(store)).await?
458            }
459            (StorageConfig::OneDrive { .. }, ProviderAuth::OAuth { tokens, custody }) => {
460                let onedrive =
461                    OneDriveStorage::new(config, session(tokens, custody)?, self.ids.clone())?;
462                waits.resend(clock, || onedrive.holds_only(store)).await?
463            }
464            _ => {
465                return Err(StorageFailure::InvalidConfiguration
466                    .with_source("credentials do not match the provider"))
467            }
468        };
469        if !holds_only {
470            return Err(StorageFailure::OwnLocationRequired.into());
471        }
472        Ok(())
473    }
474}
475
476#[cfg(all(test, not(target_vendor = "apple")))]
477#[path = "connector_tests.rs"]
478mod tests;