Expand description
Files.com Rust SDK
A comprehensive Rust client for the Files.com REST API, providing full access to file operations, user management, sharing, automation, and administrative features.
§Features
- File Operations: Upload, download, copy, move, delete files and folders
- User & Access Management: Users, groups, permissions, API keys, sessions
- Sharing: Bundles (share links), file requests, inbox uploads
- Automation: Webhooks, behaviors, remote servers, automations
- Administration: Site settings, history, notifications, billing
§Quick Start
use files_sdk::{FilesClient, files::FileHandler};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create client with API key
let client = FilesClient::builder()
.api_key("your-api-key")
.build()?;
// Use handlers for typed operations
let file_handler = FileHandler::new(client.clone());
// Upload a file
let data = b"Hello, Files.com!";
file_handler.upload_file("/path/to/file.txt", data).await?;
Ok(())
}§Core Usage Patterns
§Client Creation
The client uses a builder pattern for flexible configuration:
use files_sdk::FilesClient;
// Basic client with default settings
let client = FilesClient::builder()
.api_key("your-api-key")
.build()?;
// Custom configuration
let client = FilesClient::builder()
.api_key("your-api-key")
.base_url("https://app.files.com/api/rest/v1".to_string())
.timeout(std::time::Duration::from_secs(60))
.build()?;§Middleware with Tower (Optional)
For retry logic, rate limiting, and observability, use the optional tower feature:
[dependencies]
files-sdk = { version = "0.3", features = ["tower"] }
tower = "0.5"
tower-http = { version = "0.6", features = ["retry", "trace"] }See the tower_* examples in the examples directory for complete working code.
Benefits of Tower middleware:
- Composable: Mix and match middleware layers
- Battle-tested: Use proven crates from the tower ecosystem
- Customizable: Full control over retry, rate limiting, tracing
- Reusable: Share middleware across different HTTP clients
§File Upload (Two-Stage Process)
Files.com uses a two-stage upload process:
use files_sdk::{FilesClient, files::{FileActionHandler, FileHandler}};
let client = FilesClient::builder()
.api_key("your-api-key")
.build()?;
// Stage 1: Begin upload to get upload URLs
let file_action = FileActionHandler::new(client.clone());
let upload_info = file_action
.begin_upload("/uploads/myfile.txt", Some(1024), true)
.await?;
// Stage 2: Upload file data (simplified - see FileHandler for complete implementation)
let file_handler = FileHandler::new(client.clone());
let data = b"file contents";
file_handler.upload_file("/uploads/myfile.txt", data).await?;§Error Handling
The SDK provides comprehensive error handling:
use files_sdk::{FilesClient, FilesError, files::FileHandler};
let client = FilesClient::builder()
.api_key("test-key")
.build()
.unwrap();
let handler = FileHandler::new(client);
match handler.download_file("/path/to/file.txt").await {
Ok(file) => println!("Downloaded: {:?}", file),
Err(FilesError::NotFound { message, .. }) => {
println!("File not found: {}", message);
}
Err(FilesError::AuthenticationFailed { message, .. }) => {
println!("Invalid API key: {}", message);
}
Err(e) => println!("Other error: {}", e),
}§Authentication
Files.com uses API key authentication via the X-FilesAPI-Key header.
API keys can be obtained from the Files.com web interface under Account Settings.
Re-exports§
pub use client::FilesClient;pub use client::FilesClientBuilder;pub use error::FilesError;pub use error::Result;pub use types::FileEntity;pub use types::FileUploadPartEntity;pub use types::FolderEntity;pub use types::PaginationInfo;pub use admin::ActionNotificationExportHandler;pub use admin::ActionNotificationExportResultHandler;pub use admin::ChildSiteManagementPolicyHandler;pub use admin::DnsRecordHandler;pub use admin::HistoryExportHandler2;pub use admin::HistoryExportResultHandler2;pub use admin::HistoryHandler;pub use admin::HolidayRegionHandler;pub use admin::InvoiceHandler;pub use admin::PaymentHandler;pub use admin::SiteHandler;pub use admin::StyleHandler;pub use as2::As2IncomingMessageHandler;pub use as2::As2OutgoingMessageHandler;pub use as2::As2PartnerHandler;pub use as2::As2StationHandler;pub use automation::AutomationHandler;pub use automation::AutomationRunHandler;pub use automation::BehaviorHandler;pub use automation::RemoteMountBackendHandler;pub use automation::RemoteServerHandler;pub use automation::SyncHandler;pub use automation::SyncRunHandler;pub use developers::AppHandler;pub use files::FileActionHandler;pub use files::FileCommentHandler;pub use files::FileCommentReactionHandler;pub use files::FileHandler;pub use files::FileMigrationHandler;pub use files::FileMigrationLogHandler;pub use files::FolderHandler;pub use integrations::SiemHttpDestinationHandler;pub use logs::ApiRequestLogHandler;pub use logs::AutomationLogHandler;pub use logs::EmailIncomingMessageHandler;pub use logs::EmailLogHandler;pub use logs::ExavaultApiRequestLogHandler;pub use logs::ExternalEventHandler;pub use logs::FtpActionLogHandler;pub use logs::OutboundConnectionLogHandler;pub use logs::PublicHostingRequestLogHandler;pub use logs::SettingsChangeHandler;pub use logs::SftpActionLogHandler;pub use logs::SyncLogHandler;pub use logs::WebDavActionLogHandler;pub use messages::MessageCommentHandler;pub use messages::MessageCommentReactionHandler;pub use messages::MessageHandler;pub use messages::MessageReactionHandler;pub use messages::NotificationHandler;pub use security::ClickwrapHandler;pub use security::GpgKeyHandler;pub use security::IpAddressHandler;pub use security::SftpHostKeyHandler;pub use sharing::BundleActionHandler;pub use sharing::BundleDownloadHandler;pub use sharing::BundleHandler;pub use sharing::BundleNotificationHandler;pub use sharing::BundleRecipientHandler;pub use sharing::BundleRegistrationHandler;pub use sharing::FormFieldSetHandler;pub use sharing::InboxRecipientHandler;pub use sharing::InboxRegistrationHandler2;pub use sharing::InboxUploadHandler;pub use sharing::RequestHandler;pub use storage::BandwidthSnapshotHandler;pub use storage::LockHandler;pub use storage::PriorityHandler;pub use storage::ProjectHandler;pub use storage::RemoteBandwidthSnapshotHandler;pub use storage::RestoreHandler;pub use storage::SnapshotHandler;pub use storage::UsageDailySnapshotHandler;pub use storage::UsageSnapshotHandler;pub use users::ApiKeyCurrentHandler;pub use users::ApiKeyHandler;pub use users::CurrentUserHandler;pub use users::GroupHandler;pub use users::GroupUserHandler;pub use users::PermissionHandler;pub use users::PublicKeyHandler;pub use users::SessionHandler;pub use users::SsoStrategyHandler;pub use users::UserCipherUseHandler;pub use users::UserHandler;pub use users::UserLifecycleRuleHandler;pub use users::UserRequestHandler;pub use users::UserSftpClientUseHandler;
Modules§
- admin
- Administration and billing module
- as2
- AS2 protocol module
- automation
- Automation and integration module
- client
- Files.com API client core implementation
- developers
- Developers module
- error
- Error types for the Files.com SDK
- files
- File operations module
- integrations
- Integrations module
- logs
- Logging and audit module
- messages
- Messaging and notifications module
- prelude
- Convenient re-exports for common types and traits
- progress
- Progress tracking for file operations
- security
- Security and compliance module
- sharing
- File sharing and collaboration module
- storage
- Storage management module
- types
- Common types for Files.com API
- users
- User authentication and access control module
- utils
- Utility functions for the Files.com SDK
- webhook_
tests