Let isFromCache be about the ApolloResponse (apollographql#5805)

Author: BoD

design-docs/Error handling changes in v4.md

@@ -0,0 +1,22 @@
+# Error handling changes in v4
+
+This document describes the changes made around error handling in v4. The purpose is to keep a log of the changes, in a
+kind of "decision record" way.
+
+## Broaden the meaning of `ApolloResponse.isFromCache`
+
+In v3, `ApolloResponse.isFromCache` returns `true` if the **data** comes from the cache (implementation:
+`cacheInfo?.isCacheHit == true`). A more descriptive name could have been `isCacheHit`.
+
+In v4, since cache misses no longer throw, a response can come from the cache whether the data is present or not.
+
+With that in mind, it makes more sense for `isFromCache` to return `true` if the **response** comes from the cache,
+regardless of the data being present or not (new implementation:
+`cacheInfo?.isCacheHit == true || exception is CacheMissException`).
+
+Note: this **is** a behavior change for projects that used `emitCacheMisses(true)` in v3:
+
+- cache miss responses in v3: `isFromCache` would return `false` ("data is not a cache hit")
+- cache miss responses in v4: `isFromCache` will return `true` ("response is from the cache")
+
+More context in [#5799](https://github.com/apollographql/apollo-kotlin/issues/5799).

libraries/apollo-normalized-cache-incubating/src/commonMain/kotlin/com/apollographql/apollo3/cache/normalized/ClientCacheExtensions.kt

@@ -552,9 +552,15 @@ class CacheInfo private constructor(
   }
 }
 
+/**
+ * True if this response comes from the cache, false if it comes from the network.
+ *
+ * Note that this can be true regardless of whether the data was found in the cache.
+ * To know whether the **data** is from the cache, use `cacheInfo?.isCacheHit == true`.
+ */
 val <D : Operation.Data> ApolloResponse<D>.isFromCache: Boolean
   get() {
-    return cacheInfo?.isCacheHit == true
+    return cacheInfo?.isCacheHit == true || exception is CacheMissException
   }
 
 val <D : Operation.Data> ApolloResponse<D>.cacheInfo

libraries/apollo-normalized-cache/src/commonMain/kotlin/com/apollographql/apollo3/cache/normalized/ClientCacheExtensions.kt

@@ -533,9 +533,15 @@ class CacheInfo private constructor(
   }
 }
 
+/**
+ * True if this response comes from the cache, false if it comes from the network.
+ *
+ * Note that this can be true regardless of whether the data was found in the cache.
+ * To know whether the **data** is from the cache, use `cacheInfo?.isCacheHit == true`.
+ */
 val <D : Operation.Data> ApolloResponse<D>.isFromCache: Boolean
   get() {
-    return cacheInfo?.isCacheHit == true
+    return cacheInfo?.isCacheHit == true || exception is CacheMissException
   }
 
 val <D : Operation.Data> ApolloResponse<D>.cacheInfo
@@ -645,4 +651,4 @@ val <D : Operation.Data> ApolloResponse<D>.cacheHeaders
  */
 @Deprecated("Use fetchPolicy(FetchPolicy.CacheAndNetwork) instead", ReplaceWith("fetchPolicy(FetchPolicy.CacheAndNetwork).toFlow()"), level = DeprecationLevel.ERROR)
 @ApolloDeprecatedSince(ApolloDeprecatedSince.Version.v3_7_5)
-fun <D : Query.Data> ApolloCall<D>.executeCacheAndNetwork(): Flow<ApolloResponse<D>> = TODO()
+fun <D : Query.Data> ApolloCall<D>.executeCacheAndNetwork(): Flow<ApolloResponse<D>> = TODO()

tests/integration-tests/src/commonTest/kotlin/test/FetchPolicyTest.kt

@@ -623,4 +623,70 @@ class FetchPolicyTest {
     job.cancel()
     channel.cancel()
   }
+
+  @Test
+  fun isFromCache() = runTest(before = { setUp() }, after = { tearDown() }) {
+    val query = HeroNameQuery()
+    val data = HeroNameQuery.Data(HeroNameQuery.Hero("R2-D2"))
+    mockServer.enqueue(query, data)
+
+    // NetworkOnly / hit
+    var response = apolloClient.query(query)
+        .fetchPolicy(FetchPolicy.NetworkOnly)
+        .execute()
+    assertNotNull(response.data)
+    assertFalse(response.isFromCache)
+
+    // CacheOnly / hit
+    response = apolloClient.query(query)
+        .fetchPolicy(FetchPolicy.CacheOnly)
+        .execute()
+    assertNotNull(response.data)
+    assertTrue(response.isFromCache)
+
+    // CacheOnly / miss
+    store.clearAll()
+    response = apolloClient.query(query)
+        .fetchPolicy(FetchPolicy.CacheOnly)
+        .execute()
+    assertNull(response.data)
+    assertTrue(response.isFromCache)
+
+    // NetworkOnly / miss
+    mockServer.enqueueString("malformed")
+    response = apolloClient.query(query)
+        .fetchPolicy(FetchPolicy.NetworkOnly)
+        .execute()
+    assertNull(response.data)
+    assertFalse(response.isFromCache)
+
+    // CacheFirst / miss / miss
+    store.clearAll()
+    mockServer.enqueueString("malformed")
+    var responses = apolloClient.query(query)
+        .fetchPolicy(FetchPolicy.CacheFirst)
+        .toFlow()
+        .toList()
+    assertTrue(responses[0].isFromCache)
+    assertFalse(responses[1].isFromCache)
+
+    // NetworkFirst / miss / miss
+    store.clearAll()
+    mockServer.enqueueString("malformed")
+    responses = apolloClient.query(query)
+        .fetchPolicy(FetchPolicy.NetworkFirst)
+        .toFlow()
+        .toList()
+    assertFalse(responses[0].isFromCache)
+    assertTrue(responses[1].isFromCache)
+
+    // CacheAndNetwork / hit / hit
+    mockServer.enqueue(query, data)
+    responses = apolloClient.query(query)
+        .fetchPolicy(FetchPolicy.CacheAndNetwork)
+        .toFlow()
+        .toList()
+    assertTrue(responses[0].isFromCache)
+    assertFalse(responses[1].isFromCache)
+  }
 }