Tiercel
Pure Swift iOS download framework with background downloads, relaunch recovery, resumable transfers, and task management.
Install / Use
/learn @Danie1s/TiercelREADME
Why Teams Pick Tiercel
- Background downloads that stay close to native
URLSessionbehavior. - Relaunch recovery through persisted task metadata and resume data.
- Fine-grained control for start, suspend, cancel, remove, and batch operations.
- Multiple
SessionManagerinstances so different download domains stay isolated. - Network policy knobs for cellular, constrained, and expensive connections.
- Built-in speed, remaining-time, and file-validation callbacks.
- Thread-safe internal state designed for long-running download flows.
Choose Tiercel If
- You need downloads to recover after the app relaunches.
- You manage more than one download queue, domain, or product surface.
- You want batch downloads and operational visibility instead of ad hoc tasks.
- You prefer a higher-level API than raw
URLSessionDownloadTask, while still using Apple's native stack underneath. - You need a download layer that can be evaluated quickly through a real demo app.
At A Glance
| What you need | Raw URLSession only | Tiercel |
| --- | --- | --- |
| Background downloads | Base primitives | Higher-level manager and task model |
| Relaunch recovery | App-specific persistence work | Built-in persisted task metadata and resume data |
| Batch operations | Manual orchestration | Multi-download helpers and manager-level controls |
| Download domain isolation | Custom architecture | Multiple isolated SessionManager instances |
| Progress and validation hooks | Hand-rolled callbacks | Built-in progress, speed, ETA, and validation APIs |
Installation
CocoaPods
platform :ios, '12.0'
use_frameworks!
target 'YourTargetName' do
pod 'Tiercel'
end
Then run:
pod install
Swift Package Manager
In Xcode, choose File > Add Package Dependencies... and use:
https://github.com/Danie1s/Tiercel.git
Manual Integration
Drag the Sources directory into your project and make sure the files are included in the desired target.
Quick Start
import Tiercel
var configuration = SessionConfiguration()
configuration.allowsCellularAccess = true
configuration.maxConcurrentTasksLimit = 3
let manager = SessionManager("downloads", configuration: configuration)
let task = manager.download("https://example.com/video.mp4")
task?.progress(onMainQueue: true) { task in
print("progress:", task.progress.fractionCompleted)
}.success { task in
print("saved to:", task.filePath)
}.failure { _ in
print("download failed")
}
You can control downloads by URL or by task instance:
let url = "https://example.com/video.mp4"
manager.start(url)
manager.suspend(url)
manager.cancel(url)
manager.remove(url, completely: false)
if let task = task {
manager.start(task)
manager.suspend(task)
manager.cancel(task)
manager.remove(task, completely: false)
}
Tiercel also supports batch creation and start:
let urls = [
"https://example.com/episode-1.mp4",
"https://example.com/episode-2.mp4"
]
let tasks = manager.multiDownload(urls)
print(tasks.count)
Background Downloads And Relaunch Recovery
Tiercel persists task state and resume data to disk, so downloads can be restored after the app relaunches. If the user force-quits the app, iOS stops background execution until the next launch; once the app is opened again, Tiercel can recover eligible downloads and continue from stored state.
To support native background session callbacks, wire the completion handler from AppDelegate to the matching SessionManager:
let downloadManagers = [managerA, managerB]
func application(_ application: UIApplication,
handleEventsForBackgroundURLSession identifier: String,
completionHandler: @escaping () -> Void) {
for manager in downloadManagers where manager.identifier == identifier {
manager.completionHandler = completionHandler
break
}
}
Network Policy And File Validation
SessionConfiguration lets you tune network behavior for different products or environments:
var configuration = SessionConfiguration()
configuration.maxConcurrentTasksLimit = 3
configuration.allowsCellularAccess = true
configuration.allowsConstrainedNetworkAccess = true
configuration.allowsExpensiveNetworkAccess = true
let manager = SessionManager("downloads", configuration: configuration)
You can also validate downloaded files when integrity matters:
task?.validateFile(code: "9e2a3650530b563da297c9246acaad5c",
type: .md5,
onMainQueue: true) { task in
if task.validation == .correct {
print("file is valid")
} else {
print("file is invalid")
}
}
Compatibility
- Minimum platform:
iOS 12.0+ - Language baseline:
Swift 5.0+ - Distribution: CocoaPods, Swift Package Manager, and manual source integration
Demo
Open Demo/Tiercel-Demo.xcodeproj to explore:
- Single-file downloads
- Batch downloads
- Multiple isolated download managers
- Background session event handling
- Validation and progress callbacks
Docs And Links
Repository Layout
Sources/General: core session, task, cache, and status-management logicSources/Extensions: lightweight helpers used across the frameworkSources/Utility: checksum and resume-data utilitiesDemo: sample iOS app for evaluation and manual testing
License
Tiercel is available under the MIT license. See LICENSE for details.
