FileSyncHub API Documentation

Welcome to the FileSyncHub API documentation. This section provides detailed information about the public API for developers who want to integrate with or extend FileSyncHub.

Core Traits

SyncPlugin

The main trait for implementing cloud storage plugins:

use async_trait::async_trait;
use std::path::Path;

#[async_trait]
pub trait SyncPlugin: Send + Sync {
    /// Initialize the plugin
    async fn init(&mut self) -> Result<()>;
    
    /// Upload a file to remote storage
    async fn upload_file(&self, path: &Path) -> Result<()>;
    
    /// Download a file from remote storage
    async fn download_file(&self, path: &Path) -> Result<()>;
    
    /// List files in remote storage
    async fn list_files(&self) -> Result<Vec<FileInfo>>;
    
    /// Clean up resources
    async fn cleanup(&mut self) -> Result<()>;
}

EventHandler

Trait for handling file system events:

#[async_trait]
pub trait EventHandler: Send + Sync {
    /// Handle a file system event
    async fn handle_event(&self, event: Event) -> Result<()>;
    
    /// Handle multiple events in batch
    async fn handle_events(&self, events: Vec<Event>) -> Result<()>;
}

Core Types

FileInfo

Information about a file in the sync system:

#[derive(Debug, Clone, Eq, PartialEq)]
pub struct FileInfo {
    /// File path relative to sync root
    pub path: PathBuf,
    
    /// File metadata
    pub metadata: FileMetadata,
    
    /// File status
    pub status: FileStatus,
}

Event

File system events that trigger sync actions:

#[derive(Debug, Clone)]
pub enum Event {
    /// File created
    FileCreated(PathBuf),
    
    /// File modified
    FileModified(PathBuf),
    
    /// File deleted
    FileDeleted(PathBuf),
    
    /// File renamed
    FileRenamed {
        from: PathBuf,
        to: PathBuf,
    },
}

Error Handling

Error Types

Custom error types for different failure scenarios:

#[derive(Error, Debug)]
pub enum Error {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    
    #[error("Authentication failed: {0}")]
    Auth(String),
    
    #[error("Network error: {0}")]
    Network(String),
    
    #[error("Plugin error: {0}")]
    Plugin(String),
}

pub type Result<T> = std::result::Result<T, Error>;

Configuration

Config Types

Configuration structures for FileSyncHub:

#[derive(Debug, Deserialize)]
pub struct Config {
    /// General settings
    pub general: GeneralConfig,
    
    /// Sync settings
    pub sync: SyncConfig,
    
    /// Plugin configurations
    pub plugins: HashMap<String, PluginConfig>,
}

Plugin Development

Creating a Plugin

Basic structure for implementing a new plugin:

use filesynchub::plugin::{SyncPlugin, Result};

pub struct MyPlugin {
    config: PluginConfig,
}

#[async_trait]
impl SyncPlugin for MyPlugin {
    async fn init(&mut self) -> Result<()> {
        // Initialize plugin
        Ok(())
    }
    
    async fn upload_file(&self, path: &Path) -> Result<()> {
        // Implement file upload
        Ok(())
    }
    
    // Implement other required methods...
}

Usage Examples

Basic Usage

use filesynchub::{FileSyncHub, Config};

#[tokio::main]
async fn main() -> Result<()> {
    // Load configuration
    let config = Config::load("config.toml")?;
    
    // Create FileSyncHub instance
    let mut sync_hub = FileSyncHub::new(config);
    
    // Initialize
    sync_hub.init().await?;
    
    // Start syncing
    sync_hub.start().await?;
    
    Ok(())
}

Plugin Registration

use filesynchub::PluginRegistry;

#[tokio::main]
async fn main() -> Result<()> {
    let mut registry = PluginRegistry::new();
    
    // Register custom plugin
    let plugin = MyPlugin::new(config);
    registry.register("my-plugin", Box::new(plugin));
    
    Ok(())
}

API Stability

FileSyncHub follows semantic versioning:

Stability Guarantees

Best Practices

Error Handling

use filesynchub::{Result, Error};

async fn example() -> Result<()> {
    // Use ? operator for error propagation
    let file = File::open("test.txt")
        .await
        .map_err(Error::io)?;
    
    // Use context for better error messages
    process_file(file)
        .await
        .context("Failed to process file")?;
    
    Ok(())
}

Async Operations

use tokio::time::{timeout, Duration};

async fn with_timeout<F, T>(future: F) -> Result<T>
where
    F: Future<Output = Result<T>>,
{
    timeout(Duration::from_secs(30), future)
        .await
        .map_err(|_| Error::timeout())?
}

API Reference

For detailed API documentation, see the following sections:

Contributing

For information about contributing to FileSyncHub, see: