Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : SP Music pour macOS9// File : Core/Downloads/DownloadManager.swift10// Description : Resumable, verified downloads of original files into the11// library folder; persistent queue.12// Module : Core13// Repository : https://git.spboucher.ai/sp-music-macos14// Created : 2026-11-1715// Last Modified : 2026-11-1816//17// =============================================================================18// AUTHOR & PROFESSIONAL AFFILIATION19// =============================================================================20//21// Author : Simon-Pierre Boucher22// Position : Professor of Finance23// Institution : Université du Québec en Outaouais (UQO)24// Department : Département des sciences administratives25// Organization : SP Boucher26//27// Website : https://spboucher.ai28// Git : https://git.spboucher.ai29//30// =============================================================================31// OFFICIAL CONTACT DIRECTORY32// =============================================================================33//34// General : info@spboucher.ai35// Professional : contact@spboucher.ai36// Direct : simon@spboucher.ai37// Research : research@spboucher.ai38// Development : dev@spboucher.ai39// Support : support@spboucher.ai40// Security/Admin : admin@spboucher.ai41// Notifications : notifications@spboucher.ai42//43// Preferred Contact: support@spboucher.ai44//45// =============================================================================46// COPYRIGHT & INTELLECTUAL PROPERTY47// =============================================================================48//49// Copyright (c) 202650// Simon-Pierre Boucher51//52// All rights reserved where applicable.53//54// This file is governed by the applicable project license,55// copyright notices, institutional agreements and relevant law.56//57// Unless expressly authorized by the applicable license or58// rights holder, copying, redistribution, sublicensing,59// publication and commercial exploitation are not permitted.60//61// Existing third-party rights and notices remain unaffected.62//63// =============================================================================64// CONFIDENTIALITY & SECURITY65// =============================================================================66//67// Classification : Public68// Distribution : Public repository; use is governed by the project license69// Security Contact : admin@spboucher.ai70//71// Access to this source does not independently grant permission72// to redistribute or disclose confidential materials.73//74// Do not embed credentials, private keys, access tokens,75// certificates or confidential personal information.76//77// =============================================================================78// LICENSE & MAINTENANCE79// =============================================================================80//81// License : None specified (no license file in this repository)82// Maintainer : Simon-Pierre Boucher83// Technical Contact: dev@spboucher.ai84//85// =============================================================================86// END OF SP BOUCHER SOURCE HEADER87// =============================================================================8889import Foundation9091public struct LiveProgress: Sendable, Equatable {92 public var received: Int6493 public var total: Int6494 public var bytesPerSecond: Double95 public var fraction: Double { total > 0 ? min(1, Double(received) / Double(total)) : 0 }96}9798public enum DownloadEvent: Sendable {99 case progress100 case finished(trackID: String)101 case failed(trackID: String, message: String)102 /// The queue ran dry; `completed` files were installed since the last time it did.103 case idle(completed: Int)104}105106enum DownloadFailure: Error {107 case notFound, integrity, assetChanged, http(Int), noAsset108}109110/// Fetches the original files from the cluster into the library folder.111///112/// Each download is resumable at the byte: bytes go to `<library>/.spmusic/partial/<track>.<asset>.part`, a restart113/// (pause, network cut, quit, crash) asks the cluster for the rest only (`Range` + `If-Range` on the asset id), and114/// the file is moved into place only after its size and SHA-256 match what the cluster announced. The queue lives in115/// the database, so it survives the app.116public actor DownloadManager {117 private let store: LibraryStore118 private let api: APIClient119 private let storage: StorageManager120 private let artwork: ArtworkStore121 private var tasks: [String: Task<Void, Never>] = [:]122 private var live: [String: LiveProgress] = [:]123 private var stopping: [String: DownloadState?] = [:] // why a running task was cancelled: paused, or removed (nil)124 private var maxConcurrent: Int125 private var pausedAll = false126 private var authBlocked = false127 private var completedSinceIdle = 0128 private var continuations: [UUID: AsyncStream<DownloadEvent>.Continuation] = [:]129 private var watcher: Task<Void, Never>?130 private var lastEmit = Date.distantPast131 private var onAssetChanged: (@Sendable () -> Void)?132133 public init(store: LibraryStore, api: APIClient, storage: StorageManager, artwork: ArtworkStore, maxConcurrent: Int = 3) {134 self.store = store; self.api = api; self.storage = storage; self.artwork = artwork; self.maxConcurrent = max(1, min(8, maxConcurrent))135 }136137 public func events() -> AsyncStream<DownloadEvent> {138 let id = UUID()139 return AsyncStream(bufferingPolicy: .bufferingNewest(64)) { c in140 continuations[id] = c141 c.onTermination = { [weak self] _ in Task { await self?.drop(id) } }142 }143 }144 private func drop(_ id: UUID) { continuations[id] = nil }145 private func emit(_ e: DownloadEvent) { for c in continuations.values { c.yield(e) } }146147 /// Call once after launch: puts interrupted downloads back in the queue, checks that downloaded files are still148 /// there, and starts working. Also restarts the queue whenever the cluster becomes reachable again.149 public func start() async {150 await store.requeueInterruptedDownloads()151 await verifyFiles()152 watcher?.cancel()153 let connectivity = api.connectivity154 watcher = Task { [weak self] in155 for await online in connectivity.states() where online { await self?.pump() }156 }157 await pump()158 }159 public func stop() { watcher?.cancel(); for t in tasks.values { t.cancel() }; tasks.removeAll() }160 public func setAssetChangedHandler(_ h: (@Sendable () -> Void)?) { onAssetChanged = h }161162 /// A downloaded file that is gone from a library folder that is itself present is fetched again. When the whole163 /// folder is missing (external disk unplugged) nothing is touched.164 public func verifyFiles() async {165 guard storage.isRootAvailable else { return }166 for f in await store.downloadedFiles() where !FileManager.default.fileExists(atPath: storage.fileURL(relativePath: f.relativePath).path) {167 await store.setDownloadState(f.trackID, .queued, error: nil)168 }169 }170171 public func setMaxConcurrent(_ n: Int) async { maxConcurrent = max(1, min(8, n)); await pump() }172 public func liveProgress() -> [String: LiveProgress] { live }173 public var isPausedAll: Bool { pausedAll }174 public var activeCount: Int { tasks.count }175 public var totalSpeed: Double { live.values.reduce(0) { $0 + $1.bytesPerSecond } }176177 // MARK: Commands178179 @discardableResult180 public func enqueue(_ trackIDs: [String]) async -> Int {181 let added = await store.enqueueDownloads(trackIDs)182 await pump()183 return added.count184 }185 public func pause(_ trackID: String) async {186 if let t = tasks[trackID] { stopping[trackID] = .some(.paused); t.cancel() }187 else if await store.download(trackID)?.state == .queued { await store.setDownloadState(trackID, .paused) }188 }189 public func resume(_ trackID: String) async {190 if let s = await store.download(trackID)?.state, s == .paused || s == .failed { await store.setDownloadState(trackID, .queued) }191 await pump()192 }193 public func pauseAll() async {194 pausedAll = true195 for (id, t) in tasks { stopping[id] = .some(.queued); t.cancel() }196 }197 public func resumeAll() async {198 pausedAll = false; authBlocked = false199 for d in await store.downloads(states: [.paused]) { await store.setDownloadState(d.trackID, .queued) }200 await pump()201 }202 public func retryFailed() async {203 for d in await store.downloads(states: [.failed]) { await store.setDownloadState(d.trackID, .queued) }204 await pump()205 }206 /// Looks at the queue again (after a sync queued or re-queued something).207 public func kick() async { await pump() }208 public func sessionRestored() async { authBlocked = false; await pump() }209210 /// Cancels a download that is not finished, or deletes a finished one (file included).211 public func remove(_ trackID: String) async {212 if let t = tasks[trackID] { stopping[trackID] = .some(nil); t.cancel(); await t.value }213 let rel = await store.removeDownload(trackID)214 storage.removePartial(trackID: trackID)215 if let rel { try? storage.deleteDownloadedFile(relativePath: rel) }216 live[trackID] = nil217 emit(.progress)218 }219 public func remove(_ trackIDs: [String]) async { for id in trackIDs { await remove(id) } }220221 // MARK: Queue222223 private func pump() async {224 guard !pausedAll, !authBlocked, api.connectivity.isOnline, storage.isRootAvailable else { return }225 while tasks.count < maxConcurrent {226 let next = await store.nextQueuedDownloads(limit: maxConcurrent + tasks.count + 2).first { tasks[$0.trackID] == nil }227 guard let next, !pausedAll, tasks.count < maxConcurrent, tasks[next.trackID] == nil else { break }228 let id = next.trackID229 await store.setDownloadState(id, .downloading)230 guard tasks[id] == nil else { continue }231 tasks[id] = Task { [weak self] in await self?.run(id) }232 }233 if tasks.isEmpty, await store.nextQueuedDownloads(limit: 1).isEmpty, completedSinceIdle > 0 {234 let n = completedSinceIdle; completedSinceIdle = 0235 emit(.idle(completed: n))236 }237 }238239 private func report(_ id: String, received: Int64, total: Int64, speed: Double) {240 live[id] = LiveProgress(received: received, total: total, bytesPerSecond: speed)241 if Date().timeIntervalSince(lastEmit) > 0.2 { lastEmit = Date(); emit(.progress) }242 }243244 private func run(_ id: String) async {245 var outcome: Result<Void, Error>246 do { try await fetch(id); outcome = .success(()) } catch { outcome = .failure(error) }247 live[id] = nil248 tasks[id] = nil249 let reason = stopping.removeValue(forKey: id)250 switch outcome {251 case .success:252 completedSinceIdle += 1253 emit(.finished(trackID: id))254 case .failure(let error):255 if let reason { // cancelled on purpose256 if let state = reason { await store.setDownloadState(id, state) }257 } else if error is CancellationError {258 await store.setDownloadState(id, .queued)259 } else if APIClient.isOffline(error) {260 api.connectivity.noteFailure() // the queue restarts when the cluster answers again261 await store.setDownloadState(id, .queued)262 } else if let e = error as? APIError, e == .unauthenticated {263 authBlocked = true264 await store.setDownloadState(id, .queued)265 } else {266 let attempts = await store.downloadAttempts(id) + 1267 let (message, final): (String, Bool) = switch error {268 case DownloadFailure.notFound: ("Ce titre n’est plus disponible sur le serveur.", true)269 case DownloadFailure.noAsset: ("Le serveur n’a pas de fichier pour ce titre.", true)270 case DownloadFailure.integrity: ("Le fichier reçu ne correspond pas à l’empreinte annoncée.", attempts >= 3)271 case DownloadFailure.assetChanged: ("Le fichier a changé sur le serveur.", false)272 case DownloadFailure.http(let s): ("Le serveur a répondu \(s).", attempts >= 4)273 case StorageError.rootUnavailable: ("Le dossier de la bibliothèque est indisponible.", true)274 case StorageError.insufficientSpace: ("Espace disque insuffisant.", true)275 default: ((error as NSError).localizedDescription, attempts >= 4)276 }277 if case DownloadFailure.assetChanged = error { onAssetChanged?() }278 if final {279 await store.setDownloadState(id, .failed, error: message, countAttempt: true)280 emit(.failed(trackID: id, message: message))281 } else {282 await store.setDownloadState(id, .paused, error: message, countAttempt: true)283 // Back in the queue after a growing pause, unless the listener acted on it meanwhile.284 Task { [weak self] in285 try? await Task.sleep(nanoseconds: UInt64(min(60, 2 << attempts)) * 1_000_000_000)286 await self?.requeueAfterBackoff(id, message: message)287 }288 }289 }290 }291 emit(.progress)292 await pump()293 }294295 private func requeueAfterBackoff(_ id: String, message: String) async {296 guard let d = await store.download(id), d.state == .paused, d.error == message else { return }297 await store.setDownloadState(id, .queued, error: nil)298 await pump()299 }300301 // MARK: One file302303 private func fetch(_ id: String) async throws {304 guard let track = await store.track(id) else { throw DownloadFailure.notFound }305 guard let assetID = track.assetID else { throw DownloadFailure.noAsset }306 guard storage.isRootAvailable else { throw StorageError.rootUnavailable }307 let expected = track.sizeBytes308 let part = storage.partialURL(trackID: id, assetID: assetID)309 try FileManager.default.createDirectory(at: part.deletingLastPathComponent(), withIntermediateDirectories: true)310 // Partial files of an older version of this track are useless.311 for name in (try? FileManager.default.contentsOfDirectory(atPath: storage.partialDirectory.path)) ?? [] where name.hasPrefix(id + ".") && name != part.lastPathComponent {312 try? FileManager.default.removeItem(at: storage.partialDirectory.appendingPathComponent(name))313 }314315 var offset: Int64 = ((try? FileManager.default.attributesOfItem(atPath: part.path)[.size] as? NSNumber)?.int64Value) ?? 0316 if !FileManager.default.fileExists(atPath: part.path) {317 // Already streamed in full? Reuse those bytes instead of fetching them again.318 if let cached = StreamCache.completeFile(storage.streamCacheDirectory, trackID: id, assetID: assetID) {319 try? FileManager.default.copyItem(at: cached, to: part)320 offset = ((try? FileManager.default.attributesOfItem(atPath: part.path)[.size] as? NSNumber)?.int64Value) ?? 0321 }322 if !FileManager.default.fileExists(atPath: part.path) { FileManager.default.createFile(atPath: part.path, contents: nil); offset = 0 }323 }324 if expected > 0 && offset > expected { try Data().write(to: part); offset = 0 }325326 let free = StorageManager.freeSpace(at: storage.libraryRoot)327 if expected > 0, free < (expected - offset) + 100_000_000 { throw StorageError.insufficientSpace(needed: expected - offset, free: free) }328329 if expected == 0 || offset < expected {330 var request = try api.authorizedRequest("stream/\(id)")331 request.timeoutInterval = 30332 if offset > 0 {333 request.setValue("bytes=\(offset)-", forHTTPHeaderField: "Range")334 request.setValue("\"\(assetID)\"", forHTTPHeaderField: "If-Range")335 }336 let stream = HTTPByteStream()337 let head = try await stream.start(request)338 switch head.status {339 case 206: break340 case 200: if offset > 0 { try Data().write(to: part); offset = 0 } // the cluster sent the whole file: start over341 case 401: stream.cancel(); api.noteUnauthenticated(); throw APIError.unauthenticated342 case 404: stream.cancel(); throw DownloadFailure.notFound343 case 416: stream.cancel(); try Data().write(to: part); throw DownloadFailure.integrity344 case 502, 503, 504: stream.cancel(); throw APIError.offline345 default: stream.cancel(); throw DownloadFailure.http(head.status)346 }347 if let etag = head.header("etag"), etag != "\"\(assetID)\"" { stream.cancel(); try? FileManager.default.removeItem(at: part); throw DownloadFailure.assetChanged }348 let total = expected > 0 ? expected : offset + (Int64(head.header("content-length") ?? "") ?? 0)349 let handle = try FileHandle(forWritingTo: part)350 defer { try? handle.close() }351 try handle.seek(toOffset: UInt64(offset))352 var windowStart = Date(), windowBytes: Int64 = 0, speed = 0.0, lastSave = Date()353 try await withTaskCancellationHandler {354 for try await chunk in stream.body {355 try handle.write(contentsOf: chunk)356 offset += Int64(chunk.count); windowBytes += Int64(chunk.count)357 let now = Date(), dt = now.timeIntervalSince(windowStart)358 if dt >= 0.5 {359 let inst = Double(windowBytes) / dt360 speed = speed == 0 ? inst : speed * 0.6 + inst * 0.4361 windowStart = now; windowBytes = 0362 report(id, received: offset, total: total, speed: speed)363 if now.timeIntervalSince(lastSave) > 2 { lastSave = now; await store.setDownloadProgress(id, received: offset, total: total) }364 }365 }366 } onCancel: { stream.cancel() }367 try handle.synchronize()368 await store.setDownloadProgress(id, received: offset, total: total)369 try Task.checkCancellation()370 report(id, received: offset, total: total, speed: 0)371 }372373 // Integrity: exact size, then the SHA-256 the cluster computed when the file was imported.374 let size = ((try? FileManager.default.attributesOfItem(atPath: part.path)[.size] as? NSNumber)?.int64Value) ?? -1375 if expected > 0 && size != expected { try? FileManager.default.removeItem(at: part); throw DownloadFailure.integrity }376 if let want = track.sha256, !want.isEmpty {377 let got = try await Task.detached(priority: .utility) { try StorageManager.sha256(of: part) }.value378 if got != want { try? FileManager.default.removeItem(at: part); throw DownloadFailure.integrity }379 }380 try Task.checkCancellation()381382 var rel = await store.download(id)?.relativePath383 if rel == nil {384 let hasDiscs = await store.albumTracks(track.albumID).contains { $0.discNo > 1 }385 var candidate = storage.proposedRelativePath(for: track, albumTrackHasDiscs: hasDiscs)386 if await store.isRelativePathUsed(candidate, byOtherThan: id) || FileManager.default.fileExists(atPath: storage.fileURL(relativePath: candidate).path) {387 let ext = (candidate as NSString).pathExtension388 candidate = (candidate as NSString).deletingPathExtension + " [\(id.prefix(8))]." + ext389 }390 rel = candidate391 }392 try storage.install(part, relativePath: rel!)393 await store.completeDownload(id, relativePath: rel!, assetID: assetID, sha256: track.sha256, size: size)394395 // The album's cover next to its files (and in the cache, for offline display). Best effort.396 if let art = track.artworkID {397 _ = await artwork.url(art, size: 320)398 if let big = await artwork.url(art, size: 640) {399 let cover = storage.fileURL(relativePath: rel!).deletingLastPathComponent().appendingPathComponent("cover.jpg")400 if !FileManager.default.fileExists(atPath: cover.path) { try? FileManager.default.copyItem(at: big, to: cover) }401 }402 }403 }404}405