rzen/workouts
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Integrate IndieBackup for snapshot backup and restore

Browse Source 
Adds a local ZIP backup/restore of the iCloud document tree via the
IndieBackup package, surfaced in Settings with retention controls. A
restore suspends the sync observer, mirrors the files, then rebuilds the
SwiftData cache; opening a shared .workoutsbackup file restores it. The
engine exposes the container Documents root and a restore lifecycle
(isRestoring guards a concurrent connect), and the backup file type is
registered for open-in-place.

Claude-Session: https://claude.ai/code/session_01HJDQQDA9QdP8zByg43H5v3
This commit is contained in:
rzen
2026-07-08 08:03:30 -04:00
parent df3eac9d5f
commit 653cc65e0e
7 changed files with 190 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Workouts/AppServices.swift
+10 -1
View File
@@ -1,6 +1,7 @@
import Foundation
import Observation
import SwiftData
import IndieBackup
/// Composition root for the iOS app. Owns the SwiftData cache container and the
/// iCloud sync engine, and drives the one-shot launch sequence. Injected into the
@@ -10,6 +11,10 @@ import SwiftData
final class AppServices {
let container: ModelContainer
let syncEngine: SyncEngine
/// Local ZIP backup/restore of the iCloud document tree (`backupRoot` = the
/// container's `Documents/`). Restores rebuild the SwiftData cache via
/// `SyncEngine.rebuildCache()`; see `AppBackupConfiguration`.
let backupController: BackupController
let watchBridge: PhoneConnectivityBridge
let workoutLauncher = WorkoutLauncher()
let workoutHealthDeleter = WorkoutHealthDeleter()
@@ -26,7 +31,11 @@ final class AppServices {
init() {
let container = WorkoutsModelContainer.make()
self.container = container
self.syncEngine = SyncEngine(container: container)
let syncEngine = SyncEngine(container: container)
self.syncEngine = syncEngine
self.backupController = BackupController(
configuration: AppBackupConfiguration(syncEngine: syncEngine)
)
let liveRunState = LiveRunState()
self.liveRunState = liveRunState
self.watchBridge = PhoneConnectivityBridge(container: container, syncEngine: syncEngine, liveRunState: liveRunState)
Workouts/Backup/AppBackupConfiguration.swift
+73
View File
@@ -0,0 +1,73 @@
//
// AppBackupConfiguration.swift
// Workouts
//
// Copyright 2025 Rouslan Zenetl. All Rights Reserved.
//
import Foundation
import IndieBackup
/// Tells IndieBackup what to snapshot and how to bring the app back to a
/// consistent state after a restore.
///
/// `backupRoot` is the ubiquity container's `Documents/` directory — the exact
/// tree `SyncEngine`'s `DocumentFileStore` writes to: `Splits/`, `Workouts/`,
/// and the `Stubs/` soft-delete tombstones. Backing up that whole tree,
/// tombstones included, is deliberate — a restore that dropped the stubs could
/// resurrect records the user had already deleted. The SwiftData store is never
/// in the backup: it's a rebuildable cache, regenerated from the restored files
/// by `rebuildCacheAfterRestore`.
///
/// This type is nonisolated on purpose — the package reads `backupRoot`
/// synchronously off the main actor during its detached directory mirror. It
/// holds the `@MainActor` `SyncEngine`, which is safe because a global-actor
/// class is implicitly `Sendable`, and the three restore hooks only ever reach
/// it via `await`.
final class AppBackupConfiguration: BackupConfiguration {
private let syncEngine: SyncEngine
init(syncEngine: SyncEngine) {
self.syncEngine = syncEngine
}
var backupFileExtension: String { "workoutsbackup" }
var backupDisplayName: String { "Workouts Backup" }
/// The container's `Documents/` folder. Resolved directly from `FileManager`
/// with the app's explicit ubiquity container id so this stays synchronous and
/// nonisolated; it yields the identical URL `SyncEngine` exposes as
/// `containerDocumentsURL` once connected. Backup and restore are only
/// reachable past the iCloud gate, so the container is always resolved by the
/// time this is read — the package's local `documentsURL` fallback is only a
/// belt-and-suspenders never-nil guarantee.
var backupRoot: URL {
if let container = FileManager.default.url(
forUbiquityContainerIdentifier: SyncEngine.containerIdentifier
) {
let docs = container.appendingPathComponent("Documents", isDirectory: true)
try? FileManager.default.createDirectory(at: docs, withIntermediateDirectories: true)
return docs
}
return iCloudDocumentManager.shared.documentsURL
}
/// After the restore has replaced the document tree on disk, rebuild the
/// SwiftData cache from those files.
func rebuildCacheAfterRestore(progress: @escaping (Double, String) -> Void) async throws {
progress(0.0, "Rebuilding your library…")
await syncEngine.rebuildCache()
progress(1.0, "Library rebuilt")
}
/// Stop the metadata observer before the restore touches disk, so the bulk
/// file mirror isn't observed as a storm of live edits.
func prepareForRestore() async {
await syncEngine.beginRestore()
}
/// Resume the metadata observer (fresh, re-baselined) after the restore.
func finishRestore() async {
await syncEngine.endRestore()
}
}
Workouts/Resources/Info-iOS.plist
+37
View File
@@ -57,5 +57,42 @@
<string>Any</string>
</dict>
</dict>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
<key>CFBundleDocumentTypes</key>
<array>
<dict>
<key>CFBundleTypeName</key>
<string>Workouts Backup</string>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>LSHandlerRank</key>
<string>Owner</string>
<key>LSItemContentTypes</key>
<array>
<string>dev.rzen.indie.workoutsbackup</string>
</array>
</dict>
</array>
<key>UTExportedTypeDeclarations</key>
<array>
<dict>
<key>UTTypeIdentifier</key>
<string>dev.rzen.indie.workoutsbackup</string>
<key>UTTypeDescription</key>
<string>Workouts Backup</string>
<key>UTTypeConformsTo</key>
<array>
<string>public.data</string>
</array>
<key>UTTypeTagSpecification</key>
<dict>
<key>public.filename-extension</key>
<array>
<string>workoutsbackup</string>
</array>
</dict>
</dict>
</array>
</dict>
</plist>
Workouts/Sync/SyncEngine.swift
+55
View File
@@ -25,6 +25,19 @@ final class SyncEngine {
private(set) var iCloudStatus: ICloudStatus = .checking
private(set) var isSyncing = false
/// Resolved `Documents/` directory inside the ubiquity container — the root of
/// the on-disk JSON document tree (`Splits/`, `Workouts/`, `Stubs/`) and the
/// backup layer's `backupRoot`. Set once the container resolves in `connect()`;
/// nil until then. Read-only for callers.
private(set) var containerDocumentsURL: URL?
/// True while a backup restore is replacing the document tree. The restore
/// suspends the metadata observer itself (`beginRestore`/`endRestore`); this
/// flag additionally vetoes a concurrent `connect()`/reconcile (e.g. a
/// scenePhase foreground-return) so the two can't fight over the cache while a
/// bulk file mirror is in flight.
private(set) var isRestoring = false
/// Last non-fatal sync failure, surfaced for the UI to render. Cleared on the
/// next successful write or full reconcile.
private(set) var lastSyncError: String?
@@ -75,6 +88,10 @@ final class SyncEngine {
// MARK: - Connection (deferred, patient)
func connect() async {
// Never reconnect/reconcile mid-restore: the backup layer is rewriting the
// whole document tree and rebuilding the cache itself. Balanced by the
// restore clearing `isRestoring` in `endRestore()`.
guard !isRestoring else { log.info("connect: skipped — restore in progress"); return }
guard iCloudStatus != .available else { return }
connectAttempt += 1
let attempt = connectAttempt
@@ -142,6 +159,7 @@ final class SyncEngine {
guard attempt == connectAttempt else { return }
self.store = store
self.containerDocumentsURL = store.rootURL
self.tombstones = TombstoneStore(store: store)
iCloudStatus = .available
log.info("connect[\(attempt)]: directories ready → available")
@@ -164,6 +182,43 @@ final class SyncEngine {
log.info("connect: abandoned by user → unavailable")
}
// MARK: - Backup restore lifecycle
/// Rebuild the SwiftData cache from whatever documents are currently on disk.
/// The cache is a pure read-through projection of the files, so a full
/// `reconcile()` — import every live file, prune every entity with no backing
/// file — *is* a rebuild. Called by the backup layer after a restore has
/// replaced the document tree; safe whenever the engine is connected (a nil
/// store, i.e. not yet connected, no-ops and the next `connect()` rebuilds).
func rebuildCache() async {
await reconcile()
}
/// Suspend live file-watching for the duration of a restore. A restore mirrors
/// many files at once; without this the observer would replay each as a live
/// edit. Sets `isRestoring` (so a concurrent `connect()` bails) and tears down
/// the metadata observer. Always balanced by `endRestore()`.
func beginRestore() {
isRestoring = true
monitorTask?.cancel()
monitorTask = nil
monitor?.stop()
monitor = nil
log.info("restore: began — metadata observer suspended")
}
/// Resume live file-watching after a restore. Starts a FRESH metadata observer
/// (which re-baselines its known paths, so the just-restored files don't replay
/// as a flood of add/remove events) and clears `isRestoring`. Balanced with
/// `beginRestore()`; the backup layer calls this on both success and failure.
func endRestore() {
isRestoring = false
if let store {
startMonitoring(documentsURL: store.rootURL)
}
log.info("restore: ended — metadata observer resumed")
}
// MARK: - Monitoring
private func startMonitoring(documentsURL: URL) {
Workouts/Views/Settings/SettingsView.swift
+4
View File
@@ -8,6 +8,7 @@
import SwiftUI
import SwiftData
import IndieAbout
import IndieBackup
struct SettingsView: View {
@Environment(SyncEngine.self) private var sync
@@ -132,6 +133,9 @@ struct SettingsView: View {
Text("iCloud Sync")
}
// MARK: - Backups Section
BackupsSectionView(controller: services.backupController)
// MARK: - Developer Section (debug builds only)
#if DEBUG
Section {
Workouts/WorkoutsApp.swift
+7
View File
@@ -41,5 +41,12 @@ struct WorkoutsApp: App {
.environment(services.liveRunState)
.modelContainer(services.container)
.task { await services.bootstrap() }
// Tap a shared ".workoutsbackup" file (Files, AirDrop, share sheet) to
// restore it. The controller stops the sync observer for the restore and
// rebuilds the cache afterward (see AppBackupConfiguration).
.onOpenURL { url in
guard url.pathExtension == "workoutsbackup" else { return }
Task { try? await services.backupController.restoreBackup(from: url) }
}
}
}
project.yml
+4
View File
@@ -22,6 +22,9 @@ packages:
IndieSync:
url: https://git.rzen.dev/rzen/indie-sync.git
from: "0.3.0"
IndieBackup:
url: https://git.rzen.dev/rzen/indie-backup.git
from: "2.0.0"
# Shared post-build phase — stamps CFBundleVersion (git commit count), BuildDate, and
# BuildHash into each target's (and dSYM's) Info.plist. Aliased into every code-bearing
@@ -62,6 +65,7 @@ targets:
dependencies:
- package: IndieAbout
- package: IndieSync
- package: IndieBackup
- target: Workouts Watch App
- target: Workouts Widget
embed: true