Repository Public
1// SP Music iOS2// File: Core/Sources/SPMusicCore/Downloads/DownloadManager.swift3// Description: Offline downloads: background transfers, integrity checks, pins and reference counting.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai78import Foundation910public struct DownloadProgress: Sendable, Equatable {11 public var trackId: String12 public var state: DownloadState? // nil: the download was removed13 public var bytesDone: Int6414 public var bytesTotal: Int6415 public var error: String?16 public init(trackId: String, state: DownloadState?, bytesDone: Int64, bytesTotal: Int64, error: String?) {17 self.trackId = trackId; self.state = state; self.bytesDone = bytesDone; self.bytesTotal = bytesTotal; self.error = error18 }19 public var fraction: Double { state == .done ? 1 : (bytesTotal > 0 ? min(1, Double(bytesDone) / Double(bytesTotal)) : 0) }20}2122public struct PinStatus: Sendable, Equatable {23 public var pinned = false24 public var total = 025 public var done = 026 public var active = 0 // queued, preparing, running27 public var failed = 028 public var bytesDone: Int64 = 029 public var bytesTotal: Int64 = 030 public init(pinned: Bool = false) { self.pinned = pinned }31 public var complete: Bool { pinned && total > 0 && done == total }32 public var fraction: Double { bytesTotal > 0 ? min(1, Double(bytesDone) / Double(bytesTotal)) : (total > 0 ? Double(done) / Double(total) : 0) }33}3435/// Events of the URLSession delegate, forwarded to the actor in order.36enum TransferEvent: Sendable {37 case progress(description: String, written: Int64, expected: Int64)38 case finished(description: String, staged: URL?, status: Int, expected: Int64, moveError: String?)39 case failed(description: String, code: Int, resumeData: Data?)40 case backgroundEventsDelivered41}4243/// URLSession calls back on its own queue. The downloaded file only exists during `didFinishDownloadingTo`, so it is44/// moved to the staging folder right there; everything else is handed to the actor.45final class TransferBridge: NSObject, URLSessionDownloadDelegate, Sendable {46 let events: AsyncStream<TransferEvent>47 private let continuation: AsyncStream<TransferEvent>.Continuation48 private let files: OfflineFiles4950 init(files: OfflineFiles) {51 self.files = files52 (events, continuation) = AsyncStream<TransferEvent>.makeStream(bufferingPolicy: .unbounded)53 }5455 func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didWriteData bytesWritten: Int64, totalBytesWritten: Int64, totalBytesExpectedToWrite: Int64) {56 guard let d = downloadTask.taskDescription else { return }57 continuation.yield(.progress(description: d, written: totalBytesWritten, expected: totalBytesExpectedToWrite))58 }5960 func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didFinishDownloadingTo location: URL) {61 guard let d = downloadTask.taskDescription else { return }62 let http = downloadTask.response as? HTTPURLResponse63 let staged = files.newStagingURL()64 var moveError: String?65 do { try FileManager.default.moveItem(at: location, to: staged) } catch { moveError = "move" }66 continuation.yield(.finished(description: d, staged: moveError == nil ? staged : nil, status: http?.statusCode ?? 0, expected: http?.expectedContentLength ?? -1, moveError: moveError))67 }6869 func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: (any Error)?) {70 guard let error, let d = task.taskDescription else { return } // success was reported by didFinishDownloadingTo71 let ns = error as NSError72 continuation.yield(.failed(description: d, code: ns.code, resumeData: ns.userInfo[NSURLSessionDownloadTaskResumeData] as? Data))73 }7475 func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) { continuation.yield(.backgroundEventsDelivered) }76}7778/// Keeps music on the device.79///80/// What the listener asks for is a *pin* (a track, an album, a playlist, the whole library). A pin lists its member81/// tracks; a track is downloaded once however many pins want it, and its file is deleted only when no pin wants it82/// any more. Transfers go through a background URLSession, so they continue while the app is suspended, within what83/// iOS allows; every file is checked (size, SHA-256 of the original) before it is declared available.84public actor DownloadManager {85 public static let backgroundIdentifier = "ai.spboucher.spmusic.downloads"8687 private let db: Database88 private let api: APIClient89 public nonisolated let files: OfflineFiles90 private let settings: @Sendable () -> TransferSettings91 private let network: @Sendable () -> NetworkStatus92 private let configuration: URLSessionConfiguration93 private let bridge: TransferBridge94 private var session: URLSession?95 private var tasks: [String: URLSessionDownloadTask] = [:]96 private var live: [String: (done: Int64, total: Int64, at: Date)] = [:]97 private var renditionLoop: Task<Void, Never>?98 private var backgroundCompletion: (@Sendable () -> Void)?99 /// How many tasks are handed to the system at once: enough for it to keep going while the app sleeps.100 private let handoverWindow: Int101102 public nonisolated let updates: AsyncStream<DownloadProgress>103 private let updatesOut: AsyncStream<DownloadProgress>.Continuation104105 public init(db: Database, api: APIClient, files: OfflineFiles, configuration: URLSessionConfiguration, handoverWindow: Int = 24,106 settings: @escaping @Sendable () -> TransferSettings, network: @escaping @Sendable () -> NetworkStatus) {107 self.db = db; self.api = api; self.files = files; self.configuration = configuration108 self.settings = settings; self.network = network; self.handoverWindow = handoverWindow109 bridge = TransferBridge(files: files)110 (updates, updatesOut) = AsyncStream<DownloadProgress>.makeStream(bufferingPolicy: .bufferingNewest(500))111 }112113 public static func backgroundConfiguration(maxConnections: Int) -> URLSessionConfiguration {114 let c = URLSessionConfiguration.background(withIdentifier: backgroundIdentifier)115 c.sessionSendsLaunchEvents = true116 c.isDiscretionary = false117 c.httpMaximumConnectionsPerHost = max(1, min(4, maxConnections))118 c.httpCookieStorage = nil; c.httpShouldSetCookies = false; c.urlCache = nil119 c.timeoutIntervalForResource = 7 * 24 * 3600120 return c121 }122123 /// Creates the session (which re-attaches to transfers that ran while the app was not), then brings the124 /// database in line with what the system reports.125 public func start() async {126 guard session == nil else { return }127 session = URLSession(configuration: configuration, delegate: bridge, delegateQueue: nil)128 let stream = bridge.events129 Task { [weak self] in for await e in stream { await self?.handle(e) } }130 await reconcile()131 }132133 public func setBackgroundCompletion(_ handler: (@Sendable () -> Void)?) { backgroundCompletion = handler }134135 // MARK: Pins136137 public func pin(_ kind: PinKind, _ id: String) async {138 let members: [String] = switch kind {139 case .track: [id]140 case .album: await db.trackIds(albumId: id)141 case .playlist: await db.trackIds(playlistId: id)142 case .library: await db.allTrackIds()143 }144 await db.removePin(kind, kind == .library ? "all" : id) // a fresh pin wants every member again145 await db.setPin(kind, kind == .library ? "all" : id, members: members)146 for m in members { await db.includeInPins(trackId: m) }147 await enqueueWanted()148 }149150 public func unpin(_ kind: PinKind, _ id: String) async {151 await db.removePin(kind, kind == .library ? "all" : id)152 await collectGarbage()153 }154155 /// The listener deletes one downloaded track, whatever asked for it.156 public func removeTrack(_ trackId: String) async {157 await db.excludeFromPins(trackId: trackId)158 await collectGarbage()159 }160161 public func removeEverything() async {162 await db.removeAllPins()163 await collectGarbage()164 }165166 /// After a synchronisation: albums and playlists kept offline follow their new content.167 public func reconcilePins() async {168 for p in await db.pins() {169 switch p.kind {170 case .track: break171 case .album: await db.setPin(.album, p.id, members: await db.trackIds(albumId: p.id))172 case .playlist: await db.setPin(.playlist, p.id, members: await db.trackIds(playlistId: p.id))173 case .library: await db.setPin(.library, "all", members: await db.allTrackIds())174 }175 }176 await collectGarbage()177 if settings().autoDownloadPinned { await enqueueWanted() }178 }179180 /// Tracks a pin wants that are not on the device and not on their way (shown when automatic download is off).181 public func pendingWanted() async -> [String] { await db.wantedWithoutDownload() }182183 public func enqueueWanted() async {184 let ids = await db.wantedWithoutDownload()185 guard !ids.isEmpty else { await pump(); return }186 let quality = settings().downloadQuality187 for t in await db.tracks(ids: ids) { await db.upsertDownload(newRecord(for: t, quality: quality)); emit(t.id) }188 await pump()189 }190191 private func newRecord(for t: Track, quality: Quality) -> DownloadRecord {192 // The light rendition when asked for; the original when the server has none to offer for this track.193 var variant = quality.variant194 if variant == .original, t.file == nil { variant = .compat }195 if variant == .compat, t.compatState == "disabled" { variant = .original }196 let asset = t.asset(variant)197 let ext = variant == .compat ? "m4a" : AudioFormat.fileExtension(mime: t.file?.mime ?? "", codec: t.codec, container: t.container)198 let waiting = variant == .compat && t.compatState != "ready"199 return DownloadRecord(trackId: t.id, variant: variant, state: waiting ? .preparing : .queued, bytesTotal: asset?.sizeBytes ?? 0, bytesDone: 0,200 sha256: variant == .original ? asset?.sha256 : nil, assetId: asset?.assetId, ext: ext, error: nil, attempts: 0, addedAt: Date(), completedAt: nil)201 }202203 public func pinStatus(_ kind: PinKind, _ id: String) async -> PinStatus {204 let key = kind == .library ? "all" : id205 var s = PinStatus(pinned: await db.isPinned(kind, key))206 let members: [String] = s.pinned ? await db.pinMembers(kind, key) : (kind == .album ? await db.trackIds(albumId: id) : kind == .playlist ? await db.trackIds(playlistId: id) : kind == .track ? [id] : [])207 s.total = members.count208 for m in members {209 guard let d = await db.download(trackId: m) else { continue }210 let l = live[m]211 s.bytesTotal += max(d.bytesTotal, l?.total ?? 0)212 switch d.state {213 case .done: s.done += 1; s.bytesDone += d.bytesTotal214 case .failed: s.failed += 1215 case .queued, .preparing, .running, .paused: s.active += 1; s.bytesDone += l?.done ?? d.bytesDone216 }217 }218 return s219 }220221 /// Bytes that would be fetched to keep these tracks offline (what is already here does not count).222 public func estimate(trackIds: [String]) async -> Int64 {223 let quality = settings().downloadQuality224 var total: Int64 = 0225 for t in await db.tracks(ids: trackIds) {226 if let d = await db.download(trackId: t.id), d.state == .done { continue }227 // An AAC 256 kbit/s rendition that does not exist yet is estimated from the duration.228 total += quality == .compact ? (t.compat?.sizeBytes ?? Int64(t.durationMs) * 32) : (t.file?.sizeBytes ?? 0)229 }230 return total231 }232233 // MARK: Controls234235 public func pause(_ trackId: String) async {236 guard var d = await db.download(trackId: trackId), d.state == .running || d.state == .queued || d.state == .preparing else { return }237 d.state = .paused238 if let l = live[trackId] { d.bytesDone = l.done }239 await db.upsertDownload(d)240 if let task = tasks.removeValue(forKey: trackId) {241 let data = await task.cancelByProducingResumeData()242 if let data, let u = try? files.resumeDataURL(trackId: trackId) { try? data.write(to: u, options: .atomic) }243 }244 emit(trackId)245 await pump()246 }247248 public func resume(_ trackId: String) async {249 guard var d = await db.download(trackId: trackId), d.state == .paused || d.state == .failed else { return }250 d.state = d.variant == .compat && d.assetId == nil && d.bytesTotal == 0 ? .preparing : .queued251 d.error = nil; d.attempts = 0252 await db.upsertDownload(d)253 emit(trackId)254 await pump()255 }256257 public func pauseAll() async { for d in await db.downloads(states: [.running, .queued, .preparing]) { await pause(d.trackId) } }258 public func resumeAll() async { for d in await db.downloads(states: [.paused, .failed]) { await resume(d.trackId) } }259 /// After signing in again: transfers refused for lack of a session get another go.260 public func retryFailed() async { for d in await db.downloads(states: [.failed]) { await resume(d.trackId) } }261262 // MARK: Engine263264 /// Hands queued downloads to the system, oldest first, up to the window.265 public func pump() async {266 guard let session else { return }267 let running = tasks.count268 var room = handoverWindow - running269 if room > 0 {270 for d in await db.downloads(states: [.queued]) where room > 0 && tasks[d.trackId] == nil {271 await handOver(d, session: session); room -= 1272 }273 }274 if !(await db.downloads(states: [.preparing])).isEmpty { startRenditionLoop() }275 }276277 private func handOver(_ record: DownloadRecord, session: URLSession) async {278 var d = record279 guard SafeID.isValid(d.trackId) else { await db.deleteDownload(trackId: d.trackId); return }280 guard api.hasSession else { d.state = .failed; d.error = "auth"; await db.upsertDownload(d); emit(d.trackId); return }281 let s = settings()282 var req = api.authorized(api.streamURL(trackId: d.trackId, variant: d.variant))283 // The system itself waits for a network these flags accept — also while the app is suspended.284 req.allowsCellularAccess = s.downloadOnCellular285 req.allowsExpensiveNetworkAccess = s.downloadOnCellular286 req.allowsConstrainedNetworkAccess = false287 let task: URLSessionDownloadTask288 if let u = try? files.resumeDataURL(trackId: d.trackId), let data = try? Data(contentsOf: u) {289 try? FileManager.default.removeItem(at: u)290 task = session.downloadTask(withResumeData: data)291 } else {292 task = session.downloadTask(with: req)293 }294 task.taskDescription = d.trackId295 task.countOfBytesClientExpectsToReceive = d.bytesTotal > 0 ? d.bytesTotal : NSURLSessionTransferSizeUnknown296 tasks[d.trackId] = task297 d.state = .running; d.error = nil298 await db.upsertDownload(d)299 emit(d.trackId)300 task.resume()301 }302303 private func handle(_ e: TransferEvent) async {304 switch e {305 case .progress(let id, let written, let expected):306 guard tasks[id] != nil else { return }307 let now = Date()308 let previous = live[id]309 live[id] = (written, expected, previous?.at ?? .distantPast)310 // At most four updates a second per transfer reach the interface.311 if previous == nil || now.timeIntervalSince(previous!.at) >= 0.25 {312 live[id]?.at = now313 updatesOut.yield(DownloadProgress(trackId: id, state: .running, bytesDone: written, bytesTotal: max(expected, 0), error: nil))314 }315 case .finished(let id, let staged, let status, let expected, let moveError):316 tasks[id] = nil; live[id] = nil317 await finish(id, staged: staged, status: status, expected: expected, moveError: moveError)318 await pump()319 case .failed(let id, let code, let resumeData):320 tasks[id] = nil321 await fail(id, code: code, resumeData: resumeData)322 await pump()323 case .backgroundEventsDelivered:324 let done = backgroundCompletion325 backgroundCompletion = nil326 done?()327 }328 }329330 private func finish(_ id: String, staged: URL?, status: Int, expected: Int64, moveError: String?) async {331 func discard() { if let staged { try? FileManager.default.removeItem(at: staged) } }332 guard var d = await db.download(trackId: id) else { discard(); return } // removed meanwhile333 guard d.state == .running else { discard(); return } // paused meanwhile334 func reject(_ why: String) async {335 discard()336 d.state = .failed; d.error = why; d.attempts += 1; d.bytesDone = 0337 await db.upsertDownload(d); emit(id)338 Log.downloads.error("download \(id, privacy: .public) rejected: \(why, privacy: .public)")339 }340 guard let staged, moveError == nil else { return await reject("storage") }341 guard status == 200 || status == 206 else { return await reject(status == 401 ? "auth" : status == 404 ? "missing" : "http_\(status)") }342 let size = ((try? FileManager.default.attributesOfItem(atPath: staged.path))?[.size] as? NSNumber)?.int64Value ?? -1343 // Integrity: the announced size, then the SHA-256 of the original. A file that fails is never kept.344 if d.bytesTotal > 0, size != d.bytesTotal { return await reject("size") }345 if d.bytesTotal == 0, expected > 0, size != expected { return await reject("size") }346 if size <= 0 { return await reject("size") }347 if let want = d.sha256 {348 let got = try? await Task.detached(priority: .utility) { try FileHash.sha256(of: staged) }.value349 if got != want { return await reject("checksum") }350 }351 guard let dest = try? files.mediaURL(trackId: id, ext: d.ext) else { return await reject("storage") }352 do {353 if FileManager.default.fileExists(atPath: dest.path) { try FileManager.default.removeItem(at: dest) }354 try FileManager.default.moveItem(at: staged, to: dest)355 } catch { return await reject("storage") }356 files.protect(dest)357 d.state = .done; d.bytesTotal = size; d.bytesDone = size; d.error = nil; d.completedAt = Date()358 await db.upsertDownload(d)359 emit(id)360 await fetchCompanions(trackId: id)361 }362363 private func fail(_ id: String, code: Int, resumeData: Data?) async {364 guard var d = await db.download(trackId: id) else { return }365 if let resumeData, let u = try? files.resumeDataURL(trackId: id) { try? resumeData.write(to: u, options: .atomic) }366 if let l = live[id] { d.bytesDone = l.done }367 live[id] = nil368 guard d.state == .running else { return } // paused or cancelled by the listener: nothing to report369 d.attempts += 1370 let transient = [NSURLErrorNetworkConnectionLost, NSURLErrorNotConnectedToInternet, NSURLErrorTimedOut, NSURLErrorCannotConnectToHost, NSURLErrorCannotFindHost, NSURLErrorDNSLookupFailed, NSURLErrorInternationalRoamingOff, NSURLErrorDataNotAllowed].contains(code)371 if transient && d.attempts <= 5 { d.state = .queued; d.error = nil } // the next hand-over resumes from the saved data372 else { d.state = .failed; d.error = transient ? "network" : "transfer_\(code)" }373 await db.upsertDownload(d)374 emit(id)375 }376377 /// Cover and lyrics of a downloaded track, so its album page is complete without a connection.378 private func fetchCompanions(trackId: String) async {379 guard let t = await db.track(id: trackId) else { return }380 if let art = t.artworkId, let dest = try? files.artworkURL(artworkId: art), !FileManager.default.fileExists(atPath: dest.path) {381 if let (data, http) = try? await api.perform(api.authorized(api.artURL(artworkId: art, size: 640))), http.statusCode == 200, !data.isEmpty {382 try? data.write(to: dest, options: .atomic); files.protect(dest)383 }384 }385 if t.lyricsState == "ready", await db.lyrics(trackId: trackId) == nil, let l = try? await api.lyrics(trackId: trackId), l.hasText {386 await db.setLyrics(trackId: trackId, l)387 }388 }389390 /// Companions that could not be fetched when their track finished (app suspended, connection lost).391 public func completeCompanions() async {392 for d in await db.downloads(states: [.done]) { await fetchCompanions(trackId: d.trackId) }393 }394395 private func startRenditionLoop() {396 guard renditionLoop == nil else { return }397 renditionLoop = Task { [weak self] in398 while !Task.isCancelled {399 guard let self, await self.advanceRenditions() else { break }400 try? await Task.sleep(for: .seconds(3))401 }402 await self?.renditionLoopEnded()403 }404 }405 private func renditionLoopEnded() { renditionLoop = nil }406407 /// One pass over the downloads waiting for their AAC rendition. Returns false when none is left.408 private func advanceRenditions() async -> Bool {409 let waiting = await db.downloads(states: [.preparing])410 guard !waiting.isEmpty else { return false }411 guard network().online, api.hasSession else { return true }412 for var d in waiting.prefix(4) {413 do {414 var state = try await api.renditionState(trackId: d.trackId)415 if state == "none" || state == "error" { state = try await api.requestRendition(trackId: d.trackId) }416 if state == "ready" { d.state = .queued; d.bytesTotal = 0; d.assetId = nil; await db.upsertDownload(d); emit(d.trackId) }417 } catch let e as APIError where e.code == "renditions_disabled" || e.status == 404 {418 d.state = .failed; d.error = e.status == 404 ? "missing" : "rendition"; await db.upsertDownload(d); emit(d.trackId)419 } catch { /* rate limit or network: try again on the next pass */ }420 }421 await pump()422 return true423 }424425 /// Deletes downloads no pin wants, then the covers no downloaded album uses.426 public func collectGarbage() async {427 for id in await db.unreferencedDownloads() {428 if let task = tasks.removeValue(forKey: id) { task.cancel() }429 live[id] = nil430 if let d = await db.download(trackId: id), let u = try? files.mediaURL(trackId: id, ext: d.ext) { try? FileManager.default.removeItem(at: u) }431 if let u = try? files.resumeDataURL(trackId: id) { try? FileManager.default.removeItem(at: u) }432 await db.deleteDownload(trackId: id)433 await db.setLyrics(trackId: id, nil)434 updatesOut.yield(DownloadProgress(trackId: id, state: nil, bytesDone: 0, bytesTotal: 0, error: nil))435 }436 let used = await db.artworkIdsInUse()437 for f in (try? FileManager.default.contentsOfDirectory(at: files.artwork, includingPropertiesForKeys: nil)) ?? [] where !used.contains(f.deletingPathExtension().lastPathComponent) {438 try? FileManager.default.removeItem(at: f)439 }440 await pump()441 }442443 /// At launch: what the system says is running, what the database believes, and what is really on disk.444 public func reconcile() async {445 guard let session else { return }446 var systemTasks: [String: URLSessionDownloadTask] = [:]447 for t in await session.allTasks {448 guard let id = t.taskDescription, let dt = t as? URLSessionDownloadTask, t.state == .running || t.state == .suspended else { continue }449 systemTasks[id] = dt450 }451 for (id, t) in systemTasks {452 if let d = await db.download(trackId: id), d.state == .running || d.state == .queued { tasks[id] = t } else { t.cancel() }453 }454 for var d in await db.downloads() {455 switch d.state {456 case .running where tasks[d.trackId] == nil: d.state = .queued; await db.upsertDownload(d)457 case .queued where tasks[d.trackId] != nil: d.state = .running; await db.upsertDownload(d)458 case .done where files.existingMedia(d) == nil:459 // The file vanished (restored backup, manual clean-up): fetch it again rather than pretend.460 d.state = .queued; d.bytesDone = 0; d.completedAt = nil; await db.upsertDownload(d)461 default: break462 }463 }464 // Staged files left by an interrupted verification.465 for f in (try? FileManager.default.contentsOfDirectory(at: files.staging, includingPropertiesForKeys: nil)) ?? [] where f.pathExtension == "part" {466 try? FileManager.default.removeItem(at: f)467 }468 await pump()469 }470471 public func storageReport() async -> StorageReport {472 let c = await db.counts()473 let files = files474 let sizes = await Task.detached(priority: .utility) { (OfflineFiles.size(of: files.media), OfflineFiles.size(of: files.artwork), OfflineFiles.size(of: files.artCache)) }.value475 return StorageReport(audioBytes: sizes.0, artworkBytes: sizes.1, cacheBytes: sizes.2, freeBytes: files.freeBytes, tracks: c.downloadedTracks, albums: c.downloadedAlbums)476 }477478 /// The local file to play for a track, if it is downloaded and still on disk.479 public func localFile(trackId: String) async -> (url: URL, variant: AudioVariant)? {480 guard let d = await db.download(trackId: trackId), let u = files.existingMedia(d) else { return nil }481 return (u, d.variant)482 }483484 private func emit(_ id: String) {485 Task { [db, updatesOut] in486 if let d = await db.download(trackId: id) { updatesOut.yield(DownloadProgress(trackId: id, state: d.state, bytesDone: d.bytesDone, bytesTotal: d.bytesTotal, error: d.error)) }487 }488 }489}490