Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

15.3 KB
Raw Blame
import CryptoKit
import Darwin
import Foundation

/// Backups of a game's saves, taken before a sync could replace them, stored at
/// save-backups/<game>-<location>-<install>/<date>-<kind>[-kept]/. 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.
///
/// Backups come in two kinds, the Mac's saves and a cloud's, and each kind rotates on its own: the
/// newest `keep` of each stay. Kept backups (made before an uninstall, or before the player picked
/// a side in a conflict) and pinned ones (a download's, until it is done or undone) are never
/// pruned. A backup identical to the newest of its kind is not made again.
public struct SaveBackups: Sendable {
    public let root: URL
    static let keep = 10

    public init(root: URL) { self.root = root }

    /// What a backup holds: the Mac's saves or a cloud's.
    public enum Kind: String, Sendable { case mac, cloud }

    /// The backup folder for one install and location. The install is part of the name (sync
    /// history is per install too), 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 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)
    }

    private func newBackup(in dir: URL, label: String) -> URL {
        let formatter = ISO8601DateFormatter()
        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
        let stamp = formatter.string(from: Date()).replacingOccurrences(of: ":", with: "")
        var name = "\(stamp)-\(label)", n = 1
        while FileManager.default.fileExists(atPath: dir.appending(path: name).path) { n += 1; name = "\(stamp)-\(label)-\(n)" }
        return dir.appending(path: name, directoryHint: .isDirectory)
    }

    /// Backups are named <date>-<kind>[-kept].
    public static func kind(of backup: URL) -> Kind? {
        let name = backup.lastPathComponent
        return name.contains("-cloud") ? .cloud : name.contains("-mac") ? .mac : nil
    }
    public static func isKept(_ backup: URL) -> Bool { backup.lastPathComponent.contains("-kept") }

    // MARK: Files

    /// Every file a sync touches, as the store tools walk a folder: hidden files too, and into a
    /// linked folder (gogdl's os.path.isdir and legendary's os.walk follow links). A folder
    /// reached twice through links is walked once. Throws for a folder inside it that can't be
    /// read; one that isn't there holds nothing.
    static func walk(_ folder: URL) throws -> [URL] {
        guard FileManager.default.fileExists(atPath: folder.path) else { return [] }
        var files: [URL] = [], walked = Set<String>()
        func walk(_ dir: URL) throws {
            guard walked.insert(dir.resolvingSymlinksInPath().path).inserted else { return }
            for name in try FileManager.default.contentsOfDirectory(atPath: dir.path).sorted() {
                let item = dir.appending(path: name)
                var isFolder: ObjCBool = false
                if FileManager.default.fileExists(atPath: item.path, isDirectory: &isFolder), isFolder.boolValue { try walk(item) } else { files.append(item) }
            }
        }
        try walk(folder)
        return files
    }

    public static func files(in folder: URL) -> [URL] { (try? walk(folder)) ?? [] }

    /// 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 and the store
    /// tools name it: by the path walked, not where a link leads.
    static func relativePath(_ file: URL, in folder: URL) -> String {
        String(file.standardizedFileURL.path.dropFirst(folder.standardizedFileURL.path.count + 1))
    }

    // MARK: Fingerprints

    /// A digest of a folder's files (those `filter` picks): each one's path, size and last change.
    /// When it matches a backup's, a new backup would be a duplicate.
    public static func fingerprint(_ folder: URL, filter: SaveFilter = .everything) -> String {
        fingerprint(folder, files: files(in: folder, matching: filter))
    }

    /// The same digest of some of `folder`'s files, as walk names them.
    public static func fingerprint(_ folder: URL, files chosen: [URL]) -> String {
        let keys: Set<URLResourceKey> = [.fileSizeKey, .contentModificationDateKey]
        let lines = chosen.map { file -> String in
            let values = try? file.resolvingSymlinksInPath().resourceValues(forKeys: keys)
            return "\(relativePath(file, in: folder))\t\(values?.fileSize ?? 0)\t\(values?.contentModificationDate?.timeIntervalSince1970 ?? 0)"
        }
        return "mac " + digest(lines)
    }

    public static func digest(_ lines: [String]) -> String {
        SHA256.hash(data: Data(lines.sorted().joined(separator: "\n").utf8)).map { String(format: "%02x", $0) }.joined()
    }

    /// 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.
    public static func fingerprintFile(of backup: URL) -> URL {
        backup.deletingLastPathComponent().appending(path: backup.lastPathComponent + ".fingerprint")
    }

    // MARK: Making backups

    /// The newest backup of that kind when it holds exactly `fingerprint`. A kept backup asked
    /// for when the match isn't kept yet turns the match into a kept one instead of copying again.
    public func reuse(in dir: URL, kind: Kind, fingerprint: String, kept: Bool) -> URL? {
        guard let newest = backups(in: dir).first(where: { Self.kind(of: $0) == kind }),
              (try? String(contentsOf: Self.fingerprintFile(of: newest), encoding: .utf8)) == fingerprint else { return nil }
        guard kept, !Self.isKept(newest) else { return newest }
        let promoted = dir.appending(path: newest.lastPathComponent + "-kept", directoryHint: .isDirectory)
        guard (try? FileManager.default.moveItem(at: newest, to: promoted)) != nil else { return nil }
        try? FileManager.default.moveItem(at: Self.fingerprintFile(of: newest), to: Self.fingerprintFile(of: promoted))
        try? FileManager.default.moveItem(at: Self.pinFile(of: newest), to: Self.pinFile(of: promoted))
        return promoted
    }

    /// Backs up the local saves before something could replace or delete them: the files `filter`
    /// picks, which are the ones a download replaces. Returns the newest Mac backup when nothing
    /// has changed since it, or nil when there is nothing to back up. `kept` backups are never
    /// pruned. `only` limits it to some of the folder's files, as walk names them (`filter` still
    /// applies). Throws if the backup fails, leaving no partial copy behind; the caller must then
    /// stop.
    @discardableResult
    public func backUpLocal(_ folder: URL, into dir: URL, filter: SaveFilter = .everything, kept: Bool = false,
                            only: [URL]? = nil) throws -> URL? {
        // A folder that can't be read fails the copy: its saves would go uncopied.
        let picked = try (only ?? Self.walk(folder)).filter { filter.isEverything || filter.matches(Self.relativePath($0, in: folder)) }
        guard !picked.isEmpty else { return nil }
        let fingerprint = Self.fingerprint(folder, files: picked)
        if let same = reuse(in: dir, kind: .mac, fingerprint: fingerprint, kept: kept) { return same }
        return try backUp(into: dir, kind: .mac, kept: kept, fingerprint: fingerprint) { partial in
            try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
            // What a link points at, not the link: the tools write through it, so a download
            // replaces the file it points to. A link to nothing holds nothing to keep.
            for file in picked {
                let source = file.resolvingSymlinksInPath()
                guard FileManager.default.fileExists(atPath: source.path) else { continue }
                let destination = partial.appending(path: Self.relativePath(file, in: folder))
                try FileManager.default.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)
                try FileManager.default.copyItem(at: source, to: destination)
            }
            return nil
        }
    }

    /// Makes a new backup of `kind`, filled by `fill` under a ".partial" name and renamed only once
    /// complete, so a failed backup never sits among the real ones. `fingerprint`, when known, is
    /// stored beside it (`fill` may also return one it learned while filling). Then prunes that
    /// kind's backups to the newest `keep`, never removing this one, a kept one or a pinned one.
    public func backUp(into dir: URL, kind: Kind, kept: Bool, fingerprint: String? = nil,
                       fill: (URL) throws -> String?) throws -> URL {
        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        removeStalePartials(in: dir)
        let target = newBackup(in: dir, label: kept ? "\(kind.rawValue)-kept" : kind.rawValue)
        let partial = dir.appending(path: target.lastPathComponent + ".partial", directoryHint: .isDirectory)
        let learned: String?
        do {
            learned = try fill(partial)
            try FileManager.default.moveItem(at: partial, to: target)
            // 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
        }
        if let value = fingerprint ?? learned {
            try? value.write(to: Self.fingerprintFile(of: target), atomically: true, encoding: .utf8)
        }
        // Compare by name: the same folder can appear under both /var and /private/var.
        let rotating = backups(in: dir).filter {
            $0.lastPathComponent != target.lastPathComponent && Self.kind(of: $0) == kind && !Self.isKept($0) && !Self.isPinned($0)
        }
        for old in rotating.dropFirst(Self.keep - 1) {
            try? FileManager.default.removeItem(at: old)
            try? FileManager.default.removeItem(at: Self.fingerprintFile(of: old))
        }
        return target
    }

    /// A backup left half-filled by a crash or a forced quit: older than an hour, so no sync
    /// running now is still filling it.
    private func removeStalePartials(in dir: URL) {
        let all = (try? FileManager.default.contentsOfDirectory(at: dir, includingPropertiesForKeys: [.creationDateKey])) ?? []
        for partial in all where partial.pathExtension == "partial" {
            let made = (try? partial.resourceValues(forKeys: [.creationDateKey]).creationDate) ?? .distantPast
            if made < Date().addingTimeInterval(-3600) { try? FileManager.default.removeItem(at: partial) }
        }
    }

    /// 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", "pinned"].contains($0.pathExtension) }.sorted { made($0) > made($1) }
    }

    // MARK: Pins and restoring

    /// A pinned backup is never pruned: a download pins its backup until it is done or undone, so
    /// the copy it may need to put back is still there however many backups are made meanwhile.
    static func pinFile(of backup: URL) -> URL {
        backup.deletingLastPathComponent().appending(path: backup.lastPathComponent + ".pinned")
    }
    public static func isPinned(_ backup: URL) -> Bool { FileManager.default.fileExists(atPath: pinFile(of: backup).path) }
    public static func pin(_ backup: URL) throws { try Data().write(to: pinFile(of: backup)) }
    public static func unpin(_ backup: URL) { try? FileManager.default.removeItem(at: pinFile(of: backup)) }

    /// 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
        }
    }
}