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,159 @@
+// 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
+  let 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()
+
+    // 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() {
+    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 {
+    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,
+        ttl: dehydratedTree.ttl,
+        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,
+            ttl: response.ttl,
+            cachedAt: Date(),
+            lastAccessed: Date(),
+            rootObject: rootObj
+          )
+        )
+
+      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,30 @@
+// 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.
+
+/// Specifies the cache configuration for a Firebase Data Connect instance
+@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
+public struct CacheSettings: Sendable {
+  public enum Storage: Sendable {
+    case persistent
+    case memory
+  }
+
+  public let storage: Storage // default provider is persistent type
+  public let maxSizeBytes: UInt64
+
+  public init(storage: Storage = .persistent, maxSize: UInt64 = 100_000_000) {
+    self.storage = storage
+    maxSizeBytes = maxSize
+  }
+}

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 }
+}