SPB Git

Repository Public

TransferQueue.swift 24.6 KB 372 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Sync/TransferQueue.swift3// Description: Persistent queue of uploads and downloads: priorities, controlled parallelism that adapts to the measured link, pause, resume, cancel, retry with back-off, bandwidth limits. A transfer is "done" only after the server (upload) or the SHA-256 check (download) confirmed it; the queue survives restarts.4import Foundation5import SPDriveCore67public enum TransferDirection: String, Sendable { case upload, download }8public enum TransferState: String, Sendable { case queued, running, paused, done, failed, cancelled }9public struct Transfer: Sendable, Identifiable, Equatable {10    public var id: String11    public var direction: TransferDirection12    public var state: TransferState13    /// Upload: the file being replaced (new version), if any. Download: the file fetched.14    public var itemID: String?15    /// Upload: destination folder.16    public var parentID: String?17    public var name: String18    /// Upload: the staged copy being sent. Download: the destination.19    public var localPath: String20    public var size: Int6421    public var done: Int6422    public var sha256: String?23    public var baseVersionID: String?24    public var versionID: String?25    public var priority: Int26    public var attempts: Int27    public var error: String?28    public var source: String29    public var createdAt: Date30    public var finishedAt: Date?31    /// Bytes per second over the last seconds (running transfers only).32    public var speed: Double = 033    public var fraction: Double { size > 0 ? min(1, Double(done) / Double(size)) : (state == .done ? 1 : 0) }34    public var isActive: Bool { state == .queued || state == .running }35}36public enum TransferEvent: Sendable {37    case changed(Transfer)38    case finished(Transfer, item: DriveItem?)39    case conflict(SyncConflict)40    case failed(Transfer, persistent: Bool)41    case removed(String)42}4344/// Decides how many transfers run at once from what the link actually delivers.45public struct ConcurrencyAdvisor: Sendable {46    public var manual: Int?47    public private(set) var limit = 348    private var best: Double = 0, sinceChange = 0, lastDirection = 049    /// Outcomes of the last transfers (true = succeeded), newest last.50    private var outcomes: [Bool] = []51    public static let range = 1...652    /// Size of the window of outcomes the error rate is computed on.53    public static let errorWindow = 1054    public init(manual: Int? = nil) { self.manual = manual }55    /// The number of transfers allowed now. A number chosen by the person is respected as it is; otherwise the measured56    /// limit is capped by the network (Low Data Mode, metered link) and by power (Low Power Mode, low battery).57    public func allowed(network: NetworkStatus, power: PowerState = .unconstrained) -> Int {58        if let manual { return min(max(manual, 1), 12) }59        if network.constrained { return 1 }60        var n = limit61        if network.expensive { n = min(n, 2) }62        return max(1, min(n, power.concurrencyCap))63    }64    /// Share of failures among the recent outcomes (0 when nothing was recorded).65    public var errorRate: Double { outcomes.isEmpty ? 0 : Double(outcomes.filter { !$0 }.count) / Double(outcomes.count) }66    /// Records how one transfer attempt ended (transient failures only: a refusal by the server says nothing about the link).67    /// When at least three of the recent attempts failed and they are a third or more of the window, one slot is given68    /// back — down to a single transfer — and growth waits for a few calm windows.69    public mutating func record(success: Bool) {70        outcomes.append(success)71        if outcomes.count > ConcurrencyAdvisor.errorWindow { outcomes.removeFirst(outcomes.count - ConcurrencyAdvisor.errorWindow) }72        guard manual == nil, !success else { return }73        let failures = outcomes.filter { !$0 }.count74        if failures >= 3, errorRate >= 1.0 / 3.0 {75            if limit > ConcurrencyAdvisor.range.lowerBound { limit -= 1 }76            outcomes.removeAll(); best = 0; lastDirection = -1; sinceChange = -377        }78    }79    /// Feeds one measurement window: aggregate bytes per second, and whether every slot was in use.80    public mutating func observe(throughput: Double, saturated: Bool) {81        guard manual == nil, saturated else { return }82        sinceChange += 183        guard sinceChange >= 2 else { return } // let a change settle before judging it84        if throughput > best * 1.12 {85            best = throughput86            if limit < ConcurrencyAdvisor.range.upperBound { limit += 1; lastDirection = 1; sinceChange = 0 }87        } else if lastDirection == 1, throughput < best * 0.85 {88            // the extra slot bought nothing (or cost throughput): step back89            if limit > 2 { limit -= 1 }90            lastDirection = -1; sinceChange = 0; best = throughput91        } else if throughput < best * 0.5 { best = throughput } // the link itself got slower: forget the old record92    }93}9495public actor TransferQueue {96    public let api: APIClient97    public let store: MetadataStore98    public let uploadThrottle = Throttle()99    public let downloadThrottle = Throttle()100    private let uploader: UploadEngine101    private let downloader: DownloadEngine102    private let conflicts: ConflictResolver103    private let journal: OperationJournal104    private let network: NetworkMonitor?105    /// Staged uploads and partial downloads live here (same volume as their destinations is not required).106    public let workDirectory: URL107    private var tasks: [String: Task<Void, Never>] = [:]108    private var live: [String: (done: Int64, speed: Double, lastBytes: Int64, lastAt: Date, savedAt: Date)] = [:]109    private var listeners: [UUID: AsyncStream<TransferEvent>.Continuation] = [:]110    private var advisor = ConcurrencyAdvisor()111    private var paused = false112    private var started = false113    private var ticker: Task<Void, Never>?114    private var windowBytes: Int64 = 0115    private let power: PowerSource?116    private var powerAware = true117    private var lastPower = PowerState.unconstrained118    /// Priority of each running transfer (to make room for what the person asks for).119    private var runningPriority: [String: Int] = [:]120    /// Transfers stopped to make room: back in the queue, not failures.121    private var preempted: Set<String> = []122    public var retryPolicy = RetryPolicy.transfers123124    public init(api: APIClient, store: MetadataStore, workDirectory: URL, deviceName: String, network: NetworkMonitor? = nil, power: PowerSource? = nil) {125        self.api = api; self.store = store; self.workDirectory = workDirectory; self.network = network; self.power = power126        uploader = UploadEngine(api: api, store: store, throttle: uploadThrottle, deviceName: deviceName)127        downloader = DownloadEngine(api: api, throttle: downloadThrottle)128        conflicts = ConflictResolver(api: api, store: store)129        journal = OperationJournal(api: api, store: store)130    }131132    // MARK: Observation133    public func events() -> AsyncStream<TransferEvent> {134        AsyncStream { c in135            let id = UUID(); listeners[id] = c136            c.onTermination = { [weak self] _ in Task { await self?.dropListener(id) } }137        }138    }139    private func dropListener(_ id: UUID) { listeners[id] = nil }140    private func emit(_ e: TransferEvent) { for l in listeners.values { l.yield(e) } }141142    private static func transfer(_ r: SQLRow) -> Transfer {143        Transfer(id: r["id"]?.text ?? "", direction: TransferDirection(rawValue: r["direction"]?.text ?? "") ?? .upload, state: TransferState(rawValue: r["state"]?.text ?? "") ?? .failed,144                 itemID: r["item_id"]?.text, parentID: r["parent_id"]?.text, name: r["name"]?.text ?? "", localPath: r["local_path"]?.text ?? "", size: r["size"]?.int ?? 0, done: r["done"]?.int ?? 0,145                 sha256: r["sha256"]?.text, baseVersionID: r["base_version_id"]?.text, versionID: r["version_id"]?.text, priority: Int(r["priority"]?.int ?? 0), attempts: Int(r["attempts"]?.int ?? 0),146                 error: r["error"]?.text, source: r["source"]?.text ?? "app", createdAt: Date(timeIntervalSince1970: r["created_at"]?.double ?? 0), finishedAt: r["finished_at"]?.double.map(Date.init(timeIntervalSince1970:)))147    }148    private func decorate(_ t: Transfer) -> Transfer { var t = t; if let l = live[t.id] { t.done = max(t.done, l.done); t.speed = l.speed }; return t }149    public func list(limit: Int = 500) -> [Transfer] {150        ((try? store.db.query("SELECT * FROM transfers ORDER BY CASE state WHEN 'running' THEN 0 WHEN 'queued' THEN 1 WHEN 'paused' THEN 2 WHEN 'failed' THEN 3 ELSE 4 END, ord DESC LIMIT ?", [.int(Int64(limit))])) ?? [])151            .map(TransferQueue.transfer).map(decorate)152    }153    public func get(_ id: String) -> Transfer? { (try? store.db.query("SELECT * FROM transfers WHERE id = ?", [.text(id)]).first).map(TransferQueue.transfer).map(decorate) }154    public struct Summary: Sendable, Equatable { public var running = 0; public var queued = 0; public var paused = 0; public var failed = 0; public var bytesLeft: Int64 = 0; public var speed: Double = 0 }155    public func summary() -> Summary {156        var s = Summary()157        for r in (try? store.db.query("SELECT id, state, size, done FROM transfers WHERE state IN ('running','queued','paused','failed')")) ?? [] {158            let id = r["id"]?.text ?? "", done = max(r["done"]?.int ?? 0, live[id]?.done ?? 0)159            switch r["state"]?.text { case "running": s.running += 1; s.speed += live[id]?.speed ?? 0; case "queued": s.queued += 1; case "paused": s.paused += 1; default: s.failed += 1 }160            if r["state"]?.text != "failed" { s.bytesLeft += max(0, (r["size"]?.int ?? 0) - done) }161        }162        return s163    }164    public var isPaused: Bool { paused }165    private var powerState: PowerState { powerAware ? (power?.state ?? .unconstrained) : .unconstrained }166    public var concurrencyLimit: Int { advisor.allowed(network: network?.status ?? .unknown, power: powerState) }167    /// What the queue is doing and why, for the transfer centre.168    public struct Policy: Sendable, Equatable {169        public var concurrency = 1; public var measuredLimit = 3; public var manual: Int?; public var errorRate = 0.0170        public var power = PowerState.unconstrained; public var deferringBackground = false; public var paused = false171        public var uploadLimit: Int64 = 0; public var downloadLimit: Int64 = 0172        public init() {}173    }174    public func policy() async -> Policy {175        var p = Policy()176        p.concurrency = concurrencyLimit; p.measuredLimit = advisor.limit; p.manual = advisor.manual; p.errorRate = advisor.errorRate177        p.power = powerState; p.deferringBackground = powerState.defersBackground; p.paused = paused178        p.uploadLimit = await uploadThrottle.bytesPerSecond; p.downloadLimit = await downloadThrottle.bytesPerSecond179        return p180    }181    /// Whether battery and Low Power Mode shape the queue (on by default).182    public func setPowerAware(_ on: Bool) { powerAware = on; pump() }183    public func setRetryPolicy(_ p: RetryPolicy) { retryPolicy = p }184185    // MARK: Enqueue186    private func insert(_ t: Transfer) throws {187        let ord = (try store.db.scalar("SELECT COALESCE(MAX(ord), 0) + 1 FROM transfers").int) ?? 1188        try store.db.run("INSERT INTO transfers (id, direction, state, item_id, parent_id, name, local_path, size, done, sha256, base_version_id, version_id, priority, source, created_at, updated_at, ord) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",189                         [.text(t.id), .text(t.direction.rawValue), .text(t.state.rawValue), t.itemID.map(SQLValue.text) ?? .null, t.parentID.map(SQLValue.text) ?? .null, .text(t.name), .text(t.localPath), .int(t.size), .int(0),190                          t.sha256.map(SQLValue.text) ?? .null, t.baseVersionID.map(SQLValue.text) ?? .null, t.versionID.map(SQLValue.text) ?? .null, .int(Int64(t.priority)), .text(t.source),191                          .double(t.createdAt.timeIntervalSince1970), .double(t.createdAt.timeIntervalSince1970), .int(ord)])192        emit(.changed(t)); pump()193    }194    /// Queues a file for upload. The file is first copied into the work directory (a copy-on-write clone on APFS), so the195    /// queue owns stable bytes whatever happens to the original, across restarts and without the original's permissions.196    /// - Parameter replacing: send as a new version of this file instead of creating a new one.197    /// - Parameter baseVersionID: with `replacing`, the version the new content was derived from. When the server holds198    ///   another one by then, nothing is overwritten: the bytes become a conflict copy. nil replaces whatever is there.199    @discardableResult public func enqueueUpload(file: URL, parent: String, name: String? = nil, replacing: DriveItem? = nil, baseVersionID: String? = nil, priority: Int = 0, source: String = "app") throws -> Transfer {200        let id = UUID().uuidString201        let clean = replacing?.name ?? NameRules.sanitize(name ?? file.lastPathComponent)202        let dir = workDirectory.appendingPathComponent("staging/\(id)", isDirectory: true)203        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)204        let staged = try PathSafety.child(of: dir, named: "content")205        try FileManager.default.copyItem(at: file, to: staged)206        let size = (try FileManager.default.attributesOfItem(atPath: staged.path)[.size] as? NSNumber)?.int64Value ?? 0207        let t = Transfer(id: id, direction: .upload, state: .queued, itemID: replacing?.id, parentID: replacing?.parentID ?? parent, name: clean, localPath: staged.path, size: size, done: 0, sha256: nil,208                         baseVersionID: replacing == nil ? nil : baseVersionID, versionID: nil, priority: priority, attempts: 0, error: nil, source: source, createdAt: Date(), finishedAt: nil)209        try insert(t)210        return t211    }212    /// Queues a download of a file (or of one of its versions) to `destination`.213    @discardableResult public func enqueueDownload(_ item: DriveItem, version: FileVersion? = nil, to destination: URL, priority: Int = 0, source: String = "app") throws -> Transfer {214        guard !item.isFolder else { throw DriveError.local("un dossier se télécharge fichier par fichier") }215        let t = Transfer(id: UUID().uuidString, direction: .download, state: .queued, itemID: item.id, parentID: nil, name: destination.lastPathComponent, localPath: destination.path,216                         size: version?.size ?? item.size, done: 0, sha256: version?.sha256 ?? item.sha256, baseVersionID: nil, versionID: version?.id, priority: priority, attempts: 0, error: nil, source: source,217                         createdAt: Date(), finishedAt: nil)218        try insert(t)219        return t220    }221222    // MARK: Control223    private func set(_ id: String, state: TransferState, error: String? = nil, nextTry: Date? = nil, finished: Bool = false) {224        let now = Date().timeIntervalSince1970225        _ = try? store.db.run("UPDATE transfers SET state = ?, error = ?, updated_at = ?, finished_at = ?, done = MAX(done, ?) WHERE id = ?",226                              [.text(state.rawValue), error.map(SQLValue.text) ?? .null, .double(nextTry?.timeIntervalSince1970 ?? now), finished ? .double(now) : .null, .int(live[id]?.done ?? 0), .text(id)])227        if state != .running { live[id] = nil }228        if let t = get(id) { emit(.changed(t)) }229    }230    public func pause(_ id: String) { guard let t = get(id), t.isActive else { return }; tasks[id]?.cancel(); tasks[id] = nil; runningPriority[id] = nil; set(id, state: .paused); pump() }231    public func resume(_ id: String) { guard let t = get(id), t.state == .paused || t.state == .failed else { return }; set(id, state: .queued); pump() }232    public func retry(_ id: String) { resume(id) }233    public func cancel(_ id: String) {234        guard let t = get(id), t.state != .done, t.state != .cancelled else { return }235        tasks[id]?.cancel(); tasks[id] = nil; runningPriority[id] = nil236        set(id, state: .cancelled, finished: true); cleanup(t); pump()237    }238    /// Pauses everything: running transfers stop at once and keep what they have (server session, partial file).239    public func pauseAll() { paused = true; for (id, task) in tasks { task.cancel(); set(id, state: .queued) }; tasks.removeAll(); runningPriority.removeAll() }240    public func resumeAll() { paused = false; pump() }241    public func clearFinished() {242        for r in (try? store.db.query("SELECT id FROM transfers WHERE state IN ('done','cancelled')")) ?? [] { if let id = r["id"]?.text { emit(.removed(id)) } }243        _ = try? store.db.run("DELETE FROM transfers WHERE state IN ('done','cancelled')")244    }245    public func remove(_ id: String) { guard let t = get(id), !t.isActive else { return }; cleanup(t); _ = try? store.db.run("DELETE FROM transfers WHERE id = ?", [.text(id)]); emit(.removed(id)) }246    public func setManualConcurrency(_ n: Int?) { advisor.manual = n; pump() }247    /// Changes the priority of a transfer that has not finished ("send this one first").248    public func setPriority(_ id: String, _ priority: Int) {249        _ = try? store.db.run("UPDATE transfers SET priority = ? WHERE id = ? AND state IN ('queued','running','paused','failed')", [.int(Int64(priority)), .text(id)])250        if runningPriority[id] != nil { runningPriority[id] = priority }251        if let t = get(id) { emit(.changed(t)) }252        pump()253    }254    public func setLimits(uploadBytesPerSecond: Int64, downloadBytesPerSecond: Int64) async {255        await uploadThrottle.setLimit(uploadBytesPerSecond); await downloadThrottle.setLimit(downloadBytesPerSecond)256    }257    private func partial(_ t: Transfer) -> URL { workDirectory.appendingPathComponent("partials/\(t.id).part") }258    private func cleanup(_ t: Transfer) {259        if t.direction == .upload { try? FileManager.default.removeItem(at: URL(fileURLWithPath: t.localPath).deletingLastPathComponent()) }260        else { try? FileManager.default.removeItem(at: partial(t)) }261    }262263    // MARK: Running264    /// Starts the queue: transfers that were running when the process stopped are queued again and resume where they were.265    public func start() {266        guard !started else { return }267        started = true268        _ = try? store.db.run("UPDATE transfers SET state = 'queued' WHERE state = 'running'")269        ticker = Task { [weak self] in270            while !Task.isCancelled { try? await Task.sleep(nanoseconds: 2_000_000_000); await self?.tick() }271        }272        pump()273    }274    public func stop() { ticker?.cancel(); ticker = nil; started = false; for t in tasks.values { t.cancel() }; tasks.removeAll(); runningPriority.removeAll() }275    /// Call when the network came back or the machine woke up: retries waiting for their back-off run now.276    public func kick() { _ = try? store.db.run("UPDATE transfers SET updated_at = 0 WHERE state = 'queued'"); pump() }277278    private func tick() {279        // one measurement window: feed the advisor, persist progress, start what may start280        let running = tasks.count281        if running > 0 { advisor.observe(throughput: Double(windowBytes) / 2.0, saturated: running >= concurrencyLimit) }282        windowBytes = 0283        lastPower = powerState284        let now = Date()285        for (id, l) in live where now.timeIntervalSince(l.savedAt) >= 2 {286            _ = try? store.db.run("UPDATE transfers SET done = ? WHERE id = ?", [.int(l.done), .text(id)]); live[id]?.savedAt = now287            if let t = get(id) { emit(.changed(t)) }288        }289        pump()290    }291    private func pump() {292        guard started, !paused else { return }293        if let network, !network.status.online { return }294        let limit = concurrencyLimit295        // in Low Power Mode or on a nearly empty battery, only what the person asked for runs296        let floor = powerState.defersBackground ? TransferPriority.userInitiated : Int.min297        // queued transfers whose back-off is over (updated_at holds the earliest next try)298        let rows = ((try? store.db.query("SELECT * FROM transfers WHERE state = 'queued' AND updated_at <= ? AND priority >= ? ORDER BY priority DESC, ord LIMIT ?",299                                         [.double(Date().timeIntervalSince1970), .int(Int64(max(floor, -1_000_000))), .int(Int64(limit + tasks.count + 1))])) ?? []).map(TransferQueue.transfer).filter { tasks[$0.id] == nil }300        // every slot busy and something more important waits: the least important running transfer goes back to the queue (it keeps what it has)301        if tasks.count >= limit, let next = rows.first, next.priority >= TransferPriority.userInitiated,302           let victim = runningPriority.filter({ $0.value < next.priority }).min(by: { $0.value < $1.value }) {303            preempted.insert(victim.key); tasks[victim.key]?.cancel(); tasks[victim.key] = nil; runningPriority[victim.key] = nil304            set(victim.key, state: .queued)305        }306        for t in rows where tasks[t.id] == nil && tasks.count < limit {307            set(t.id, state: .running)308            live[t.id] = (t.done, 0, t.done, Date(), Date())309            runningPriority[t.id] = t.priority310            tasks[t.id] = Task { [weak self] in await self?.run(t) }311        }312    }313    private func progress(_ id: String, _ done: Int64) {314        guard var l = live[id] else { return }315        windowBytes += max(0, done - l.done)316        l.done = done317        let dt = Date().timeIntervalSince(l.lastAt)318        if dt >= 1 { l.speed = Double(done - l.lastBytes) / dt * 0.7 + l.speed * 0.3; l.lastBytes = done; l.lastAt = Date() }319        live[id] = l320    }321    private func run(_ t: Transfer) async {322        let report: @Sendable (Int64, Int64) -> Void = { [weak self] done, _ in Task { await self?.progress(t.id, done) } }323        do {324            var stored: DriveItem?325            switch t.direction {326            case .upload:327                let parent = journal.resolve(t.parentID ?? "root")328                if OperationJournal.isLocal(parent) { throw DriveError.offline("le dossier de destination n’est pas encore créé sur le serveur") }329                let target: UploadTarget = t.itemID.map { .newVersion(fileID: $0, folderID: parent, name: t.name, baseVersionID: t.baseVersionID) } ?? .newFile(folderID: parent, name: t.name, onConflict: .rename)330                let outcome = try await uploader.upload(file: URL(fileURLWithPath: t.localPath), to: target, progress: report)331                try store.upsert([outcome.item]); stored = outcome.item332                if case .conflictCopy(let copy, let original) = outcome, let c = try? conflicts.record(itemID: original, itemName: t.name, copy: copy) { emit(.conflict(c)) }333            case .download:334                guard let id = t.itemID else { throw DriveError.local("transfert sans fichier") }335                try await downloader.download(fileID: id, versionID: t.versionID, sha256: t.sha256 ?? "", size: t.size > 0 ? t.size : nil, to: URL(fileURLWithPath: t.localPath), partial: partial(t), progress: report)336            }337            finish(t, item: stored)338        } catch {339            fail(t, DriveError.wrap(error))340        }341    }342    private func finish(_ t: Transfer, item: DriveItem?) {343        tasks[t.id] = nil; runningPriority[t.id] = nil; preempted.remove(t.id)344        advisor.record(success: true)345        live[t.id]?.done = t.size346        set(t.id, state: .done, finished: true)347        _ = try? store.db.run("UPDATE transfers SET done = size WHERE id = ?", [.text(t.id)])348        if t.direction == .upload { cleanup(t) }349        if let done = get(t.id) { emit(.finished(done, item: item)) }350        pump()351    }352    private func fail(_ t: Transfer, _ e: DriveError) {353        if preempted.remove(t.id) != nil { pump(); return } // stopped to make room: its slot may already belong to another run of the same transfer354        tasks[t.id] = nil; runningPriority[t.id] = nil355        guard let now = get(t.id), now.state == .running else { pump(); return } // paused or cancelled meanwhile: that decision stands356        if e == .cancelled { set(t.id, state: .queued); pump(); return }357        let attempts = t.attempts + 1358        _ = try? store.db.run("UPDATE transfers SET attempts = ? WHERE id = ?", [.int(Int64(attempts)), .text(t.id)])359        if e.isTransient || e.code == "content_changed" || e == .unauthenticated {360            // not a verdict: wait and try again, with what was already transferred361            if e.isTransient { advisor.record(success: false) }362            let delay = retryPolicy.delay(attempt: attempts)363            set(t.id, state: .queued, error: e.errorDescription, nextTry: Date().addingTimeInterval(delay))364            if attempts == 6, let cur = get(t.id) { emit(.failed(cur, persistent: true)) }365        } else {366            set(t.id, state: .failed, error: e.errorDescription ?? e.code, finished: true)367            if let cur = get(t.id) { emit(.failed(cur, persistent: false)) }368        }369        pump()370    }371}372
Files main
Menu

Theme