backbone_storage/
traits.rs

1//! Storage service traits
2
3use async_trait::async_trait;
4use crate::{
5    StorageResult, StorageFile, StorageConfig, StorageStats,
6    UploadOptions, DownloadOptions, PresignedUrlOptions, ByteRange,
7    types::EncryptionConfig,
8};
9use std::collections::HashMap;
10use bytes::Bytes;
11
12/// Generic storage service trait
13#[async_trait]
14pub trait StorageService: Send + Sync {
15    /// Upload a file from bytes
16    async fn upload_bytes(
17        &self,
18        path: &str,
19        data: Bytes,
20        options: Option<UploadOptions>,
21    ) -> StorageResult<StorageFile>;
22
23    /// Upload a file from a reader
24    async fn upload_reader(
25        &self,
26        path: &str,
27        reader: Box<dyn tokio::io::AsyncRead + Send + Unpin>,
28        size: Option<u64>,
29        options: Option<UploadOptions>,
30    ) -> StorageResult<StorageFile>;
31
32    /// Upload a file from local path
33    async fn upload_file(
34        &self,
35        path: &str,
36        local_path: &str,
37        options: Option<UploadOptions>,
38    ) -> StorageResult<StorageFile>;
39
40    /// Download a file to bytes
41    async fn download_bytes(
42        &self,
43        path: &str,
44        options: Option<DownloadOptions>,
45    ) -> StorageResult<Bytes>;
46
47    /// Download a file to a writer
48    async fn download_writer(
49        &self,
50        path: &str,
51        writer: Box<dyn tokio::io::AsyncWrite + Send + Unpin>,
52        options: Option<DownloadOptions>,
53    ) -> StorageResult<()>;
54
55    /// Download a file to local path
56    async fn download_file(
57        &self,
58        path: &str,
59        local_path: &str,
60        options: Option<DownloadOptions>,
61    ) -> StorageResult<()>;
62
63    /// Stream a file (useful for large files)
64    async fn stream_file(
65        &self,
66        path: &str,
67        range: Option<ByteRange>,
68    ) -> StorageResult<Box<dyn futures::stream::Stream<Item = StorageResult<Bytes>> + Send + Unpin>>;
69
70    /// Get file metadata
71    async fn get_file(&self, path: &str) -> StorageResult<StorageFile>;
72
73    /// Check if file exists
74    async fn file_exists(&self, path: &str) -> StorageResult<bool>;
75
76    /// Delete a file
77    async fn delete_file(&self, path: &str) -> StorageResult<bool>;
78
79    /// Copy a file
80    async fn copy_file(&self, from_path: &str, to_path: &str) -> StorageResult<StorageFile>;
81
82    /// Move a file
83    async fn move_file(&self, from_path: &str, to_path: &str) -> StorageResult<StorageFile>;
84
85    /// List files in a directory/prefix
86    async fn list_files(
87        &self,
88        prefix: &str,
89        limit: Option<u32>,
90        continuation_token: Option<String>,
91    ) -> StorageResult<FileListResult>;
92
93    /// Generate presigned URL for file operations
94    async fn generate_presigned_url(
95        &self,
96        path: &str,
97        options: PresignedUrlOptions,
98    ) -> StorageResult<String>;
99
100    /// Get file URL (public access or presigned)
101    async fn get_file_url(
102        &self,
103        path: &str,
104        expiry_seconds: Option<u64>,
105    ) -> StorageResult<String>;
106
107    /// Update file metadata
108    async fn update_metadata(
109        &self,
110        path: &str,
111        metadata: HashMap<String, String>,
112    ) -> StorageResult<StorageFile>;
113
114    /// Get storage statistics
115    async fn get_stats(&self) -> StorageResult<StorageStats>;
116
117    /// Test storage connection
118    async fn test_connection(&self) -> StorageResult<bool>;
119
120    /// Get storage backend type
121    fn backend_type(&self) -> crate::StorageBackend;
122
123    /// Get bucket/container name
124    fn bucket(&self) -> &str;
125
126    /// Get configuration
127    fn config(&self) -> &StorageConfig;
128}
129
130/// Storage management trait for administrative operations
131#[async_trait]
132pub trait StorageManager: Send + Sync {
133    /// Create a new bucket/container
134    async fn create_bucket(&self, bucket_name: &str, config: Option<BucketConfig>) -> StorageResult<bool>;
135
136    /// Delete a bucket/container
137    async fn delete_bucket(&self, bucket_name: &str, force: bool) -> StorageResult<bool>;
138
139    /// List all buckets/containers
140    async fn list_buckets(&self) -> StorageResult<Vec<String>>;
141
142    /// Get bucket/container information
143    async fn get_bucket_info(&self, bucket_name: &str) -> StorageResult<BucketInfo>;
144
145    /// Set bucket lifecycle rules
146    async fn set_lifecycle_rules(
147        &self,
148        bucket_name: &str,
149        rules: Vec<LifecycleRule>,
150    ) -> StorageResult<bool>;
151
152    /// Enable bucket versioning
153    async fn enable_versioning(&self, bucket_name: &str) -> StorageResult<bool>;
154
155    /// Disable bucket versioning
156    async fn disable_versioning(&self, bucket_name: &str) -> StorageResult<bool>;
157
158    /// Set bucket access control
159    async fn set_access_control(
160        &self,
161        bucket_name: &str,
162        policy: AccessPolicy,
163    ) -> StorageResult<bool>;
164
165    /// Get bucket access control
166    async fn get_access_control(&self, bucket_name: &str) -> StorageResult<AccessPolicy>;
167
168    /// Restore from backup
169    async fn restore_backup(
170        &self,
171        backup_path: &str,
172        target_bucket: &str,
173        target_prefix: Option<String>,
174    ) -> StorageResult<RestoreResult>;
175
176    /// Create backup
177    async fn create_backup(
178        &self,
179        bucket_name: &str,
180        backup_path: &str,
181        prefix_filter: Option<String>,
182    ) -> StorageResult<BackupResult>;
183}
184
185/// Storage monitoring trait
186#[async_trait]
187pub trait StorageMonitor: Send + Sync {
188    /// Start monitoring storage operations
189    async fn start_monitoring(&self, bucket_name: &str) -> StorageResult<()>;
190
191    /// Stop monitoring storage operations
192    async fn stop_monitoring(&self, bucket_name: &str) -> StorageResult<()>;
193
194    /// Get real-time metrics
195    async fn get_metrics(&self, bucket_name: &str) -> StorageResult<HashMap<String, f64>>;
196
197    /// Set alert thresholds
198    async fn set_alert_thresholds(
199        &self,
200        bucket_name: &str,
201        thresholds: AlertThresholds,
202    ) -> StorageResult<()>;
203
204    /// Get current alerts
205    async fn get_alerts(&self, bucket_name: &str) -> StorageResult<Vec<StorageAlert>>;
206
207    /// Get usage trends
208    async fn get_usage_trends(
209        &self,
210        bucket_name: &str,
211        period: TrendPeriod,
212    ) -> StorageResult<UsageTrend>;
213
214    /// Generate storage report
215    async fn generate_report(
216        &self,
217        bucket_name: &str,
218        report_type: ReportType,
219    ) -> StorageResult<StorageReport>;
220}
221
222/// Result type for file listing operations
223#[derive(Debug, Clone)]
224pub struct FileListResult {
225    /// List of files
226    pub files: Vec<StorageFile>,
227
228    /// Common prefixes (directories)
229    pub prefixes: Vec<String>,
230
231    /// Whether there are more results
232    pub truncated: bool,
233
234    /// Token for next page of results
235    pub next_continuation_token: Option<String>,
236
237    /// Total number of files (if available)
238    pub total_count: Option<u64>,
239}
240
241/// Bucket configuration
242#[derive(Debug, Clone)]
243pub struct BucketConfig {
244    /// Geographic region
245    pub region: Option<String>,
246
247    /// Access policy
248    pub access_policy: Option<AccessPolicy>,
249
250    /// Storage class
251    pub storage_class: Option<String>,
252
253    /// Enable versioning
254    pub versioning: Option<bool>,
255
256    /// Lifecycle rules
257    pub lifecycle_rules: Option<Vec<LifecycleRule>>,
258
259    /// Tags
260    pub tags: Option<HashMap<String, String>>,
261
262    /// Encryption settings
263    pub encryption: Option<EncryptionConfig>,
264}
265
266/// Bucket information
267#[derive(Debug, Clone)]
268pub struct BucketInfo {
269    /// Bucket name
270    pub name: String,
271
272    /// Creation timestamp
273    pub created_at: chrono::DateTime<chrono::Utc>,
274
275    /// Geographic region
276    pub region: String,
277
278    /// Storage class
279    pub storage_class: String,
280
281    /// Versioning status
282    pub versioning: VersioningStatus,
283
284    /// Access policy
285    pub access_policy: AccessPolicy,
286
287    /// Total size in bytes
288    pub size_bytes: u64,
289
290    /// Number of objects
291    pub object_count: u64,
292
293    /// Tags
294    pub tags: HashMap<String, String>,
295}
296
297/// Versioning status
298#[derive(Debug, Clone, Copy, PartialEq, Eq)]
299pub enum VersioningStatus {
300    Enabled,
301    Suspended,
302    Disabled,
303}
304
305/// Lifecycle rule
306#[derive(Debug, Clone)]
307pub struct LifecycleRule {
308    /// Rule ID
309    pub id: String,
310
311    /// Rule status
312    pub status: LifecycleRuleStatus,
313
314    /// Filter for objects
315    pub filter: LifecycleFilter,
316
317    /// Action to perform
318    pub action: LifecycleAction,
319}
320
321/// Lifecycle rule status
322#[derive(Debug, Clone, Copy, PartialEq, Eq)]
323pub enum LifecycleRuleStatus {
324    Enabled,
325    Disabled,
326}
327
328/// Lifecycle filter
329#[derive(Debug, Clone)]
330pub struct LifecycleFilter {
331    /// Object prefix
332    pub prefix: Option<String>,
333
334    /// Object tags
335    pub tags: Option<HashMap<String, String>>,
336
337    /// Object size range
338    pub size_range: Option<(u64, u64)>,
339}
340
341/// Lifecycle action
342#[derive(Debug, Clone)]
343pub struct LifecycleAction {
344    /// Action type
345    pub action_type: LifecycleActionType,
346
347    /// Number of days for transition/expiration
348    pub days: Option<u32>,
349
350    /// Storage class for transition
351    pub storage_class: Option<String>,
352}
353
354/// Lifecycle action types
355#[derive(Debug, Clone, Copy, PartialEq, Eq)]
356pub enum LifecycleActionType {
357    /// Delete object
358    Delete,
359
360    /// Transition to different storage class
361    Transition,
362
363    /// Expire object
364    Expire,
365
366    /// Archive to glacier
367    Archive,
368}
369
370/// Access policy
371#[derive(Debug, Clone, Copy, PartialEq, Eq)]
372pub enum AccessPolicy {
373    Private,
374    PublicRead,
375    PublicReadWrite,
376    Custom,
377}
378
379/// Restore operation result
380#[derive(Debug, Clone)]
381pub struct RestoreResult {
382    /// Number of files restored
383    pub files_restored: u64,
384
385    /// Total bytes restored
386    pub bytes_restored: u64,
387
388    /// Number of files failed
389    pub files_failed: u64,
390
391    /// Errors encountered
392    pub errors: Vec<String>,
393
394    /// Duration in seconds
395    pub duration_seconds: u64,
396}
397
398/// Backup operation result
399#[derive(Debug, Clone)]
400pub struct BackupResult {
401    /// Number of files backed up
402    pub files_backed_up: u64,
403
404    /// Total bytes backed up
405    pub bytes_backed_up: u64,
406
407    /// Backup file path
408    pub backup_path: String,
409
410    /// Checksum of backup
411    pub backup_checksum: String,
412
413    /// Number of files skipped
414    pub files_skipped: u64,
415
416    /// Errors encountered
417    pub errors: Vec<String>,
418
419    /// Duration in seconds
420    pub duration_seconds: u64,
421}
422
423/// Alert thresholds
424#[derive(Debug, Clone)]
425pub struct AlertThresholds {
426    /// Storage usage percentage (0-100)
427    pub storage_usage_percent: Option<f64>,
428
429    /// File count limit
430    pub file_count_limit: Option<u64>,
431
432    /// Large file size threshold in bytes
433    pub large_file_threshold: Option<u64>,
434
435    /// Error rate percentage (0-100)
436    pub error_rate_percent: Option<f64>,
437
438    /// Average response time in milliseconds
439    pub avg_response_time_ms: Option<f64>,
440}
441
442/// Storage alert
443#[derive(Debug, Clone)]
444pub struct StorageAlert {
445    /// Alert ID
446    pub id: String,
447
448    /// Alert type
449    pub alert_type: StorageAlertType,
450
451    /// Alert severity
452    pub severity: AlertSeverity,
453
454    /// Alert message
455    pub message: String,
456
457    /// Alert timestamp
458    pub timestamp: chrono::DateTime<chrono::Utc>,
459
460    /// Associated bucket
461    pub bucket: String,
462
463    /// Additional details
464    pub details: HashMap<String, String>,
465}
466
467/// Storage alert types
468#[derive(Debug, Clone, Copy, PartialEq, Eq)]
469pub enum StorageAlertType {
470    StorageUsage,
471    FileCount,
472    LargeFile,
473    ErrorRate,
474    ResponseTime,
475    ConnectionFailure,
476    PermissionDenied,
477}
478
479/// Alert severity
480#[derive(Debug, Clone, Copy, PartialEq, Eq)]
481pub enum AlertSeverity {
482    Info,
483    Warning,
484    Error,
485    Critical,
486}
487
488/// Trend period for analytics
489#[derive(Debug, Clone, Copy, PartialEq, Eq)]
490pub enum TrendPeriod {
491    LastHour,
492    Last24Hours,
493    Last7Days,
494    Last30Days,
495    Custom { hours: u32 },
496}
497
498/// Usage trend data
499#[derive(Debug, Clone)]
500pub struct UsageTrend {
501    /// Trend period
502    pub period: TrendPeriod,
503
504    /// Data points
505    pub data_points: Vec<TrendDataPoint>,
506
507    /// Growth rate (percentage)
508    pub growth_rate: f64,
509
510    /// Predicted usage for next period
511    pub predicted_usage: Option<u64>,
512}
513
514/// Trend data point
515#[derive(Debug, Clone)]
516pub struct TrendDataPoint {
517    /// Timestamp
518    pub timestamp: chrono::DateTime<chrono::Utc>,
519
520    /// Storage usage in bytes
521    pub usage_bytes: u64,
522
523    /// File count
524    pub file_count: u64,
525
526    /// Number of operations
527    pub operations: u64,
528}
529
530/// Report type
531#[derive(Debug, Clone, Copy, PartialEq, Eq)]
532pub enum ReportType {
533    Usage,
534    Performance,
535    Cost,
536    Security,
537    Compliance,
538}
539
540/// Storage report
541#[derive(Debug, Clone)]
542pub struct StorageReport {
543    /// Report type
544    pub report_type: ReportType,
545
546    /// Generated at timestamp
547    pub generated_at: chrono::DateTime<chrono::Utc>,
548
549    /// Report data
550    pub data: serde_json::Value,
551
552    /// Summary statistics
553    pub summary: HashMap<String, String>,
554
555    /// Recommendations
556    pub recommendations: Vec<String>,
557}
backbone_storage/traits.rs

backbone_storage/
traits.rs
