feat: DataLoader Sync Execution Exhaustion Instrumentation (#1419)

* feat: sync execution exhaustion

* feat: make extension fun internal

* feat: specific import

* feat: just verify independent dataloader statistics

* feat: update README

Co-authored-by: samvazquez <[email protected]>

Author: samuelAndalon

README.md

@@ -13,6 +13,7 @@ Visit our [documentation site](https://expediagroup.github.io/graphql-kotlin) fo
 
 * [clients](/clients) - Lightweight GraphQL Kotlin HTTP clients based on Ktor HTTP client and Spring WebClient
 * [examples](/examples) - Example apps that use graphql-kotlin libraries to test and demonstrate usages
+* [executions](/executions) - Custom instrumentations for a GraphQL operation
 * [generator](/generator) - Code-First schema generator and extensions to build Apollo Federation schemas
 * [plugins](/plugins) - Gradle and Maven plugins
 * [servers](/servers) - Common and library specific modules for running a GraphQL server

executions/graphql-kotlin-dataloader-instrumentation/README.md

@@ -33,40 +33,43 @@ implementation("com.expediagroup:graphql-kotlin-dataloader-instrumentation:$late
 ## Use it
 
 When creating your `GraphQL` instance make sure to include either
-`DataLoaderLevelDispatchedInstrumentation` or `DataLoaderSyncExhaustionInstrumentation`.
+`DataLoaderLevelDispatchedInstrumentation` or `DataLoaderSyncExecutionExhaustedInstrumentation`.
 
 ```kotlin
 GraphQL
-    .instrumentation(DataLoaderSyncExhaustionInstrumentation())
+    .instrumentation(DataLoaderSyncExecutionExhaustedInstrumentation())
     // configure schema, type wiring, etc.
     .build()
 ```
 
-When ready to execute an operation or operations make sure to create a single instance of `KotlinDataLoaderRegistry`
-and an instance of either `ExecutionLevelInstrumentationState` or `SyncExhaustionInstrumentationState`
-and store them in the `graphQLContext`.
+When ready to execute an operation or operations create a `GraphQLContext` instance with the following entries:
+1. An instance of `KotlinDataLoaderRegistry`
+2. Either:
+    - An instance of `ExecutionLevelDispatchedState` if you choose `DataLoaderLevelDispatchedInstrumentation`.
+    - An instance of `SyncExecutionExhaustedState` if you choose `DataLoaderSyncExecutionExhaustedInstrumentation`.
+
 
 ```kotlin
 val queries = [
     """
-         query Query1 {
-           nasa {
-             astronaut(id: 1)
-           }
-         }
+      query Query1 {
+        nasa {
+          astronaut(id: 1)
+        }
+      }
     """,
     """
-         query Query1 {
-           nasa {
-             astronaut(id: 1)
-           }
-         }
+      query Query1 {
+        nasa {
+          astronaut(id: 2)
+        }
+      }
     """
 ]
 
 val graphQLContext = mapOf(
     KotlinDataLoaderRegistry::class to kotlinDataLoaderRegistry,
-    SyncExhaustionInstrumentationState::class to SyncExhaustionInstrumentationState(
+    SyncExecutionExhaustedState::class to SyncExecutionExhaustedState(
         queries.size,
         kotlinDataLoaderRegistry
     )
@@ -81,17 +84,17 @@ val result2 = graphQL.executeAsync(executionInput2)
 
 - `DataLoaderLevelDispatchedInstrumentation` will dispatch the `KotlinDataLoaderRegistry` instance when
   a certain level of all executionInputs was dispatched (all DataFetchers were invoked).
-- `DataLoaderSyncExhaustionInstrumentation` will dispatch the `KotlinDataLoaderRegistry` instance when
+- `DataLoaderSyncExecutionExhaustedInstrumentation` will dispatch the `KotlinDataLoaderRegistry` instance when
   the synchronous execution of an operation exhausted (synchronous execution will be exhausted when all data fetchers
-  of all paths executed up until a scalar leaf, or a [CompletableFuture]).
+  of all paths executed up until a scalar leaf, or a `CompletableFuture`).
 
 This way even if you are executing 2 separate operations you can still batch operations triggered from a DataFetcher.
 
 ### Usage in DataFetcher
 
 You can use the `DataFetchingEnvironment` which is passed to each
 `DataFetcher` and invoke the `getDataLoaderFromContext(dataLoaderName)` method which will access to the `KotlinDataLoaderRegistry`
-in the `GraphQLContext` and provide the `DataLaoder` that you specified as `dataLoaderName` argument.
+in the `GraphQLContext` and provide the `DataLoader` that you specified as `dataLoaderName` argument.
 
 ```kotlin
 class AstronautService {

executions/graphql-kotlin-dataloader-instrumentation/src/main/kotlin/com/expediagroup/graphql/dataloader/instrumentation/syncexhaustion/DataLoaderSyncExecutionExhaustedInstrumentation.kt

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2022 Expedia, Inc
+ *
+ * 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.
+ */
+
+package com.expediagroup.graphql.dataloader.instrumentation.syncexhaustion
+
+import com.expediagroup.graphql.dataloader.KotlinDataLoaderRegistry
+import com.expediagroup.graphql.dataloader.instrumentation.syncexhaustion.execution.AbstractSyncExecutionExhaustedInstrumentation
+import com.expediagroup.graphql.dataloader.instrumentation.syncexhaustion.execution.OnSyncExecutionExhaustedCallback
+import com.expediagroup.graphql.dataloader.instrumentation.syncexhaustion.execution.SyncExecutionExhaustedInstrumentationParameters
+import graphql.ExecutionInput
+import graphql.GraphQLContext
+import graphql.execution.instrumentation.Instrumentation
+import graphql.schema.DataFetcher
+import org.dataloader.DataLoader
+import java.util.concurrent.CompletableFuture
+
+/**
+ * Custom GraphQL [Instrumentation] that will dispatch all [DataLoader]s inside a [KotlinDataLoaderRegistry]
+ * when the synchronous execution of all [ExecutionInput] sharing a [GraphQLContext] was exhausted.
+ *
+ * A Synchronous Execution is considered Exhausted when all [DataFetcher]s of all paths were executed up until
+ * an scalar leaf or a [DataFetcher] that returns a [CompletableFuture]
+ */
+class DataLoaderSyncExecutionExhaustedInstrumentation : AbstractSyncExecutionExhaustedInstrumentation() {
+    override fun getOnSyncExecutionExhaustedCallback(
+        parameters: SyncExecutionExhaustedInstrumentationParameters
+    ): OnSyncExecutionExhaustedCallback = {
+        parameters
+            .executionContext
+            .graphQLContext.get<KotlinDataLoaderRegistry>(KotlinDataLoaderRegistry::class)
+            ?.dispatchAll()
+    }
+}

executions/graphql-kotlin-dataloader-instrumentation/src/main/kotlin/com/expediagroup/graphql/dataloader/instrumentation/syncexhaustion/execution/AbstractSyncExecutionExhaustedInstrumentation.kt

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2022 Expedia, Inc
+ *
+ * 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.
+ */
+
+package com.expediagroup.graphql.dataloader.instrumentation.syncexhaustion.execution
+
+import com.expediagroup.graphql.dataloader.instrumentation.NoOpExecutionStrategyInstrumentationContext
+import com.expediagroup.graphql.dataloader.instrumentation.syncexhaustion.state.SyncExecutionExhaustedState
+import graphql.ExecutionInput
+import graphql.ExecutionResult
+import graphql.GraphQLContext
+import graphql.execution.instrumentation.ExecutionStrategyInstrumentationContext
+import graphql.execution.instrumentation.Instrumentation
+import graphql.execution.instrumentation.InstrumentationContext
+import graphql.execution.instrumentation.SimpleInstrumentation
+import graphql.execution.instrumentation.SimpleInstrumentationContext
+import graphql.execution.instrumentation.parameters.InstrumentationExecuteOperationParameters
+import graphql.execution.instrumentation.parameters.InstrumentationExecutionStrategyParameters
+import graphql.execution.instrumentation.parameters.InstrumentationFieldFetchParameters
+
+/**
+ * typealias that represents the signature of a callback that will be executed when sync execution is exhausted
+ */
+internal typealias OnSyncExecutionExhaustedCallback = (List<ExecutionInput>) -> Unit
+
+/**
+ * Custom GraphQL [Instrumentation] that calculate the synchronous execution exhaustion
+ * of all GraphQL operations sharing the same [GraphQLContext]
+ */
+abstract class AbstractSyncExecutionExhaustedInstrumentation : SimpleInstrumentation() {
+    /**
+     * This is invoked each time instrumentation attempts to calculate exhaustion state, this can be called from either
+     * `beginFieldField.dispatch` or `beginFieldFetch.complete`.
+     *
+     * @param parameters contains information of which [ExecutionInput] caused the calculation
+     * @return [OnSyncExecutionExhaustedCallback] to invoke when the synchronous execution of all operations was exhausted
+     */
+    abstract fun getOnSyncExecutionExhaustedCallback(
+        parameters: SyncExecutionExhaustedInstrumentationParameters
+    ): OnSyncExecutionExhaustedCallback
+
+    override fun beginExecuteOperation(
+        parameters: InstrumentationExecuteOperationParameters
+    ): InstrumentationContext<ExecutionResult> =
+        parameters.executionContext
+            .graphQLContext.get<SyncExecutionExhaustedState>(SyncExecutionExhaustedState::class)
+            ?.beginExecuteOperation(parameters)
+            ?: SimpleInstrumentationContext.noOp()
+
+    override fun beginExecutionStrategy(
+        parameters: InstrumentationExecutionStrategyParameters
+    ): ExecutionStrategyInstrumentationContext =
+        parameters.executionContext
+            .graphQLContext.get<SyncExecutionExhaustedState>(SyncExecutionExhaustedState::class)
+            ?.beginExecutionStrategy(parameters)
+            ?: NoOpExecutionStrategyInstrumentationContext
+
+    override fun beginFieldFetch(
+        parameters: InstrumentationFieldFetchParameters
+    ): InstrumentationContext<Any> =
+        parameters.executionContext
+            .graphQLContext.get<SyncExecutionExhaustedState>(SyncExecutionExhaustedState::class)
+            ?.beginFieldFetch(
+                parameters,
+                this.getOnSyncExecutionExhaustedCallback(
+                    SyncExecutionExhaustedInstrumentationParameters(parameters.executionContext)
+                )
+            )
+            ?: SimpleInstrumentationContext.noOp()
+}

executions/graphql-kotlin-dataloader-instrumentation/src/main/kotlin/com/expediagroup/graphql/dataloader/instrumentation/syncexhaustion/execution/SyncExecutionExhaustedInstrumentationParameters.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2022 Expedia, Inc
+ *
+ * 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.
+ */
+
+package com.expediagroup.graphql.dataloader.instrumentation.syncexhaustion.execution
+
+import com.expediagroup.graphql.dataloader.instrumentation.syncexhaustion.DataLoaderSyncExecutionExhaustedInstrumentation
+import graphql.execution.ExecutionContext
+
+/**
+ * Hold information that will be provided to an instance of [DataLoaderSyncExecutionExhaustedInstrumentation]
+ */
+data class SyncExecutionExhaustedInstrumentationParameters(
+    val executionContext: ExecutionContext
+)