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:

#[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: Core trait definitions, list item metadata (StorageItem), sync policies (SyncPolicy), and error types (StorageError).
• providers/: Submodule housing specific client implementations and helpers:
  • google_drive.rs: Google Drive REST API integration.
  • dropbox.rs: Dropbox REST API integration. Includes pagination listing loop.
  • onedrive.rs: Microsoft OneDrive Graph API integration. Includes pagination listing loop.
  • webdav.rs: WebDAV client integration.
  • s3.rs: Amazon S3 and S3-Compatible API integration.
  • sftp.rs: SFTP client integration.
  • nextcloud.rs: Nextcloud WebDAV & OCS client integration.
  • azure_blob.rs: Azure Blob Storage REST API integration.
  • gcs.rs: Google Cloud Storage JSON API integration.
  • b2.rs: Backblaze B2 REST API integration. Includes pagination listing loop.
  • pcloud.rs: pCloud REST API integration.
  • ipfs.rs: IPFS Pinning Service REST API integration.
  • box_provider.rs: Box storage API integration.
  • mega_provider.rs: MEGA cloud storage encrypted client integration.
  • local_sim.rs: Shared local fallback simulator (LocalSimulation) implementing local folder operations for offline testing.
  • encryption.rs: Client-side zero-knowledge encryption decorator. Implements PBKDF2-HMAC-SHA256 key derivation and secure Unix 0600 file permissions.
  • 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/ module to enable dynamic backend configuration parsing and instantiation:

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.

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 for examples of automated mock HTTP flow tests. Real integration tests automatically skip gracefully when configuration is missing or tokens are expired.