Generate DataLoaders on every request (#1040)

With the introduction of the new KotlinDataLoader interface we made the way to get the data loaders a property. However taking the advice from graphql-java we should generate each DataLoader every request. The factory generates the registry for every request currently but the data loaders themselves would still be static.

This also updates the docs and examples around data loaders from the last PR

Author: smyrick

docs/server/data-loader-registry-factory.md

@@ -0,0 +1,86 @@
+---
+id: data-loaders
+title: Data Loaders
+---
+
+Data Loaders are a popular caching pattern from the [JavaScript GraphQL implementation](https://github.com/graphql/dataloader).
+`graphql-java` provides [support for this pattern](https://www.graphql-java.com/documentation/v16/batching/) using the `DataLoader` and `DataLoaderRegistry`.
+
+Since `graphql-kotlin` allows you to abstract the schema generation and data fetching code, you may not even need data loaders if instead you have some persistant cache on your server.
+
+```kotlin
+class User(val id: ID) {
+
+    // The friendService and userService, which have nothing to do with GraphQL,
+    // should be concerned with caching and batch calls instead of your schema classes
+    fun getFriends(): List<User> {
+        val friends: List<ID> = friendService.getFriends(id)
+        return userService.getUsers(friends)
+    }
+
+}
+```
+
+If you still want to use data loaders though, they are supported through the common interfaces.
+
+## `KotlinDataLoader`
+
+The [GraphQLRequestHandler](./graphql-request-handler.md) accepts an optional `DataLoaderRegistryFactory` that will be used on every request.
+The `DataLoaderRegistryFactory` generates a new `DataLoaderRegistry` on every request. The registry is a map of a unique data loader names to a `DataLoader` object that handles the cache for an output type in your graph.
+A `DataLoader` caches the types by some unique value, usually by the type id, and can handle different types of batch requests.
+
+To help in the registration of these various `DataLoaders`, we have created a basic interface `KotlinDataLoader`:
+
+```kotlin
+interface KotlinDataLoader<K, V> {
+    val dataLoaderName: String
+    fun getDataLoader(): DataLoader<K, V>
+}
+```
+
+This allows for library users to still have full control over the creation of the `DataLoader` and its various configuraiton options,
+but then allows common server code to handle the registration, generation on request, and execution.
+
+```kotlin
+class UserDataLoader : KotlinDataLoader<ID, User> {
+    override val dataLoaderName = "UserDataLoader"
+    override fun getDataLoader() = DataLoader<ID, User>({ ids ->
+        CompletableFuture.supplyAsync {
+            ids.map { id -> userService.getUser(id) }
+        }
+    }, DataLoaderOptions.newOptions().setCachingEnabled(false))
+}
+
+class FriendsDataLoader : KotlinDataLoader<ID, List<User>> {
+    override val dataLoaderName = "FriendsDataLoader"
+    override fun getDataLoader() = DataLoader<ID, List<User>> { ids ->
+        CompletableFuture.supplyAsync {
+            ids.map { id ->
+                val friends: List<ID> = friendService.getFriends(id)
+                userService.getUsers(friends)
+            }
+        }
+    }
+}
+```
+
+## `getValueFromDataLoader`
+
+`graphql-kotlin-server` includes a helpful extension function on the `DataFetchingEnvironment` so that you can easily retrieve values from the data loaders in your schema code.
+
+
+```kotlin
+class User(val id: ID) {
+
+    @GraphQLDescription("Get the users friends using data loader")
+    fun getFriends(dataFetchingEnvironment: DataFetchingEnvironment): CompletableFuture<List<User>> {
+        return dataFetchingEnvironment.getValueFromDataLoader("FriendsDataLoader", id)
+    }
+}
+```
+
+
+
+> NOTE: Because the execution of data loaders is handled by `graphql-java`, which runs using `CompletionStage`, currently we can not support `suspend` functions when envoking data loaders.
+> Instead, return the `CompletableFuture` directly from the `DataLoader` response in your schema functions.
+> See issue [#986](https://github.com/ExpediaGroup/graphql-kotlin/issues/986).

docs/server/data-loaders.md

@@ -4,6 +4,6 @@ title: GraphQLRequestHandler
 ---
 
 The `GraphQLRequestHandler` is an open and extendable class that contains the basic logic to get a `GraphQLResponse` from `graphql-kotlin-types`.
-It accepts a `GraphQLRequest`, an optional [GraphQLContext](./graphql-context-factory.md) and sends that to the GraphQL schema along with the [DataLoaderRegistryFactory](./data-loader-registry-factory.md).
+It accepts a `GraphQLRequest`, an optional [GraphQLContext](./graphql-context-factory.md) and sends that to the GraphQL schema along with the [DataLoaderRegistry](data-loaders.md).
 
 There shouldn't be much need to change this class but if you wanted to add custom logic or logging it is possible to override it or just create your own.

docs/server/graphql-request-handler.md

@@ -3,14 +3,15 @@ id: graphql-server
 title: GraphQLServer
 ---
 
-`graphql-kotlin-server` provides a common code and basic interfaces to setup a GraphQL server in a specific server library.
+`graphql-kotlin-server` provides common code and basic interfaces to setup a GraphQL server in any framework.
 
 The official reference implementations are:
 
 * [graphql-kotlin-spring-server](./spring-server/spring-overview.md)
 
-We reccomend using one of the implementations if you can as the common code has very little logic.
-It is more of a scaffolding on how to write your server code.
+We reccomend using one of the implementations as the common code has very little logic but you can still use the common
+package to create implementation for other libraries (Ktor, Spark, etc).
+
 There are demos of how to use these server libraries in the `/examples` folder of the repo.
 
 ## `GraphQLServer`
@@ -23,7 +24,7 @@ This class is open for extensions and requires that you specify the type of the
 
 In its simplest form, a GraphQL server has the following responsibilties:
 
-* Parse the request info from the HTTP request
+* Parse the GraphQL request info from the HTTP request
 * Create a `GraphQLContext` object from the HTTP request to be used during execution
 * Send the request and the context to the GraphQL schema to execute and get a response (may contain `data` or `errors`)
 * Send the reponse back to the client over HTTP

docs/server/graphql-server.md

@@ -10,8 +10,9 @@ Many of the beans are conditionally created and the default behavior can be cust
 | Bean                             | Description |
 |:---------------------------------|:------------|
 | DataFetcherExceptionHandler      | GraphQL exception handler used from the various execution strategies, defaults to [KotlinDataFetcherExceptionHandler](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/exception/KotlinDataFetcherExceptionHandler.kt). |
-| DataLoaderRegistryFactory        | Factory used to create DataLoaderRegistry instance per query execution. See [graphql-java documentation](https://www.graphql-java.com/documentation/v14/batching/) for more details. |
 | KotlinDataFetcherFactoryProvider | Factory used during schema construction to obtain `DataFetcherFactory` that should be used for target function (using Spring aware `SpringDataFetcher`) and property resolution. |
+| KotlinDataLoader (optional)      | Any number of beans created that implement `KotlinDataLoader`. See [Data Loaders](../data-loaders.md) for more details. |
+| DataLoaderRegistryFactory        | A factory class that creates a `DataLoaderRegistry` of all the `KotlinDataLoaders`. Defaults to empty registry. |
 
 
 ## Non-Federated Schema

docs/server/spring-server/spring-beans.md

@@ -54,7 +54,7 @@ graphql:
 ```
 
 ## Writing Schema Code
-In order to expose your queries, mutations and/or subscriptions in the GraphQL schema you simply need to implement
+In order to expose your queries, mutations, and/or subscriptions in the GraphQL schema, implement
 corresponding marker interface and they will be automatically picked up by `graphql-kotlin-spring-server`
 auto-configuration library.
 
@@ -77,7 +77,7 @@ class MyAwesomeSubscription : Subscription {
 data class Widget(val id: Int, val value: String)
 ```
 
-will result in a Spring Boot reactive GraphQL web application with following schema.
+The above code will result in a GraphQL server with following schema:
 
 ```graphql
 schema {

docs/server/spring-server/spring-overview.md

@@ -16,12 +16,9 @@
 
 package com.expediagroup.graphql.examples.server.ktor
 
-import com.expediagroup.graphql.examples.server.ktor.schema.models.BATCH_BOOK_LOADER_NAME
-import com.expediagroup.graphql.examples.server.ktor.schema.models.COURSE_LOADER_NAME
-import com.expediagroup.graphql.examples.server.ktor.schema.models.UNIVERSITY_LOADER_NAME
-import com.expediagroup.graphql.examples.server.ktor.schema.models.batchBookLoader
-import com.expediagroup.graphql.examples.server.ktor.schema.models.batchCourseLoader
-import com.expediagroup.graphql.examples.server.ktor.schema.models.batchUniversityLoader
+import com.expediagroup.graphql.examples.server.ktor.schema.dataloaders.BookDataLoader
+import com.expediagroup.graphql.examples.server.ktor.schema.dataloaders.CourseDataLoader
+import com.expediagroup.graphql.examples.server.ktor.schema.dataloaders.UniversityDataLoader
 import com.expediagroup.graphql.server.execution.DataLoaderRegistryFactory
 import org.dataloader.DataLoaderRegistry
 
@@ -32,9 +29,9 @@ class KtorDataLoaderRegistryFactory : DataLoaderRegistryFactory {
 
     override fun generate(): DataLoaderRegistry {
         val registry = DataLoaderRegistry()
-        registry.register(UNIVERSITY_LOADER_NAME, batchUniversityLoader)
-        registry.register(COURSE_LOADER_NAME, batchCourseLoader)
-        registry.register(BATCH_BOOK_LOADER_NAME, batchBookLoader)
+        registry.register(UniversityDataLoader.dataLoaderName, UniversityDataLoader.getDataLoader())
+        registry.register(CourseDataLoader.dataLoaderName, CourseDataLoader.getDataLoader())
+        registry.register(BookDataLoader.dataLoaderName, BookDataLoader.getDataLoader())
         return registry
     }
 }

examples/server/ktor-server/src/main/kotlin/com/expediagroup/graphql/examples/server/ktor/KtorDataLoaderRegistryFactory.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2021 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.examples.server.ktor.schema.dataloaders
+
+import com.expediagroup.graphql.examples.server.ktor.schema.models.Book
+import com.expediagroup.graphql.server.execution.KotlinDataLoader
+import kotlinx.coroutines.runBlocking
+import org.dataloader.DataLoader
+import java.util.concurrent.CompletableFuture
+
+val BookDataLoader = object : KotlinDataLoader<List<Long>, List<Book>> {
+    override val dataLoaderName = "BATCH_BOOK_LOADER"
+    override fun getDataLoader() = DataLoader<List<Long>, List<Book>> { ids ->
+        CompletableFuture.supplyAsync {
+            val allBooks = runBlocking { Book.search(ids.flatten()).toMutableList() }
+            // produce lists of results from returned books
+            ids.fold(mutableListOf()) { acc: MutableList<List<Book>>, idSet ->
+                val matchingBooks = allBooks.filter { idSet.contains(it.id) }
+                acc.add(matchingBooks)
+                acc
+            }
+        }
+    }
+}

examples/server/ktor-server/src/main/kotlin/com/expediagroup/graphql/examples/server/ktor/schema/dataloaders/BookDataLoader.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2021 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.examples.server.ktor.schema.dataloaders
+
+import com.expediagroup.graphql.examples.server.ktor.schema.models.Course
+import com.expediagroup.graphql.server.execution.KotlinDataLoader
+import kotlinx.coroutines.runBlocking
+import org.dataloader.DataLoader
+import java.util.concurrent.CompletableFuture
+
+val CourseDataLoader = object : KotlinDataLoader<Long, Course?> {
+    override val dataLoaderName = "COURSE_LOADER"
+    override fun getDataLoader() = DataLoader<Long, Course?> { ids ->
+        CompletableFuture.supplyAsync {
+            runBlocking { Course.search(ids).toMutableList() }
+        }
+    }
+}

examples/server/ktor-server/src/main/kotlin/com/expediagroup/graphql/examples/server/ktor/schema/dataloaders/CourseDataLoader.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2021 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.examples.server.ktor.schema.dataloaders
+
+import com.expediagroup.graphql.examples.server.ktor.schema.models.University
+import com.expediagroup.graphql.server.execution.KotlinDataLoader
+import kotlinx.coroutines.runBlocking
+import org.dataloader.DataLoader
+import java.util.concurrent.CompletableFuture
+
+val UniversityDataLoader = object : KotlinDataLoader<Long, University?> {
+    override val dataLoaderName = "UNIVERSITY_LOADER"
+    override fun getDataLoader() = DataLoader<Long, University?> { ids ->
+        CompletableFuture.supplyAsync {
+            runBlocking { University.search(ids).toMutableList() }
+        }
+    }
+}