Cache implementation

Sources/BaseOperationRef.swift

@@ -14,11 +14,6 @@
 
 import Foundation
 
-@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
-public struct OperationResult<ResultData: Decodable & Sendable>: Sendable {
-  public var data: ResultData
-}
-
 // notional protocol that denotes a variable.
 @available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
 public protocol OperationVariable: Encodable, Hashable, Equatable, Sendable {}
@@ -31,7 +26,7 @@ protocol OperationRequest: Hashable, Equatable, Sendable {
 }
 
 @available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
-public protocol OperationRef {
+public protocol OperationRef: Hashable, Equatable {
   associatedtype ResultData: Decodable & Sendable
 
   func execute() async throws -> OperationResult<ResultData>

Sources/Cache/Cache.swift

@@ -0,0 +1,174 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//      http://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 FirebaseAuth
+
+// FDC field name in server response that identifies a GlobalID
+let GlobalIDKey: String = "_id"
+
+// Client cache that internally uses a CacheProvider to store content.
+@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
+actor Cache {
+  let config: CacheSettings
+  weak var dataConnect: DataConnect?
+
+  private var cacheProvider: CacheProvider?
+
+  // holding it to avoid dealloc
+  private var authChangeListenerProtocol: NSObjectProtocol?
+
+  init(config: CacheSettings, dataConnect: DataConnect) {
+    self.config = config
+    self.dataConnect = dataConnect
+
+    // this is a potential race since update or get could get scheduled before initialize
+    // workarounds are complex since caller DataConnect APIs aren't async
+    Task {
+      await initializeCacheProvider()
+      await setupChangeListeners()
+    }
+  }
+
+  private func initializeCacheProvider() {
+    let identifier = contructCacheIdentifier()
+
+    guard identifier.isEmpty == false else {
+      DataConnectLogger.error("CacheIdentifier is empty. Caching is disabled")
+      return
+    }
+
+    // Create a cacheProvider if -
+    // we don't have an existing cacheProvider
+    // we have one but its identifier is different than new one (e.g. auth uid changed)
+    if cacheProvider != nil, cacheProvider?.cacheIdentifier == identifier {
+      return
+    }
+
+    do {
+      switch config.storage {
+      case .memory:
+        cacheProvider = try SQLiteCacheProvider(identifier, ephemeral: true)
+      case .persistent:
+        cacheProvider = try SQLiteCacheProvider(identifier, ephemeral: false)
+      }
+    } catch {
+      DataConnectLogger.error("Unable to initialize Persistent provider \(error)")
+    }
+  }
+
+  private func setupChangeListeners() {
+    guard let dataConnect else {
+      DataConnectLogger.error("Unable to setup auth change listeners since DataConnect is nil")
+      return
+    }
+
+    authChangeListenerProtocol = Auth.auth(app: dataConnect.app).addStateDidChangeListener { _, _ in
+      self.initializeCacheProvider()
+    }
+  }
+
+  // Create an identifier for the cache that the Provider will use for cache scoping
+  private func contructCacheIdentifier() -> String {
+    guard let dataConnect else {
+      DataConnectLogger.error("Unable to construct a cache identifier since DataConnect is nil")
+      return ""
+    }
+
+    let identifier =
+      "\(config.storage)-\(dataConnect.app.options.projectID!)-\(dataConnect.app.name)-\(dataConnect.connectorConfig.serviceId)-\(dataConnect.connectorConfig.connector)-\(dataConnect.connectorConfig.location)-\(Auth.auth(app: dataConnect.app).currentUser?.uid ?? "anon")-\(dataConnect.settings.host)"
+    let encoded = identifier.sha256
+    DataConnectLogger.debug("Created Encoded Cache Identifier \(encoded) for \(identifier)")
+    return encoded
+  }
+
+  func resultTree(queryId: String) -> ResultTree? {
+    // result trees are stored dehydrated in the cache
+    // retrieve cache, hydrate it and then return
+    guard let cacheProvider else {
+      DataConnectLogger.error("CacheProvider is nil in the Cache")
+      return nil
+    }
+
+    guard let dehydratedTree = cacheProvider.resultTree(queryId: queryId) else {
+      return nil
+    }
+
+    do {
+      let resultsProcessor = ResultTreeProcessor()
+      let (hydratedResults, rootObj) = try resultsProcessor.hydrateResults(
+        dehydratedTree.data,
+        cacheProvider: cacheProvider
+      )
+
+      let hydratedTree = ResultTree(
+        data: hydratedResults,
+        cachedAt: dehydratedTree.cachedAt,
+        lastAccessed: dehydratedTree.lastAccessed,
+        rootObject: rootObj
+      )
+
+      return hydratedTree
+    } catch {
+      DataConnectLogger.warning("Error decoding result tree \(error)")
+      return nil
+    }
+  }
+
+  func update(queryId: String, response: ServerResponse, requestor: (any QueryRefInternal)? = nil) {
+    // server response contains hydrated trees
+    // dehydrate (normalize) the results and store dehydrated trees
+    guard let cacheProvider = cacheProvider else {
+      DataConnectLogger
+        .debug("Cache provider not initialized yet. Skipping update for \(queryId)")
+      return
+    }
+    do {
+      let processor = ResultTreeProcessor()
+      let (dehydratedResults, rootObj, impactedRefs) = try processor.dehydrateResults(
+        response.jsonResults,
+        cacheProvider: cacheProvider,
+        requestor: requestor
+      )
+
+      cacheProvider
+        .setResultTree(
+          queryId: queryId,
+          tree: .init(
+            data: dehydratedResults,
+            cachedAt: Date(),
+            lastAccessed: Date(),
+            rootObject: rootObj
+          )
+        )
+
+      if let dataConnect {
+        for refId in impactedRefs {
+          guard let q = dataConnect.queryRef(for: refId) as? (any QueryRefInternal) else {
+            continue
+          }
+          Task {
+            do {
+              try await q.publishCacheResultsToSubscribers(allowStale: true)
+            } catch {
+              DataConnectLogger
+                .warning("Error republishing cached results for impacted queryrefs \(error))")
+            }
+          }
+        }
+      }
+    } catch {
+      DataConnectLogger.warning("Error updating cache for \(queryId): \(error)")
+    }
+  }
+}

Sources/Cache/CacheProvider.swift

@@ -0,0 +1,31 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//      http://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 Foundation
+
+import FirebaseCore
+
+// Key to store cache provider in Codables userInfo object.
+let CacheProviderUserInfoKey = CodingUserInfoKey(rawValue: "fdc_cache_provider")!
+
+@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
+protocol CacheProvider {
+  var cacheIdentifier: String { get }
+
+  func resultTree(queryId: String) -> ResultTree?
+  func setResultTree(queryId: String, tree: ResultTree)
+
+  func entityData(_ entityGuid: String) -> EntityDataObject
+  func updateEntityData(_ object: EntityDataObject)
+}

Sources/Cache/CacheSettings.swift

@@ -0,0 +1,56 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//      http://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 Foundation
+
+/// Specifies the cache configuration for a `DataConnect` instance.
+///
+/// You can configure the cache's storage policy and its maximum size.
+@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
+public struct CacheSettings: Sendable {
+  /// Defines the storage mechanism for the cache.
+  public enum Storage: Sendable {
+    /// The cache will be written to disk, persisting data across application launches.
+    case persistent
+    /// The cache will only be stored in memory and will be cleared when the application terminates.
+    case memory
+  }
+
+  /// The storage mechanism to be used for caching. The default is `.persistent`.
+  public let storage: Storage
+  /// The maximum size of the cache in bytes.
+  ///
+  /// This size is not strictly enforced but is used as a guideline by the cache
+  /// to trigger cleanup procedures. The default is 100MB (100,000,000 bytes).
+  public let maxSizeBytes: UInt64
+
+  /// Max time interval before a queries cache is considered stale and refreshed from the server
+  /// This interval does not imply that cached data is evicted and it can still be accessed using
+  /// the `cacheOnly` fetch policy
+  public let maxAge: TimeInterval
+
+  /// Creates a new cache settings configuration.
+  ///
+  /// - Parameters:
+  ///   - storage: The storage mechanism to use. Defaults to `.persistent`.
+  ///   - maxSize: The maximum desired size of the cache in bytes. Defaults to 100MB.
+  ///   - maxAge: The max time interval before a queries cache is considered stale and refreshed
+  /// from the server
+  public init(storage: Storage = .persistent, maxSize: UInt64 = 100_000_000,
+              maxAge: TimeInterval = 0) {
+    self.storage = storage
+    maxSizeBytes = maxSize
+    self.maxAge = maxAge
+  }
+}

Sources/Cache/DynamicCodingKey.swift

@@ -0,0 +1,22 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//      http://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.
+
+// Used for inline inline hydration of entity values
+@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
+struct DynamicCodingKey: CodingKey {
+  var intValue: Int?
+  let stringValue: String
+  init?(intValue: Int) { return nil }
+  init?(stringValue: String) { self.stringValue = stringValue }
+}