Added StoreInfo to refer to the store as a whole on disk

Author: dimitribouniol

Sources/CodableDatastore/CodableDatastore.docc/On Disk Representation.md

@@ -12,13 +12,13 @@ saved to disk, located at the user's chosen ``/Foundation/URL``.
 The persistence store is the top-most level a ``DiskPersistence`` uses, and
 contains a list of [snapshots](#Snapshots) and [backups](#Backups), a pointer
 to the most recent snapshot, and some basic metadata such as version and last
-modification date in `Manifest.json`.
+modification date in `Info.json`.
 
 The file layout is as follows:
 
 ```
 - 📦 Path/To/Data.persistencestore/
-    - 📃 Manifest.json
+    - 📃 Info.json
     - 📁 Snapshots/
     - 📁 Backups/
 ```

Sources/CodableDatastore/Persistence/Disk Persistence/DiskPersistence.swift

@@ -35,6 +35,8 @@ public actor DiskPersistence<AccessMode: _AccessMode>: Persistence {
     /// The location of this persistence.
     let storeURL: URL
 
+    var cachedStoreInfo: StoreInfo?
+    
     /// Initialize a ``DiskPersistence`` with a read-write URL.
     ///
     /// Use this initializer when creating a persistence from the main process that will access it, such as your app. To access the same persistence from another process, use ``init(readOnlyURL:)`` instead.
@@ -118,6 +120,41 @@ extension DiskPersistence {
     var backupsURL: URL {
         storeURL.appendingPathComponent("Backups", isDirectory: true)
     }
+    
+    var storeInfoURL: URL {
+        storeURL.appendingPathComponent("Info.json", isDirectory: false)
+    }
+}
+
+extension DiskPersistence {
+    /// Load the store info from disk, or create a suitable starting value if such a file does not exist.
+    func loadStoreInfo() throws -> StoreInfo {
+        do {
+            let data = try Data(contentsOf: storeInfoURL)
+            
+            let storeInfoDecoder = JSONDecoder()
+            storeInfoDecoder.dateDecodingStrategy = .iso8601WithMilliseconds
+            let storeInfo = try storeInfoDecoder.decode(StoreInfo.self, from: data)
+            
+            cachedStoreInfo = storeInfo
+            return storeInfo
+        } catch URLError.fileDoesNotExist, CocoaError.fileReadNoSuchFile {
+            return StoreInfo(modificationDate: Date())
+        } catch let error as NSError where error.domain == NSPOSIXErrorDomain && error.code == Int(POSIXError.ENOENT.rawValue) {
+            return StoreInfo(modificationDate: Date())
+        } catch {
+            throw error
+        }
+    }
+    
+    /// Write the specified store info to the store, and cache the results in ``DiskPersistence/cachedStoreInfo``.
+    func write(_ storeInfo: StoreInfo) throws {
+        let storeInfoEncoder = JSONEncoder()
+        storeInfoEncoder.dateEncodingStrategy = .iso8601WithMilliseconds
+        let data = try storeInfoEncoder.encode(storeInfo)
+        try data.write(to: storeInfoURL, options: .atomic)
+        cachedStoreInfo = storeInfo
+    }
 }
 
 extension DiskPersistence where AccessMode == ReadWrite {
@@ -129,6 +166,13 @@ extension DiskPersistence where AccessMode == ReadWrite {
         try FileManager.default.createDirectory(at: storeURL, withIntermediateDirectories: true)
         try FileManager.default.createDirectory(at: snapshotsURL, withIntermediateDirectories: true)
         try FileManager.default.createDirectory(at: backupsURL, withIntermediateDirectories: true)
+        
+        // Load the store info, so we can see if we'll need to write it or not.
+        let storeInfo = try loadStoreInfo()
+        // If the cached store info is nil, we didn't have one already, so write the one we got back to disk.
+        if (cachedStoreInfo == nil) {
+            try write(storeInfo)
+        }
     }
 }
 

Sources/CodableDatastore/Persistence/Disk Persistence/ISO8601DateFormatter+Milliseconds.swift

@@ -0,0 +1,44 @@
+//
+//  ISO8601DateFormatter+Milliseconds.swift
+//  CodableDatastore
+//
+//  Created by Dimitri Bouniol on 2023-06-07.
+//  Copyright © 2023 Mochi Development, Inc. All rights reserved.
+//
+
+import Foundation
+
+extension ISO8601DateFormatter {
+    static var withMilliseconds: ISO8601DateFormatter = {
+        let formatter = ISO8601DateFormatter()
+        formatter.timeZone = TimeZone(secondsFromGMT: 0)
+        formatter.formatOptions = [
+            .withInternetDateTime,
+            .withDashSeparatorInDate,
+            .withColonSeparatorInTime,
+            .withTimeZone,
+            .withFractionalSeconds
+        ]
+        return formatter
+    }()
+}
+
+extension JSONDecoder.DateDecodingStrategy {
+    static let iso8601WithMilliseconds: Self = custom { decoder in
+        let container = try decoder.singleValueContainer()
+        let string = try container.decode(String.self)
+        guard let date = ISO8601DateFormatter.withMilliseconds.date(from: string) else {
+            throw DecodingError.dataCorruptedError(in: container, debugDescription: "Invalid date: \(string)")
+        }
+        return date
+
+    }
+}
+
+extension JSONEncoder.DateEncodingStrategy {
+    static let iso8601WithMilliseconds: Self = custom { date, encoder in
+        let string = ISO8601DateFormatter.withMilliseconds.string(from: date)
+        var container = encoder.singleValueContainer()
+        try container.encode(string)
+    }
+}

Sources/CodableDatastore/Persistence/Disk Persistence/StoreInfo.swift

@@ -0,0 +1,28 @@
+//
+//  StoreInfo.swift
+//  CodableDatastore
+//
+//  Created by Dimitri Bouniol on 2023-06-07.
+//  Copyright © 2023 Mochi Development, Inc. All rights reserved.
+//
+
+import Foundation
+
+/// Versions supported by ``DiskPersisitence``.
+///
+/// These are used when dealing with format changes at the library level.
+enum StoreInfoVersion: String, Codable {
+    case alpha
+}
+
+/// A struct to store information about a ``DiskPersistence`` on disk.
+struct StoreInfo: Codable, Equatable {
+    /// The version of the persistence, used when dealing with format changes at the library level.
+    var version: StoreInfoVersion = .alpha
+    
+    /// A pointer to the current snapshot.
+    var currentSnapshot: String?
+    
+    /// The last modification date of the persistence.
+    var modificationDate: Date
+}

Tests/CodableDatastoreTests/DiskPersistenceTests.swift

@@ -73,16 +73,50 @@ final class DiskPersistenceTests: XCTestCase {
         XCTAssertTrue(try temporaryStoreURL.checkResourceIsReachable())
         XCTAssertTrue(try temporaryStoreURL.appendingPathComponent("Snapshots", isDirectory: true).checkResourceIsReachable())
         XCTAssertTrue(try temporaryStoreURL.appendingPathComponent("Backups", isDirectory: true).checkResourceIsReachable())
+        XCTAssertTrue(try temporaryStoreURL.appendingPathComponent("Info.json", isDirectory: false).checkResourceIsReachable())
+    }
+    
+    func testStoreInfoOnEmptyStore() async throws {
+        let persistence = try DiskPersistence(readWriteURL: temporaryStoreURL)
+        try await persistence.createPersistenceIfNecessary()
+        
+        let data = try Data(contentsOf: temporaryStoreURL.appendingPathComponent("Info.json", isDirectory: false))
+        
+        struct TestStruct: Codable {
+            var version: String
+            var modificationDate: String
+            var currentSnapshot: String?
+        }
+        
+        let testStruct = try JSONDecoder().decode(TestStruct.self, from: data)
+        XCTAssertEqual(testStruct.version, "alpha")
+        XCTAssertNil(testStruct.currentSnapshot)
+        
+        let formatter = ISO8601DateFormatter()
+        formatter.timeZone = TimeZone(secondsFromGMT: 0)
+        formatter.formatOptions = [
+            .withInternetDateTime,
+            .withDashSeparatorInDate,
+            .withColonSeparatorInTime,
+            .withTimeZone,
+            .withFractionalSeconds
+        ]
+        XCTAssertNotNil(formatter.date(from: testStruct.modificationDate))
     }
 
     func testStoreCreatesOnlyIfNecessary() async throws {
         let persistence = try DiskPersistence(readWriteURL: temporaryStoreURL)
         try await persistence.createPersistenceIfNecessary()
+        let dataBefore = try Data(contentsOf: temporaryStoreURL.appendingPathComponent("Info.json", isDirectory: false))
         // This second time should be a no-op and shouldn't throw
         try await persistence.createPersistenceIfNecessary()
 
         XCTAssertTrue(try temporaryStoreURL.checkResourceIsReachable())
         XCTAssertTrue(try temporaryStoreURL.appendingPathComponent("Snapshots", isDirectory: true).checkResourceIsReachable())
         XCTAssertTrue(try temporaryStoreURL.appendingPathComponent("Backups", isDirectory: true).checkResourceIsReachable())
+        XCTAssertTrue(try temporaryStoreURL.appendingPathComponent("Info.json", isDirectory: false).checkResourceIsReachable())
+        
+        let dataAfter = try Data(contentsOf: temporaryStoreURL.appendingPathComponent("Info.json", isDirectory: false))
+        XCTAssertEqual(dataBefore, dataAfter)
     }
 }