SPB Git

Repository Public

DownloadManager.swift 25.7 KB 490 lines swift

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
Files main
Menu

Theme