SPB Git

Repository Public

SyncEngine.swift 26.8 KB 565 lines swift

1// SP Drive iOS2// File: Sync/SyncEngine.swift3// Description: Two-way synchronisation between this device and MacLustr. Local changes are applied at once, written to a persistent4//              journal and replayed against the server in order; remote changes arrive through the change feed. Nothing is decided5//              by modification dates: versions and content hashes are compared.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import Foundation1011public enum EngineEvent: Sendable, Equatable {12    case itemsChanged13    case transfersChanged14    case conflictsChanged15    case status(SyncStatus)16    /// The server no longer accepts this device's session.17    case signedOut18    case transferFinished(TransferRecord)19    case conflictDetected(name: String)20}2122public enum SyncStatus: Sendable, Equatable {23    case idle(lastSync: Date?)24    case syncing25    case offline26    case error(String)27}2829public enum EngineError: Error, Sendable, Equatable {30    case notFound31    case invalidName32    case notAvailableOffline33    case transferFailed(String)34    case cancelled35}3637public actor SyncEngine {38    public nonisolated let store: DriveStore39    public nonisolated let files: LocalFiles40    public nonisolated let remote: DriveRemote41    let driver: TransferDriver42    /// How many transfers may run at once right now (network conditions).43    let concurrency: @Sendable () -> Int4445    var listeners: [UUID: AsyncStream<EngineEvent>.Continuation] = [:]46    var syncing = false47    var syncAgain = false48    var syncWaiters: [CheckedContinuation<Void, Never>] = []49    /// Consecutive temporary failures per transfer (in memory: a relaunch starts from short delays again).50    var backoff: [String: Int] = [:]51    public private(set) var status: SyncStatus = .idle(lastSync: nil)52    var inFlight: Set<String> = []53    var notBefore: [String: Date] = [:]54    var waiters: [String: [CheckedContinuation<Void, Error>]] = [:]55    var lastProgressSave: [String: Date] = [:]56    var liveProgress: [String: Int64] = [:]57    /// Bytes already on disk when the current network request of a download started.58    var progressBase: [String: Int64] = [:]59    var eventTask: Task<Void, Never>?60    var retryTask: Task<Void, Never>?6162    // Sync engine 2.0 (see TransferPolicy.swift)63    /// What the device looks like right now (network path, Low Power Mode, battery).64    let conditions: @Sendable () -> TransferConditions65    /// The user's choices, read each time so a change in Settings applies at once.66    let policy: @Sendable () -> TransferPolicy67    var adaptive = AdaptiveConcurrency()68    /// Why each queued transfer is waiting, when it is the policy that holds it.69    var holds: [String: TransferPolicy.Hold] = [:]70    /// Transfers the user explicitly let through on a cellular path although « Wi-Fi only » is on.71    var wifiOnlyExempt: Set<String> = []72    /// Start of the network step under way for each transfer, to measure throughput.73    var stepStarted: [String: (at: Date, bytes: Int64)] = [:]74    /// Source of randomness of the retry jitter (fixed in tests).75    var jitter: @Sendable () -> Double = { Double.random(in: 0...1) }7677    public init(store: DriveStore, files: LocalFiles, remote: DriveRemote, driver: TransferDriver, concurrency: @escaping @Sendable () -> Int = { 3 },78                conditions: @escaping @Sendable () -> TransferConditions = { .ideal }, policy: @escaping @Sendable () -> TransferPolicy = { .default }) {79        self.store = store80        self.files = files81        self.remote = remote82        self.driver = driver83        self.concurrency = concurrency84        self.conditions = conditions85        self.policy = policy86    }8788    // MARK: Events8990    public func events() -> AsyncStream<EngineEvent> {91        let id = UUID()92        let (stream, continuation) = AsyncStream<EngineEvent>.makeStream(bufferingPolicy: .bufferingNewest(256))93        listeners[id] = continuation94        continuation.onTermination = { [weak self] _ in Task { await self?.removeListener(id) } }95        return stream96    }97    func removeListener(_ id: UUID) { listeners[id] = nil }98    func emit(_ e: EngineEvent) { for l in listeners.values { l.yield(e) } }99    func setStatus(_ s: SyncStatus) { if status != s { status = s; emit(.status(s)) } }100101    private enum DriverSignal: Sendable {102        case event(BackgroundEvent)103        /// Everything the driver replayed at start has been handled.104        case replayed(CheckedContinuation<Void, Never>)105    }106107    /// Connects the transfer driver and recovers what was under way when the process last stopped. Crash-safe by construction:108    /// 1. results the system kept for us (steps finished while the app was not running) are handled first, and adopted;109    /// 2. transfers recorded as running that the system no longer holds go back to the queue with what they already moved110    ///    (partial file, server-side upload session) — after a short grace period when the driver may still deliver late results;111    /// 3. operations recorded as running are replayed (every operation is idempotent on the server side or re-checked there).112    public func start() async {113        guard eventTask == nil else { return }114        let (stream, continuation) = AsyncStream<DriverSignal>.makeStream()115        eventTask = Task { [weak self] in116            var replaying = true117            for await signal in stream {118                switch signal {119                case .replayed(let done):120                    replaying = false121                    done.resume()122                case .event(let e):123                    // progress is cheap and ordered; a finished step may talk to the server for a long time and must not hold the others124                    // (except at launch: replayed results are settled before the queue is read again)125                    if case .progress = e { await self?.handle(e) } else if replaying { await self?.handle(e) } else { Task { await self?.handle(e) } }126                }127            }128        }129        driver.start { continuation.yield(.event($0)) }130        await withCheckedContinuation { continuation.yield(.replayed($0)) }131        for op in store.ops() where op.state == .running { store.setOpState(op.id, .pending) }132        if driver.resultsMayArriveLate {133            Task { [weak self] in134                try? await Task.sleep(for: .seconds(2))135                await self?.requeueOrphans()136            }137            await pump()138        } else {139            await requeueOrphans()140        }141    }142143    /// Transfers recorded as running that nobody is moving any more go back to the queue.144    func requeueOrphans() async {145        let active = await driver.activeTags()146        for t in store.transfers(states: [.running]) where !active.contains(t.id) && !inFlight.contains(t.id) {147            var t = t148            t.state = .queued149            try? store.saveTransfer(t)150        }151        emit(.transfersChanged)152        await pump()153    }154155    // MARK: Synchronisation156157    /// Pulls remote changes, then pushes local ones. Calls made while a pass is running are folded into one more pass.158    public func sync() async {159        if syncing {160            // one more pass will run for this caller; it returns when that pass is over161            syncAgain = true162            await withCheckedContinuation { syncWaiters.append($0) }163            return164        }165        syncing = true166        defer {167            syncing = false168            let w = syncWaiters169            syncWaiters = []170            for c in w { c.resume() }171        }172        repeat {173            syncAgain = false174            setStatus(.syncing)175            do {176                try await pull()177                try await push()178                try await pull() // what the push changed on the server comes back with its revisions179                store.setMeta("lastSync", String(Date.now.timeIntervalSince1970))180                setStatus(.idle(lastSync: .now))181            } catch let e as RemoteError where e == .unauthenticated {182                setStatus(.error("Session expirée"))183                emit(.signedOut)184                return185            } catch let e as RemoteError where e.isTransient {186                setStatus(.offline)187            } catch is CancellationError {188                setStatus(.idle(lastSync: lastSync))189            } catch {190                Log.sync.error("sync failed: \(String(describing: error), privacy: .public)")191                setStatus(.error("La synchronisation a échoué"))192            }193            await pump()194        } while syncAgain195    }196197    public var lastSync: Date? { store.meta("lastSync").flatMap(Double.init).map(Date.init(timeIntervalSince1970:)) }198199    func pull() async throws {200        let result = try await MirrorSync.pull(store: store, remote: remote)201        guard !result.isEmpty else { return }202        for (old, new) in result.changed { remoteChanged(old: old, new: new) }203        for gone in result.deleted { remoteDeleted(gone) }204        rebase()205        enforcePinConsistency()206        emit(.itemsChanged)207    }208209    /// Re-applies the effect of every unconfirmed local operation on top of what the server just said.210    func rebase() {211        for op in store.ops() where op.state != .failed { applyLocally(op) }212    }213214    // MARK: Local operations (applied at once, sent when possible)215216    func validName(_ raw: String) throws -> String {217        let n = raw.precomposedStringWithCanonicalMapping.trimmingCharacters(in: .whitespacesAndNewlines)218        guard !n.isEmpty, n != ".", n != "..", !n.contains("/"), !n.contains("\\"), n.utf8.count <= 255, !n.unicodeScalars.contains(where: { $0.value < 0x20 }) else { throw EngineError.invalidName }219        return n220    }221222    func record(_ kind: PendingOp.Kind, itemID: String, targetID: String? = nil, name: String? = nil, flag: Bool = false) throws {223        let id = try store.appendOp(kind, itemID: itemID, targetID: targetID, name: name, flag: flag)224        if let op = store.op(id) {225            applyLocally(op)226            // content waits in the transfer queue even offline, so the user sees it and can cancel it227            if op.kind == .uploadVersion || (op.kind == .uploadNew && op.targetID?.hasPrefix(DriveItem.localPrefix) != true) { ensureUploadTransfer(for: op) }228        }229        emit(.itemsChanged)230        kick()231    }232233    /// Starts a sync pass without making the caller wait for it.234    nonisolated func kick() { Task { await self.sync() } }235236    @discardableResult237    public func createFolder(name: String, in parentID: String) throws -> DriveItem {238        let n = store.freeName(try validName(name), in: parentID)239        guard let parent = store.item(parentID), parent.isFolder else { throw EngineError.notFound }240        let item = DriveItem(id: DriveItem.newLocalID(), isFolder: true, parentID: parent.id, name: n, pending: true)241        try store.upsert(item)242        try record(.createFolder, itemID: item.id, targetID: parent.id, name: n)243        return item244    }245246    public func rename(_ id: String, to name: String) throws {247        guard let item = store.item(id), let parent = item.parentID else { throw EngineError.notFound }248        let n = try validName(name)249        guard n != item.name else { return }250        guard store.freeName(n, in: parent, excluding: id) == n else { throw RemoteError.nameConflict(name: n) }251        try record(.rename, itemID: id, name: n)252    }253254    public func move(_ ids: [String], to destinationID: String) throws {255        guard let dest = store.item(destinationID), dest.isFolder, !dest.isTrashed else { throw EngineError.notFound }256        let destPath = Set(store.path(to: destinationID).map(\.id))257        for id in ids {258            guard let item = store.item(id), item.parentID != nil, item.parentID != destinationID else { continue }259            if item.isFolder, destPath.contains(id) { continue } // a folder cannot go into itself260            try record(.move, itemID: id, targetID: destinationID)261        }262        // moved into or out of a folder kept offline: the copies follow at once, even offline263        if enforcePinConsistency() { emit(.itemsChanged) }264    }265266    public func setStarred(_ ids: [String], _ starred: Bool) throws {267        for id in ids where store.item(id)?.starred != starred { try record(.star, itemID: id, flag: starred) }268    }269270    /// Moves items to the Drive's trash (restorable). Never a definitive deletion.271    public func trash(_ ids: [String]) throws {272        for id in ids where store.item(id).map({ !$0.isTrashed && $0.parentID != nil }) == true { try record(.trash, itemID: id) }273    }274    public func restore(_ ids: [String]) throws {275        for id in ids where store.item(id)?.isTrashed == true { try record(.restore, itemID: id) }276    }277278    /// Definitive deletion of items already in the trash. Refused offline: a deletion for good is only decided with the server reachable.279    public func purge(_ ids: [String]) async throws {280        let items = ids.compactMap(store.item).filter { $0.isTrashed && $0.trashRoot && !$0.isLocalOnly }281        guard !items.isEmpty else { return }282        try await remote.purge(fileIDs: items.filter { !$0.isFolder }.map(\.id), folderIDs: items.filter(\.isFolder).map(\.id))283        await sync()284    }285    public func emptyTrash() async throws {286        try await remote.emptyTrash()287        await sync()288    }289290    /// Duplicates items next to themselves or into another folder (server-side copy, no bytes travel).291    public func copy(_ ids: [String], to destinationID: String) async throws {292        let items = ids.compactMap(store.item).filter { !$0.isLocalOnly }293        guard !items.isEmpty else { return }294        try await remote.copy(fileIDs: items.filter { !$0.isFolder }.map(\.id), folderIDs: items.filter(\.isFolder).map(\.id), to: destinationID)295        await sync()296    }297298    /// Adds a file from this device to the Drive. The bytes are copied into the app's persistent storage first, so the import survives299    /// being offline, the source disappearing, and a restart. Returns the provisional item.300    @discardableResult301    public func importFile(at source: URL, named name: String? = nil, into parentID: String, move: Bool = false) throws -> DriveItem {302        guard let parent = store.item(parentID), parent.isFolder else { throw EngineError.notFound }303        let n = store.freeName(try validName(LocalFiles.safeName(name ?? source.lastPathComponent)), in: parent.id)304        let id = DriveItem.newLocalID()305        let stored = try files.install(source, itemID: id, name: n, location: .offline, move: move)306        let url = files.directory(for: id, location: .offline).appendingPathComponent(stored)307        let size = IntegrityVerifier.size(of: url)308        try store.db.transaction {309            try store.upsert(DriveItem(id: id, isFolder: false, parentID: parent.id, name: n, size: size, pending: true))310            try store.saveLocalState(LocalState(itemID: id, pinned: false, location: .offline, fileName: stored, baseSHA: nil, baseVersionID: nil, localSize: size, dirty: true, downloadedAt: .now, openedAt: nil))311        }312        try record(.uploadNew, itemID: id, targetID: parent.id, name: n)313        return store.item(id)!314    }315316    /// The local copy of a file was modified (an editor saved into it): it will be sent as a new version, based on the version it came from.317    public func noteLocalEdit(_ id: String) throws {318        guard var ls = store.localState(id), let url = files.url(for: ls), let item = store.item(id) else { throw EngineError.notFound }319        ls.localSize = IntegrityVerifier.size(of: url)320        if item.isLocalOnly {321            // not sent yet: the pending first upload will simply take the newer bytes322            try store.saveLocalState(ls)323            restartUpload(for: id)324            emit(.itemsChanged)325            return326        }327        // an edited copy must not be purgeable: keep it in persistent storage until the server has it328        if ls.location == .cache, let name = ls.fileName {329            let stored = try files.install(url, itemID: id, name: name, location: .offline, move: true)330            files.removeCopy(itemID: id, location: .cache)331            ls.location = .offline332            ls.fileName = stored333        }334        ls.dirty = true335        try store.saveLocalState(ls)336        restartUpload(for: id)337        if !store.ops().contains(where: { $0.itemID == id && $0.kind == .uploadVersion && $0.state != .failed }) {338            try record(.uploadVersion, itemID: id)339        } else {340            emit(.itemsChanged)341            kick()342        }343    }344345    /// Writes new content over the local copy of a file and schedules its upload (in-app editor, « replace content »).346    public func replaceContent(of id: String, with source: URL) throws {347        guard let item = store.item(id), !item.isFolder else { throw EngineError.notFound }348        var ls = store.localState(id) ?? LocalState(itemID: id, pinned: false, location: nil, fileName: nil, baseSHA: item.sha256, baseVersionID: item.versionID, localSize: 0, dirty: false, downloadedAt: nil, openedAt: nil)349        if !ls.hasCopy { ls.baseSHA = item.sha256; ls.baseVersionID = item.versionID }350        ls.fileName = try files.install(source, itemID: id, name: item.name, location: .offline, move: false)351        if ls.location == .cache { files.removeCopy(itemID: id, location: .cache) }352        ls.location = .offline353        try store.saveLocalState(ls)354        try noteLocalEdit(id)355    }356357    // MARK: Applying an operation to the local mirror358359    func applyLocally(_ op: PendingOp) {360        guard var item = store.item(op.itemID) else { return }361        switch op.kind {362        case .createFolder, .uploadNew, .uploadVersion:363            item.pending = true364        case .rename:365            if let n = op.name { item.name = n }366            item.pending = true367        case .move:368            if let t = op.targetID { item.parentID = t }369            item.pending = true370        case .star:371            item.starred = op.flag372        case .trash:373            if item.trashedAt == nil { item.trashedAt = op.createdAt; item.trashRoot = true }374            if item.isFolder {375                _ = try? store.db.run("""376                WITH RECURSIVE sub(id) AS (SELECT id FROM items WHERE parent_id = ? UNION ALL SELECT i.id FROM items i JOIN sub ON i.parent_id = sub.id)377                UPDATE items SET trashed_at = ? WHERE trashed_at IS NULL AND id IN (SELECT id FROM sub)378                """, item.id, op.createdAt)379            }380        case .restore:381            item.trashedAt = nil382            item.trashRoot = false383            if item.isFolder {384                _ = try? store.db.run("""385                WITH RECURSIVE sub(id) AS (SELECT id FROM items WHERE parent_id = ? UNION ALL SELECT i.id FROM items i JOIN sub ON i.parent_id = sub.id)386                UPDATE items SET trashed_at = NULL WHERE trash_root = 0 AND id IN (SELECT id FROM sub)387                """, item.id)388            }389        case .purge:390            break391        }392        try? store.upsert(item)393    }394395    // MARK: Push396397    func push() async throws {398        var blocked: Set<String> = []399        var needsPump = false400        for listed in store.ops() where listed.state != .failed {401            // read again: an earlier operation of this pass may have given the item its real identifier402            guard let op = store.op(listed.id), op.state != .failed else { continue }403            let ids = [op.itemID, op.targetID].compactMap { $0 }404            if ids.contains(where: blocked.contains) { blocked.formUnion(ids); continue }405            if op.kind == .uploadNew || op.kind == .uploadVersion {406                // content travels through the transfer queue; later operations on the same item wait for it407                if op.kind == .uploadNew, let parent = op.targetID, parent.hasPrefix(DriveItem.localPrefix) { blocked.insert(op.itemID); continue }408                if store.conflict(itemID: op.itemID) == nil { ensureUploadTransfer(for: op); needsPump = true }409                blocked.insert(op.itemID)410                continue411            }412            if ids.contains(where: { $0.hasPrefix(DriveItem.localPrefix) }) && op.kind != .createFolder {413                // refers to an item whose creation did not go through414                store.setOpState(op.id, .failed, errorCode: "missing_item")415                continue416            }417            do {418                try await run(op)419                store.deleteOp(op.id)420            } catch let e as RemoteError where e.isTransient || e == .unauthenticated {421                throw e422            } catch let e as RemoteError {423                Log.sync.notice("operation \(op.kind.rawValue, privacy: .public) refused: \(String(describing: e), privacy: .public)")424                await refused(op, e)425            }426        }427        emit(.itemsChanged)428        if needsPump { await pump() }429    }430431    func run(_ op: PendingOp) async throws {432        guard let item = store.item(op.itemID) else { return }433        switch op.kind {434        case .createFolder:435            var parent = op.targetID ?? store.rootID ?? ""436            let created: DriveItem437            do { created = try await remote.createFolder(parentID: parent, name: op.name ?? item.name, onConflict: .rename) }438            catch RemoteError.notFound {439                // the parent disappeared on the server: the folder (and what was put in it offline) is kept at the root440                parent = try await rootIdentifier()441                created = try await remote.createFolder(parentID: parent, name: op.name ?? item.name, onConflict: .rename)442            }443            try store.remap(localID: op.itemID, to: created.id)444            moveLocalDirectory(from: op.itemID, to: created.id)445            try store.upsert(created)446        case .rename:447            try store.upsert(try await remote.rename(id: item.id, isFolder: item.isFolder, name: op.name ?? item.name))448        case .star:449            try store.upsert(try await remote.setStarred(id: item.id, isFolder: item.isFolder, starred: op.flag))450        case .move:451            guard let dest = op.targetID else { return }452            try await remote.move(fileIDs: item.isFolder ? [] : [item.id], folderIDs: item.isFolder ? [item.id] : [], to: dest, onConflict: .rename)453        case .trash:454            do { try await remote.trash(fileIDs: item.isFolder ? [] : [item.id], folderIDs: item.isFolder ? [item.id] : []) }455            catch RemoteError.notFound { /* already gone on the server: same outcome */ }456        case .restore:457            try await remote.restore(fileIDs: item.isFolder ? [] : [item.id], folderIDs: item.isFolder ? [item.id] : [])458        case .purge, .uploadNew, .uploadVersion:459            break460        }461    }462463    func rootIdentifier() async throws -> String {464        if let r = store.rootID { return r }465        let r = try await remote.rootID()466        store.setMeta("root", r)467        return r468    }469470    /// The server refused an operation for good: it is kept as « failed » for the user to see, and the item goes back to the server's state.471    func refused(_ op: PendingOp, _ error: RemoteError) async {472        let code: String473        switch error {474        case .nameConflict: code = "name_conflict"475        case .notFound: code = "not_found"476        case .quotaExceeded: code = "quota"477        case .server(_, let c, _): code = c.isEmpty ? "refused" : c478        default: code = "refused"479        }480        store.setOpState(op.id, .failed, errorCode: code, bumpAttempts: true)481        guard let item = store.item(op.itemID), !item.isLocalOnly else { return }482        if let fresh = try? await remote.item(id: item.id, isFolder: item.isFolder) { try? store.upsert(fresh) }483        else if error == .notFound { try? store.deleteItem(item.id) }484    }485486    /// Operations the server refused, for the « problems » list.487    public func failedOps() -> [PendingOp] { store.ops().filter { $0.state == .failed } }488    /// Gives up a refused operation: the device goes back to the Drive's state for that item. For content, this is explicit:489    /// a file that never reached the Drive leaves the device's records, an unsent edit is dropped and the Drive's version comes back.490    public func dismissFailedOp(_ id: Int64) async {491        guard let op = store.op(id), op.state == .failed else { return }492        store.deleteOp(id)493        switch op.kind {494        case .createFolder:495            // a creation that never reached the server leaves a provisional folder behind496            if op.itemID.hasPrefix(DriveItem.localPrefix), store.children(of: op.itemID).isEmpty { try? store.deleteItem(op.itemID) }497        case .uploadNew:498            if op.itemID.hasPrefix(DriveItem.localPrefix) {499                files.removeCopy(itemID: op.itemID, location: .offline)500                try? store.deleteLocalState(op.itemID)501                try? store.deleteItem(op.itemID)502            }503        case .uploadVersion:504            if let item = store.item(op.itemID), let ls = store.localState(op.itemID), store.conflict(itemID: op.itemID) == nil { try? await discardLocalEdit(item, ls, refetch: true) }505        default: break506        }507        emit(.itemsChanged)508        await pump()509    }510    public func retryFailedOp(_ id: Int64) {511        guard let op = store.op(id), op.state == .failed else { return }512        store.setOpState(id, .pending)513        applyLocally(op)514        emit(.itemsChanged)515        kick()516    }517518    func moveLocalDirectory(from oldID: String, to newID: String) {519        let fm = FileManager.default520        for loc in [LocalState.Location.offline, .cache] {521            let a = files.directory(for: oldID, location: loc), b = files.directory(for: newID, location: loc)522            if fm.fileExists(atPath: a.path) { try? fm.removeItem(at: b); try? fm.moveItem(at: a, to: b) }523        }524    }525526    // MARK: Badges527528    /// The network is back: waiting transfers and pending operations go at once instead of waiting for their retry delay.529    public func networkBecameAvailable() async {530        notBefore = [:]531        backoff = [:]532        await sync()533    }534535    /// Something other than reachability changed (Wi-Fi ↔ cellular, Low Data Mode, Low Power Mode, battery, a setting): transfers that may536    /// no longer run go back to the queue with what they already moved, those that may now run start.537    public func conditionsChanged() async {538        await enforcePolicyOnRunning()539        await pump()540        emit(.transfersChanged)541    }542543    public nonisolated func isEffectivelyPinned(_ id: String) -> Bool {544        let pinned = store.pinnedIDs()545        guard !pinned.isEmpty else { return false }546        return store.path(to: id).contains { pinned.contains($0.id) }547    }548549    /// Forgets the account on this device: metadata, journal, every local copy. Call after the user confirmed.550    public func wipe() async {551        await driver.cancelAll()552        for (_, list) in waiters { for c in list { c.resume(throwing: EngineError.cancelled) } }553        waiters = [:]554        inFlight = []555        holds = [:]556        wifiOnlyExempt = []557        stepStarted = [:]558        try? store.wipe()559        files.removeEverything()560        emit(.itemsChanged)561        emit(.transfersChanged)562        emit(.conflictsChanged)563    }564}565
Files main
Menu

Theme