cloud_sync_lib 0.1.0

Cloud storage provider synchronization library
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# `cloud_sync_lib`


A modular Rust library providing clean abstractions and clients to interface with cloud storage backends.

---

## Core Abstractions


All providers implement the `StorageBackend` trait defined in [`traits.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/traits.rs):

```rust
#[async_trait]

pub trait StorageBackend: Send + Sync {
    fn name(&self) -> &str;
    async fn upload(&self, local_path: &Path, remote_path: &str) -> Result<(), StorageError>;
    async fn download(&self, remote_path: &str, local_path: &Path) -> Result<(), StorageError>;
    async fn delete(&self, remote_path: &str) -> Result<(), StorageError>;
    async fn list(&self, remote_path: &str) -> Result<Vec<StorageItem>, StorageError>;
    async fn create_folder(&self, remote_path: &str) -> Result<(), StorageError>;
}
```

---

## Crate Layout


- **[`traits.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/traits.rs)**: Core trait definitions, list item metadata (`StorageItem`), sync policies (`SyncPolicy`), and error types (`StorageError`).
- **[`providers/`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/)**: Submodule housing specific client implementations and helpers:
  - [`google_drive.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/google_drive.rs): Google Drive REST API integration.
  - [`dropbox.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/dropbox.rs): Dropbox REST API integration. Includes pagination listing loop.
  - [`onedrive.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/onedrive.rs): Microsoft OneDrive Graph API integration. Includes pagination listing loop.
  - [`webdav.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/webdav.rs): WebDAV client integration.
  - [`s3.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/s3.rs): Amazon S3 and S3-Compatible API integration.
  - [`sftp.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/sftp.rs): SFTP client integration.
  - [`nextcloud.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/nextcloud.rs): Nextcloud WebDAV & OCS client integration.
  - [`azure_blob.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/azure_blob.rs): Azure Blob Storage REST API integration.
  - [`gcs.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/gcs.rs): Google Cloud Storage JSON API integration.
  - [`b2.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/b2.rs): Backblaze B2 REST API integration. Includes pagination listing loop.
  - [`pcloud.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/pcloud.rs): pCloud REST API integration.
  - [`ipfs.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/ipfs.rs): IPFS Pinning Service REST API integration.
  - [`box_provider.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/box_provider.rs): Box storage API integration.
  - [`mega_provider.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/mega_provider.rs): MEGA cloud storage encrypted client integration.
  - [`local_sim.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/local_sim.rs): Shared local fallback simulator (`LocalSimulation`) implementing local folder operations for offline testing.
  - [`encryption.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/encryption.rs): Client-side zero-knowledge encryption decorator. Implements PBKDF2-HMAC-SHA256 key derivation and secure Unix `0600` file permissions.
  - [`utils.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/utils.rs): Helpers for OAuth2, HTTP error response mapping, transient retry timing tests.

---

## Backend Registry (Dynamic Instantiation)


The library provides `BackendRegistry` and `BackendCredentials` inside the [`providers/`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/mod.rs) module to enable dynamic backend configuration parsing and instantiation:

```rust
use cloud_sync_lib::{BackendRegistry, BackendCredentials};

// Instantiate any backend dynamically by passing its matching enum variant
let provider = BackendRegistry::build(BackendCredentials::S3(s3_credentials));
```

---

## Local Simulation Fallback


When `OAuthCredentials` (or other provider credentials) are passed as `None` to a provider constructor, the client automatically defaults to **Simulation Mode**, which is powered by the shared `LocalSimulation` struct inside [`local_sim.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/providers/local_sim.rs).

Instead of connecting to remote web APIs, the providers delegate file operations (upload, download, listing, deletion) to this helper. It maps and copies files inside the local simulation directories:
* Google Drive simulated root: `./cloud_simulation/google_drive`
* Dropbox simulated root: `./cloud_simulation/dropbox`
* OneDrive simulated root: `./cloud_simulation/onedrive`
* WebDAV simulated root: `./cloud_simulation/webdav`
* S3 simulated root: `./cloud_simulation/s3`
* SFTP simulated root: `./cloud_simulation/sftp`
* Nextcloud simulated root: `./cloud_simulation/nextcloud`
* Azure Blob simulated root: `./cloud_simulation/azure_blob`
* GCS simulated root: `./cloud_simulation/gcs`
* B2 simulated root: `./cloud_simulation/b2`
* pCloud simulated root: `./cloud_simulation/pcloud`
* IPFS simulated root: `./cloud_simulation/ipfs`
* Box simulated root: `./cloud_simulation/box`
* MEGA simulated root: `./cloud_simulation/mega`

This layout keeps all providers DRY (Don't Repeat Yourself) while allowing full development and testing without internet access or active cloud tokens.

---

## Testing & Mocking


All providers support dynamic endpoint redirection for automated testing using `wiremock`:
- Google Drive: `.with_endpoints(auth_url, api_url, upload_url)`
- Dropbox: `.with_endpoints(auth_url, api_url, content_url)`

Check [`lib.rs`](file:///home/robt/projects/cloud_sync_lib/cloud_sync_lib/src/lib.rs) for examples of automated mock HTTP flow tests.
Real integration tests automatically skip gracefully when configuration is missing or tokens are expired.