Repository Public MIT
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX Astra9// File : Packages/AstraLocal/Sources/DownloadCoordinator.swift10// Module : Packages11// Repository : https://git.spboucher.ai/orix-astra12// Created : 2026-11-2113// Last Modified : 2026-11-2214//15// =============================================================================16// AUTHOR & PROFESSIONAL AFFILIATION17// =============================================================================18//19// Author : Simon-Pierre Boucher20// Position : Professor of Finance21// Institution : Université du Québec en Outaouais (UQO)22// Department : Département des sciences administratives23// Organization : SP Boucher24//25// Website : https://spboucher.ai26// Git : https://git.spboucher.ai27//28// =============================================================================29// OFFICIAL CONTACT DIRECTORY30// =============================================================================31//32// General : info@spboucher.ai33// Professional : contact@spboucher.ai34// Direct : simon@spboucher.ai35// Research : research@spboucher.ai36// Development : dev@spboucher.ai37// Support : support@spboucher.ai38// Security/Admin : admin@spboucher.ai39// Notifications : notifications@spboucher.ai40//41// Preferred Contact: support@spboucher.ai42//43// =============================================================================44// COPYRIGHT & INTELLECTUAL PROPERTY45// =============================================================================46//47// Copyright (c) 202648// Simon-Pierre Boucher49//50// All rights reserved where applicable.51//52// This file is governed by the applicable project license,53// copyright notices, institutional agreements and relevant law.54//55// Unless expressly authorized by the applicable license or56// rights holder, copying, redistribution, sublicensing,57// publication and commercial exploitation are not permitted.58//59// Existing third-party rights and notices remain unaffected.60//61// =============================================================================62// CONFIDENTIALITY & SECURITY63// =============================================================================64//65// Classification : Public66// Distribution : Public repository; use is governed by the project license67// Security Contact : admin@spboucher.ai68//69// Access to this source does not independently grant permission70// to redistribute or disclose confidential materials.71//72// Do not embed credentials, private keys, access tokens,73// certificates or confidential personal information.74//75// =============================================================================76// LICENSE & MAINTENANCE77// =============================================================================78//79// License : Proprietary, all rights reserved (see license file)80// License File : LICENSE81// Maintainer : Simon-Pierre Boucher82// Technical Contact: dev@spboucher.ai83//84// =============================================================================85// END OF SP BOUCHER SOURCE HEADER86// =============================================================================8788import AstraCore89import Foundation9091// MARK: - Plan, status, errors9293/// What to download for one model and from where. Persisted beside the files so an interrupted download can resume after relaunch.94public struct DownloadPlan: Codable, Sendable, Hashable, Identifiable {95 public struct File: Codable, Sendable, Hashable {96 public var path: String97 /// Exact size the server must deliver; nothing beyond it is ever written.98 public var size: Int6499 public var sha256: String?100 /// Git blob id, accepted in place of a SHA-256 for small repository files when resolving straight from the Hub.101 public var gitBlobSHA1: String?102 public init(path: String, size: Int64, sha256: String? = nil, gitBlobSHA1: String? = nil) {103 self.path = path; self.size = size; self.sha256 = sha256; self.gitBlobSHA1 = gitBlobSHA1104 }105 }106 public var id: String107 public var files: [File]108 /// Base URLs ending in "/", tried in order: the mirror first, then the fallback.109 public var sources: [URL]110 /// Written into the store when the download completes, which makes the model loadable. nil = files only.111 public var card: LocalModelCard?112113 public init(id: String, files: [File], sources: [URL], card: LocalModelCard? = nil) { self.id = id; self.files = files; self.sources = sources; self.card = card }114115 public init(card: LocalModelCard) {116 self.init(id: card.id, files: card.files.map { File(path: $0.path, size: $0.size, sha256: $0.sha256) }, sources: card.sourceURLs, card: card)117 }118 public var totalBytes: Int64 { files.reduce(0) { $0 + $1.size } }119 var fingerprint: [String] { files.sorted { $0.path < $1.path }.map { "\($0.path)|\($0.size)|\($0.sha256 ?? "")|\($0.gitBlobSHA1 ?? "")" } }120}121122public enum DownloadError: Error, Sendable, Hashable, Codable, LocalizedError {123 case alreadyInProgress(String)124 case invalidPlan(String)125 case unsafePath(String)126 case insufficientDisk(neededBytes: Int64, availableBytes: Int64)127 case hashMismatch(file: String)128 case oversize(file: String)129 case sourceFailed(file: String, detail: String)130 case unknownDownload(String)131 case storage(String)132133 public var errorDescription: String? {134 switch self {135 case .alreadyInProgress(let id): "“\(id)” is already being downloaded."136 case .invalidPlan(let m): "This download cannot start: \(m)"137 case .unsafePath(let p): "The model manifest lists a file path that is not allowed (“\(p)”). Nothing was written."138 case .insufficientDisk(let need, let have):139 "Not enough free storage: \(MemoryGovernor.format(need)) needed including a safety margin, \(MemoryGovernor.format(have)) available."140 case .hashMismatch(let f): "“\(f)” did not match its expected checksum. The file was deleted; the model was not installed."141 case .oversize(let f): "The server sent more data for “\(f)” than the manifest declares. The file was deleted."142 case .sourceFailed(let f, let detail): "“\(f)” could not be downloaded: \(detail)"143 case .unknownDownload(let id): "There is no download for “\(id)”."144 case .storage(let m): "The model could not be written to storage: \(m)"145 }146 }147 public var astraError: AstraError { .local(errorDescription ?? "The download failed.") }148}149150public struct DownloadStatus: Sendable, Hashable, Identifiable {151 public enum Phase: Sendable, Hashable {152 case preparing, downloading, verifying, paused, failed(DownloadError), completed, cancelled153 public var isActive: Bool { self == .preparing || self == .downloading || self == .verifying }154 }155 public var id: String156 public var phase: Phase157 public var bytesDone: Int64158 public var bytesTotal: Int64159 /// Measured over the last few seconds; nil until there is something to measure.160 public var bytesPerSecond: Double?161 public var etaSeconds: Double?162 public var currentFile: String?163 public var filesDone: Int164 public var filesTotal: Int165 /// True when at least one file came from a source other than the first one.166 public var usedFallback: Bool = false167 public var retries: Int = 0168 /// SHA-256 of every verified file, computed locally.169 public var sha256: [String: String] = [:]170 public var fraction: Double { bytesTotal > 0 ? min(1, Double(bytesDone) / Double(bytesTotal)) : (phase == .completed ? 1 : 0) }171}172173// MARK: - Coordinator174175/// Downloads models file by file with HTTP Range resume into `.partial` files, verifies every file, and installs into the `ModelStore`.176/// Foreground transfers only (see `URLSessionDownloadTransport`); an interrupted download is found again by `restore()` and continues from its partial files.177public actor DownloadCoordinator {178 public struct Configuration: Sendable {179 /// Attempts per file and per source before moving to the next source. An attempt that made progress does not count.180 public var maxAttemptsPerSource = 4181 /// Free space required beyond the bytes still to download: the larger of the absolute and the relative margin.182 public var safetyMarginBytes: Int64 = 500 << 20183 public var safetyMarginFraction = 0.05184 public var retryDelay: @Sendable (Int) -> TimeInterval = { min(20, pow(2, Double($0 - 1))) }185 public var sleep: @Sendable (TimeInterval) async throws -> Void = { try await Task.sleep(nanoseconds: UInt64($0 * 1_000_000_000)) }186 /// Free bytes on the volume of the given URL; nil = unknown (the preflight then passes).187 public var freeSpace: (@Sendable (URL) -> Int64?)?188 public init() {}189 }190191 struct Persisted: Codable { var plan: DownloadPlan; var verified: [String: String] = [:]; var usedFallback = false }192 private struct Job { var plan: DownloadPlan; var status: DownloadStatus; var task: Task<Void, Never>?; var generation = 0; var samples: [(Date, Int64)] = [] }193194 public let store: ModelStore195 private let transport: any DownloadTransport196 private let configuration: Configuration197 private var jobs: [String: Job] = [:]198 private var observers: [UUID: AsyncStream<[DownloadStatus]>.Continuation] = [:]199200 public init(store: ModelStore, transport: any DownloadTransport = URLSessionDownloadTransport(), configuration: Configuration = Configuration()) {201 self.store = store; self.transport = transport; self.configuration = configuration202 }203204 // MARK: Observation205206 public func statuses() -> [DownloadStatus] { jobs.values.map(\.status).sorted { $0.id < $1.id } }207 public func status(id: String) -> DownloadStatus? { jobs[id]?.status }208209 public func updates() -> AsyncStream<[DownloadStatus]> {210 let key = UUID()211 return AsyncStream(bufferingPolicy: .bufferingNewest(1)) { continuation in212 observers[key] = continuation213 continuation.yield(statuses())214 continuation.onTermination = { _ in Task { await self.removeObserver(key) } }215 }216 }217 private func removeObserver(_ key: UUID) { observers[key] = nil }218 private func publish() { let s = statuses(); for o in observers.values { o.yield(s) } }219220 /// Waits until the download is no longer active and returns its final status.221 public func waitUntilSettled(id: String) async -> DownloadStatus? {222 while let job = jobs[id], job.status.phase.isActive {223 if let task = job.task { await task.value } else { await Task.yield() }224 }225 return jobs[id]?.status226 }227228 // MARK: Commands229230 /// Starts (or continues) a download. Throws `alreadyInProgress` when this model is already being downloaded.231 @discardableResult232 public func start(_ plan: DownloadPlan) throws -> DownloadStatus {233 if let job = jobs[plan.id], job.status.phase.isActive { throw DownloadError.alreadyInProgress(plan.id) }234 try Self.validate(plan)235 do { try store.prepare() } catch { throw DownloadError.storage(error.localizedDescription) }236 // A different file list under the same id is another version: never mix its files with the old ones.237 if let old = Self.readState(store, plan.id), old.plan.fingerprint != plan.fingerprint { _ = try? store.remove(id: plan.id) }238 else if let card = store.card(id: plan.id), store.installRecord(id: plan.id) != nil,239 DownloadPlan(card: card).fingerprint != plan.fingerprint { _ = try? store.remove(id: plan.id) }240 launch(plan)241 return jobs[plan.id]!.status242 }243244 /// Stops the transfer and keeps the partial files.245 public func pause(id: String) async {246 guard var job = jobs[id], job.status.phase.isActive else { return }247 let task = job.task248 job.generation += 1; job.task = nil; job.status.phase = .paused; job.status.bytesPerSecond = nil; job.status.etaSeconds = nil249 jobs[id] = job; publish()250 task?.cancel(); await task?.value251 }252253 /// Continues a paused, failed or restored download from its partial files.254 public func resume(id: String) throws {255 guard let job = jobs[id] else { throw DownloadError.unknownDownload(id) }256 if job.status.phase.isActive { throw DownloadError.alreadyInProgress(id) }257 if job.status.phase == .completed { return }258 launch(job.plan)259 }260261 /// Same as `resume` for a failed download; kept as a separate verb for the UI.262 public func retry(id: String) throws { try resume(id: id) }263264 /// Stops the transfer and removes everything written for this model, partial files included.265 public func cancel(id: String) async {266 guard var job = jobs[id] else { return }267 let task = job.task268 job.generation += 1; job.task = nil; job.status.phase = .cancelled; job.status.bytesDone = 0269 job.status.bytesPerSecond = nil; job.status.etaSeconds = nil; job.status.currentFile = nil270 jobs[id] = job; publish()271 task?.cancel(); await task?.value272 if jobs[id]?.status.phase == .cancelled { _ = try? store.remove(id: id) }273 }274275 /// Forgets a finished, failed or cancelled download (files are left as they are).276 public func forget(id: String) { if let job = jobs[id], !job.status.phase.isActive { jobs[id] = nil; publish() } }277278 /// Finds downloads interrupted by a crash, a kill or a relaunch and lists them as paused, ready for `resume`.279 @discardableResult280 public func restore() -> [DownloadStatus] {281 let names = (try? FileManager.default.contentsOfDirectory(atPath: store.root.path)) ?? []282 for name in names where ModelPath.isSafeID(name) && jobs[name] == nil {283 guard let state = Self.readState(store, name), state.plan.id == name, (try? Self.validate(state.plan)) != nil, !store.isInstalled(name) else { continue }284 let done = Self.bytesPresent(store, state.plan)285 jobs[name] = Job(plan: state.plan, status: DownloadStatus(id: name, phase: .paused, bytesDone: done.bytes, bytesTotal: state.plan.totalBytes,286 filesDone: done.files, filesTotal: state.plan.files.count, usedFallback: state.usedFallback, sha256: state.verified))287 }288 publish()289 return statuses()290 }291292 // MARK: Running293294 private func launch(_ plan: DownloadPlan) {295 let previous = jobs[plan.id]296 let generation = (previous?.generation ?? 0) + 1297 let done = Self.bytesPresent(store, plan)298 var job = Job(plan: plan, status: DownloadStatus(id: plan.id, phase: .preparing, bytesDone: done.bytes, bytesTotal: plan.totalBytes,299 filesDone: done.files, filesTotal: plan.files.count), generation: generation)300 let lastRun = previous?.task301 let store = store, transport = transport, configuration = configuration302 let report: @Sendable (Event) async -> Void = { [weak self] event in await self?.note(plan.id, generation, event) }303 let settle: @Sendable (Result<Void, Error>) async -> Void = { [weak self] result in await self?.finish(plan.id, generation, result) }304 let meter = ByteMeter(done.bytes)305 job.task = Task(priority: .userInitiated) {306 await lastRun?.value // two runs never write the same partial file307 // Byte counts are polled, never awaited from the transfer loop: a busy actor must not slow the download down.308 let ticker = Task {309 while !Task.isCancelled {310 try? await Task.sleep(nanoseconds: 250_000_000)311 await report(.bytes(meter.read()))312 }313 }314 let worker = Worker(store: store, transport: transport, configuration: configuration, plan: plan, meter: meter, report: report)315 let result: Result<Void, Error>316 do { try await worker.run(); result = .success(()) } catch { result = .failure(error) }317 ticker.cancel(); await ticker.value318 await report(.bytes(meter.read()))319 await settle(result)320 }321 jobs[plan.id] = job322 publish()323 }324325 enum Event: Sendable {326 case phase(DownloadStatus.Phase, file: String?)327 case bytes(Int64)328 case fileDone(path: String, sha256: String, files: Int)329 case fallback330 case retry331 }332333 private func note(_ id: String, _ generation: Int, _ event: Event) {334 guard var job = jobs[id], job.generation == generation else { return }335 switch event {336 case .phase(let phase, let file): job.status.phase = phase; job.status.currentFile = file337 case .bytes(let done):338 guard done != job.status.bytesDone || job.samples.isEmpty else { return }339 job.status.bytesDone = done340 let now = Date()341 job.samples.append((now, done))342 job.samples.removeAll { now.timeIntervalSince($0.0) > 6 }343 if let first = job.samples.first, now.timeIntervalSince(first.0) >= 0.5, done > first.1 {344 let rate = Double(done - first.1) / now.timeIntervalSince(first.0)345 job.status.bytesPerSecond = rate346 job.status.etaSeconds = Double(max(0, job.status.bytesTotal - done)) / rate347 }348 case .fileDone(let path, let hash, let files): job.status.sha256[path] = hash; job.status.filesDone = files349 case .fallback: job.status.usedFallback = true350 case .retry: job.status.retries += 1351 }352 jobs[id] = job; publish()353 }354355 private func finish(_ id: String, _ generation: Int, _ result: Result<Void, Error>) {356 guard var job = jobs[id], job.generation == generation else { return }357 job.task = nil; job.status.bytesPerSecond = nil; job.status.etaSeconds = nil; job.status.currentFile = nil358 switch result {359 case .success:360 job.status.phase = .completed; job.status.bytesDone = job.status.bytesTotal; job.status.filesDone = job.status.filesTotal361 case .failure(let error):362 if error is CancellationError { job.status.phase = .paused }363 else { job.status.phase = .failed((error as? DownloadError) ?? .sourceFailed(file: job.status.currentFile ?? id, detail: AstraError.wrap(error).message)) }364 job.status.bytesDone = Self.bytesPresent(store, job.plan).bytes365 }366 jobs[id] = job; publish()367 }368369 // MARK: Shared helpers370371 static func validate(_ plan: DownloadPlan) throws {372 guard ModelPath.isSafeID(plan.id) else { throw DownloadError.invalidPlan("the model identifier is not valid") }373 guard !plan.files.isEmpty, plan.files.count <= ModelPath.maxFiles else { throw DownloadError.invalidPlan("the file list is empty or too long") }374 guard !plan.sources.isEmpty else { throw DownloadError.invalidPlan("no download source is listed") }375 for source in plan.sources {376 let local = EndpointPolicy.isLocalHost(source.host ?? "")377 guard source.scheme == "https" || (source.scheme == "http" && local), source.absoluteString.hasSuffix("/") else {378 throw DownloadError.invalidPlan("a download source is not an https URL ending in “/”")379 }380 }381 var seen = Set<String>()382 for file in plan.files {383 guard ModelPath.isSafe(file.path), !file.path.hasSuffix(ModelStore.partialSuffix) else { throw DownloadError.unsafePath(file.path) }384 guard seen.insert(file.path.lowercased()).inserted else { throw DownloadError.invalidPlan("“\(file.path)” is listed twice") }385 guard file.size >= 0, file.size <= ModelPath.maxFileBytes else { throw DownloadError.invalidPlan("“\(file.path)” has an unacceptable size") }386 let hasSHA256 = file.sha256.map { ModelPath.isHex($0, count: 64) } ?? false387 let hasGit = file.gitBlobSHA1.map { ModelPath.isHex($0, count: 40) } ?? false388 guard hasSHA256 || hasGit else { throw DownloadError.invalidPlan("“\(file.path)” has no checksum") }389 }390 }391392 static func stateURL(_ store: ModelStore, _ id: String) -> URL? { try? store.meta(id).appendingPathComponent(ModelStore.downloadFile) }393394 static func readState(_ store: ModelStore, _ id: String) -> Persisted? {395 guard let url = stateURL(store, id), let data = try? Data(contentsOf: url) else { return nil }396 return try? JSONDecoder().decode(Persisted.self, from: data)397 }398399 static func bytesPresent(_ store: ModelStore, _ plan: DownloadPlan) -> (bytes: Int64, files: Int) {400 var bytes: Int64 = 0, files = 0401 for file in plan.files {402 guard let url = try? store.fileURL(modelID: plan.id, path: file.path) else { continue }403 if ModelStore.fileSize(url) == file.size { bytes += file.size; files += 1 }404 else if let n = ModelStore.fileSize(URL(fileURLWithPath: url.path + ModelStore.partialSuffix)) { bytes += min(n, file.size) }405 }406 return (bytes, files)407 }408}409410/// Bytes written so far, shared between the transfer loop and the coordinator without an actor hop.411final class ByteMeter: @unchecked Sendable {412 private let lock = NSLock()413 private var value: Int64414 init(_ value: Int64) { self.value = value }415 func set(_ v: Int64) { lock.withLock { value = v } }416 func read() -> Int64 { lock.withLock { value } }417}418419// MARK: - Worker420421/// One run of one download, off the coordinator's actor. Owns the files of its model while it runs.422struct Worker: Sendable {423 let store: ModelStore424 let transport: any DownloadTransport425 let configuration: DownloadCoordinator.Configuration426 let plan: DownloadPlan427 let meter: ByteMeter428 let report: @Sendable (DownloadCoordinator.Event) async -> Void429430 struct HTTPFailure: Error { var status: Int }431 struct RangeIgnored: Error {}432 struct Truncated: Error { var got: Int64; var expected: Int64 }433434 func run() async throws {435 try DownloadCoordinator.validate(plan)436 let fm = FileManager.default437 let directory: URL438 do {439 directory = try store.directory(for: plan.id)440 try fm.createDirectory(at: try store.meta(plan.id), withIntermediateDirectories: true)441 ModelStore.excludeFromBackup(directory)442 } catch { throw DownloadError.storage(error.localizedDescription) }443444 var state = DownloadCoordinator.readState(store, plan.id) ?? .init(plan: plan)445 state.plan = plan446 try save(state)447 if let card = plan.card { try? store.writeCard(card) } // lets the store list an unfinished download with its real size448 removeStrayPartials(directory)449450 // Disk-space preflight: what is still to fetch, plus a margin.451 let present = DownloadCoordinator.bytesPresent(store, plan)452 let remaining = max(0, plan.totalBytes - present.bytes)453 let margin = max(configuration.safetyMarginBytes, Int64(Double(plan.totalBytes) * configuration.safetyMarginFraction))454 let free = configuration.freeSpace.map { $0(directory) } ?? store.availableDiskBytes()455 if let free, remaining > 0, free < remaining + margin { throw DownloadError.insufficientDisk(neededBytes: remaining + margin, availableBytes: free) }456457 var done = present.bytes458 var filesDone = 0459 for file in plan.files {460 try Task.checkCancellation()461 let destination: URL, partial: URL462 do {463 destination = try store.fileURL(modelID: plan.id, path: file.path)464 partial = try store.fileURL(modelID: plan.id, path: file.path + ModelStore.partialSuffix)465 try fm.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)466 } catch { throw DownloadError.unsafePath(file.path) }467468 if ModelStore.fileSize(destination) == file.size {469 // Already complete: trust it only if this run or a previous one verified it, otherwise verify now.470 if let known = state.verified[file.path] { filesDone += 1; await report(.fileDone(path: file.path, sha256: known, files: filesDone)); continue }471 await report(.phase(.verifying, file: file.path))472 if let hash = try verify(destination, file) {473 state.verified[file.path] = hash; try save(state); filesDone += 1474 await report(.fileDone(path: file.path, sha256: hash, files: filesDone)); continue475 }476 try? fm.removeItem(at: destination); done -= file.size; meter.set(done)477 } else if fm.fileExists(atPath: destination.path) {478 try? fm.removeItem(at: destination) // wrong size: not ours or damaged479 }480 state.verified[file.path] = nil481482 let hash = try await fetch(file, partial: partial, done: &done, state: &state)483 do {484 if fm.fileExists(atPath: destination.path) { try fm.removeItem(at: destination) }485 try fm.moveItem(at: partial, to: destination)486 } catch { throw DownloadError.storage(error.localizedDescription) }487 state.verified[file.path] = hash; try save(state); filesDone += 1488 await report(.fileDone(path: file.path, sha256: hash, files: filesDone))489 }490 if let card = plan.card {491 do { try store.markInstalled(card) } catch { throw DownloadError.storage(error.localizedDescription) }492 }493 }494495 /// Downloads one file into `partial`, trying each source in order, and returns its verified SHA-256.496 private func fetch(_ file: DownloadPlan.File, partial: URL, done: inout Int64, state: inout DownloadCoordinator.Persisted) async throws -> String {497 let fm = FileManager.default498 var lastError: DownloadError = .sourceFailed(file: file.path, detail: "no source answered")499 func discard(_ done: inout Int64) {500 if let n = ModelStore.fileSize(partial) { done -= min(n, file.size) }501 try? fm.removeItem(at: partial)502 meter.set(done)503 }504 sources: for (index, base) in plan.sources.enumerated() {505 guard let url = Self.url(base: base, path: file.path) else { continue }506 var attempt = 0507 while true {508 try Task.checkCancellation()509 var offset = ModelStore.fileSize(partial) ?? 0510 if offset > file.size { discard(&done); offset = 0 }511 if offset == file.size, fm.fileExists(atPath: partial.path) { break } // complete: verify below512 attempt += 1513 if attempt > configuration.maxAttemptsPerSource { continue sources }514 await report(.phase(.downloading, file: file.path))515 do {516 try await transfer(url: url, partial: partial, offset: offset, file: file, done: &done)517 if (ModelStore.fileSize(partial) ?? 0) == file.size { break }518 throw Truncated(got: ModelStore.fileSize(partial) ?? 0, expected: file.size)519 } catch is CancellationError {520 throw CancellationError()521 } catch let error as DownloadError {522 // oversize: this source cannot be trusted for this file523 discard(&done); lastError = error; continue sources524 } catch let failure as HTTPFailure {525 lastError = .sourceFailed(file: file.path, detail: "the server answered HTTP \(failure.status)")526 if failure.status == 416 { discard(&done); continue }527 if failure.status < 500, failure.status != 408, failure.status != 429 { continue sources }528 } catch is RangeIgnored {529 discard(&done); lastError = .sourceFailed(file: file.path, detail: "the server answered a different byte range than requested"); continue530 } catch let t as Truncated {531 lastError = .sourceFailed(file: file.path, detail: "the connection ended after \(t.got) of \(t.expected) bytes")532 if t.got - offset >= 1 << 20 { attempt -= 1 } // real progress: resuming is not a failed attempt533 } catch {534 if Task.isCancelled { throw CancellationError() }535 lastError = .sourceFailed(file: file.path, detail: AstraError.wrap(error).message)536 if (ModelStore.fileSize(partial) ?? 0) - offset >= 1 << 20 { attempt -= 1 }537 }538 await report(.retry)539 try await configuration.sleep(configuration.retryDelay(max(1, attempt)))540 }541 await report(.phase(.verifying, file: file.path))542 if let hash = try verify(partial, file) {543 if index > 0 { state.usedFallback = true; await report(.fallback) }544 return hash545 }546 discard(&done)547 lastError = .hashMismatch(file: file.path)548 }549 throw lastError550 }551552 /// One HTTP exchange: appends the body to `partial` from `offset`. Never writes past the declared size.553 private func transfer(url: URL, partial: URL, offset: Int64, file: DownloadPlan.File, done: inout Int64) async throws {554 var request = URLRequest(url: url)555 request.setValue("identity", forHTTPHeaderField: "Accept-Encoding") // byte offsets must be offsets in the stored file556 if offset > 0 { request.setValue("bytes=\(offset)-", forHTTPHeaderField: "Range") }557 let response = try await transport.open(request)558 var position = offset559 switch response.status {560 case 206:561 guard let range = Self.contentRange(response.headers["content-range"]), range.start == offset else { throw RangeIgnored() }562 if let total = range.total, total != file.size { throw total > file.size ? DownloadError.oversize(file: file.path) : RangeIgnored() }563 case 200:564 if offset > 0 { done -= offset; position = 0 } // the server ignored the range: start over565 default: throw HTTPFailure(status: response.status)566 }567 if let length = response.headers["content-length"].flatMap(Int64.init), position + length > file.size { throw DownloadError.oversize(file: file.path) }568569 let fm = FileManager.default570 if position == 0 { fm.createFile(atPath: partial.path, contents: nil) }571 let handle: FileHandle572 do {573 handle = try FileHandle(forWritingTo: partial)574 try handle.truncate(atOffset: UInt64(position)); try handle.seek(toOffset: UInt64(position))575 } catch { throw DownloadError.storage(error.localizedDescription) }576 defer { try? handle.close() }577578 meter.set(done)579 for try await chunk in response.body {580 try Task.checkCancellation()581 guard position + Int64(chunk.count) <= file.size else { throw DownloadError.oversize(file: file.path) }582 do { try handle.write(contentsOf: chunk) } catch { throw DownloadError.storage(error.localizedDescription) }583 position += Int64(chunk.count); done += Int64(chunk.count)584 response.consumed?(chunk.count)585 meter.set(done)586 }587 try Task.checkCancellation()588 }589590 /// Returns the file's SHA-256 when it matches the plan's checksum, nil on a mismatch.591 private func verify(_ url: URL, _ file: DownloadPlan.File) throws -> String? {592 let hash: String593 do { hash = try FileDigest.sha256(of: url, shouldContinue: { !Task.isCancelled }) }594 catch is CancellationError { throw CancellationError() }595 catch { throw DownloadError.storage(error.localizedDescription) }596 if let expected = file.sha256 { return hash == expected.lowercased() ? hash : nil }597 if let expected = file.gitBlobSHA1 { return (try? FileDigest.gitBlobSHA1(of: url)) == expected.lowercased() ? hash : nil }598 return nil599 }600601 private func save(_ state: DownloadCoordinator.Persisted) throws {602 guard let url = DownloadCoordinator.stateURL(store, plan.id) else { return }603 do { try JSONEncoder().encode(state).write(to: url, options: .atomic) } catch { throw DownloadError.storage(error.localizedDescription) }604 }605606 /// Deletes `.partial` files that do not belong to this plan (left by an older version of the model).607 private func removeStrayPartials(_ directory: URL) {608 let wanted = Set(plan.files.map { $0.path + ModelStore.partialSuffix })609 guard let walker = FileManager.default.enumerator(at: directory, includingPropertiesForKeys: nil) else { return }610 let prefix = directory.standardizedFileURL.path + "/"611 var stray: [URL] = []612 for case let url as URL in walker where url.lastPathComponent.hasSuffix(ModelStore.partialSuffix) {613 let relative = String(url.standardizedFileURL.path.dropFirst(prefix.count))614 if !wanted.contains(relative) { stray.append(url) }615 }616 for url in stray { try? FileManager.default.removeItem(at: url) }617 }618619 static func url(base: URL, path: String) -> URL? {620 let encoded = path.split(separator: "/").map { $0.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed.subtracting(CharacterSet(charactersIn: "/?#"))) ?? String($0) }621 return URL(string: base.absoluteString + encoded.joined(separator: "/"))622 }623624 /// Parses `bytes <start>-<end>/<total|*>`.625 static func contentRange(_ header: String?) -> (start: Int64, total: Int64?)? {626 guard let header, header.lowercased().hasPrefix("bytes ") else { return nil }627 let parts = header.dropFirst(6).split(separator: "/")628 guard let span = parts.first, let start = span.split(separator: "-").first.flatMap({ Int64($0.trimmingCharacters(in: .whitespaces)) }) else { return nil }629 return (start, parts.count > 1 ? Int64(parts[1].trimmingCharacters(in: .whitespaces)) : nil)630 }631}632