Trash Management

Relevant source files

The following files were used as context for generating this wiki page:

• Putio/Features/Trash/TrashViewController.swift
• Putio/Features/Trash/TrashViewModel.swift
• Putio/Features/Trash/TrashTableViewCell.swift
• Putio/Common/API/PutioSDK.swift
• Putio/Features/Settings/SettingsViewModel+Sections.swift
• Putio/Features/Settings/SettingsViewModel+Persistence.swift
• Putio/Common/Helpers/Realm.swift

The Trash Management system in the put.io iOS application provides users with a safety net for deleted files. It allows for the temporary storage of removed items, which can either be restored to their original locations or permanently deleted to free up storage space. This feature is integrated into the application's file management workflow and is controlled via user settings.

The module is built using a standard MVVM (Model-View-ViewModel) architecture, utilizing a TrashViewController for UI management and a TrashViewModel for handling business logic and API interactions. Persistence is managed through Realm, specifically for tracking the total trash size and user preferences regarding trash behavior.

Sources: Putio/Features/Trash/TrashViewModel.swift, Putio/Features/Trash/TrashViewController.swift, Putio/Features/Settings/SettingsViewModel+Sections.swift

Architecture and Data Flow

The Trash Management module interacts with the Putio SDK to perform remote operations and uses a delegate pattern to update the UI based on state changes.

Component Relationship

The following diagram illustrates the relationship between the UI components, the ViewModel, and the backend SDK.

State Management

The TrashViewModel manages an internal state machine to coordinate UI updates through the TrashViewModelDelegate.

State	Description
idle	Initial state before any actions are taken.
loading	Active API request is in progress (e.g., fetching or restoring).
empty	The trash contains no files.
loaded	Files have been successfully retrieved and are ready for display.
refreshing	Background update of the file list is in progress.
failure	An error occurred during an API operation.

Sources: Putio/Features/Trash/TrashViewModel.swift:15-22, Putio/Features/Trash/TrashViewController.swift:250-272

Feature Configuration

Trash behavior is configurable within the application settings. Users can toggle whether deleted files are moved to the trash or immediately removed.

User Settings Logic

The visibility of trash management options depends on the trashEnabled setting. When enabled, a link to the Trash view appears, displaying the current human-readable size of the trash (e.g., "2.5 GB").

Persistence and Sync

Trash size is persisted in the local Realm database to ensure the UI remains responsive and reflects the latest known state from the server.

var trashSize: Int64 = 0 {
    didSet {
        guard let realm = PutioRealm.open(context: "TrashViewModel.trashSize"),
            let user = realm.objects(User.self).first else { return }

        PutioRealm.write(realm, context: "TrashViewModel.trashSize") {
            user.trashSize = self.trashSize
        }
    }
}

Sources: Putio/Features/Trash/TrashViewModel.swift:42-53, Putio/Common/Helpers/Realm.swift:120-124

Operations and API Integration

The system supports individual, bulk, and global operations on trashed items.

API Endpoint Mapping

The following table summarizes the SDK methods used by the Trash module.

Operation	SDK Method	Purpose
Fetch List	listTrash()	Retrieves metadata and file list for trashed items.
Restore Files	restoreTrashFiles(fileIDs:cursor:)	Moves items from trash back to active storage.
Delete Files	deleteTrashFiles(fileIDs:cursor:)	Permanently deletes specific items from trash.
Empty Trash	emptyTrash()	Permanently deletes all items currently in trash.

Sources: Putio/Common/API/PutioSDK.swift:256-285, Putio/Features/Trash/TrashViewModel.swift:85-156

Restore Sequence

When a user initiates a restore operation, the system follows a specific sequence to ensure the UI remains consistent with the server state.

User Interface Components

TrashViewController

This controller manages a UITableView to list items. It supports:

• Stateful Views: Displays specific views for loading, empty, error, and offline states using a stateMachine.
• Editing Mode: Allows bulk selection of files for restoration or deletion.
• Swipe Actions: Provides a contextual "Delete" action on individual rows.
• Navigation Menu: Includes a "Select," "Restore all," and "Empty trash" menu under an ellipsis button.

Sources: Putio/Features/Trash/TrashViewController.swift:34-118, Putio/Features/Trash/TrashViewController.swift:240-248

TrashTableViewCell

The cell displays file metadata including:

• Icon: Differentiates between folder, video, audio, and generic files.
• Name: The filename of the trashed item.
• Detail Label: Combines the human-readable file size with the expiration date (e.g., "15 MB - Expires on May 24").

Sources: Putio/Features/Trash/TrashTableViewCell.swift:5-30

Conclusion

The Trash Management module provides a robust interface for handling deleted content within the put.io ecosystem. By leveraging a ViewModel-driven state machine and a dedicated SDK wrapper, it ensures that data remains synchronized between the local Realm database and the remote server while providing a responsive user experience for file recovery and storage maintenance.