[server] support batch requests (ExpediaGroup#1019)

* [server] support batch requests

Add support for handling both individual GraphQL requests (current) as well as batch requests (new) that specify a list of `GraphQLRequest`s in their HTTP body. Single context is created for batch requests and each one of the requests has to provide valid response.

* fix example/ktor-server ktlint violations

Author: dariuszkuc

docs/server/graphql-request-parser.md

@@ -7,11 +7,29 @@ The `GraphQLRequestParser` interface is requrired to parse the library-specific
 
 ```kotlin
 interface GraphQLRequestParser<Request> {
-    suspend fun parseRequest(request: Request): GraphQLRequest?
+    suspend fun parseRequest(request: Request): GraphQLServerRequest<*>?
 }
 ```
 
-While not offically part of the spec, there is a standard format used by most GraphQL clients and servers for [serving GraphQL over HTTP](https://graphql.org/learn/serving-over-http/).
+While not officially part of the spec, there is a standard format used by most GraphQL clients and servers for [serving GraphQL over HTTP](https://graphql.org/learn/serving-over-http/).
+Following the above convention, GraphQL clients should generally use HTTP POST requests with the following body structure
+
+```json
+{
+  "query": "...",
+  "operationName": "...",
+  "variables": { "myVariable": "someValue" }
+}
+```
+
+where
+* `query` is a required field and contains operation (query, mutation or subscription) that specify their selection set to be executed
+* `operationName` is an optional operation name, only required if multiple operations are specified in `query` string
+* `variables` is an optional field that holds an arbitrary JSON objects that are referenced as input arguments from `query` string
+
+GraphQL Kotlin server supports both single and batch GraphQL requests. Batch requests are represented as a list of individual
+GraphQL requests. When processing batch requests, same context will be used for processing all requests and server will respond
+with a list of GraphQL responses.
 
 If the request is not a valid GraphQL format, the interface should return `null` and let the server specific code return a bad request status to the client.
 This is not the same as a GraphQL error or an exception thrown by the schema.

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

@@ -16,26 +16,36 @@
 
 package com.expediagroup.graphql.examples.server.ktor
 
+import com.expediagroup.graphql.server.execution.GraphQLBatchRequest
 import com.expediagroup.graphql.server.execution.GraphQLRequestParser
+import com.expediagroup.graphql.server.execution.GraphQLServerRequest
+import com.expediagroup.graphql.server.execution.GraphQLSingleRequest
 import com.expediagroup.graphql.types.GraphQLRequest
+import com.fasterxml.jackson.core.type.TypeReference
 import com.fasterxml.jackson.databind.ObjectMapper
-import com.fasterxml.jackson.module.kotlin.readValue
 import io.ktor.request.ApplicationRequest
 import io.ktor.request.receiveText
 import java.io.IOException
 
 /**
- * Custom logic for how Ktor parses the incoming [ApplicationRequest] into the [GraphQLRequest]
+ * Custom logic for how Ktor parses the incoming [ApplicationRequest] into the [GraphQLServerRequest]
  */
 class KtorGraphQLRequestParser(
     private val mapper: ObjectMapper
 ) : GraphQLRequestParser<ApplicationRequest> {
 
-    override suspend fun parseRequest(request: ApplicationRequest): GraphQLRequest {
-        return try {
-            mapper.readValue(request.call.receiveText())
-        } catch (e: IOException) {
-            throw IOException("Unable to parse GraphQL payload.")
+    private val graphQLBatchRequestTypeReference: TypeReference<List<GraphQLRequest>> = object : TypeReference<List<GraphQLRequest>>() {}
+
+    @Suppress("BlockingMethodInNonBlockingContext")
+    override suspend fun parseRequest(request: ApplicationRequest): GraphQLServerRequest<*> = try {
+        val rawRequest = request.call.receiveText()
+        val jsonNode = mapper.readTree(rawRequest)
+        if (jsonNode.isArray) {
+            GraphQLBatchRequest(mapper.convertValue(jsonNode, graphQLBatchRequestTypeReference))
+        } else {
+            GraphQLSingleRequest(mapper.treeToValue(jsonNode, GraphQLRequest::class.java))
         }
+    } catch (e: IOException) {
+        throw IOException("Unable to parse GraphQL payload.")
     }
 }

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

@@ -39,7 +39,7 @@ class KtorServer {
 
         if (result != null) {
             // write response as json
-            val json = mapper.writeValueAsString(result)
+            val json = mapper.writeValueAsString(result.response)
             applicationCall.response.call.respond(json)
         } else {
             applicationCall.response.call.respond(HttpStatusCode.BadRequest, "Invalid request")

servers/graphql-kotlin-server/src/main/kotlin/com/expediagroup/graphql/server/execution/GraphQLRequestParser.kt

@@ -16,13 +16,11 @@
 
 package com.expediagroup.graphql.server.execution
 
-import com.expediagroup.graphql.types.GraphQLRequest
-
 /**
- * A generic server interface that handles parsing the specific server implementation request to a [GraphQLRequest].
+ * A generic server interface that handles parsing the specific server implementation request to a [GraphQLServerRequest].
  * If the request is not valid return null.
  */
 interface GraphQLRequestParser<Request> {
 
-    suspend fun parseRequest(request: Request): GraphQLRequest?
+    suspend fun parseRequest(request: Request): GraphQLServerRequest<*>?
 }

servers/graphql-kotlin-server/src/main/kotlin/com/expediagroup/graphql/server/execution/GraphQLServer.kt

@@ -36,12 +36,21 @@ open class GraphQLServer<Request>(
      * In the case of errors or exceptions, return a response with [GraphQLResponse.errors] populated.
      * If you need custom logic inside this method you can override this class or choose not to use it.
      */
-    open suspend fun execute(request: Request): GraphQLResponse<*>? {
+    open suspend fun execute(request: Request): GraphQLServerResponse<*>? {
         val graphQLRequest = requestParser.parseRequest(request)
 
         return if (graphQLRequest != null) {
             val context = contextFactory.generateContext(request)
-            requestHandler.executeRequest(graphQLRequest, context)
+            when (graphQLRequest) {
+                is GraphQLSingleRequest -> GraphQLSingleResponse(
+                    requestHandler.executeRequest(graphQLRequest.request, context)
+                )
+                is GraphQLBatchRequest -> GraphQLBatchResponse(
+                    graphQLRequest.request.map {
+                        requestHandler.executeRequest(it, context)
+                    }
+                )
+            }
         } else {
             null
         }

servers/graphql-kotlin-server/src/main/kotlin/com/expediagroup/graphql/server/execution/GraphQLServerRequest.kt

@@ -0,0 +1,34 @@
+/*
+ * 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.server.execution
+
+import com.expediagroup.graphql.types.GraphQLRequest
+
+/**
+ * GraphQL server request abstraction that provides a convenient way to handle both single and batch requests.
+ */
+sealed class GraphQLServerRequest<T : Any>(val request: T)
+
+/**
+ * Wrapper that holds single GraphQLRequest to be processed within an HTTP request.
+ */
+class GraphQLSingleRequest(graphQLRequest: GraphQLRequest) : GraphQLServerRequest<GraphQLRequest>(graphQLRequest)
+
+/**
+ * Wrapper that holds list of GraphQLRequests to be processed together within a single HTTP request.
+ */
+class GraphQLBatchRequest(requests: List<GraphQLRequest>) : GraphQLServerRequest<List<GraphQLRequest>>(requests)

servers/graphql-kotlin-server/src/main/kotlin/com/expediagroup/graphql/server/execution/GraphQLServerResponse.kt

@@ -0,0 +1,34 @@
+/*
+ * 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.server.execution
+
+import com.expediagroup.graphql.types.GraphQLResponse
+
+/**
+ * GraphQL server response abstraction that provides a convenient way to handle both single and batch responses.
+ */
+sealed class GraphQLServerResponse<T : Any>(val response: T)
+
+/**
+ * Wrapper that holds single GraphQLResponse to an HTTP request.
+ */
+class GraphQLSingleResponse(graphQLResponse: GraphQLResponse<*>) : GraphQLServerResponse<GraphQLResponse<*>>(graphQLResponse)
+
+/**
+ * Wrapper that holds list of GraphQLResponses that were processed together within a single HTTP request.
+ */
+class GraphQLBatchResponse(responses: List<GraphQLResponse<*>>) : GraphQLServerResponse<List<GraphQLResponse<*>>>(responses)

servers/graphql-kotlin-server/src/test/kotlin/com/expediagroup/graphql/server/execution/GraphQLServerTest.kt

@@ -34,7 +34,7 @@ class GraphQLServerTest {
     @Test
     fun `the request handler and parser are called`() {
         val mockParser = mockk<GraphQLRequestParser<MockHttpRequest>> {
-            coEvery { parseRequest(any()) } returns mockk()
+            coEvery { parseRequest(any()) } returns GraphQLBatchRequest(requests = listOf(mockk()))
         }
         val mockContextFactory = mockk<GraphQLContextFactory<MockContext, MockHttpRequest>> {
             coEvery { generateContext(any()) } returns MockContext()
@@ -57,7 +57,7 @@ class GraphQLServerTest {
     @Test
     fun `null context is used and passed to the request handler`() {
         val mockParser = mockk<GraphQLRequestParser<MockHttpRequest>> {
-            coEvery { parseRequest(any()) } returns mockk()
+            coEvery { parseRequest(any()) } returns GraphQLSingleRequest(graphQLRequest = mockk())
         }
         val mockContextFactory = mockk<GraphQLContextFactory<MockContext, MockHttpRequest>> {
             coEvery { generateContext(any()) } returns null

servers/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/server/spring/GraphQLRoutesConfiguration.kt

@@ -48,7 +48,7 @@ class GraphQLRoutesConfiguration(
         (isEndpointRequest and isNotWebsocketRequest).invoke { serverRequest ->
             val graphQLResponse = graphQLServer.execute(serverRequest)
             if (graphQLResponse != null) {
-                ok().json().bodyValueAndAwait(graphQLResponse)
+                ok().json().bodyValueAndAwait(graphQLResponse.response)
             } else {
                 badRequest().buildAndAwait()
             }

servers/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/server/spring/execution/SpringGraphQLRequestParser.kt

@@ -16,11 +16,17 @@
 
 package com.expediagroup.graphql.server.spring.execution
 
+import com.expediagroup.graphql.server.execution.GraphQLBatchRequest
+import com.expediagroup.graphql.server.execution.GraphQLSingleRequest
 import com.expediagroup.graphql.server.execution.GraphQLRequestParser
+import com.expediagroup.graphql.server.execution.GraphQLServerRequest
 import com.expediagroup.graphql.types.GraphQLRequest
+import com.fasterxml.jackson.core.type.TypeReference
+import com.fasterxml.jackson.databind.JsonNode
 import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.databind.type.MapType
 import com.fasterxml.jackson.databind.type.TypeFactory
+import kotlinx.coroutines.reactive.awaitFirst
 import org.springframework.http.HttpMethod
 import org.springframework.http.MediaType
 import org.springframework.web.reactive.function.server.ServerRequest
@@ -36,34 +42,42 @@ open class SpringGraphQLRequestParser(
 ) : GraphQLRequestParser<ServerRequest> {
 
     private val mapTypeReference: MapType = TypeFactory.defaultInstance().constructMapType(HashMap::class.java, String::class.java, Any::class.java)
+    private val graphQLRequestListTypeReference: TypeReference<List<GraphQLRequest>> = object : TypeReference<List<GraphQLRequest>>() {}
 
-    override suspend fun parseRequest(request: ServerRequest): GraphQLRequest? = when {
+    override suspend fun parseRequest(request: ServerRequest): GraphQLServerRequest<*>? = when {
         request.queryParam(REQUEST_PARAM_QUERY).isPresent -> { getRequestFromGet(request) }
         request.method() == HttpMethod.POST -> { getRequestFromPost(request) }
         else -> null
     }
 
-    private fun getRequestFromGet(serverRequest: ServerRequest): GraphQLRequest {
+    private fun getRequestFromGet(serverRequest: ServerRequest): GraphQLServerRequest<*> {
         val query = serverRequest.queryParam(REQUEST_PARAM_QUERY).get()
         val operationName: String? = serverRequest.queryParam(REQUEST_PARAM_OPERATION_NAME).orElseGet { null }
         val variables: String? = serverRequest.queryParam(REQUEST_PARAM_VARIABLES).orElseGet { null }
         val graphQLVariables: Map<String, Any>? = variables?.let {
             objectMapper.readValue(it, mapTypeReference)
         }
 
-        return GraphQLRequest(query = query, operationName = operationName, variables = graphQLVariables)
+        return GraphQLSingleRequest(GraphQLRequest(query = query, operationName = operationName, variables = graphQLVariables))
     }
 
     /**
      * We have have to suppress the warning due to a jackson issue
      * https://github.com/FasterXML/jackson-module-kotlin/issues/221
      */
     @Suppress("BlockingMethodInNonBlockingContext")
-    private suspend fun getRequestFromPost(serverRequest: ServerRequest): GraphQLRequest? {
+    private suspend fun getRequestFromPost(serverRequest: ServerRequest): GraphQLServerRequest<*>? {
         val contentType = serverRequest.headers().contentType().orElse(MediaType.APPLICATION_JSON)
         return when {
-            contentType.includes(MediaType.APPLICATION_JSON) -> serverRequest.awaitBody()
-            contentType.includes(graphQLMediaType) -> GraphQLRequest(query = serverRequest.awaitBody())
+            contentType.includes(MediaType.APPLICATION_JSON) -> {
+                val jsonNode = serverRequest.bodyToMono(JsonNode::class.java).awaitFirst()
+                if (jsonNode.isArray) {
+                    GraphQLBatchRequest(objectMapper.convertValue(jsonNode, graphQLRequestListTypeReference))
+                } else {
+                    GraphQLSingleRequest(objectMapper.treeToValue(jsonNode, GraphQLRequest::class.java))
+                }
+            }
+            contentType.includes(graphQLMediaType) -> GraphQLSingleRequest(GraphQLRequest(query = serverRequest.awaitBody()))
             else -> null
         }
     }