Home
Relevant source files
The following files were used as context for generating this wiki page:
The "Home" concept within the putio-ios application represents the root of the user's file system and the primary entry point for the application's core functionality. It serves as the top-level directory (ID 0) where users begin browsing their stored media and files. High-level management of the "Home" state involves user authentication, synchronization with the put.io API, and local persistence of account metadata.
The application architecture follows a UIKit-based approach, utilizing a RootContainerViewController to manage the primary navigation stack once a user is authenticated. The system ensures that a valid session exists before granting access to the Home environment, falling back to a login screen if credentials are missing or invalid.
Sources: README.md:14-16, Putio/AppDelegate.swift:183-187, Putio/Common/API/PutioE2EMockURLProtocol.swift:103-112
Application Lifecycle and Initialization
The AppDelegate is responsible for initializing the application environment and determining whether the user should be directed to the Home screen (main screen) or the Login screen. This process involves configuring shared SDKs (Realm, Sentry, Intercom), setting up the UI appearance, and initiating the authentication flow.
Authentication Flow
The app checks for a stored OAuth token in the keychain. If present, it attempts to fetch user account information and configuration settings from the put.io API to validate the session.
File System Root (ID 0)
In the put.io API and the iOS client's internal representation, "Home" is identified as the folder with ID 0. This folder is the parent of all top-level user files and folders.
Home Folder Properties
The application treats the root directory with specific metadata used for rendering the file browser.
| Property | Value | Description |
|---|---|---|
| ID | 0 | The unique identifier for the root directory. |
| Name | "Home" | The display name for the root of the file system. |
| File Type | FOLDER | The structural type of the entity. |
| Icon | "folder" | The visual asset used in the UI. |
| Parent ID | 0 | Indicates that the folder has no external parent. |
Sources: Putio/Common/API/PutioE2EMockURLProtocol.swift:105-112, Putio/Common/API/PutioSDK.swift:65-72
Data Synchronization and Persistence
The Home experience relies on PutioRealm for local storage of user sessions and configuration. When a user successfully authenticates, the application fetches PutioAccount and PutioConfig data.
Session Persistence Logic
- Opening Realm: The app attempts to open the default Realm database using
PutioRealm.open. - Replacing Session: It uses
PutioRealm.replaceUserSessionto clear existing user data and write the newUserandUserConfigobjects. - Error Handling: If persistence fails, the app defaults to the login screen to prevent inconsistent states.
Sources: Putio/AppDelegate.swift:189-215, Putio/Common/Helpers/Realm.swift:57-65
Navigation and Deeplinking
The DeeplinkManager facilitates direct navigation to specific areas of the app, including the Home/Files tab. It interacts with the MainTabBarController to switch context based on incoming URLs.
URL Routing for Home/Files
When a URL with the /files path is received, the application performs the following sequence:
- Sets the selected tab to
.files. - Extracts the file ID from the path (e.g.,
/files/42). - Queries the API for the file metadata.
- Instructs the visible
FilesViewControllerto present the specific file or directory.
End-to-End Mocking for Home
For development and testing, the project includes PutioE2EMockURLProtocol, which simulates API responses for the Home directory and its contents without requiring a live network connection. This allows for consistent testing of the Home screen's file listing and account info display.
| Mock Route | Response Data |
|---|---|
GET /v2/files/list | Returns the Home folder (ID 0) and a list of files. |
GET /v2/account/info | Returns mock user data (username: "e2e-user"). |
GET /v2/config | Returns mock system config (e.g., Chromecast type). |
Sources: Putio/Common/API/PutioE2EMockURLProtocol.swift:66-70, Putio/Common/API/PutioSDK.swift:16-25
Conclusion
"Home" in the putio-ios repository is more than a single view; it is a state of successful authentication and the logical root of the file-browsing hierarchy. It is maintained through a combination of Keychain-based security, Realm-based persistence, and a robust API wrapper that handles the synchronization of user account data and file structures.