Danie1s/Tiercel

English | 简体中文

Tiercel is a production-oriented iOS download framework in pure Swift for background downloads, relaunch recovery, resumable transfers, and URLSession-based task orchestration.

Indexed on Swift Package Index and featured in awesome-swift and awesome-ios.

If Tiercel helps your team ship reliable downloads, consider starring the repository.

Why Teams Pick Tiercel

• Background downloads that stay close to native URLSession behavior.
• Relaunch recovery through persisted task metadata and resume data.
• Fine-grained control for start, suspend, cancel, remove, and batch operations.
• Multiple SessionManager instances 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

• Wiki
• Tiercel 3.0 Migration Guide
• Objective-C Bridge
• Contributing Guide
• Security Policy

Repository Layout

• Sources/General: core session, task, cache, and status-management logic
• Sources/Extensions: lightweight helpers used across the framework
• Sources/Utility: checksum and resume-data utilities
• Demo: sample iOS app for evaluation and manual testing

License

Tiercel is available under the MIT license. See LICENSE for details.