[client] create new GraphQL client serialization abstraction (#1066)

* [client] create new GraphQL client serialization abstraction

This is a first PR in a series that will introduce support for both `Jackson` and `kotlinx.serialization` data formats for GraphQL Kotlin clients. This PR provides general refactoring of GraphQL client request and response types and introduces new GraphQL client serialization abstraction. We need this additional abstraction as we need to provide some default configurations for both `Jackson` and `kotlinx.serialization` serializers and we cannot rely on the provided defaults. By serializing requests to raw String (and deserializing responses from String) allows us to simplify the configuration logic that would be required to support both formats across Ktor and Spring based clients. If serializer is not explicitly specified, then default one will be automatically loaded from a classpath using `Java ServiceLoader` mechanism.

NOTE: clients still default to use Jackson which is currently only supported format from the generator (support for generation of `kotlinx.serialization` data models will be added in subsequent PRs)

Changes:

* Update GraphQL client request and response types to support both `Jackson` and `kotlinx.serialization` formats.
* Create new `GraphQLClientSerializer` abstraction that is used by the GraphQL clients to serialize requests and deserialize responses
* Create `Jackson` and `kotlinx.serialization` compatible GraphQL serializers
* Drop the generation of unnecessary `executeXQuery` extension functions

Related:

* #1048 - this is an attempt to split it up to more manageable pieces
* #929 - adds initial support for `kotlinx.serialization`

* add missing copyright headers to test files

Author: dariuszkuc

clients/graphql-kotlin-client-jackson/README.md

@@ -0,0 +1,10 @@
+# GraphQL Kotlin Client Jackson
+[![Maven Central](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-client-jackson.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.expediagroup%22%20AND%20a:%22graphql-kotlin-client-jackson%22)
+[![Javadocs](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-client-jackson.svg?label=javadoc&colorB=brightgreen)](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-client-jackson)
+
+`graphql-kotlin-client-jackson` is a [Jackson](https://github.com/FasterXML/jackson) based GraphQL client serializer. GraphQL
+client serializers provide a serializer/deserializer abstraction to the GraphQL clients and handle actual request/response
+serialization logic allowing clients to POST and receive raw Strings.
+
+## Documentation
+For the latest documentation, see our GitHub pages docs site: [https://expediagroup.github.io/graphql-kotlin](https://expediagroup.github.io/graphql-kotlin)

clients/graphql-kotlin-client-jackson/build.gradle.kts

@@ -0,0 +1,22 @@
+description = "GraphQL client serializer based on Jackson"
+
+val jacksonVersion: String by project
+
+dependencies {
+    api(project(path = ":graphql-kotlin-client"))
+    api("com.fasterxml.jackson.module:jackson-module-kotlin:$jacksonVersion")
+}
+
+tasks {
+    jacocoTestCoverageVerification {
+        violationRules {
+            rule {
+                limit {
+                    counter = "INSTRUCTION"
+                    value = "COVEREDRATIO"
+                    minimum = "0.85".toBigDecimal()
+                }
+            }
+        }
+    }
+}

clients/graphql-kotlin-client-jackson/src/main/kotlin/com/expediagroup/graphql/client/jackson/GraphQLClientJacksonSerializer.kt

@@ -0,0 +1,61 @@
+/*
+ * 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.client.jackson
+
+import com.expediagroup.graphql.client.jackson.types.JacksonGraphQLResponse
+import com.expediagroup.graphql.client.serializer.GraphQLClientSerializer
+import com.fasterxml.jackson.databind.DeserializationFeature
+import com.fasterxml.jackson.databind.JavaType
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
+import java.util.concurrent.ConcurrentHashMap
+import kotlin.reflect.KClass
+
+/**
+ * Jackson based GraphQL request/response serializer.
+ */
+class GraphQLClientJacksonSerializer(private val mapper: ObjectMapper = jacksonObjectMapper()) : GraphQLClientSerializer {
+    private val typeCache = ConcurrentHashMap<KClass<*>, JavaType>()
+
+    init {
+        mapper.enable(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE)
+    }
+
+    override fun serialize(request: Any): String = mapper.writeValueAsString(request)
+
+    override fun <T : Any> deserialize(rawResponse: String, responseType: KClass<T>): JacksonGraphQLResponse<T> =
+        mapper.readValue(rawResponse, parameterizedType(responseType))
+
+    override fun deserialize(rawResponses: String, responseTypes: List<KClass<*>>): List<JacksonGraphQLResponse<*>> {
+        val jsonResponse = mapper.readTree(rawResponses)
+
+        return if (jsonResponse.isArray) {
+            jsonResponse.withIndex().map { (index, element) ->
+                val singleResponse: JacksonGraphQLResponse<*> = mapper.convertValue(element, parameterizedType(responseTypes[index]))
+                singleResponse
+            }
+        } else {
+            // should never be the case
+            listOf(mapper.convertValue(jsonResponse, parameterizedType(responseTypes.first())))
+        }
+    }
+
+    private fun <T : Any> parameterizedType(resultType: KClass<T>): JavaType =
+        typeCache.computeIfAbsent(resultType) {
+            mapper.typeFactory.constructParametricType(JacksonGraphQLResponse::class.java, resultType.java)
+        }
+}

clients/graphql-kotlin-client-jackson/src/main/kotlin/com/expediagroup/graphql/client/jackson/types/JacksonGraphQLError.kt

@@ -0,0 +1,30 @@
+/*
+ * 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.client.jackson.types
+
+import com.expediagroup.graphql.client.types.GraphQLError
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties
+import com.fasterxml.jackson.annotation.JsonInclude
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+data class JacksonGraphQLError(
+    override val message: String,
+    override val locations: List<JacksonSourceLocation>? = null,
+    override val path: List<Any>? = null,
+    override val extensions: Map<String, Any?>? = null
+) : GraphQLError

clients/graphql-kotlin-client-jackson/src/main/kotlin/com/expediagroup/graphql/client/jackson/types/JacksonGraphQLResponse.kt

@@ -0,0 +1,29 @@
+/*
+ * 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.client.jackson.types
+
+import com.expediagroup.graphql.client.types.GraphQLClientResponse
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties
+import com.fasterxml.jackson.annotation.JsonInclude
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+data class JacksonGraphQLResponse<T>(
+    override val data: T? = null,
+    override val errors: List<JacksonGraphQLError>? = null,
+    override val extensions: Map<String, Any?>? = null
+) : GraphQLClientResponse<T>

clients/graphql-kotlin-client-jackson/src/main/kotlin/com/expediagroup/graphql/client/jackson/types/JacksonSourceLocation.kt

@@ -0,0 +1,28 @@
+/*
+ * 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.client.jackson.types
+
+import com.expediagroup.graphql.client.types.SourceLocation
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties
+import com.fasterxml.jackson.annotation.JsonInclude
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+data class JacksonSourceLocation(
+    override val line: Int,
+    override val column: Int
+) : SourceLocation

clients/graphql-kotlin-client-jackson/src/main/resources/META-INF/services/com.expediagroup.graphql.client.serializer.GraphQLClientSerializer

@@ -0,0 +1 @@
+com.expediagroup.graphql.client.jackson.GraphQLClientJacksonSerializer

clients/graphql-kotlin-client-jackson/src/test/kotlin/com/expediagroup/graphql/client/jackson/GraphQLClientJacksonSerializerTest.kt

@@ -0,0 +1,169 @@
+/*
+ * 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.client.jackson
+
+import com.expediagroup.graphql.client.jackson.data.EnumQuery
+import com.expediagroup.graphql.client.jackson.data.FirstQuery
+import com.expediagroup.graphql.client.jackson.data.OtherQuery
+import com.expediagroup.graphql.client.jackson.data.PolymorphicQuery
+import com.expediagroup.graphql.client.jackson.data.ScalarQuery
+import com.expediagroup.graphql.client.jackson.data.polymorphicquery.SecondInterfaceImplementation
+import com.expediagroup.graphql.client.jackson.types.JacksonGraphQLError
+import com.expediagroup.graphql.client.jackson.types.JacksonGraphQLResponse
+import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
+import org.junit.jupiter.api.Test
+import java.util.UUID
+import kotlin.test.assertEquals
+
+class GraphQLClientJacksonSerializerTest {
+
+    @Test
+    fun `verify we can serialize GraphQLClientRequest`() {
+        val testQuery = FirstQuery(FirstQuery.Variables(input = 1.0f))
+        val expected =
+            """{
+            |  "query": "FIRST_QUERY",
+            |  "operationName": "FirstQuery",
+            |  "variables": { "input": 1.0 }
+            |}
+        """.trimMargin()
+
+        val mapper = jacksonObjectMapper()
+        val serializer = GraphQLClientJacksonSerializer(mapper)
+        val result = serializer.serialize(testQuery)
+        assertEquals(mapper.readTree(expected), mapper.readTree(result))
+    }
+
+    @Test
+    fun `verify we can serialize batch GraphQLClientRequest`() {
+        val queries = listOf(FirstQuery(FirstQuery.Variables(input = 1.0f)), OtherQuery())
+        val expected =
+            """[{
+            |  "query": "FIRST_QUERY",
+            |  "operationName": "FirstQuery",
+            |  "variables": { "input": 1.0 }
+            |},{
+            |  "query": "OTHER_QUERY",
+            |  "operationName": "OtherQuery",
+            |  "variables": null
+            |}]
+        """.trimMargin()
+
+        val mapper = jacksonObjectMapper()
+        val serializer = GraphQLClientJacksonSerializer(mapper)
+        val result = serializer.serialize(queries)
+        assertEquals(mapper.readTree(expected), mapper.readTree(result))
+    }
+
+    @Test
+    fun `verify we can deserialize JacksonGraphQLResponse`() {
+        val testQuery = FirstQuery(variables = FirstQuery.Variables())
+        val expected = JacksonGraphQLResponse(
+            data = FirstQuery.Result("hello world"),
+            errors = listOf(JacksonGraphQLError(message = "test error message")),
+            extensions = mapOf("extVal" to 123, "extList" to listOf("ext1", "ext2"), "extMap" to mapOf("1" to 1, "2" to 2))
+        )
+        val rawResponse =
+            """{
+            |  "data": { "stringResult" : "hello world" },
+            |  "errors": [{ "message" : "test error message" }],
+            |  "extensions" : { "extVal" : 123, "extList" : ["ext1", "ext2"], "extMap" : { "1" : 1, "2" : 2} }
+            |}
+        """.trimMargin()
+
+        val serializer = GraphQLClientJacksonSerializer()
+        val result = serializer.deserialize(rawResponse, testQuery.responseType())
+        assertEquals(expected, result)
+    }
+
+    @Test
+    fun `verify we can deserialize batch JacksonGraphQLResponse`() {
+        val testQuery = FirstQuery(variables = FirstQuery.Variables())
+        val otherQuery = OtherQuery()
+        val expected = listOf(
+            JacksonGraphQLResponse(
+                data = FirstQuery.Result("hello world"),
+                errors = listOf(JacksonGraphQLError(message = "test error message")),
+                extensions = mapOf("extVal" to 123, "extList" to listOf("ext1", "ext2"), "extMap" to mapOf("1" to 1, "2" to 2))
+            ),
+            JacksonGraphQLResponse(
+                data = OtherQuery.Result(stringResult = "goodbye world", integerResult = 42)
+            )
+        )
+        val rawResponses =
+            """[{
+            |  "data": { "stringResult" : "hello world" },
+            |  "errors": [{ "message" : "test error message" }],
+            |  "extensions" : { "extVal" : 123, "extList" : ["ext1", "ext2"], "extMap" : { "1" : 1, "2" : 2} }
+            |}, {
+            |  "data": { "stringResult" : "goodbye world", "integerResult" : 42 }
+            |}]
+        """.trimMargin()
+
+        val serializer = GraphQLClientJacksonSerializer()
+        val result = serializer.deserialize(rawResponses, listOf(testQuery.responseType(), otherQuery.responseType()))
+        assertEquals(expected, result)
+    }
+
+    @Test
+    fun `verify we can deserialize polymorphic response`() {
+        val polymorphicResponse =
+            """{
+            |  "data": {
+            |    "polymorphicResult": {
+            |      "__typename": "SecondInterfaceImplementation",
+            |      "id": 123,
+            |      "floatValue": 1.2
+            |    }
+            |  }
+            |}
+        """.trimMargin()
+        val serializer = GraphQLClientJacksonSerializer()
+        val result = serializer.deserialize(polymorphicResponse, PolymorphicQuery().responseType())
+        assertEquals(SecondInterfaceImplementation(123, 1.2f), result.data?.polymorphicResult)
+    }
+
+    @Test
+    fun `verify we can deserialize custom scalars`() {
+        val expectedUUID = UUID.randomUUID()
+        val scalarResponse =
+            """{
+            |  "data": {
+            |    "scalarAlias": "1234",
+            |    "customScalar": "$expectedUUID"
+            |  }
+            |}
+        """.trimMargin()
+        val serializer = GraphQLClientJacksonSerializer()
+        val result = serializer.deserialize(scalarResponse, ScalarQuery().responseType())
+        assertEquals("1234", result.data?.scalarAlias)
+        assertEquals(expectedUUID, result.data?.customScalar?.value)
+    }
+
+    @Test
+    fun `verify we can deserialize unknown enums`() {
+        val unknownResponse =
+            """{
+            |  "data": { "enumResult": "INVALID" }
+            |}
+        """.trimMargin()
+
+        val serializer = GraphQLClientJacksonSerializer()
+        val result = serializer.deserialize(unknownResponse, EnumQuery().responseType())
+        assertEquals(EnumQuery.TestEnum.__UNKNOWN, result.data?.enumResult)
+    }
+}

clients/graphql-kotlin-client-jackson/src/test/kotlin/com/expediagroup/graphql/client/jackson/data/EnumQuery.kt

@@ -0,0 +1,40 @@
+/*
+ * 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.client.jackson.data
+
+import com.expediagroup.graphql.client.types.GraphQLClientRequest
+import com.fasterxml.jackson.annotation.JsonEnumDefaultValue
+import kotlin.reflect.KClass
+
+class EnumQuery : GraphQLClientRequest<EnumQuery.Result> {
+    override val query: String = "ENUM_QUERY"
+
+    override val operationName: String = "EnumQuery"
+
+    override fun responseType(): KClass<Result> = Result::class
+
+    enum class TestEnum {
+        ONE,
+        TWO,
+        @JsonEnumDefaultValue
+        __UNKNOWN
+    }
+
+    data class Result(
+        val enumResult: TestEnum = TestEnum.__UNKNOWN
+    )
+}