From 99e4623af1b08f36120a01b67cbe60df99668651 Mon Sep 17 00:00:00 2001 From: Christian Cleberg Date: Fri, 24 Jul 2026 23:35:18 -0500 Subject: feat: versioned store-migration policy for persisted data (v5 step 2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Third v5.0.0 roadmap item: define and implement a migration policy for the on-device persisted store (tracked domains, history/snapshots, audits, workflows, monitoring, settings), so data upgrades cleanly across app versions instead of relying on a one-shot marker. - DataMigrationService is reworked from a single boolean marker (`data.migrations.v3_4_0`) into a versioned runner keyed by an integer store schema version (`data.storeSchemaVersion`). It runs each step once in ascending order up to `currentStoreSchemaVersion`, stamping the version as it goes. Adding a future migration is now a `case N:` plus a version bump. Policy guarantees, all covered by tests: - Forward-only and idempotent; every step must be safe on an empty/older store. - Never downgrades: a store written by a newer build (higher version) is left byte-for-byte untouched. - Pre-versioning installs are handled: a set legacy boolean marker reads as "already at v1", so the v1 normalization never re-runs for them. v1 is the existing normalization pass (dedup + drop the legacy `watchedDomains` key + sanitize monitoring settings), now expressed as migration step 1. - Docs/data-migration.md documents the persisted surface, the two independent version lines (store vs. backup export), when to use lenient decoding vs. a migration step, the runner contract, an "adding a migration" checklist, and backup-import compatibility. Linked from the README. - DataMigrationServiceTests: 6 tests over legacy fixtures — fresh-store stamping, legacy `watchedDomains` migration + key drop, in-place dedup of the stored blob, idempotence, legacy-marker-as-v1, and the no-downgrade guard. Full unit suite: 58 passing. --- DomainDigTests/DataMigrationServiceTests.swift | 109 +++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 DomainDigTests/DataMigrationServiceTests.swift (limited to 'DomainDigTests/DataMigrationServiceTests.swift') diff --git a/DomainDigTests/DataMigrationServiceTests.swift b/DomainDigTests/DataMigrationServiceTests.swift new file mode 100644 index 0000000..3a6cdd9 --- /dev/null +++ b/DomainDigTests/DataMigrationServiceTests.swift @@ -0,0 +1,109 @@ +import XCTest +@testable import DomainDig + +/// Characterization tests for the versioned store-migration runner. They drive +/// `migrateIfNeeded` against legacy on-disk fixtures in an ephemeral +/// `UserDefaults` suite and pin the policy: forward-only, idempotent, and +/// non-destructive to a store written by a newer build. +/// +/// The raw storage-key strings ("trackedDomains", "watchedDomains", the legacy +/// marker) are duplicated here on purpose — they are the on-disk contract, and +/// hard-coding them means an accidental rename shows up as a failing migration. +final class DataMigrationServiceTests: XCTestCase { + private let suiteName = "DomainDigTests.migration" + private var defaults: UserDefaults! + private let base = Date(timeIntervalSince1970: 1_700_000_000) + + override func setUp() { + super.setUp() + defaults = UserDefaults(suiteName: suiteName) + defaults.removePersistentDomain(forName: suiteName) + } + + override func tearDown() { + defaults.removePersistentDomain(forName: suiteName) + defaults = nil + super.tearDown() + } + + func testFreshStoreIsStampedAtCurrentVersion() { + XCTAssertEqual(DataMigrationService.storeSchemaVersion(defaults: defaults), 0) + + DataMigrationService.migrateIfNeeded(defaults: defaults) + + XCTAssertEqual( + DataMigrationService.storeSchemaVersion(defaults: defaults), + DataMigrationService.currentStoreSchemaVersion + ) + } + + func testLegacyWatchedDomainsAreMigratedAndTheOldKeyIsDropped() throws { + let legacy = [WatchedDomain(domain: "legacy.example", createdAt: base, lastKnownAvailability: .registered)] + defaults.set(try JSONEncoder().encode(legacy), forKey: "watchedDomains") + + DataMigrationService.migrateIfNeeded(defaults: defaults) + + let tracked = DomainDataPortabilityService.loadTrackedDomains(defaults: defaults) + XCTAssertEqual(tracked.map(\.domain), ["legacy.example"]) + XCTAssertNil(defaults.data(forKey: "watchedDomains"), "legacy key is dropped after migration") + XCTAssertNotNil(defaults.data(forKey: "trackedDomains"), "data is rewritten under the current key") + XCTAssertEqual(DataMigrationService.storeSchemaVersion(defaults: defaults), 1) + } + + func testMigrationDeduplicatesTheStoredBlobInPlace() throws { + let dupes = [ + TrackedDomain(domain: "dupe.example", updatedAt: base.addingTimeInterval(-10)), + TrackedDomain(domain: "DUPE.example", updatedAt: base) + ] + defaults.set(try JSONEncoder().encode(dupes), forKey: "trackedDomains") + + DataMigrationService.migrateIfNeeded(defaults: defaults) + + let data = try XCTUnwrap(defaults.data(forKey: "trackedDomains")) + let stored = try JSONDecoder().decode([TrackedDomain].self, from: data) + XCTAssertEqual(stored.count, 1, "the persisted blob is deduplicated, not just the load result") + } + + func testMigrationIsIdempotent() throws { + defaults.set( + try JSONEncoder().encode([TrackedDomain(domain: "a.example", updatedAt: base)]), + forKey: "trackedDomains" + ) + + DataMigrationService.migrateIfNeeded(defaults: defaults) + let afterFirst = defaults.data(forKey: "trackedDomains") + + DataMigrationService.migrateIfNeeded(defaults: defaults) + let afterSecond = defaults.data(forKey: "trackedDomains") + + XCTAssertEqual(afterFirst, afterSecond, "a second run makes no further changes") + XCTAssertEqual( + DataMigrationService.storeSchemaVersion(defaults: defaults), + DataMigrationService.currentStoreSchemaVersion + ) + } + + func testLegacyBooleanMarkerCountsAsVersionOne() { + defaults.set(true, forKey: "data.migrations.v3_4_0") + + XCTAssertEqual(DataMigrationService.storeSchemaVersion(defaults: defaults), 1) + + // Already at v1, so the v1 step must not re-run: a leftover legacy blob + // is left exactly as found. + defaults.set(Data("x".utf8), forKey: "watchedDomains") + DataMigrationService.migrateIfNeeded(defaults: defaults) + XCTAssertNotNil(defaults.data(forKey: "watchedDomains"), "v1 is treated as already applied; no re-run") + } + + func testNewerStoreVersionIsNeverDowngradedOrRewritten() throws { + let future = DataMigrationService.currentStoreSchemaVersion + 1 + defaults.set(future, forKey: DataMigrationService.storeSchemaVersionKey) + let blob = try JSONEncoder().encode([TrackedDomain(domain: "keep.example", updatedAt: base)]) + defaults.set(blob, forKey: "trackedDomains") + + DataMigrationService.migrateIfNeeded(defaults: defaults) + + XCTAssertEqual(DataMigrationService.storeSchemaVersion(defaults: defaults), future, "must never downgrade") + XCTAssertEqual(defaults.data(forKey: "trackedDomains"), blob, "future-version data is left byte-for-byte") + } +} -- cgit v1.2.3