chore: import upstream snapshot with attribution

Sources/ContainerPersistence/EntityStore.swift

@@ -0,0 +1,134 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025-2026 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import ContainerizationError
+import Foundation
+import Logging
+import SystemPackage
+
+private let metadataFilename: String = "entity.json"
+
+public protocol EntityStore<T> {
+    associatedtype T: Codable & Identifiable<String> & Sendable
+
+    func list() async throws -> [T]
+    func create(_ entity: T) async throws
+    func retrieve(_ id: String) async throws -> T?
+    func update(_ entity: T) async throws
+    func upsert(_ entity: T) async throws
+    func delete(_ id: String) async throws
+}
+
+public actor FilesystemEntityStore<T>: EntityStore where T: Codable & Identifiable<String> & Sendable {
+    typealias Index = [String: T]
+
+    private let path: FilePath
+    private let type: String
+    private var index: Index
+    private let log: Logger
+    private let encoder = JSONEncoder()
+
+    public init(path: FilePath, type: String, log: Logger) throws {
+        self.path = path
+        self.type = type
+        self.log = log
+        self.index = try Self.load(path: path, log: log)
+    }
+
+    public func list() async throws -> [T] {
+        Array(index.values)
+    }
+
+    public func create(_ entity: T) async throws {
+        let metadataPath = try metadataPath(entity.id)
+        guard !FileManager.default.fileExists(atPath: metadataPath.string) else {
+            throw ContainerizationError(.exists, message: "entity \(entity.id) already exist")
+        }
+
+        let entityPath = try entityPath(entity.id)
+        try FileManager.default.createDirectory(atPath: entityPath.string, withIntermediateDirectories: true)
+        let data = try encoder.encode(entity)
+        try data.write(to: URL(filePath: metadataPath.string))
+        index[entity.id] = entity
+    }
+
+    public func retrieve(_ id: String) throws -> T? {
+        index[id]
+    }
+
+    public func update(_ entity: T) async throws {
+        let metadataPath = try metadataPath(entity.id)
+        guard FileManager.default.fileExists(atPath: metadataPath.string) else {
+            throw ContainerizationError(.notFound, message: "entity \(entity.id) not found")
+        }
+
+        let data = try encoder.encode(entity)
+        try data.write(to: URL(filePath: metadataPath.string))
+        index[entity.id] = entity
+    }
+
+    public func upsert(_ entity: T) async throws {
+        let entityPath = try entityPath(entity.id)
+        try FileManager.default.createDirectory(atPath: entityPath.string, withIntermediateDirectories: true)
+        let metadataPath = try metadataPath(entity.id)
+        let data = try encoder.encode(entity)
+        try data.write(to: URL(filePath: metadataPath.string))
+        index[entity.id] = entity
+    }
+
+    public func delete(_ id: String) async throws {
+        let metadataPath = try entityPath(id)
+        guard FileManager.default.fileExists(atPath: metadataPath.string) else {
+            throw ContainerizationError(.notFound, message: "entity \(id) not found")
+        }
+        try FileManager.default.removeItem(atPath: metadataPath.string)
+        index.removeValue(forKey: id)
+    }
+
+    public nonisolated func entityPath(_ id: String) throws -> FilePath {
+        guard let component = FilePath.Component(id) else {
+            throw ContainerizationError(.invalidArgument, message: "entity ID \(id) cannot be a path component")
+        }
+        return path.appending(component)
+    }
+
+    private static func load(path: FilePath, log: Logger) throws -> Index {
+        let directories = try FileManager.default.contentsOfDirectory(atPath: path.string)
+        var index: FilesystemEntityStore<T>.Index = Index()
+        let decoder = JSONDecoder()
+
+        for filename in directories {
+            let metadataPath = path.appending(filename).appending(metadataFilename)
+            do {
+                let data = try Data(contentsOf: URL(filePath: metadataPath.string))
+                let entity = try decoder.decode(T.self, from: data)
+                index[entity.id] = entity
+            } catch {
+                log.warning(
+                    "failed to load entity, ignoring",
+                    metadata: [
+                        "path": "\(metadataPath.string)"
+                    ])
+            }
+        }
+
+        return index
+    }
+
+    private func metadataPath(_ id: String) throws -> FilePath {
+        try entityPath(id).appending(metadataFilename)
+    }
+}