Oxicloud/doc/trash-feature-summary.md

14 - Trash Feature

Soft-delete for files and folders. Items go to a per-user trash bin instead of being permanently removed. Configurable retention period with automatic cleanup.

Architecture

Follows the hexagonal architecture:

1. Domain Layer (/src/domain/):

   • Entities: TrashedItem representing files and folders in the trash
   • Repository interfaces: TrashRepository defining trash management operations

2. Application Layer (/src/application/):

   • DTOs: TrashedItemDto for data transfer between layers
   • Ports: TrashUseCase defining available operations
   • Services: TrashService implementing the trash use cases

3. Infrastructure Layer (/src/infrastructure/):

   • Repositories: TrashFsRepository for filesystem-based trash storage
   • Trash-related methods in existing repositories: FileWriteRepository::move_to_trash(), FolderRepository::move_to_trash(), etc.
   • Services: TrashCleanupService for automatic cleanup of expired items

4. Interface Layer (/src/interfaces/):

   • API handlers: trash_handler.rs with HTTP endpoints for trash operations
   • Routes: updated routes.rs to include trash endpoints

Key Features

1. Soft Deletion -- files and folders move to trash, not immediately deleted
2. Per-User Trash -- each user has an isolated trash bin
3. Retention Policy -- items auto-delete after a configurable period
4. Restoration -- items can be restored to their original location
5. Permanent Deletion -- items can be permanently deleted before retention expires
6. Empty Trash -- wipe everything in the trash at once

API Endpoints

• GET /api/trash or GET /api/trash/ -- list all items in the user's trash
• DELETE /api/trash/files/:id -- move a file to trash
• DELETE /api/trash/folders/:id -- move a folder to trash
• POST /api/trash/:id/restore -- restore an item to its original location
• DELETE /api/trash/:id -- permanently delete an item from trash
• DELETE /api/trash/empty -- empty the entire trash bin

Testing

1. Unit Tests -- testing TrashService:

   • Move files and folders to trash
   • Restore items from trash
   • Permanent deletion
   • Empty trash operation

2. Integration Tests -- Python script hitting the API endpoints:

   • End-to-end testing of all trash operations
   • Verification of move, list, restore, and delete behavior

3. Shell Script -- for manual testing and demonstration

Configuration

• OXICLOUD_ENABLE_TRASH: enable/disable the trash feature via FeaturesConfig (default: true)
• OXICLOUD_TRASH_RETENTION_DAYS: days to keep items before automatic deletion (default: 30, via StorageConfig)

Implementation Details

1. Physical File Storage -- when items are trashed, they physically move to a .trash directory
2. Metadata Storage -- trashed item info stored in a separate database table or file
3. User Isolation -- trash items are isolated by user ID
4. Automatic Cleanup -- a background job runs periodically to clean up expired items
5. Transaction Safety -- operations are atomic with proper error handling

Future Enhancements

1. Trash Quotas -- limit trash storage per user
2. Batch Operations -- trash, restore, or delete multiple items at once
3. Storage Optimization -- deduplication for trashed items
4. Version Control -- track file versions when moving to trash
5. Scheduled Cleanup -- let users configure custom retention periods
6. Trash Monitoring -- metrics and alerts for trash usage and cleanup