Extensions & Utilities
Relevant source files
The following files were used as context for generating this wiki page:
The Extensions & Utilities module provides a suite of shared helpers, convenience wrappers, and system-level configurations that support the core functionality of the put.io iOS application. These utilities bridge the gap between the underlying SDK, the local persistence layer (Realm), and the user interface.
The scope of this module includes deep link management, database lifecycle handling (including recovery migrations), API communication wrappers, and global UI stylization. By centralizing these cross-cutting concerns, the application maintains consistency in data handling and user experience.
Persistence & Data Recovery Utilities
The application utilizes PutioRealm as a centralized utility class to manage the lifecycle of the local Realm database. This includes handling schema migrations, safe write operations, and a specialized recovery system for download records.
Database Lifecycle and Migrations
The utility manages schema versions (currently version 12) and provides a migration block to update legacy data structures, such as transforming raw integer values into modern enumeration types for download states.
The diagram above illustrates the startup logic for the persistence layer, including the handling of incompatible file formats between Realm versions.
Sources: Putio/Common/Helpers/Realm.swift:5-80
Download Recovery System
A critical utility within PutioRealm is the ability to rebuild Download records if the database is wiped. It scans UserDefaults for file references (bookmarks for video, paths for audio) and cross-references the local Documents directory to restore user downloads.
| Function | Description |
|---|---|
recoverDownloadsIfNeeded | Orchestrates the restoration of download records from persistent storage and local disk. |
enrichPlaceholderDownloads | Fetches real filenames and metadata from the put.io API for recovered items. |
recoveredAudioFileId | Extracts numeric file IDs from audio filenames using a specific prefix pattern (putio_adm_). |
Sources: Putio/Common/Helpers/Realm.swift:145-235
SDK & API Wrappers
The PutioSDKFactory and related extensions provide a streamlined interface for interacting with the put.io backend. These utilities handle environment configuration, authentication token management, and asynchronous result mapping.
API Integration Flow
The utility wraps asynchronous SDK calls into completion handlers that ensure results are returned on the MainActor for UI safety.
This sequence shows how the SDK utility abstracts threading and error handling for the rest of the application.
Sources: Putio/Common/API/PutioSDK.swift:34-50
Deeplink & Navigation Management
The DeeplinkManager utility serves as the central router for external URLs and universal links. It parses incoming paths and coordinates with the MainTabBarController to navigate the user to specific files, downloads, or settings pages.
Navigation Logic
The manager uses regular expressions to extract IDs from paths like /files/{id} or /downloads/{id}. It handles state checks (via isReadyToHandleURL) to ensure navigation only occurs when the UI hierarchy is fully initialized.
- File Paths: Routes to the "Files" tab and triggers a remote file fetch before presenting the file page.
- Download Paths: Routes to the "Downloads" tab and fetches the local record from Realm.
- Static Paths: Handles
/history,/settings, and/linkshortcuts.
Sources: Putio/Common/Managers/DeeplinkManager.swift:10-90
System Utilities
The Utils class and AppDelegate extensions provide global configuration for system-level services.
Audio/Visual Session Management
The Utils.configureAVSession() helper ensures the application's audio session is correctly categorized for media playback, allowing audio to continue as expected based on system settings.
Sources: Putio/Common/Helpers/Utils.swift:10-25, Putio/AppDelegate.swift:75-80
UI Stylization
The Stylize utility is invoked during application launch to apply global appearance proxies to UIKit components, ensuring a consistent visual identity (such as the signature "Putio yellow" tint) across the app.
Sources: Putio/AppDelegate.swift:130-135, Putio/Features/Settings/SettingsViewModel+Sections.swift:230-240
Summary
Extensions and Utilities in the put.io project provide the essential "glue" between system frameworks and application-specific logic. By centralizing Realm database management, API communication patterns, and deep link routing, these modules ensure that complex operations—like recovering lost download data or navigating from a web link—are handled reliably and consistently throughout the codebase.