Repository Public
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