SPB Git

Repository Public License

SaveStore.swift 7.9 KB 199 lines swift

1// ORIX Arcade2// File: Persistence/SaveStore.swift3// Description: Local JSON save store — atomic writes, rolling backup, schema migration, corruption recovery and validated export/import.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import Observation910nonisolated enum SaveError: Error, Equatable, LocalizedError {11    case notAnArcadeSave12    case newerSchema(Int)13    case unreadable1415    var errorDescription: String? {16        switch self {17        case .notAnArcadeSave: "This file is not an ORIX Arcade save."18        case .newerSchema(let v): "This save was made by a newer version of ORIX Arcade (format \(v)). Update the app to import it."19        case .unreadable: "The save file is damaged and could not be read."20        }21    }22}2324/// Pure encoding, decoding and migration helpers (no file access) so they can be unit-tested directly.25nonisolated enum SaveCodec {26    static let exportFormat = "orix-arcade-save"2728    private struct Probe: Decodable { var schemaVersion: Int? }29    private struct ExportEnvelope: Codable {30        var format: String31        var exportedAt: Date32        var appVersion: String33        var save: SaveData34    }3536    static func encode(_ data: SaveData) throws -> Data {37        let encoder = JSONEncoder()38        encoder.outputFormatting = [.sortedKeys]39        return try encoder.encode(data)40    }4142    /// Decodes a save, migrating older schemas forward. Throws `newerSchema` rather than guessing at an unknown future format.43    static func decode(_ raw: Data) throws -> SaveData {44        guard let probe = try? JSONDecoder().decode(Probe.self, from: raw) else { throw SaveError.unreadable }45        let version = probe.schemaVersion ?? 146        if version > SaveData.currentSchema { throw SaveError.newerSchema(version) }47        var json = raw48        var current = version49        while current < SaveData.currentSchema {50            json = try migrate(json, from: current)51            current += 152        }53        guard var decoded = try? JSONDecoder().decode(SaveData.self, from: json) else { throw SaveError.unreadable }54        decoded.schemaVersion = SaveData.currentSchema55        return decoded56    }5758    /// Schema migration hook: transforms raw JSON of version `from` into version `from + 1`.59    static func migrate(_ raw: Data, from version: Int) throws -> Data {60        guard var object = try JSONSerialization.jsonObject(with: raw) as? [String: Any] else { throw SaveError.unreadable }61        switch version {62        default: break // Schema 1 is the first shipped format; future migrations go here.63        }64        object["schemaVersion"] = version + 165        return try JSONSerialization.data(withJSONObject: object)66    }6768    static func exportEnvelope(_ data: SaveData, appVersion: String, date: Date = Date()) throws -> Data {69        let encoder = JSONEncoder()70        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]71        return try encoder.encode(ExportEnvelope(format: exportFormat, exportedAt: date, appVersion: appVersion, save: data))72    }7374    static func importEnvelope(_ raw: Data) throws -> SaveData {75        guard let object = try? JSONSerialization.jsonObject(with: raw) as? [String: Any],76              object["format"] as? String == exportFormat,77              let save = object["save"],78              let saveData = try? JSONSerialization.data(withJSONObject: save)79        else { throw SaveError.notAnArcadeSave }80        var decoded = try decode(saveData)81        decoded.interrupted = nil82        return decoded83    }84}8586@Observable87final class SaveStore {88    private(set) var data: SaveData89    /// Set when the previous save could not be read; the lobby shows it once. The damaged file is kept on disk.90    private(set) var recoveryNotice: String?9192    let directory: URL93    let name: String94    @ObservationIgnored private var saveTask: Task<Void, Never>?95    @ObservationIgnored private var dirty = false9697    var fileURL: URL { directory.appendingPathComponent("\(name).json") }98    var backupURL: URL { directory.appendingPathComponent("\(name).bak.json") }99100    init(name: String = "save", directory: URL? = nil, reset: Bool = false) {101        let base = directory ?? FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]102            .appendingPathComponent("ORIXArcade", isDirectory: true)103        self.directory = base104        self.name = name105        try? FileManager.default.createDirectory(at: base, withIntermediateDirectories: true)106        let file = base.appendingPathComponent("\(name).json")107        let backup = base.appendingPathComponent("\(name).bak.json")108        if reset {109            try? FileManager.default.removeItem(at: file)110            try? FileManager.default.removeItem(at: backup)111        }112        var loaded = SaveData()113        var notice: String?114        if let raw = try? Data(contentsOf: file) {115            do {116                loaded = try SaveCodec.decode(raw)117            } catch {118                // Never delete a save we cannot read: set it aside, then fall back to the last good backup.119                let stamp = Int(Date().timeIntervalSince1970)120                let label = (error as? SaveError).map { if case .newerSchema = $0 { "newer" } else { "damaged" } } ?? "damaged"121                try? FileManager.default.moveItem(at: file, to: base.appendingPathComponent("\(name).\(label)-\(stamp).json"))122                if let rawBackup = try? Data(contentsOf: backup), let restored = try? SaveCodec.decode(rawBackup) {123                    loaded = restored124                    notice = "Your save file was damaged, so the most recent backup was restored."125                } else {126                    notice = "Your save file could not be read. It was set aside and a fresh profile was started."127                }128            }129        }130        data = loaded131        recoveryNotice = notice132    }133134    func update(_ mutate: (inout SaveData) -> Void) {135        mutate(&data)136        scheduleSave()137    }138139    func dismissRecoveryNotice() { recoveryNotice = nil }140141    private func scheduleSave() {142        dirty = true143        guard saveTask == nil else { return }144        saveTask = Task { [weak self] in145            try? await Task.sleep(for: .milliseconds(400))146            self?.saveTask = nil147            self?.flush()148        }149    }150151    /// Writes immediately. Called on backgrounding and after important milestones.152    func flush() {153        guard dirty else { return }154        dirty = false155        guard let encoded = try? SaveCodec.encode(data) else { return }156        let fm = FileManager.default157        if fm.fileExists(atPath: fileURL.path) {158            try? fm.removeItem(at: backupURL)159            try? fm.copyItem(at: fileURL, to: backupURL)160        }161        try? encoded.write(to: fileURL, options: .atomic)162    }163164    // MARK: Export / import / reset165166    func exportData() throws -> Data {167        let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "0"168        return try SaveCodec.exportEnvelope(data, appVersion: version)169    }170171    /// Replaces the current progress with a validated import. The previous save is kept as `<name>.pre-import.json`.172    func importData(_ raw: Data) throws {173        let imported = try SaveCodec.importEnvelope(raw)174        setAside(suffix: "pre-import")175        data = imported176        dirty = true177        flush()178    }179180    /// Clears progress but keeps settings. The previous save is kept as `<name>.pre-reset.json`.181    func resetProgress() {182        setAside(suffix: "pre-reset")183        var fresh = SaveData()184        fresh.settings = data.settings185        fresh.hasSeenWelcome = true186        data = fresh187        dirty = true188        flush()189    }190191    private func setAside(suffix: String) {192        dirty = true193        flush()194        let target = directory.appendingPathComponent("\(name).\(suffix).json")195        try? FileManager.default.removeItem(at: target)196        try? FileManager.default.copyItem(at: fileURL, to: target)197    }198}199
Files main
Menu

Theme