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