Repository Public
1// SP Music iOS2// File: Core/Sources/SPMusicCore/Synchronization/SyncEngine.swift3// Description: Incremental synchronisation with MacLustr and the outbox of offline changes.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai78import Foundation910public struct SyncReport: Sendable, Equatable {11 public var catalogRows = 0 // artists + albums + tracks + deletions applied12 public var full = false13 public var playback: UserSync.Playback?14 public var revision: Int64 = 015}1617/// Keeps the device's copy of the library in step with MacLustr.18///19/// Catalogue: incremental — the device remembers the highest revision it applied and asks only for what is above it20/// (changed rows and tombstones). Audio is never part of a synchronisation. Account data (lists, favourites) is small21/// and read whole. Changes made on the device while offline wait in an outbox and are sent first.22public actor SyncEngine {23 private let db: Database24 private let api: APIClient25 private var running: Task<SyncReport, Error>?2627 public init(db: Database, api: APIClient) { self.db = db; self.api = api }2829 /// Concurrent callers share one run.30 public func sync(full: Bool = false) async throws -> SyncReport {31 if let running { return try await running.value }32 let t = Task { try await self.run(full: full) }33 running = t34 defer { running = nil }35 return try await t.value36 }3738 private func run(full requested: Bool) async throws -> SyncReport {39 var report = SyncReport()40 await flushOutbox()41 let known = await db.catalogRevision42 var full = requested || known == 043 for attempt in 0..<2 {44 var since: Int64 = full ? 0 : await db.catalogRevision45 var seen = (tracks: Set<String>(), albums: Set<String>(), artists: Set<String>())46 var counts = SyncPage.Counts(artists: 0, albums: 0, tracks: 0)47 while true {48 let page = try await api.librarySync(since: since)49 try await db.apply(page)50 report.catalogRows += page.artists.count + page.albums.count + page.tracks.count + page.deleted.count51 if full { for t in page.tracks { seen.tracks.insert(t.id) }; for a in page.albums { seen.albums.insert(a.id) }; for a in page.artists { seen.artists.insert(a.id) } }52 counts = page.counts; since = page.rev; report.revision = page.rev53 if !page.more { break }54 }55 if full { try await db.pruneCatalog(keepingTracks: seen.tracks, albums: seen.albums, artists: seen.artists); report.full = true }56 // Drift check: an incremental pass that does not land on the server's count is redone from zero, once.57 let local = await db.allTrackIds().count58 if full || attempt == 1 || local == counts.tracks { break }59 Log.sync.notice("catalogue drift detected, reading everything again")60 full = true61 }62 let me = try await api.userSync()63 try await db.apply(me)64 await reapplyPendingFavorites()65 report.playback = me.playback66 if let events = try? await api.history(limit: 200) { for e in events { await db.addPlay(e) } }67 await db.setString("sync.at", ISO8601.string(Date()))68 return report69 }7071 public func lastSync() async -> Date? { await db.string("sync.at").flatMap(ISO8601.date) }7273 /// Only the account's lists and favourites (after a playlist edit).74 public func refreshAccount() async throws {75 try await db.apply(try await api.userSync())76 await reapplyPendingFavorites()77 }7879 // MARK: Changes made on the device8081 private struct FavoriteChange: Codable { var kind: String; var id: String; var on: Bool }8283 /// Applied locally at once, sent when the server can be reached.84 public func setFavorite(kind: String, id: String, on: Bool) async {85 await db.setFavorite(kind: kind, id: id, on: on)86 if let data = try? JSONEncoder().encode(FavoriteChange(kind: kind, id: id, on: on)) { await db.enqueue(kind: "favorite", payload: data) }87 await flushOutbox()88 }8990 public func recordPlay(_ e: PlayEvent) async {91 await db.addPlay(e)92 if let data = try? APIClient.encoder.encode(e) { await db.enqueue(kind: "play", payload: data) }93 await flushOutbox()94 }9596 private func reapplyPendingFavorites() async {97 for item in await db.outbox() where item.kind == "favorite" {98 if let f = try? JSONDecoder().decode(FavoriteChange.self, from: item.payload) { await db.setFavorite(kind: f.kind, id: f.id, on: f.on) }99 }100 }101102 /// Sends what is waiting, in order. A network failure keeps everything for later; an item the server refuses103 /// for good (track deleted, invalid) is dropped so it cannot block the ones behind it.104 public func flushOutbox() async {105 guard api.hasSession else { return }106 let items = await db.outbox()107 guard !items.isEmpty else { return }108 var sent: [Int64] = []109 var plays: [(Int64, PlayEvent)] = []110 do {111 for item in items {112 switch item.kind {113 case "favorite":114 guard let f = try? JSONDecoder().decode(FavoriteChange.self, from: item.payload) else { sent.append(item.seq); continue }115 do { try await api.setFavorite(kind: f.kind, id: f.id, on: f.on); sent.append(item.seq) }116 catch let e as APIError where !e.isNetwork && e.status != 401 && e.status != 429 && e.status < 500 { sent.append(item.seq) }117 case "play":118 if let e = try? APIClient.decoder.decode(PlayEvent.self, from: item.payload) { plays.append((item.seq, e)) } else { sent.append(item.seq) }119 default: sent.append(item.seq)120 }121 }122 if !plays.isEmpty {123 do { try await api.postHistory(plays.map(\.1)); sent.append(contentsOf: plays.map(\.0)) }124 catch let e as APIError where !e.isNetwork && e.status != 401 && e.status != 429 && e.status < 500 { sent.append(contentsOf: plays.map(\.0)) }125 }126 } catch { /* network, expired session or throttling: keep the rest */ }127 await db.removeOutbox(seqs: sent)128 }129}130