Danie1s/Tiercel

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

[Tiercel demo 1] [Tiercel demo 2]

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.

Package Metadata

Repository: Danie1s/Tiercel

Homepage: https://github.com/Danie1s/Tiercel/wiki

Stars: 2857

Forks: 413

Open issues: 2

Default branch: master

Primary language: swift

License: MIT

Topics: background-download, cocoapods, download-manager, file-download, ios, network, resumable-download, swift, urlsession, xcode

README: README.md