Add KDoc for ApolloInterceptor (#6295)

Author: martinbonnin

libraries/apollo-runtime/src/commonMain/kotlin/com/apollographql/apollo/interceptor/ApolloInterceptor.kt

@@ -5,13 +5,48 @@ import com.apollographql.apollo.api.Operation
 import com.apollographql.apollo.api.ApolloResponse
 import kotlinx.coroutines.flow.Flow
 
+/**
+ * An [ApolloInterceptor] intercepts requests at the GraphQL layer.
+ *
+ * [ApolloInterceptor]s may modify the request and or the response:
+ *
+ * ```kotlin
+ * // Add a header to each request and extensions to each response.
+ * val newRequest = request.newBuilder()
+ *     .addHttpHeader("foo1", "bar1")
+ *     .build()
+ *
+ * return chain.proceed(newRequest).map {
+ *   it.newBuilder()
+ *       .extensions(mapOf("foo2" to "bar2"))
+ *       .build()
+ * }
+ * ```
+ *
+ * @see [com.apollographql.apollo.api.ExecutionContext]
+ * @see [com.apollographql.apollo.network.http.HttpInterceptor]
+ */
+interface ApolloInterceptor {
+  /**
+   * Intercepts the given [request]. Call `chain.proceed()` to continue with the next interceptor or emit items
+   * directly to bypass the chain.
+   *
+   * Exceptions thrown from [intercept] are not caught and are propagated to the call site. Use `ApolloResponse.Builder.exception()`
+   * to return an exception response if you don't want your [com.apollographql.apollo.ApolloCall] to throw.
+   *
+   * @see ApolloResponse.Builder
+   */
+  fun <D : Operation.Data> intercept(request: ApolloRequest<D>, chain: ApolloInterceptorChain): Flow<ApolloResponse<D>>
+}
+
+/**
+ * An [ApolloInterceptorChain] is a list of interceptors called in order. Each interceptor wraps the subsequent ones
+ * and can delegate to them by calling [proceed] or emit items directly.
+ */
 interface ApolloInterceptorChain {
   fun <D : Operation.Data> proceed(request: ApolloRequest<D>): Flow<ApolloResponse<D>>
 }
 
-interface ApolloInterceptor {
-  fun <D : Operation.Data> intercept(request: ApolloRequest<D>, chain: ApolloInterceptorChain): Flow<ApolloResponse<D>>
-}
 
 internal class DefaultInterceptorChain(
     private val interceptors: List<ApolloInterceptor>,

libraries/apollo-runtime/src/jvmTest/kotlin/InterceptorsErrorTest.kt

@@ -0,0 +1,77 @@
+import com.apollographql.apollo.ApolloClient
+import com.apollographql.apollo.api.ApolloRequest
+import com.apollographql.apollo.api.ApolloResponse
+import com.apollographql.apollo.api.Operation
+import com.apollographql.apollo.exception.DefaultApolloException
+import com.apollographql.apollo.interceptor.ApolloInterceptor
+import com.apollographql.apollo.interceptor.ApolloInterceptorChain
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.runBlocking
+import okio.use
+import test.FooQuery
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertIs
+
+class InterceptorsErrorTest {
+  @Test
+  fun interceptorsMayThrow() {
+    ApolloClient.Builder()
+        .serverUrl("unused")
+        .addInterceptor(object : ApolloInterceptor {
+          override fun <D : Operation.Data> intercept(
+              request: ApolloRequest<D>,
+              chain: ApolloInterceptorChain,
+          ): Flow<ApolloResponse<D>> {
+            throw IllegalStateException("woops")
+          }
+        })
+        .build()
+        .use { apolloClient ->
+
+          runBlocking {
+            val exception = assertFailsWith<IllegalStateException> {
+              apolloClient.query(FooQuery())
+                  .execute()
+            }
+
+            assertEquals("woops", exception.message)
+          }
+        }
+  }
+
+  @Test
+  fun interceptorsMayReturnExceptionResponse() {
+    ApolloClient.Builder()
+        .serverUrl("unused")
+        .addInterceptor(object : ApolloInterceptor {
+          override fun <D : Operation.Data> intercept(
+              request: ApolloRequest<D>,
+              chain: ApolloInterceptorChain,
+          ): Flow<ApolloResponse<D>> {
+            return flow {
+              emit(
+                  ApolloResponse.Builder(request.operation, request.requestUuid)
+                      .exception(DefaultApolloException("oh no", IllegalStateException("woops")))
+                      .build()
+              )
+            }
+          }
+        })
+        .build()
+        .use { apolloClient ->
+          runBlocking {
+            apolloClient.query(FooQuery())
+                .execute()
+                .apply {
+                  assertIs<DefaultApolloException>(exception)
+                  assertIs<IllegalStateException>(exception!!.cause)
+                  assertEquals("woops", exception!!.cause!!.message)
+                }
+          }
+        }
+  }
+}