Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.
Swift apple-silicond3dmetaldxmtdxvkfexgame-porting-toolkitgamingmac-gamingmacosmetalmoltenvksteamswiftuivkd3d-protonwhisky-alternativewindows-gameswinewine-wrapper
Epic saves: decide by what changed, undo failed downloads, verify uploads
Gabed01ff5e09ab4
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swiftindex 1a3bc8a..c4b2c00 100644--- a/Sources/HighballApp/AppState.swift+++ b/Sources/HighballApp/AppState.swift@@ -15,8 +15,9 @@ struct GOGSaveConflict: Identifiable {let title: String/// Asked before Play (the launch waits) or after the game ended.let beforePlay: Bool- /// An Epic game's: Epic's cloud keeps its earlier saves when the Mac's go up.+ /// An Epic game's (EpicSaves), and whether it is the first sync of saves on both sides.var epic = false+ var firstSync = falselet resolve: (Choice) -> Void}@@ -3399,19 +3400,21 @@ final class AppState {}let folder = epicInstalls[game.app_name].map { URL(fileURLWithPath: $0, isDirectory: true) }runBusy("Starting \(game.app_title)", done: .handedOff, stop: .killBottle(bottle, label: L("Stop"))) { [self] in- let store = epicStore+ let store = epicStore, app = game.app_nameawait removeMacMetadataFiles(from: folder, of: game.app_title)- // Fresh single-use token, fetched off the main thread right before launch.- let info = try await Task.detached { try store.launchInfo(game.app_name) }.value- // Saves down from Epic's cloud first, where the game keeps them there and the player- // has not turned it off (EpicSaves).- let syncSaves = epicSignedIn && !epicCloudSavesOff.contains(game.app_name) && folder != nil- && EpicSaves(store: store).supportsCloudSaves(game.app_name)- if syncSaves, let folder {+ // Saves come down from Epic's cloud first, where the game keeps them there and the+ // player hasn't turned it off (EpicSaves). They go back up after the game only when+ // this check left the two sides safe to upload over.+ var uploadAfter = false+ if epicSignedIn, !epicCloudSavesOff.contains(app), let folder,+ await Task.detached(operation: { EpicSaves(store: store).supportsCloudSaves(app) }).value {stage = L("Bringing your saves down from Epic")- try await epicSync(game, install: folder, in: bottle, direction: .download, beforePlay: true)+ uploadAfter = try await epicSync(game, install: folder, in: bottle, direction: .download, beforePlay: true)}try Task.checkCancellation()+ // A fresh single-use token, fetched off the main thread after the sync (which may+ // wait on a question) and right before launch.+ let info = try await Task.detached { try store.launchInfo(app) }.valuelet runner = WineRunner(paths: paths, engine: engine, bottle: bottle)let box = LaunchOutcome()let log = logLine(box)@@ -3453,7 +3456,7 @@ final class AppState {let session = GameSession(title: game.app_title, bottleName: bottle.name, appid: nil, markers: markers,renderer: (renderer ?? bottle.settings.renderer).rawValue, libraryID: "epic:\(game.app_name)",startNotice: row?.startNotice, startNoticeMinutes: row?.startNoticeMinutes)- if syncSaves, let folder {+ if uploadAfter, let folder {epicSessionEnds[session.id] = { [weak self] inTask { @MainActor in _ = try? await self?.epicSync(game, install: folder, in: bottle, direction: .upload, beforePlay: false) }}@@ -3474,47 +3477,75 @@ final class AppState {if on { epicCloudSavesOff.remove(app) } else { epicCloudSavesOff.insert(app) }}- /// One Epic sync, asking the player on a conflict, as gogSync does. Whether the Mac's saves and- /// the cloud's ended up in step.+ /// One Epic sync, asking the player when both sides changed (EpicSaves). Returns true when the+ /// saves end up in step, or when only the other direction has work left, so an upload after+ /// the game may follow; false when the player chose to decide later or the sync failed, so+ /// nothing goes up afterwards. A download that failed partway has the Mac's saves put back+ /// from their backup: before Play that throws, so the game never starts on them.@discardableResult- private func epicSync(_ game: EpicStore.Game, install: URL, in bottle: Bottle, direction: EpicSaves.Direction,+ private func epicSync(_ game: EpicStore.Game, install: URL, in bottle: Bottle?, direction: EpicSaves.Direction,beforePlay: Bool) async throws -> Bool {let saves = EpicSaves(store: epicStore)- let title = game.app_title, app = game.app_name, prefix = bottle.url+ let title = game.app_title, app = game.app_name, prefix = bottle?.urllet log: @Sendable (String) -> Void = { line in Task { @MainActor in self.appendLog(line) } }let outcome = await Task.detached { saves.sync(app, install: install, prefix: prefix, direction: direction, onLine: log) }.valueswitch outcome {case .synced:return true+ case .left:+ appendLog(beforePlay ? "\(title): this Mac's saves are newer than Epic's cloud; they go up after you play"+ : "\(title): Epic's cloud has newer saves from elsewhere; they come down before you next play")+ return truecase let .failed(why):- appendLog("\(title): Epic cloud saves did not sync (\(why)); \(beforePlay ? "playing with the saves on this Mac" : "they stay on this Mac until the next sync")")+ appendLog("\(title): Epic cloud saves did not sync (\(why)); \(beforePlay ? "playing with this Mac's saves, which won't be uploaded afterwards" : "they stay on this Mac until the next sync")")return false- case .conflict:+ case let .restored(why):+ try epicRestored(title, why: why, beforePlay: beforePlay)+ return false+ case let .conflict(firstSync):let choice: GOGSaveConflict.Choice = await withCheckedContinuation { continuation inif let pending = gogSaveConflict {appendLog("\(pending.title): cloud saves left as they are this time (\(title) needed the question)")resolveGOGSaveConflict(.skip)}- gogSaveConflict = GOGSaveConflict(title: title, beforePlay: beforePlay, epic: true) { continuation.resume(returning: $0) }+ gogSaveConflict = GOGSaveConflict(title: title, beforePlay: beforePlay, epic: true, firstSync: firstSync) { continuation.resume(returning: $0) }}let forced: EpicSaves.Directionswitch choice {case .useCloud: forced = .forceDownloadcase .keepMac: forced = .forceUploadcase .skip:- appendLog("\(title): Epic cloud saves left as they are this time")+ appendLog("\(title): Epic cloud saves left as they are; \(beforePlay ? "this Mac's saves won't be uploaded after this session, and " : "")Highball asks again next time")return false}let again = await Task.detached { saves.sync(app, install: install, prefix: prefix, direction: forced, onLine: log) }.valueswitch again {- case .synced: appendLog("\(title): Epic cloud saves \(choice == .useCloud ? "replaced this Mac's, a copy of them kept first" : "now hold this Mac's, beside their earlier saves")")- case let .failed(why): appendLog("\(title): Epic cloud saves did not sync (\(why))")- case .conflict: appendLog("\(title): Epic cloud saves did not sync")+ case .synced:+ appendLog("\(title): \(choice == .useCloud ? "Epic's cloud saves replaced this Mac's, after a backup of them" : "Epic's cloud now has this Mac's saves as its newest")")+ return true+ case let .restored(why):+ try epicRestored(title, why: why, beforePlay: beforePlay)+ return false+ case let .failed(why):+ appendLog("\(title): Epic cloud saves did not sync (\(why))")+ return false+ case .left, .conflict:+ appendLog("\(title): Epic cloud saves did not sync")+ return false}- return again == .synced}}+ /// A download that failed partway, with the Mac's saves put back: before Play it stops the+ /// launch, after the game the player hears about it.+ private func epicRestored(_ title: String, why: String, beforePlay: Bool) throws {+ let message = String(format: L("Highball couldn't bring %@'s saves down from Epic (%@), so it put this Mac's saves back as they were."), title, why)+ if beforePlay {+ throw HighballError.failed(message + " " + L("The game didn't start. Try again, or turn off Sync saves with Epic on the game's page to play with this Mac's saves."))+ }+ fail(HighballError.failed(message))+ }+/// Copies the bundled EpicGamesLauncher.exe stand-in into the game folder when it is missing/// or differs, and returns its location. Nil when this build has none (a debug build without/// mingw) or the folder cannot be written.diff --git a/Sources/HighballApp/GameDetailView.swift b/Sources/HighballApp/GameDetailView.swiftindex cf5e36b..998226e 100644--- a/Sources/HighballApp/GameDetailView.swift+++ b/Sources/HighballApp/GameDetailView.swift@@ -16,6 +16,8 @@ struct GameDetailView: View {@State private var argsText = ""/// The game keeps saves in Epic's cloud (EpicSaves.supportsCloudSaves): read once per page.@State private var epicCloudSaves = false+ /// Where legendary keeps the game's saves, once a sync has worked it out.+ @State private var epicSaveFolder: URL?@State private var argsLoaded = false/// Saves a line still being typed, so the Play that follows launches with it. Skipped until the/// field has loaded, or its empty text would clear the stored arguments.@@ -89,7 +91,11 @@ struct GameDetailView: View {.background(BottleBackdrop()).navigationTitle(state.displayTitle(item)).task(id: item.id) {- epicCloudSaves = item.epicAppName.map { EpicSaves(store: state.epicStore).supportsCloudSaves($0) } ?? false+ // Read off the main thread: legendary's metadata and install records are JSON files.+ let saves = EpicSaves(store: state.epicStore), app = item.epicAppName+ let found = await Task.detached { app.map { (saves.supportsCloudSaves($0), saves.savePath($0)) } }.value+ epicCloudSaves = found?.0 ?? false+ epicSaveFolder = found?.1}.task(id: storeAppID) {storeDetails = nil@@ -138,9 +144,7 @@ struct GameDetailView: View {}}- /// A GOG game's own settings, one row each like the rest of the page: comet (achievements and- /// stats), cloud saves, which launch task Play runs, and an update for a game gogdl installed.-+ /// An Epic game's cloud-save setting, in the game settings like GOG's.private func epicSettings(_ app: String) -> some View {HStack(alignment: .top, spacing: 12) {Text(L("Cloud saves")).font(.caption).foregroundStyle(.secondary).frame(width: 110, alignment: .leading).padding(.top, 2)@@ -148,12 +152,18 @@ struct GameDetailView: View {Toggle(L("Sync saves with Epic"), isOn: Binding(get: { !state.epicCloudSavesOff.contains(app) }, set: { state.epicSetCloudSaves($0, for: app) })).toggleStyle(.checkbox).disabled(!state.epicSignedIn)- Text(L("Saves come down from Epic's cloud before Play, after a copy of this Mac's is kept, and go back up when the game ends. If both changed, Highball asks which one wins."))+ Text(L("Before Play, newer saves come down from Epic's cloud, after this Mac's are backed up; when the game ends, this Mac's go back up. If both changed since the last sync, Highball asks which to keep.")).font(.caption).foregroundStyle(.secondary).fixedSize(horizontal: false, vertical: true)+ if let epicSaveFolder {+ Text(String(format: L("Saves sync from %@."), (epicSaveFolder.path as NSString).abbreviatingWithTildeInPath))+ .font(.caption).foregroundStyle(.secondary).fixedSize(horizontal: false, vertical: true).textSelection(.enabled)+ }}}}+ /// A GOG game's own settings, one row each like the rest of the page: comet (achievements and+ /// stats), cloud saves, which launch task Play runs, and an update for a game gogdl installed.@ViewBuilder private func gogSettings(_ game: GOGStore.InstalledGame) -> some View {let cometOff = state.gogSettings.cometOff[game.id]HStack(alignment: .top, spacing: 12) {diff --git a/Sources/HighballApp/HighballApp.swift b/Sources/HighballApp/HighballApp.swiftindex bc9baa7..b3555f8 100644--- a/Sources/HighballApp/HighballApp.swift+++ b/Sources/HighballApp/HighballApp.swift@@ -555,7 +555,7 @@ private extension View {Button(L("Keep this Mac's saves")) { state.resolveGOGSaveConflict(.keepMac) }Button(L("Decide later"), role: .cancel) { state.resolveGOGSaveConflict(.skip) }} message: { conflict in- Text(conflict.epic ? Self.epicSaveConflictMessage(beforePlay: conflict.beforePlay, backups: EpicSaves(store: state.epicStore).backups.root)+ Text(conflict.epic ? Self.epicSaveConflictMessage(beforePlay: conflict.beforePlay, firstSync: conflict.firstSync, backups: EpicSaves(store: state.epicStore).backups.root): Self.saveConflictMessage(beforePlay: conflict.beforePlay, backups: GOGSaves(store: state.gogStore).backupsDir))}}@@ -590,13 +590,16 @@ private extension View {}}- /// Epic's: the Mac's saves changed since the last sync and the cloud has newer ones. Epic's cloud- /// keeps its earlier saves when the Mac's go up, so only the Mac's need a copy (EpicSaves).- static func epicSaveConflictMessage(beforePlay: Bool, backups: URL) -> String {- let decideLater = beforePlay ? L("Decide later plays with this Mac's saves and leaves the cloud alone.")- : L("Decide later leaves both as they are until the next time you play.")- return [L("The saves on this Mac changed since they were last synced, and Epic's cloud has newer ones, so neither was copied."),- String(format: L("Use Epic's cloud saves replaces this Mac's, after a copy of them is kept in %@; Keep this Mac's saves adds them to Epic's cloud, which keeps its earlier saves."),+ /// For an Epic game (EpicSaves). Each choice says what it replaces; the Mac's saves are+ /// backed up before Epic's replace them.+ static func epicSaveConflictMessage(beforePlay: Bool, firstSync: Bool, backups: URL) -> String {+ let situation = firstSync+ ? L("This Mac and Epic's cloud both have saves for this game, and Highball hasn't synced them before, so it can't tell which to keep. Nothing was copied or replaced.")+ : L("The saves on this Mac and the ones in Epic's cloud have both changed since they were last synced. Nothing was copied or replaced.")+ let decideLater = beforePlay ? L("Decide later plays with this Mac's saves and doesn't upload them afterwards; Highball asks again next time.")+ : L("Decide later leaves both as they are; Highball asks again next time you play.")+ return [situation,+ String(format: L("Use Epic's cloud saves replaces this Mac's, after backing them up to %@. Keep this Mac's saves uploads them as Epic's newest save, which your other devices then download."),(backups.path as NSString).abbreviatingWithTildeInPath),decideLater].joined(separator: " ")}diff --git a/Sources/HighballApp/L10n.swift b/Sources/HighballApp/L10n.swiftindex e319723..ec83117 100644--- a/Sources/HighballApp/L10n.swift+++ b/Sources/HighballApp/L10n.swift@@ -230,14 +230,25 @@ enum L10n {"The saves on this Mac and the ones in GOG's cloud have both changed since they were last synced, or haven't been synced from this install yet, so neither was copied.":"Les sauvegardes de ce Mac et celles du cloud GOG ont toutes deux changé depuis leur dernière synchronisation, ou n’ont pas encore été synchronisées depuis cette installation : aucune n’a été copiée.","Use Epic's cloud saves": "Utiliser les sauvegardes du cloud Epic",- "The saves on this Mac changed since they were last synced, and Epic's cloud has newer ones, so neither was copied.":- "Les sauvegardes de ce Mac ont changé depuis leur dernière synchronisation, et le cloud Epic en a de plus récentes : aucune n’a été copiée.",- "Use Epic's cloud saves replaces this Mac's, after a copy of them is kept in %@; Keep this Mac's saves adds them to Epic's cloud, which keeps its earlier saves.":- "Utiliser les sauvegardes du cloud Epic remplace celles de ce Mac, après en avoir gardé une copie dans %@ ; Garder les sauvegardes de ce Mac les ajoute au cloud Epic, qui garde ses sauvegardes précédentes.",+ "This Mac and Epic's cloud both have saves for this game, and Highball hasn't synced them before, so it can't tell which to keep. Nothing was copied or replaced.":+ "Ce Mac et le cloud Epic ont tous deux des sauvegardes de ce jeu, et Highball ne les a encore jamais synchronisées : il ne peut pas savoir lesquelles garder. Rien n’a été copié ni remplacé.",+ "The saves on this Mac and the ones in Epic's cloud have both changed since they were last synced. Nothing was copied or replaced.":+ "Les sauvegardes de ce Mac et celles du cloud Epic ont toutes changé depuis leur dernière synchronisation. Rien n’a été copié ni remplacé.",+ "Decide later plays with this Mac's saves and doesn't upload them afterwards; Highball asks again next time.":+ "Décider plus tard joue avec les sauvegardes de ce Mac sans les envoyer ensuite ; Highball redemandera la prochaine fois.",+ "Decide later leaves both as they are; Highball asks again next time you play.":+ "Décider plus tard laisse les deux telles quelles ; Highball redemandera à la prochaine partie.",+ "Use Epic's cloud saves replaces this Mac's, after backing them up to %@. Keep this Mac's saves uploads them as Epic's newest save, which your other devices then download.":+ "Utiliser les sauvegardes du cloud Epic remplace celles de ce Mac, après les avoir sauvegardées dans %@. Garder les sauvegardes de ce Mac les envoie comme sauvegarde la plus récente d’Epic, que vos autres appareils téléchargeront ensuite.",+ "Highball couldn't bring %@'s saves down from Epic (%@), so it put this Mac's saves back as they were.":+ "Highball n’a pas pu récupérer les sauvegardes de %@ depuis Epic (%@) : il a remis celles de ce Mac telles qu’elles étaient.",+ "The game didn't start. Try again, or turn off Sync saves with Epic on the game's page to play with this Mac's saves.":+ "Le jeu n’a pas été lancé. Réessayez, ou désactivez Synchroniser avec Epic sur la page du jeu pour jouer avec les sauvegardes de ce Mac.",+ "Saves sync from %@.": "Les sauvegardes se synchronisent depuis %@.","Bringing your saves down from Epic": "Récupération de vos sauvegardes depuis Epic","Sync saves with Epic": "Synchroniser avec Epic",- "Saves come down from Epic's cloud before Play, after a copy of this Mac's is kept, and go back up when the game ends. If both changed, Highball asks which one wins.":- "Les sauvegardes arrivent du cloud Epic avant de jouer, après une copie de celles de ce Mac, et y repartent quand le jeu se termine. Si les deux ont changé, Highball demande laquelle garder.",+ "Before Play, newer saves come down from Epic's cloud, after this Mac's are backed up; when the game ends, this Mac's go back up. If both changed since the last sync, Highball asks which to keep.":+ "Avant de jouer, les sauvegardes plus récentes arrivent du cloud Epic, après une copie de celles de ce Mac ; quand le jeu se termine, celles de ce Mac y repartent. Si les deux ont changé depuis la dernière synchronisation, Highball demande lesquelles garder.","Use GOG's cloud saves replaces this Mac's; Keep this Mac's saves replaces the cloud's. Either way, a copy of what gets replaced is kept first, in %@.":"Utiliser les sauvegardes du cloud GOG remplace celles de ce Mac ; Garder les sauvegardes de ce Mac remplace celles du cloud. Dans les deux cas, une copie de ce qui est remplacé est d’abord conservée dans %@.","Remove %@ without a copy of every save?": "Supprimer %@ sans copie de toutes ses sauvegardes ?",diff --git a/Sources/HighballKit/EpicSaves.swift b/Sources/HighballKit/EpicSaves.swiftindex 24ab8e9..e81959a 100644--- a/Sources/HighballKit/EpicSaves.swift+++ b/Sources/HighballKit/EpicSaves.swift@@ -1,19 +1,31 @@+import Darwinimport Foundationimport os-/// Epic cloud saves, through legendary's `sync-saves`, before and after a Windows Epic game plays.+/// Epic cloud saves, through legendary's `sync-saves`, before and after an Epic game plays.///-/// legendary decides by age alone: whichever of the newest local file and the newest cloud save is-/// newer wins, with no notion of both having changed (legendary/cli.py `sync_saves`). A download-/// empties the save folder first (`download_saves(clean_dir=True)`); an upload adds a save to-/// Epic's cloud, which keeps the earlier ones. So here:-/// - the folder legendary resolves (from the game's CloudSaveFolder, inside the environment's-/// registry) is copied before any download (SaveBackups), and a failed copy stops it;-/// - a download over saves changed since Highball last synced them is a conflict, asked, never-/// decided by age;-/// - an upload needs no copy: the cloud keeps what it had.-/// legendary runs with `-y` (it would otherwise stop at a question with no terminal to answer)-/// and `--accept-path` (to take the path it resolved).+/// legendary 0.21.0 decides by age alone: it compares the newest local file with the newest cloud+/// save and lets the newer side win, with no notion of both sides having changed (cli.py+/// `sync_saves`, core.py `check_savegame_state`). A download first deletes the save folder's files+/// (`download_saves(clean_dir=True)`), and carries on and exits 0 when a manifest or chunk then+/// fails to download. An upload adds a new cloud save and ignores the status of each file it puts.+/// So Highball works around it:+/// - It records, per install, when the saves were last in step and which cloud save they matched.+/// A sync then knows which side changed since, and asks when both did, in either direction, or+/// when a first sync finds saves on both sides. Age alone never decides.+/// - Before a download, the files it would delete are backed up (SaveBackups), and a failed backup+/// stops it. A download that reports any failure, or after which legendary does not see the two+/// sides in step, is undone from that backup. A marker kept during the download undoes one that+/// was interrupted.+/// - After an upload, legendary must see a new cloud save in step with the Mac, or the upload+/// counts as failed.+/// - A save folder that holds more than one game's saves (the home folder, Documents, Application+/// Support, a whole install folder) is never synced: a download would empty it.+/// - A save folder legendary resolved for another environment is resolved again.+/// - Syncs of one game never overlap.+/// legendary runs with `-y` (it would otherwise stop at a question with no terminal to answer),+/// `--accept-path` (to take the save folder it resolves) and `-v` (its debug line carries the+/// cloud save's date in every case).public struct EpicSaves: Sendable {public let store: EpicStorepublic init(store: EpicStore) { self.store = store }@@ -21,17 +33,31 @@ public struct EpicSaves: Sendable {public enum Direction: Sendable { case download, upload, forceDownload, forceUpload }public enum Outcome: Sendable, Equatable {+ /// The two sides are in step, or one was copied to the other and checked.case synced- /// Saves changed on the Mac since the last sync, and the cloud has newer ones: nothing- /// moved, the player chooses.- case conflict+ /// Only the other side's direction has anything to do (newer saves on the Mac before Play,+ /// or newer saves in the cloud after it). Nothing moved.+ case left+ /// Both sides changed since the last sync, or a first sync found saves on both. Nothing+ /// moved; the player chooses.+ case conflict(firstSync: Bool)+ /// Nothing moved.case failed(String)+ /// A download failed partway, and the Mac's saves were put back from the backup.+ case restored(String)}- /// What legendary found, from its log; nil when it said nothing about this game (no cloud- /// saves, or no save folder it could resolve).+ /// What legendary found, from its log.public enum State: Sendable, Equatable { case nothing, inStep, cloudNewer, localNewer }+ /// One comparison: the state, and the date of the newest cloud save (as legendary names it,+ /// "yyyy-MM-dd HH:mm:ss" in UTC), nil when the cloud has none.+ public struct Check: Sendable, Equatable {+ public let state: State+ public let cloud: String?+ public init(state: State, cloud: String?) { self.state = state; self.cloud = cloud }+ }+static func state(in lines: [String]) -> State? {for line in lines {if line.contains("No cloud or local savegame found") { return .nothing }@@ -42,8 +68,50 @@ public struct EpicSaves: Sendable {return nil}- /// legendary's lines for something it could not do and carried on past.- static func isFailure(_ line: String) -> Bool { line.contains(" ERROR: ") || line.contains(" CRITICAL: ") }+ /// The newest cloud save's date. The debug line ("Remote save date: 2026-11-01 01:36:04+00:00")+ /// appears whenever both sides have saves; the info line ("- Cloud save date: …") covers the+ /// rest.+ static func cloudDate(in lines: [String]) -> String? {+ for line in lines {+ if let range = line.range(of: "Remote save date: ") {+ return String(line[range.upperBound...].prefix(19))+ }+ }+ for line in lines {+ if let range = line.range(of: "- Cloud save date: ") {+ let value = String(line[range.upperBound...].prefix(19))+ return value.hasPrefix("N/A") ? nil : value+ }+ }+ return nil+ }++ static func check(in lines: [String]) -> Check? {+ state(in: lines).map { Check(state: $0, cloud: $0 == .nothing ? nil : cloudDate(in: lines)) }+ }++ static func isDebug(_ line: String) -> Bool { line.contains("] DEBUG: ") }++ /// legendary's lines for something it could not do and carried on past. A download that+ /// skips a chunk or a file part only warns or errors and still "completes".+ static func isFailure(_ line: String) -> Bool {+ line.contains(" ERROR: ") || line.contains(" CRITICAL: ")+ || line.contains("may be incomplete") || line.contains("may have been corrupted")+ }++ /// Why a run told nothing about the game, in the player's terms, from legendary's log.+ static func explanation(_ lines: [String]) -> String {+ let all = lines.joined(separator: "\n")+ if all.contains("Login failed") { return "Highball's Epic sign-in has expired; sign in to Epic again" }+ if all.contains("Unable to lock install data") { return "legendary was busy with another task" }+ if all.contains("unprocessed variables") { return "legendary couldn't work out where this game keeps its saves on this Mac" }+ if all.contains("Game not installed") { return "legendary doesn't list this game as installed" }+ if all.contains("does not support cloud saves") { return "Epic lists no cloud saves for this game" }+ if let error = lines.first(where: isFailure) {+ return "legendary reported: " + (error.components(separatedBy: ": ").dropFirst().joined(separator: ": "))+ }+ return "legendary said nothing about this game's saves"+ }static func arguments(app: String, direction: Direction?) -> [String] {let flags: [String]@@ -54,112 +122,398 @@ public struct EpicSaves: Sendable {case .forceDownload?: flags = ["--force-download"]case .forceUpload?: flags = ["--force-upload"]}- return ["sync-saves", app, "-y", "--accept-path"] + flags+ return ["-v", "sync-saves", app, "-y", "--accept-path"] + flags+ }++ // MARK: The catalog++ /// What Epic's catalog says about a game's cloud saves, from the metadata legendary keeps+ /// (metadata/<app>.json customAttributes).+ public struct Catalog: Sendable, Equatable {+ public let windowsFolder: String?+ public let macFolder: String?+ public let filter: SaveFilter}- /// Whether the game's catalog item names a cloud save folder for Windows, from the metadata- /// legendary keeps (metadata/<app>.json customAttributes.CloudSaveFolder).- public func supportsCloudSaves(_ app: String) -> Bool {+ public func catalog(_ app: String) -> Catalog? {let file = store.configDir.appending(path: "metadata/\(app).json")guard let data = try? Data(contentsOf: file),let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any],- let attributes = (obj["metadata"] as? [String: Any])?["customAttributes"] as? [String: Any],- let folder = (attributes["CloudSaveFolder"] as? [String: Any])?["value"] as? String else { return false }- return !folder.isEmpty+ let attributes = (obj["metadata"] as? [String: Any])?["customAttributes"] as? [String: Any] else { return nil }+ func value(_ key: String) -> String? { (attributes[key] as? [String: Any])?["value"] as? String }+ return Catalog(windowsFolder: value("CloudSaveFolder").flatMap { $0.isEmpty ? nil : $0 },+ macFolder: value("CloudSaveFolder_MAC").flatMap { $0.isEmpty ? nil : $0 },+ filter: SaveFilter(includeList: value("CloudIncludeList"), excludeList: value("CloudExcludeList")))}- // MARK: Sync+ /// Whether the catalog names a cloud save folder for that build.+ public func supportsCloudSaves(_ app: String, mac: Bool = false) -> Bool {+ guard let catalog = catalog(app) else { return false }+ return (mac ? catalog.macFolder : catalog.windowsFolder) != nil+ }++ // MARK: Where the saves are++ var installedFile: URL { store.configDir.appending(path: "installed.json") }++ /// The save folder legendary stored for the game, read from its install records directly.+ public func savePath(_ app: String) -> URL? {+ guard let data = try? Data(contentsOf: installedFile),+ let all = try? JSONSerialization.jsonObject(with: data) as? [String: Any],+ let path = (all[app] as? [String: Any])?["save_path"] as? String, !path.isEmpty else { return nil }+ return URL(fileURLWithPath: path, isDirectory: true)+ }- /// Copies kept before a download (SaveBackups), beside GOG's.+ /// Forgets the save folder legendary stored, so its next run resolves it again. Holds+ /// legendary's own lock on its install records (installed.json.lock, the flock its filelock+ /// takes) while writing, and gives up when another legendary holds it.+ func forgetSavePath(_ app: String) throws {+ let lockPath = installedFile.path + ".lock"+ let fd = open(lockPath, O_RDWR | O_CREAT, 0o644)+ guard fd >= 0 else { throw HighballError.failed("couldn't open legendary's lock") }+ defer { close(fd) }+ guard flock(fd, LOCK_EX | LOCK_NB) == 0 else { throw HighballError.failed("legendary was busy with another task") }+ defer { flock(fd, LOCK_UN) }+ let data = try Data(contentsOf: installedFile)+ guard var all = try JSONSerialization.jsonObject(with: data) as? [String: Any],+ var game = all[app] as? [String: Any] else { return }+ game["save_path"] = NSNull()+ all[app] = game+ try JSONSerialization.data(withJSONObject: all, options: [.prettyPrinted, .sortedKeys]).write(to: installedFile, options: .atomic)+ }++ /// Where a save folder may be: inside the environment, or in a Mac folder one of its user+ /// folders links to (Documents, by default, is ~/Documents). For a Mac build, anywhere in the+ /// home folder.+ static func allowedRoots(prefix: URL?, home: URL) -> [URL] {+ guard let prefix else { return [home] }+ var roots = [prefix]+ for user in UserFolders.userDirectories(driveC: prefix.appending(path: "drive_c")) {+ let entries = (try? FileManager.default.contentsOfDirectory(at: user, includingPropertiesForKeys: nil)) ?? []+ for entry in entries {+ if let target = try? FileManager.default.destinationOfSymbolicLink(atPath: entry.path) {+ roots.append(URL(fileURLWithPath: target, relativeTo: user).standardizedFileURL)+ }+ }+ }+ return roots+ }++ /// A path's components with symlinks resolved, lowercased (APFS ignores case). Only an+ /// existing path resolves, so the nearest existing folder above it is resolved and the rest+ /// appended.+ static func components(_ url: URL) -> [String] {+ var existing = url.standardizedFileURL, rest: [String] = []+ while !FileManager.default.fileExists(atPath: existing.path), existing.pathComponents.count > 1 {+ rest.insert(existing.lastPathComponent, at: 0)+ existing = existing.deletingLastPathComponent()+ }+ return (existing.resolvingSymlinksInPath().pathComponents + rest).map { $0.lowercased() }+ }++ static func isInside(_ path: URL, roots: [URL]) -> Bool {+ let parts = components(path)+ return roots.contains { parts.starts(with: components($0)) }+ }++ /// Why a save folder must not be synced, nil when it may. A download deletes every file in the+ /// folder that the game's filters pick (all of them, without filters), so a folder that holds+ /// more than the game's saves never syncs: the home folder and its usual folders, an+ /// environment's drive and user folders, and the game's install folder or anything above it+ /// (unless an include list limits the sync to the saves in it).+ static func refusal(for folder: URL, install: URL, prefix: URL?, home: URL, filter: SaveFilter) -> String? {+ let parts = components(folder)+ var shared = [home]+ shared += ["Documents", "Documents/My Games", "Desktop", "Downloads", "Music", "Pictures", "Movies",+ "Library", "Library/Application Support", "Library/Preferences", "Library/Caches",+ "Library/Containers", "Library/Group Containers", "Saved Games"].map { home.appending(path: $0) }+ if let prefix {+ let driveC = prefix.appending(path: "drive_c")+ shared += [prefix, driveC, driveC.appending(path: "users"), driveC.appending(path: "users/Public"),+ driveC.appending(path: "users/Public/Documents"), driveC.appending(path: "ProgramData"),+ driveC.appending(path: "Program Files"), driveC.appending(path: "Program Files (x86)"),+ driveC.appending(path: "windows")]+ for user in UserFolders.userDirectories(driveC: driveC) {+ shared += [user] + ["AppData", "AppData/Local", "AppData/Roaming", "AppData/LocalLow", "Documents",+ "Documents/My Games", "Saved Games", "Desktop"].map { user.appending(path: $0) }+ }+ }+ let shown = (folder.path as NSString).abbreviatingWithTildeInPath+ let why = "Epic names \(shown) as this game's save folder, and it holds more than this game's saves, so Highball doesn't sync it: a download from Epic would empty it first"+ if shared.contains(where: { components($0) == parts }) { return why }+ // Above the home folder or an environment (/, /Users).+ if ([home] + (prefix.map { [$0] } ?? [])).contains(where: { components($0).starts(with: parts) }) { return why }+ let installParts = components(install)+ if installParts.starts(with: parts), parts != installParts || filter.include?.isEmpty != false { return why }+ return nil+ }++ // MARK: Sync history++ /// What Highball knows about an install's saves after its last sync.+ public struct Record: Codable, Sendable, Equatable {+ /// When the two sides were last in step.+ public var synced: Date+ /// The newest cloud save they matched then; nil in a record from before it was kept.+ public var cloud: String? = nil+ /// The save folder they were in.+ public var path: String? = nil+ /// A summary of the folder's saves then (SaveBackups.fingerprint): any change to them+ /// since, however soon after, changes it.+ public var local: String? = nil+ /// Set while a download runs: the backup to put back if it never finished ("" when the+ /// folder held no saves before it).+ public var restoring: String? = nil+ }++ /// Backups taken before a download (SaveBackups), next to GOG's.public var backups: SaveBackups { SaveBackups(root: store.configDir.deletingLastPathComponent().appending(path: "save-backups", directoryHint: .isDirectory)) }- var lastSyncsFile: URL { store.configDir.deletingLastPathComponent().appending(path: "epic-saves.json") }+ var recordsFile: URL { store.configDir.deletingLastPathComponent().appending(path: "epic-saves.json") }- /// When each install's saves were last in step with the cloud: per install, like GOG's.- func lastSyncs() -> [String: Date] {+ public func records() -> [String: Record] {let decoder = JSONDecoder(); decoder.dateDecodingStrategy = .iso8601- return (try? decoder.decode([String: Date].self, from: Data(contentsOf: lastSyncsFile))) ?? [:]+ guard let data = try? Data(contentsOf: recordsFile) else { return [:] }+ if let records = try? decoder.decode([String: Record].self, from: data) { return records }+ // The first version kept only the date.+ let dates = (try? decoder.decode([String: Date].self, from: data)) ?? [:]+ return dates.mapValues { Record(synced: $0) }}- private static let lastSyncsLock = NSLock()- private func noteSynced(_ key: String) {- Self.lastSyncsLock.withLock {- var all = lastSyncs()- all[key] = Date()+ private static let recordsLock = NSLock()+ func update(_ key: String, _ change: (inout Record?) -> Void) {+ Self.recordsLock.withLock {+ var all = records()+ var record = all[key]+ change(&record)+ all[key] = recordlet encoder = JSONEncoder(); encoder.dateEncodingStrategy = .iso8601; encoder.outputFormatting = [.sortedKeys]- try? encoder.encode(all).write(to: lastSyncsFile, options: .atomic)+ try? encoder.encode(all).write(to: recordsFile, options: .atomic)}}- /// Syncs a Windows Epic game's saves. `prefix` is the environment it is installed in, which- /// legendary reads to resolve the save folder; `install` keys the backups and sync history.- public func sync(_ app: String, install: URL, prefix: URL, direction: Direction,- onLine: (@Sendable (String) -> Void)? = nil) -> Outcome {- let key = "\(app)@\(install.standardizedFileURL.path)"- let environment = ["WINEPREFIX": prefix.path]- // First, only where the saves are and which side is newer: nothing moves.- let lines = OSAllocatedUnfairLock(initialState: [String]())- let checked: Int32- do {- checked = try store.runStreaming(Self.arguments(app: app, direction: nil), environment: environment) { line in- lines.withLock { $0.append(line) }- onLine?(line)- }- } catch { return .failed(error.localizedDescription) }- let log = lines.withLock { $0 }- guard checked == 0, !log.contains(where: Self.isFailure) else { return .failed("legendary could not compare the saves") }- guard let state = Self.state(in: log) else { return .failed("legendary found no save folder for this game") }- guard let folder = (try? store.installedGames())?.first(where: { $0.app_name == app })?.save_path.map({ URL(fileURLWithPath: $0) })- else { return .failed("legendary kept no save folder for this game") }-- let downloads: Bool- switch Self.decide(state, direction: direction, lastChange: Self.latestChange(in: folder), lastSync: lastSyncs()[key]) {- case .inStep: noteSynced(key); return .synced- case .leave: return .synced- case .conflict: return .conflict- case .transfer(let download): downloads = download- }- if downloads {- do { try backups.backUpLocal(folder, into: backups.folder("epic-\(app)", install: install)) } catch {- return .failed("the saves could not be backed up first (\(error.localizedDescription)), so nothing was synced")- }+ /// Drops a download's marker, and the whole record when the marker was all there was.+ func clearRestoring(_ key: String) {+ update(key) { record in+ record?.restoring = nil+ if record?.synced == .distantPast { record = nil }}- let failed = OSAllocatedUnfairLock(initialState: false)- let status: Int32- do {- status = try store.runStreaming(Self.arguments(app: app, direction: direction), environment: environment) { line in- if Self.isFailure(line) { failed.withLock { $0 = true } }- onLine?(line)- }- } catch { return .failed(error.localizedDescription) }- guard status == 0, !failed.withLock({ $0 }) else { return .failed("legendary sync-saves did not finish (status \(status))") }- noteSynced(key)- return .synced}- enum Decision: Equatable { case inStep, leave, conflict, transfer(download: Bool) }+ public static func key(app: String, install: URL) -> String { "\(app)@\(install.standardizedFileURL.path)" }- /// What a sync does once legendary has compared the two sides. A download over saves changed- /// here since the last sync (or never synced) is a conflict: legendary would let the newer- /// side win and empty the folder. Newer here before Play, or newer in the cloud after the- /// game, is left for the other direction to take.- static func decide(_ state: State, direction: Direction, lastChange: Date?, lastSync: Date?) -> Decision {+ // MARK: Deciding++ public enum Decision: Sendable, Equatable { case inStep, leave, conflict(firstSync: Bool), transfer(download: Bool) }++ /// What a sync does once legendary has compared the two sides, from what changed on each+ /// since the record: never the age alone. With no record, a side with saves counts as changed.+ static func decide(_ check: Check, direction: Direction, record: Record?, lastChange: Date?, hasLocal: Bool,+ fingerprint: String? = nil) -> Decision {switch direction {case .forceDownload: return .transfer(download: true)case .forceUpload: return .transfer(download: false)+ case .download, .upload: break+ }+ if check.state == .nothing || check.state == .inStep { return .inStep }+ let cloudChanged: Bool+ let localChanged: Bool+ if let record {+ if let seen = record.cloud {+ cloudChanged = check.cloud != seen+ } else {+ // A record from before the cloud save was kept: a cloud save newer than the sync+ // (beyond legendary's 60 seconds) came from elsewhere.+ cloudChanged = check.cloud.flatMap(Self.date(legendary:)).map { $0 > record.synced.addingTimeInterval(60) } ?? false+ }+ if let then = record.local, let now = fingerprint {+ localChanged = then != now+ } else {+ localChanged = lastChange.map { $0 > record.synced.addingTimeInterval(60) } ?? false+ }+ } else {+ cloudChanged = check.cloud != nil+ localChanged = hasLocal+ }+ if cloudChanged && localChanged && hasLocal && check.cloud != nil { return .conflict(firstSync: record == nil) }+ switch direction {case .download:- if state == .nothing || state == .inStep { return .inStep }- guard state == .cloudNewer else { return .leave }- let changedHere = lastChange.map { change in lastSync.map { change > $0.addingTimeInterval(60) } ?? true } ?? false- return changedHere ? .conflict : .transfer(download: true)- case .upload:- if state == .nothing || state == .inStep { return .inStep }- return state == .localNewer ? .transfer(download: false) : .leave+ // Also with nothing here to lose: saves deleted on the Mac come back.+ return cloudChanged || (!hasLocal && check.cloud != nil) ? .transfer(download: true) : .leave+ default:+ return localChanged || (hasLocal && check.cloud == nil) ? .transfer(download: false) : .leave+ }+ }++ static func date(legendary: String) -> Date? {+ let formatter = DateFormatter()+ formatter.locale = Locale(identifier: "en_US_POSIX")+ formatter.timeZone = TimeZone(identifier: "UTC")+ formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"+ return formatter.date(from: legendary)+ }++ static func latestChange(of files: [URL]) -> Date? {+ files.compactMap { try? $0.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate }.max()+ }++ // MARK: Sync++ /// One lock per game: a sync that starts while another runs (an upload still going when+ /// Play is pressed again) waits for it.+ private static let gameLocks = OSAllocatedUnfairLock(initialState: [String: NSLock]())+ private static func lock(for app: String) -> NSLock {+ gameLocks.withLock { locks in+ if let lock = locks[app] { return lock }+ let lock = NSLock(); locks[app] = lock+ return lock+ }+ }++ private struct Run { var status: Int32; var lines: [String] }++ private func run(_ app: String, direction: Direction?, environment: [String: String],+ onLine: (@Sendable (String) -> Void)?) throws -> Run {+ let lines = OSAllocatedUnfairLock(initialState: [String]())+ let status = try store.runStreaming(Self.arguments(app: app, direction: direction), environment: environment) { line in+ lines.withLock { $0.append(line) }+ if !Self.isDebug(line) { onLine?(line) }+ }+ return Run(status: status, lines: lines.withLock { $0 })+ }++ private enum Compared { case success(Check), failure(String) }++ private func compare(_ app: String, environment: [String: String], onLine: (@Sendable (String) -> Void)?) -> Compared {+ do {+ let result = try run(app, direction: nil, environment: environment, onLine: onLine)+ guard result.status == 0, !result.lines.contains(where: Self.isFailure), let check = Self.check(in: result.lines) else {+ return .failure(Self.explanation(result.lines))+ }+ return .success(check)+ } catch { return .failure(error.localizedDescription) }+ }++ /// Syncs an Epic game's saves. `prefix` is the environment a Windows build is installed in,+ /// which legendary reads to resolve the save folder; nil for a Mac build, whose folder it+ /// resolves under the home folder. `install` keys the backups and the sync history.+ public func sync(_ app: String, install: URL, prefix: URL?, direction: Direction,+ home: URL = FileManager.default.homeDirectoryForCurrentUser,+ onLine: (@Sendable (String) -> Void)? = nil) -> Outcome {+ let gameLock = Self.lock(for: app)+ gameLock.lock()+ defer { gameLock.unlock() }++ let key = Self.key(app: app, install: install)+ let environment = prefix.map { ["WINEPREFIX": $0.path] } ?? [:]+ let filter = catalog(app)?.filter ?? .everything+ let backupDir = backups.folder("epic-\(app)", install: install)++ // A download that never finished: its backup goes back first.+ if let pending = records()[key]?.restoring, let folder = savePath(app) {+ do {+ try SaveBackups.restore(pending.isEmpty ? nil : URL(fileURLWithPath: pending), into: folder, filter: filter)+ clearRestoring(key)+ onLine?("Highball: an earlier download of these saves didn't finish, so this Mac's saves were put back from their backup")+ } catch {+ return .failed("an earlier download didn't finish, and the saves couldn't be put back from \((pending as NSString).abbreviatingWithTildeInPath) (\(error.localizedDescription))")+ }+ }++ // A save folder resolved for another environment (the game moved) is resolved again.+ if let stored = savePath(app), !Self.isInside(stored, roots: Self.allowedRoots(prefix: prefix, home: home)) {+ do { try forgetSavePath(app) } catch { return .failed(error.localizedDescription) }+ onLine?("Highball: the save folder legendary had for this game is outside its environment, so it is worked out again")+ }++ let before: Check+ switch compare(app, environment: environment, onLine: onLine) {+ case .success(let check): before = check+ case .failure(let why): return .failed(why)+ }+ guard let folder = savePath(app) else { return .failed("legendary kept no save folder for this game") }+ if let why = Self.refusal(for: folder, install: install, prefix: prefix, home: home, filter: filter) { return .failed(why) }++ // History for another folder doesn't describe this one: a first sync.+ var record = records()[key]+ if let path = record?.path, path != folder.path { record = nil }+ if record?.synced == .distantPast { record = nil } // only a download's marker, never synced+ let local = SaveBackups.files(in: folder, matching: filter)+ let decision = Self.decide(before, direction: direction, record: record, lastChange: Self.latestChange(of: local),+ hasLocal: !local.isEmpty, fingerprint: SaveBackups.fingerprint(folder, filter: filter))+ func noteSynced(_ cloud: String?) {+ let fingerprint = SaveBackups.fingerprint(folder, filter: filter)+ update(key) { $0 = Record(synced: Date(), cloud: cloud, path: folder.path, local: fingerprint) }+ }+ switch decision {+ case .inStep:+ noteSynced(before.cloud)+ return .synced+ case .leave:+ return .left+ case .conflict(let first):+ return .conflict(firstSync: first)+ case .transfer(download: true):+ return download(app, folder: folder, filter: filter, backupDir: backupDir, key: key,+ before: before, environment: environment, onLine: onLine, noteSynced: noteSynced)+ case .transfer(download: false):+ let upload: Run+ // Forced: Highball decided from what changed, and legendary's age check could+ // otherwise skip it (a Mac clock behind, or legendary's DST slip).+ do { upload = try run(app, direction: .forceUpload, environment: environment, onLine: onLine) } catch {+ return .failed(error.localizedDescription)+ }+ guard upload.status == 0, !upload.lines.contains(where: Self.isFailure) else {+ return .failed("the upload to Epic didn't finish (\(Self.explanation(upload.lines)))")+ }+ if upload.lines.contains(where: { $0.contains("No files to upload") }) {+ return .failed("none of the files in the save folder match what Epic syncs for this game")+ }+ // legendary ignores whether each file reached Epic: a new cloud save, in step with+ // the Mac, is what shows it did.+ guard case .success(let after) = compare(app, environment: environment, onLine: onLine),+ after.state == .inStep, let cloud = after.cloud, cloud != before.cloud else {+ return .failed("Highball couldn't confirm that Epic's cloud received the saves")+ }+ noteSynced(cloud)+ return .synced}}- /// The newest change among a folder's files, nil when it holds none.- static func latestChange(in folder: URL) -> Date? {- SaveBackups.files(in: folder).compactMap { try? $0.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate }.max()+ private func download(_ app: String, folder: URL, filter: SaveFilter, backupDir: URL, key: String,+ before: Check, environment: [String: String], onLine: (@Sendable (String) -> Void)?,+ noteSynced: (String?) -> Void) -> Outcome {+ let backup: URL?+ do { backup = try backups.backUpLocal(folder, into: backupDir, filter: filter) } catch {+ return .failed("the saves couldn't be backed up first (\(error.localizedDescription)), so nothing was synced")+ }+ update(key) { record in+ if record == nil { record = Record(synced: .distantPast, cloud: nil, path: folder.path) }+ record?.restoring = backup?.path ?? ""+ }+ var problem: String?+ do {+ let result = try run(app, direction: .forceDownload, environment: environment, onLine: onLine)+ if result.status != 0 || result.lines.contains(where: Self.isFailure) {+ problem = Self.explanation(result.lines)+ } else if case .success(let after) = compare(app, environment: environment, onLine: onLine) {+ if after.state != .inStep || after.cloud != before.cloud { problem = "legendary doesn't see the saves in step afterwards" }+ else if SaveBackups.files(in: folder, matching: filter).isEmpty { problem = "no saves came down" }+ } else {+ problem = "legendary couldn't compare the saves afterwards"+ }+ } catch { problem = error.localizedDescription }++ guard let problem else {+ noteSynced(before.cloud)+ return .synced+ }+ do {+ try SaveBackups.restore(backup, into: folder, filter: filter)+ clearRestoring(key)+ } catch {+ return .failed("the download from Epic failed (\(problem)), and the saves couldn't be put back automatically; their backup is in \(((backup?.path ?? backupDir.path) as NSString).abbreviatingWithTildeInPath)")+ }+ return .restored(problem)}}diff --git a/Sources/HighballKit/SaveBackups.swift b/Sources/HighballKit/SaveBackups.swiftindex a562a9d..2848036 100644--- a/Sources/HighballKit/SaveBackups.swift+++ b/Sources/HighballKit/SaveBackups.swift@@ -1,20 +1,20 @@import Foundation-/// Copies of a game's saves taken before a sync could replace them, in the Highball folder:-/// save-backups/<game>-<location>-<install>/<date>-<mac|cloud>/. Store tools replace saves-/// wholesale (gogdl deletes what the other side lacks, legendary empties the folder before a-/// download), so whatever a sync could replace is copied first, and a failed copy stops the sync.-/// The newest `keep` copies per install and location stay.+/// Backups of a game's saves, taken before a sync could replace them, stored at+/// save-backups/<game>-<location>-<install>/<date>-<mac|cloud>/. The store tools replace saves+/// wholesale (gogdl deletes whatever the other side lacks, and legendary empties the save folder+/// before a download), so anything a sync could replace is backed up first, and a failed backup+/// stops the sync. The newest `keep` backups per install and location are kept.public struct SaveBackups: Sendable {public let root: URLstatic let keep = 10public init(root: URL) { self.root = root }- /// One install's backups of one location: the install is in the name, so a second copy of the- /// game never rotates out the first one's backups.+ /// The backup folder for one install and location. The install is part of the name, so a+ /// second copy of the game never rotates out the first one's backups.public func folder(_ name: String, install: URL) -> URL {- // FNV-1a over the install's path: short, and the same from one run to the next.+ // FNV-1a of the install path: short and stable across runs.let hash = install.standardizedFileURL.path.utf8.reduce(UInt64(0xcbf2_9ce4_8422_2325)) { ($0 ^ UInt64($1)) &* 0x100_0000_01b3 }return root.appending(path: "\(name)-\(String(hash, radix: 16).prefix(8))", directoryHint: .isDirectory)}@@ -28,7 +28,8 @@ public struct SaveBackups: Sendable {return dir.appending(path: name, directoryHint: .isDirectory)}- /// Every file a sync sees: hidden files and links too, which the store tools replace or delete.+ /// Every file a sync touches. The store tools include hidden files and symlinks, and replace+ /// or delete them too.public static func files(in folder: URL) -> [URL] {let keys: Set<URLResourceKey> = [.isRegularFileKey, .isSymbolicLinkKey]let walker = FileManager.default.enumerator(at: folder, includingPropertiesForKeys: Array(keys))@@ -40,57 +41,81 @@ public struct SaveBackups: Sendable {return files}- /// What a folder holds, in brief (files, bytes, latest change): two equal mean a new copy would- /// only repeat the last one.- static func fingerprint(_ folder: URL) -> String {+ /// The files in `folder` that `filter` picks, the ones a sync can replace.+ public static func files(in folder: URL, matching filter: SaveFilter) -> [URL] {+ guard !filter.isEverything else { return files(in: folder) }+ return files(in: folder).filter { filter.matches(relativePath($0, in: folder)) }+ }++ /// A file's path below `folder`, with "/" between components, as the filters see it.+ static func relativePath(_ file: URL, in folder: URL) -> String {+ let base = folder.standardizedFileURL.resolvingSymlinksInPath().pathComponents+ let parts = file.standardizedFileURL.resolvingSymlinksInPath().pathComponents+ guard parts.starts(with: base) else { return file.lastPathComponent }+ return parts.dropFirst(base.count).joined(separator: "/")+ }++ /// A summary of a folder (file count, total bytes, latest change). When it matches the last+ /// backup's, a new backup would be a duplicate.+ static func fingerprint(_ folder: URL, filter: SaveFilter = .everything) -> String {let keys: Set<URLResourceKey> = [.fileSizeKey, .contentModificationDateKey]- let values = files(in: folder).map { try? $0.resourceValues(forKeys: keys) }+ let values = files(in: folder, matching: filter).map { try? $0.resourceValues(forKeys: keys) }let bytes = values.reduce(0) { $0 + ($1?.fileSize ?? 0) }let latest = values.compactMap { $0?.contentModificationDate?.timeIntervalSince1970 }.max() ?? 0return "\(values.count) \(bytes) \(latest)"}- /// Beside a copy, not in it: a copy restored by hand never carries it into the game's folder,- /// where a sync would upload it with the saves.+ /// Stored next to the backup rather than inside it, so restoring a backup by hand never puts+ /// this file in the game's folder, where a sync would upload it with the saves.static func fingerprintFile(of backup: URL) -> URL {backup.deletingLastPathComponent().appending(path: backup.lastPathComponent + ".fingerprint")}- /// A copy of the saves on the Mac, before a download could replace them: the newest copy when- /// nothing changed since it, nil when there is nothing to copy. Throws when the copy fails, and- /// leaves no half copy behind: then nothing may replace them.+ /// Backs up the local saves before a download could replace them: the files `filter` picks,+ /// which are the ones a download replaces. Returns the newest existing backup when nothing+ /// has changed since it, or nil when there is nothing to back up. Throws if the backup fails,+ /// leaving no partial copy behind; the sync must then stop.@discardableResult- public func backUpLocal(_ folder: URL, into dir: URL) throws -> URL? {- guard !Self.files(in: folder).isEmpty else { return nil }- let fingerprint = Self.fingerprint(folder)+ public func backUpLocal(_ folder: URL, into dir: URL, filter: SaveFilter = .everything) throws -> URL? {+ let picked = Self.files(in: folder, matching: filter)+ guard !picked.isEmpty else { return nil }+ let fingerprint = Self.fingerprint(folder, filter: filter)if let newest = backups(in: dir).first, (try? String(contentsOf: Self.fingerprintFile(of: newest), encoding: .utf8)) == fingerprint {return newest}let target = try backUp(into: dir, label: "mac") { partial intry FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)- try FileManager.default.copyItem(at: folder, to: partial)+ if filter.isEverything {+ try FileManager.default.copyItem(at: folder, to: partial)+ } else {+ for file in picked {+ let destination = partial.appending(path: Self.relativePath(file, in: folder))+ try FileManager.default.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)+ try FileManager.default.copyItem(at: file, to: destination)+ }+ }}try? fingerprint.write(to: Self.fingerprintFile(of: target), atomically: true, encoding: .utf8)return target}- /// A new copy, filled by `fill` under a ".partial" name and given its own name only once- /// complete, so a failed copy never sits among the real ones; then the newest `keep` stay,- /// never this one.+ /// Makes a new backup, filled by `fill` under a ".partial" name and renamed only once+ /// complete, so a failed backup never sits among the real ones. Then prunes to the newest+ /// `keep`, never removing this one.public func backUp(into dir: URL, label: String, fill: (URL) throws -> Void) throws -> URL {let target = newBackup(in: dir, label: label)let partial = dir.appending(path: target.lastPathComponent + ".partial", directoryHint: .isDirectory)do {try fill(partial)try FileManager.default.moveItem(at: partial, to: target)- // A copied folder keeps its source's creation date, often years old: the copy is- // dated now, so the newest copies are the ones kept.+ // A copied folder keeps the source's creation date, often years old. Date the backup+ // now so pruning keeps the newest ones.try FileManager.default.setAttributes([.creationDate: Date()], ofItemAtPath: target.path)} catch {try? FileManager.default.removeItem(at: partial)throw error}- // By name: the same folder can be listed under /var and /private/var.+ // Compare by name: the same folder can appear under both /var and /private/var.for old in backups(in: dir).filter({ $0.lastPathComponent != target.lastPathComponent }).dropFirst(Self.keep - 1) {try? FileManager.default.removeItem(at: old)try? FileManager.default.removeItem(at: Self.fingerprintFile(of: old))@@ -98,11 +123,59 @@ public struct SaveBackups: Sendable {return target}- /// A location's complete backups, newest first by when they were made (not by name: a Mac- /// whose clock was wrong once must not prune today's copy as the oldest).+ /// A location's complete backups, newest first by creation date rather than by name, so a+ /// clock that was once wrong never gets today's backup pruned as the oldest.public func backups(in dir: URL) -> [URL] {let all = (try? FileManager.default.contentsOfDirectory(at: dir, includingPropertiesForKeys: [.creationDateKey])) ?? []func made(_ url: URL) -> Date { (try? url.resourceValues(forKeys: [.creationDateKey]).creationDate) ?? .distantPast }return all.filter { !["partial", "fingerprint"].contains($0.pathExtension) }.sorted { made($0) > made($1) }}++ /// Puts a backup's files back into `folder`: first removes the files `filter` picks there+ /// (what a failed download may have left half written), then copies the backup's files in,+ /// keeping their dates. A nil backup means the folder held none of those files, so it ends+ /// up without them again.+ public static func restore(_ backup: URL?, into folder: URL, filter: SaveFilter) throws {+ for file in files(in: folder, matching: filter) { try FileManager.default.removeItem(at: file) }+ guard let backup else { return }+ for file in files(in: backup) {+ let destination = folder.appending(path: relativePath(file, in: backup))+ try FileManager.default.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)+ try FileManager.default.copyItem(at: file, to: destination)+ }+ }+}++/// Which files in a save folder belong to the saves, from a game's CloudIncludeList and+/// CloudExcludeList, matched the way legendary 0.21.0 does (utils/savegame_helper.py+/// `_filename_matches`): a pattern ending in "/" matches a path starting with it, any pattern+/// matches a path ending with it, and "*" wildcards match as Python's fnmatch does, across "/"+/// too. With an include list, only matching files count; an exclude list then removes some.+public struct SaveFilter: Sendable, Equatable {+ public let include: [String]?+ public let exclude: [String]?++ public init(include: [String]?, exclude: [String]?) { self.include = include; self.exclude = exclude }+ public static let everything = SaveFilter(include: nil, exclude: nil)++ /// legendary splits the attributes on "," without trimming, and so does this.+ public init(includeList: String?, excludeList: String?) {+ self.init(include: includeList.map { $0.components(separatedBy: ",") },+ exclude: excludeList.map { $0.components(separatedBy: ",") })+ }++ var isEverything: Bool { (include ?? []).isEmpty && (exclude ?? []).isEmpty }++ public func matches(_ path: String) -> Bool {+ if let include, !include.isEmpty, !Self.matches(path, include) { return false }+ if let exclude, !exclude.isEmpty, Self.matches(path, exclude) { return false }+ return true+ }++ static func matches(_ path: String, _ patterns: [String]) -> Bool {+ patterns.contains { pattern in+ (pattern.hasSuffix("/") && path.hasPrefix(pattern)) || path.hasSuffix(pattern)+ || fnmatch(pattern, path, 0) == 0+ }+ }}diff --git a/Tests/HighballKitTests/EpicFakeLegendaryTests.swift b/Tests/HighballKitTests/EpicFakeLegendaryTests.swiftnew file mode 100644index 0000000..9846cd3--- /dev/null+++ b/Tests/HighballKitTests/EpicFakeLegendaryTests.swift@@ -0,0 +1,320 @@+import XCTest+@testable import HighballKit++/// EpicSaves against a stand-in for legendary 0.21.0's `sync-saves`: the same decisions as cli.py+/// and core.py (newest wins by age, 60 seconds of slack, a download deletes the folder's files+/// first and carries on past a failed download, an upload ignores whether its files arrived),+/// over a folder that plays Epic's cloud.+final class EpicFakeLegendaryTests: XCTestCase {+ private var root: URL!+ private var home: URL { root.appending(path: "home") }+ private var config: URL { home.appending(path: "legendary") }+ private var cloud: URL { home.appending(path: "fake-cloud") }+ private var prefix: URL { root.appending(path: "Env") }+ private var install: URL { root.appending(path: "Env/drive_c/Games/Game") }+ private var userHome: URL { root.appending(path: "user") }+ private var folder: URL { prefix.appending(path: "drive_c/users/player/AppData/Local/Game/Saved") }+ private let app = "Game"++ override func setUpWithError() throws {+ guard FileManager.default.isExecutableFile(atPath: "/usr/bin/python3") else { throw XCTSkip("needs python3") }+ root = FileManager.default.temporaryDirectory.appending(path: "fake-legendary-\(UUID().uuidString)")+ for dir in [home.appending(path: "tools"), config.appending(path: "metadata"), cloud, install, userHome,+ prefix.appending(path: "drive_c/users/player")] {+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)+ }+ let legendary = home.appending(path: "tools/legendary")+ try Self.script.write(to: legendary, atomically: true, encoding: .utf8)+ try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: legendary.path)+ try #"{"app_name":"Game","metadata":{"customAttributes":{"CloudSaveFolder":{"type":"STRING","value":"{AppData}/Game/Saved"}}}}"#+ .write(to: config.appending(path: "metadata/Game.json"), atomically: true, encoding: .utf8)+ try installed(savePath: nil)+ // Where the stand-in resolves the save folder, inside the WINEPREFIX it is given.+ try "drive_c/users/player/AppData/Local/Game/Saved".write(to: home.appending(path: "fake-save-path"), atomically: true, encoding: .utf8)+ }+ override func tearDown() {+ if let root { try? FileManager.default.removeItem(at: root) }+ }++ private var saves: EpicSaves { EpicSaves(store: EpicStore(paths: HighballPaths(home: home))) }+ private func sync(_ direction: EpicSaves.Direction) -> EpicSaves.Outcome {+ saves.sync(app, install: install, prefix: prefix, direction: direction, home: userHome)+ }++ private func installed(savePath: String?) throws {+ let game: [String: Any] = ["app_name": app, "title": "Game", "install_path": install.path, "save_path": savePath ?? NSNull()]+ try JSONSerialization.data(withJSONObject: [app: game]).write(to: config.appending(path: "installed.json"))+ }+ private func write(_ text: String, to url: URL, at date: Date) throws {+ try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)+ try Data(text.utf8).write(to: url)+ try FileManager.default.setAttributes([.modificationDate: date], ofItemAtPath: url.path)+ }+ private func read(_ url: URL) -> String? { try? String(contentsOf: url, encoding: .utf8) }+ private func flag(_ name: String, _ text: String = "") throws { try text.write(to: home.appending(path: name), atomically: true, encoding: .utf8) }+ private func unflag(_ name: String) { try? FileManager.default.removeItem(at: home.appending(path: name)) }++ /// Another device uploads a save: a new cloud manifest named by its files' date.+ private func cloudSave(_ text: String, at date: Date) throws {+ let formatter = DateFormatter()+ formatter.locale = Locale(identifier: "en_US_POSIX"); formatter.timeZone = TimeZone(identifier: "UTC")+ formatter.dateFormat = "yyyy.MM.dd-HH.mm.ss"+ let name = formatter.string(from: date) + ".manifest"+ try write(text, to: cloud.appending(path: "\(name)/slot.sav"), at: date)+ // Uploaded now: the newest by upload time, as Epic's listing orders them.+ let index = cloud.appending(path: "index.json")+ var list = (try? JSONSerialization.jsonObject(with: Data(contentsOf: index)) as? [[String: Any]]) ?? []+ list.append(["name": name, "uploaded": Date().timeIntervalSince1970 + Double(list.count)])+ try JSONSerialization.data(withJSONObject: list).write(to: index)+ }+ private var cloudSaveCount: Int {+ ((try? JSONSerialization.jsonObject(with: Data(contentsOf: cloud.appending(path: "index.json"))) as? [Any]) ?? []).count+ }++ private let hourAgo = Date().addingTimeInterval(-3_600)+ private let dayAgo = Date().addingTimeInterval(-86_400)++ /// Synced once from the cloud, so later tests start with a record.+ private func syncedOnce() throws {+ try cloudSave("v1", at: dayAgo)+ XCTAssertEqual(sync(.download), .synced)+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "v1")+ }++ func testAFirstDownloadIntoAnEmptyFolder() throws {+ try syncedOnce()+ let record = try XCTUnwrap(saves.records()[EpicSaves.key(app: app, install: install)])+ XCTAssertNotNil(record.cloud, "the cloud save the Mac matched is kept")+ XCTAssertEqual(record.path, folder.path)+ XCTAssertNil(record.restoring)+ }++ /// A newer cloud save from another device comes down, after a backup of this Mac's.+ func testANewerCloudSaveComesDownAfterABackup() throws {+ try syncedOnce()+ try cloudSave("v2", at: hourAgo)+ XCTAssertEqual(sync(.download), .synced)+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "v2")+ let backup = try XCTUnwrap(saves.backups.backups(in: saves.backups.folder("epic-\(app)", install: install)).first)+ XCTAssertEqual(read(backup.appending(path: "slot.sav")), "v1")+ }++ /// legendary deletes the folder's files, then fails to download and still exits 0: the+ /// backup goes back, and the outcome says so (the game must not start on an empty folder).+ func testADownloadThatFailsAfterEmptyingTheFolderIsUndone() throws {+ try syncedOnce()+ try cloudSave("v2", at: hourAgo)+ try flag("fake-fail-download")+ guard case .restored = sync(.download) else { return XCTFail("expected the saves put back") }+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "v1")+ XCTAssertNil(saves.records()[EpicSaves.key(app: app, install: install)]?.restoring)+ unflag("fake-fail-download")+ XCTAssertEqual(sync(.download), .synced, "the next try still sees the cloud as changed")+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "v2")+ }++ func testAFailedBackupStopsTheDownload() throws {+ try syncedOnce()+ try cloudSave("v2", at: hourAgo)+ let locked = folder.appending(path: "locked")+ try write("x", to: locked.appending(path: "f"), at: dayAgo)+ try FileManager.default.setAttributes([.posixPermissions: 0o000], ofItemAtPath: locked.path)+ defer { try? FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: locked.path) }+ guard case let .failed(why) = sync(.download) else { return XCTFail() }+ XCTAssertTrue(why.contains("backed up"))+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "v1", "nothing was deleted")+ }++ /// The Mac's saves are newer than the cloud's by age, but the cloud also changed since the+ /// last sync: asked in both directions, never decided by age.+ func testBothChangedIsAskedEvenWhenTheMacIsNewer() throws {+ try syncedOnce()+ try cloudSave("from the PC", at: hourAgo)+ try write("played here", to: folder.appending(path: "slot.sav"), at: Date())+ XCTAssertEqual(sync(.download), .conflict(firstSync: false))+ XCTAssertEqual(sync(.upload), .conflict(firstSync: false))+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "played here")+ XCTAssertEqual(cloudSaveCount, 2, "nothing went up")+ }++ func testAFirstSyncWithSavesOnBothSidesIsAsked() throws {+ try cloudSave("cloud", at: dayAgo)+ try write("mac", to: folder.appending(path: "slot.sav"), at: hourAgo)+ try installed(savePath: folder.path)+ XCTAssertEqual(sync(.download), .conflict(firstSync: true))+ XCTAssertEqual(sync(.upload), .conflict(firstSync: true))+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "mac")+ }++ /// Only the Mac changed: Play leaves it, and the upload after the game takes it.+ func testOnlyTheMacChangedGoesUpAfterTheGame() throws {+ try syncedOnce()+ try write("played here", to: folder.appending(path: "slot.sav"), at: Date())+ XCTAssertEqual(sync(.download), .left)+ XCTAssertEqual(sync(.upload), .synced)+ XCTAssertEqual(cloudSaveCount, 2)+ XCTAssertEqual(sync(.download), .synced, "in step afterwards")+ }++ /// legendary reports a finished upload whether or not the files arrived; a new cloud save in+ /// step with the Mac is what counts.+ func testAnUploadThatNeverArrivedFails() throws {+ try syncedOnce()+ let before = saves.records()[EpicSaves.key(app: app, install: install)]+ try write("played here", to: folder.appending(path: "slot.sav"), at: Date())+ try flag("fake-fail-upload")+ guard case let .failed(why) = sync(.upload) else { return XCTFail() }+ XCTAssertTrue(why.contains("confirm"))+ XCTAssertEqual(saves.records()[EpicSaves.key(app: app, install: install)], before, "not noted as synced")+ }++ /// A save folder that holds more than the game's saves is never synced: legendary would+ /// empty it.+ func testABroadSaveFolderIsRefused() throws {+ let documents = prefix.appending(path: "drive_c/users/player/Documents")+ try write("someone else's file", to: documents.appending(path: "letter.txt"), at: dayAgo)+ try installed(savePath: documents.path)+ try cloudSave("v1", at: hourAgo)+ guard case let .failed(why) = sync(.download) else { return XCTFail() }+ XCTAssertTrue(why.contains("holds more than"))+ XCTAssertEqual(read(documents.appending(path: "letter.txt")), "someone else's file")+ }++ /// A save folder legendary stored for another environment (the game moved) is worked out+ /// again inside this one.+ func testASaveFolderFromAnotherEnvironmentIsResolvedAgain() throws {+ let elsewhere = root.appending(path: "OtherEnv/drive_c/users/player/AppData/Local/Game/Saved")+ try FileManager.default.createDirectory(at: elsewhere, withIntermediateDirectories: true)+ try installed(savePath: elsewhere.path)+ try cloudSave("v1", at: dayAgo)+ XCTAssertEqual(sync(.download), .synced)+ XCTAssertEqual(saves.savePath(app)?.standardizedFileURL.path, folder.standardizedFileURL.path)+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "v1")+ }++ /// A download Highball was in the middle of when it quit: its backup goes back first.+ func testAnInterruptedDownloadIsUndoneNextTime() throws {+ try syncedOnce()+ let backup = try XCTUnwrap(try saves.backups.backUpLocal(folder, into: saves.backups.folder("epic-\(app)", install: install)))+ saves.update(EpicSaves.key(app: app, install: install)) { $0?.restoring = backup.path }+ try write("half written", to: folder.appending(path: "slot.sav"), at: Date())+ try write("stray", to: folder.appending(path: "partial.sav"), at: Date())+ _ = sync(.download)+ XCTAssertEqual(read(folder.appending(path: "slot.sav")), "v1")+ XCTAssertFalse(FileManager.default.fileExists(atPath: folder.appending(path: "partial.sav").path))+ XCTAssertNil(saves.records()[EpicSaves.key(app: app, install: install)]?.restoring)+ }++ /// Two syncs of one game never run at once: the second waits.+ func testSyncsOfOneGameDoNotOverlap() throws {+ try syncedOnce()+ try flag("fake-slow")+ let group = DispatchGroup()+ for _ in 0..<2 {+ group.enter()+ DispatchQueue.global().async { _ = self.sync(.upload); group.leave() }+ }+ XCTAssertEqual(group.wait(timeout: .now() + 60), .success)+ XCTAssertNil(read(home.appending(path: "fake-overlap")), "two legendary runs overlapped")+ }++ /// legendary 0.21.0's sync-saves, reduced to what EpicSaves relies on.+ static let script = #"""+ #!/usr/bin/python3 -I+ import json, os, sys, shutil, time+ from datetime import datetime, timezone++ args = sys.argv[1:]+ debug = args and args[0] == '-v'+ if debug: args = args[1:]+ assert args[0] == 'sync-saves', args+ app = args[1]+ flags = set(args[2:])+ config = os.environ['LEGENDARY_CONFIG_PATH']+ home = os.path.dirname(config)+ cloud = os.path.join(home, 'fake-cloud')+ def log(name, level, msg):+ if level == 'DEBUG' and not debug: return+ print(f'[{name}] {level}: {msg}', flush=True)+ def flag(n): return os.path.exists(os.path.join(home, n))++ running = os.path.join(home, 'fake-running')+ if os.path.exists(running): open(os.path.join(home, 'fake-overlap'), 'w').write('yes')+ open(running, 'w').write('1')+ try:+ if flag('fake-slow'): time.sleep(0.5)+ installed_file = os.path.join(config, 'installed.json')+ installed = json.load(open(installed_file))+ igame = installed[app]+ try: index = json.load(open(os.path.join(cloud, 'index.json')))+ except Exception: index = []+ latest = sorted(index, key=lambda s: s['uploaded'])[-1] if index else None+ log('cli', 'INFO', f'Got {1 if latest else 0} remote save game(s)')+ log('cli', 'INFO', f'Checking "Game" ({app})')+ if not igame.get('save_path'):+ rel = open(os.path.join(home, 'fake-save-path')).read().strip()+ path = os.path.join(os.environ['WINEPREFIX'], rel)+ log('cli', 'INFO', f'Computed save path: "{path}"')+ os.makedirs(path, exist_ok=True)+ igame['save_path'] = path+ json.dump(installed, open(installed_file, 'w'))+ save_path = igame['save_path']++ newest = 0+ for d, _, fs in os.walk(save_path):+ for f in fs: newest = max(newest, os.stat(os.path.join(d, f)).st_mtime)+ dt_l = datetime.fromtimestamp(newest, timezone.utc) if newest else None+ dt_r = datetime.strptime(latest['name'], '%Y.%m.%d-%H.%M.%S.manifest').replace(tzinfo=timezone.utc) if latest else None+ if not newest and not latest:+ log('cli', 'INFO', 'No cloud or local savegame found.'); sys.exit(0)+ if dt_l and dt_r: log('Core', 'DEBUG', f'Local save date: {dt_l}, Remote save date: {dt_r}')+ if dt_l and dt_r and abs((dt_l - dt_r).total_seconds()) < 60: state = 'same'+ elif not dt_r or (dt_l and dt_l > dt_r): state = 'local'+ else: state = 'remote'+ force_up, force_down = '--force-upload' in flags, '--force-download' in flags+ if state == 'same' and not (force_up or force_down):+ log('cli', 'INFO', 'Save game for "Game" is up to date, skipping...'); sys.exit(0)+ def fmt(d): return d.strftime('%Y-%m-%d %H:%M:%S') if d else 'N/A'+ if (state == 'remote' and not force_up) or force_down:+ if state == 'remote':+ log('cli', 'INFO', 'Cloud save for "Game" is newer:')+ log('cli', 'INFO', f'- Cloud save date: {fmt(dt_r)}')+ log('cli', 'INFO', f'- Local save date: {fmt(dt_l)}')+ if '--skip-download' in flags:+ log('cli', 'INFO', 'Save game downloading is disabled, skipping...'); sys.exit(0)+ log('cli', 'INFO', 'Downloading remote savegame...')+ log('Core', 'INFO', 'Deleting old save files...')+ for d, _, fs in os.walk(save_path):+ for f in fs: os.remove(os.path.join(d, f))+ if flag('fake-fail-download'):+ log('Core', 'ERROR', 'Download failed, status code: 500')+ else:+ src = os.path.join(cloud, latest['name'])+ for d, _, fs in os.walk(src):+ for f in fs:+ rel = os.path.relpath(os.path.join(d, f), src)+ dst = os.path.join(save_path, rel)+ os.makedirs(os.path.dirname(dst), exist_ok=True)+ shutil.copyfile(os.path.join(d, f), dst)+ os.utime(dst, (dt_r.timestamp(), dt_r.timestamp()))+ log('Core', 'INFO', 'Successfully completed savegame download.')+ else:+ if state == 'local':+ log('cli', 'INFO', 'Local save for "Game" is newer')+ log('cli', 'INFO', f'- Cloud save date: {fmt(dt_r)}')+ log('cli', 'INFO', f'- Local save date: {fmt(dt_l)}')+ if '--skip-upload' in flags:+ log('cli', 'INFO', 'Save game uploading is disabled, skipping...'); sys.exit(0)+ log('cli', 'INFO', 'Uploading local savegame...')+ log('Core', 'INFO', 'Starting upload...')+ if not flag('fake-fail-upload'):+ name = dt_l.strftime('%Y.%m.%d-%H.%M.%S.manifest')+ dst = os.path.join(cloud, name)+ shutil.copytree(save_path, dst, dirs_exist_ok=True)+ index.append({'name': name, 'uploaded': time.time() + len(index)})+ json.dump(index, open(os.path.join(cloud, 'index.json'), 'w'))+ log('Core', 'INFO', 'Finished uploading savegame.')+ finally:+ os.remove(running)+ """#+}diff --git a/Tests/HighballKitTests/EpicSavesTests.swift b/Tests/HighballKitTests/EpicSavesTests.swiftindex d8b2d15..22ddc98 100644--- a/Tests/HighballKitTests/EpicSavesTests.swift+++ b/Tests/HighballKitTests/EpicSavesTests.swift@@ -1,45 +1,132 @@import XCTest@testable import HighballKit-/// Epic cloud saves through legendary's sync-saves (EpicSaves): what legendary found, what a sync-/// then does, and that nothing replaces the Mac's saves without a copy and, when both changed, a-/// question.+/// Epic cloud saves through legendary's sync-saves (EpicSaves): reading legendary's log, deciding+/// from what changed on each side, and which folders are never synced. EpicFakeLegendaryTests+/// runs whole syncs.final class EpicSavesTests: XCTestCase {/// legendary's log lines, as 0.21.0 writes them (legendary/cli.py sync_saves).- func testStateComesFromLegendarysLog() {- XCTAssertEqual(EpicSaves.state(in: ["[cli] INFO: No cloud or local savegame found."]), .nothing)- XCTAssertEqual(EpicSaves.state(in: [#"[cli] INFO: Save game for "Game" is up to date, skipping..."#]), .inStep)- XCTAssertEqual(EpicSaves.state(in: [#"[cli] INFO: Cloud save for "Game" is newer:"#, "[cli] INFO: - Cloud save date: 2026-10-31 12:00:00"]), .cloudNewer)- XCTAssertEqual(EpicSaves.state(in: [#"[cli] INFO: Local save for "Game" is newer"#]), .localNewer)- XCTAssertNil(EpicSaves.state(in: ["[cli] INFO: Got 0 remote save game(s)"]), "said nothing about the game: no folder resolved")- XCTAssertTrue(EpicSaves.isFailure("[Core] ERROR: Failed to download save"))+ func testStateAndCloudDateComeFromLegendarysLog() {+ XCTAssertEqual(EpicSaves.check(in: ["[cli] INFO: No cloud or local savegame found."]), .init(state: .nothing, cloud: nil))+ XCTAssertEqual(EpicSaves.check(in: ["[Core] DEBUG: Local save date: 2026-11-01 01:36:04.5+00:00, Remote save date: 2026-11-01 01:36:04+00:00",+ #"[cli] INFO: Save game for "Game" is up to date, skipping..."#]),+ .init(state: .inStep, cloud: "2026-11-01 01:36:04"))+ XCTAssertEqual(EpicSaves.check(in: [#"[cli] INFO: Cloud save for "Game" is newer:"#, "[cli] INFO: - Cloud save date: 2026-10-31 12:00:00",+ "[cli] INFO: - Local save date: N/A"]),+ .init(state: .cloudNewer, cloud: "2026-10-31 12:00:00"))+ XCTAssertEqual(EpicSaves.check(in: [#"[cli] INFO: Local save for "Game" is newer"#, "[cli] INFO: - Cloud save date: N/A"]),+ .init(state: .localNewer, cloud: nil))+ XCTAssertNil(EpicSaves.check(in: ["[cli] INFO: Got 0 remote save game(s)"]), "said nothing about the game")}- /// Always -y and --accept-path: legendary would otherwise stop at a question no one can answer.+ /// A download that skipped a chunk or a file part only warns, and still "completes".+ func testFailuresIncludeTheWarningsOfAnIncompleteDownload() {+ XCTAssertTrue(EpicSaves.isFailure("[Core] ERROR: Download failed, status code: 500"))+ XCTAssertTrue(EpicSaves.isFailure("[Core] CRITICAL: No chunks were available, aborting."))+ XCTAssertTrue(EpicSaves.isFailure("[Core] WARNING: Chunk a/b not in file list, save data may be incomplete!"))+ XCTAssertTrue(EpicSaves.isFailure(#"[SGH] WARNING: Got EOF for "x" with 3 bytes remaining! File may have been corrupted/modified."#))+ XCTAssertFalse(EpicSaves.isFailure("[cli] INFO: Got 1 remote save game(s)"))+ }++ func testFailuresAreExplainedByCause() {+ XCTAssertTrue(EpicSaves.explanation(["[cli] ERROR: Login failed! Cannot continue with download process."]).contains("sign-in"))+ XCTAssertTrue(EpicSaves.explanation(["[cli] ERROR: Unable to lock install data, cannot modify save path."]).contains("busy"))+ XCTAssertTrue(EpicSaves.explanation(["[cli] WARNING: Path contains unprocessed variables, please enter the correct path manually."]).contains("work out"))+ XCTAssertEqual(EpicSaves.explanation([]), "legendary said nothing about this game's saves")+ }++ /// Always -y and --accept-path (legendary would otherwise stop at a question no one can+ /// answer), and -v for the cloud save's date.func testArguments() {XCTAssertEqual(EpicSaves.arguments(app: "Garlic", direction: nil),- ["sync-saves", "Garlic", "-y", "--accept-path", "--skip-upload", "--skip-download"])+ ["-v", "sync-saves", "Garlic", "-y", "--accept-path", "--skip-upload", "--skip-download"])XCTAssertEqual(EpicSaves.arguments(app: "Garlic", direction: .download).suffix(1), ["--skip-upload"])XCTAssertEqual(EpicSaves.arguments(app: "Garlic", direction: .upload).suffix(1), ["--skip-download"])XCTAssertEqual(EpicSaves.arguments(app: "Garlic", direction: .forceDownload).suffix(1), ["--force-download"])}- /// A download over saves changed since the last sync is asked, never decided by age.- func testADownloadOverChangedSavesIsAConflict() {- let synced = Date(timeIntervalSince1970: 1_790_000_000)+ private let synced = Date(timeIntervalSince1970: 1_790_000_000)+ private func record(cloud: String?) -> EpicSaves.Record { .init(synced: synced, cloud: cloud, path: "/saves") }++ /// Which side changed since the last sync decides, in both directions; age never does.+ func testDecisionsComeFromWhatChangedOnEachSide() {+ let seen = record(cloud: "2026-10-01 10:00:00")let later = synced.addingTimeInterval(3_600)- XCTAssertEqual(EpicSaves.decide(.cloudNewer, direction: .download, lastChange: later, lastSync: synced), .conflict)- XCTAssertEqual(EpicSaves.decide(.cloudNewer, direction: .download, lastChange: later, lastSync: nil), .conflict, "never synced: asked")- XCTAssertEqual(EpicSaves.decide(.cloudNewer, direction: .download, lastChange: synced, lastSync: synced), .transfer(download: true))- XCTAssertEqual(EpicSaves.decide(.cloudNewer, direction: .download, lastChange: nil, lastSync: nil), .transfer(download: true), "nothing here to lose")+ let newCloud = EpicSaves.Check(state: .localNewer, cloud: "2026-10-02 10:00:00")+ // Both changed, even with the Mac newer by age: asked.+ XCTAssertEqual(EpicSaves.decide(newCloud, direction: .download, record: seen, lastChange: later, hasLocal: true), .conflict(firstSync: false))+ XCTAssertEqual(EpicSaves.decide(newCloud, direction: .upload, record: seen, lastChange: later, hasLocal: true), .conflict(firstSync: false))+ // Only the cloud changed: down before Play, left after the game.+ let cloudOnly = EpicSaves.Check(state: .cloudNewer, cloud: "2026-10-02 10:00:00")+ XCTAssertEqual(EpicSaves.decide(cloudOnly, direction: .download, record: seen, lastChange: synced, hasLocal: true), .transfer(download: true))+ XCTAssertEqual(EpicSaves.decide(cloudOnly, direction: .upload, record: seen, lastChange: synced, hasLocal: true), .leave)+ // Only the Mac changed: left before Play, up after the game.+ let macOnly = EpicSaves.Check(state: .localNewer, cloud: "2026-10-01 10:00:00")+ XCTAssertEqual(EpicSaves.decide(macOnly, direction: .download, record: seen, lastChange: later, hasLocal: true), .leave)+ XCTAssertEqual(EpicSaves.decide(macOnly, direction: .upload, record: seen, lastChange: later, hasLocal: true), .transfer(download: false))+ XCTAssertEqual(EpicSaves.decide(.init(state: .inStep, cloud: "x"), direction: .download, record: nil, lastChange: later, hasLocal: true), .inStep)+ }++ /// A change to the saves right after a sync still counts: the folder's summary differs, even+ /// within legendary's 60 seconds.+ func testAChangeSoonAfterASyncCounts() {+ var seen = record(cloud: "2026-10-01 10:00:00")+ seen.local = "1 10 1790000000.0"+ let macNewer = EpicSaves.Check(state: .localNewer, cloud: "2026-10-01 10:00:00")+ XCTAssertEqual(EpicSaves.decide(macNewer, direction: .upload, record: seen, lastChange: synced.addingTimeInterval(5),+ hasLocal: true, fingerprint: "1 12 1790000005.0"), .transfer(download: false))+ XCTAssertEqual(EpicSaves.decide(macNewer, direction: .upload, record: seen, lastChange: synced.addingTimeInterval(5),+ hasLocal: true, fingerprint: seen.local), .leave)+ }++ func testAFirstSyncAsksOnlyWithSavesOnBothSides() {+ let both = EpicSaves.Check(state: .cloudNewer, cloud: "2026-10-02 10:00:00")+ XCTAssertEqual(EpicSaves.decide(both, direction: .download, record: nil, lastChange: synced, hasLocal: true), .conflict(firstSync: true))+ XCTAssertEqual(EpicSaves.decide(both, direction: .download, record: nil, lastChange: nil, hasLocal: false), .transfer(download: true), "nothing here to lose")+ let macOnly = EpicSaves.Check(state: .localNewer, cloud: nil)+ XCTAssertEqual(EpicSaves.decide(macOnly, direction: .upload, record: nil, lastChange: synced, hasLocal: true), .transfer(download: false), "an empty cloud")+ }++ /// The first version kept only the date: a cloud save newer than it came from elsewhere.+ func testARecordFromBeforeTheCloudWasKept() {+ let old = EpicSaves.Record(synced: synced)+ let afterSync = EpicSaves.Check(state: .cloudNewer, cloud: "2026-12-01 00:00:00")+ let beforeSync = EpicSaves.Check(state: .localNewer, cloud: "2026-09-01 00:00:00")+ XCTAssertEqual(EpicSaves.decide(afterSync, direction: .download, record: old, lastChange: synced, hasLocal: true), .transfer(download: true))+ XCTAssertEqual(EpicSaves.decide(beforeSync, direction: .upload, record: old, lastChange: synced.addingTimeInterval(600), hasLocal: true), .transfer(download: false))+ }++ /// Filters as legendary matches them: a directory prefix, a suffix, or an fnmatch wildcard.+ func testFiltersMatchLikeLegendary() {+ let filter = SaveFilter(includeList: "Saved/,*.sav,profile.dat", excludeList: "Saved/cache/")+ XCTAssertTrue(filter.matches("Saved/slot1"))+ XCTAssertTrue(filter.matches("deep/dir/game.sav"))+ XCTAssertTrue(filter.matches("x/profile.dat"))+ XCTAssertFalse(filter.matches("Saved/cache/blob"))+ XCTAssertFalse(filter.matches("Binaries/Game.exe"))+ XCTAssertTrue(SaveFilter.everything.matches("anything"))}- func testEachDirectionTakesOnlyItsOwnSide() {- XCTAssertEqual(EpicSaves.decide(.localNewer, direction: .download, lastChange: nil, lastSync: nil), .leave)- XCTAssertEqual(EpicSaves.decide(.cloudNewer, direction: .upload, lastChange: nil, lastSync: nil), .leave)- XCTAssertEqual(EpicSaves.decide(.localNewer, direction: .upload, lastChange: nil, lastSync: nil), .transfer(download: false))- XCTAssertEqual(EpicSaves.decide(.inStep, direction: .download, lastChange: nil, lastSync: nil), .inStep)- XCTAssertEqual(EpicSaves.decide(.inStep, direction: .forceUpload, lastChange: nil, lastSync: nil), .transfer(download: false))+ /// Folders holding more than the game's saves are never synced: a download would empty them.+ func testBroadFoldersAreRefused() throws {+ let root = FileManager.default.temporaryDirectory.appending(path: "epic-broad-\(UUID().uuidString)")+ defer { try? FileManager.default.removeItem(at: root) }+ let home = root.appending(path: "home"), prefix = root.appending(path: "Env")+ let user = prefix.appending(path: "drive_c/users/player")+ try FileManager.default.createDirectory(at: user, withIntermediateDirectories: true)+ let install = prefix.appending(path: "drive_c/Games/Game")+ func refused(_ folder: URL, _ filter: SaveFilter = .everything) -> Bool {+ EpicSaves.refusal(for: folder, install: install, prefix: prefix, home: home, filter: filter) != nil+ }+ for broad in [home, home.appending(path: "Documents"), home.appending(path: "Library/Application Support"),+ root, prefix, user.appending(path: "AppData/Local"), user.appending(path: "documents/my games"),+ install, install.deletingLastPathComponent()] {+ XCTAssertTrue(refused(broad), broad.path)+ }+ XCTAssertFalse(refused(user.appending(path: "AppData/Local/Game/Saved")))+ XCTAssertFalse(refused(home.appending(path: "Library/Application Support/Dodge Roll/Enter the Gungeon")))+ XCTAssertFalse(refused(install.appending(path: "Saves")))+ XCTAssertFalse(refused(install, SaveFilter(includeList: "Saves/", excludeList: nil)), "an include list limits it to the saves")}/// Cloud saves are a game's when its catalog item names a folder for them.@@ -49,10 +136,12 @@ final class EpicSavesTests: XCTestCase {let saves = EpicSaves(store: EpicStore(paths: HighballPaths(home: home)))let metadata = home.appending(path: "legendary/metadata")try FileManager.default.createDirectory(at: metadata, withIntermediateDirectories: true)- try #"{"app_name":"Garlic","metadata":{"customAttributes":{"CloudSaveFolder":{"type":"STRING","value":"{AppData}/../LocalLow/Dodge Roll/Enter the Gungeon"}}}}"#+ try #"{"app_name":"Garlic","metadata":{"customAttributes":{"CloudSaveFolder":{"type":"STRING","value":"{AppData}/../LocalLow/Dodge Roll/Enter the Gungeon"},"CloudIncludeList":{"type":"STRING","value":"*.sav"}}}}"#.write(to: metadata.appending(path: "Garlic.json"), atomically: true, encoding: .utf8)try #"{"app_name":"Duck","metadata":{"customAttributes":{}}}"#.write(to: metadata.appending(path: "Duck.json"), atomically: true, encoding: .utf8)XCTAssertTrue(saves.supportsCloudSaves("Garlic"))+ XCTAssertFalse(saves.supportsCloudSaves("Garlic", mac: true))+ XCTAssertEqual(saves.catalog("Garlic")?.filter, SaveFilter(include: ["*.sav"], exclude: nil))XCTAssertFalse(saves.supportsCloudSaves("Duck"))XCTAssertFalse(saves.supportsCloudSaves("Missing"))}