[Phase 1.2] Define Storage trait and error types

[zhexuany]

Summary

Define the core Storage trait and associated error types that will be implemented by both local filesystem and cloud storage backends.

Parent Epic

• [Epic] Distributed Roboflow with Alibaba Cloud (OSS + ACK) #9 Distributed Roboflow with Alibaba Cloud

Dependencies

• Depends on: [Phase 1.1] Add core dependencies for storage abstraction #10 (Core dependencies)

Tasks

1. Create src/storage/mod.rs module file
2. Define StorageError enum covering all failure modes:
   • NotFound - Object does not exist
   • PermissionDenied - Access denied
   • AlreadyExists - Object already exists (for exclusive create)
   • InvalidPath - Malformed path or URL
   • NetworkError - Network connectivity issue
   • Timeout - Operation timed out
   • IoError - Wrapping std::io::Error
   • Other - Catch-all with message
3. Define ObjectMetadata struct with fields:
   • size: u64
   • last_modified: Option<chrono::DateTime<Utc>>
   • content_type: Option<String>
   • etag: Option<String>
4. Define synchronous Storage trait with methods:
   • fn reader(&self, path: &str) -> Result<Box<dyn Read + Send>, StorageError>
   • fn writer(&self, path: &str) -> Result<Box<dyn Write + Send>, StorageError>
   • fn exists(&self, path: &str) -> Result<bool, StorageError>
   • fn size(&self, path: &str) -> Result<u64, StorageError>
   • fn metadata(&self, path: &str) -> Result<ObjectMetadata, StorageError>
   • fn list(&self, prefix: &str) -> Result<Vec<String>, StorageError>
   • fn delete(&self, path: &str) -> Result<(), StorageError>
   • fn copy(&self, from: &str, to: &str) -> Result<(), StorageError>
5. Define SeekableStorage extension trait for backends supporting seek
6. Implement std::error::Error for StorageError
7. Implement From<std::io::Error> for StorageError
8. Add module to src/lib.rs exports
9. Write documentation for all public types

Acceptance Criteria

• StorageError enum defined with all variants
• ObjectMetadata struct defined
• Storage trait defined with all methods
• SeekableStorage trait defined
• Error conversions implemented
• Module exported in src/lib.rs
• All public items documented
• Code compiles without warnings

Files to Create/Modify

• src/storage/mod.rs (new)
• src/storage/error.rs (new, optional - can be in mod.rs)
• src/lib.rs (add module export)

Design Notes

• Trait uses synchronous API to minimize changes to existing code
• Box<dyn Read/Write> allows flexibility in implementation
• Cloud backends will use internal tokio runtime for blocking