[client] change GQL client to interface and add webclient implementation (#837)

Changed `graphql-kotlin-client` to a generic interface to allow custom implementations. Existing `GraphQLClient` is now a `GraphQLKtorClient`, a reference implementation for Ktor HTTP client based implementation of generic `GraphQLClient` interface. This change also introduced new Spring WebClient based reference implementation. When generating client code we default to target generic interface. In order to generate client code that allows per request customizations of Ktor/Spring WebClient plugins have to be explicitly configured to generate type specific client code.

Updated/new modules:
* clients/graphql-kotlin-client - new generic interface
* clients/graphql-kotlin-ktor-client - Ktor HTTP Client based reference implementation of `GraphQLClient`
* clients/graphql-kotlin-spring-client - Spring WebClient based reference implementation of `GraphQLClient`

Author: dariuszkuc

README.md

@@ -10,8 +10,8 @@ Visit our [documentation site](https://expediagroup.github.io/graphql-kotlin) fo
 
 ## 📦 Modules
 
+* [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
-* [graphql-kotlin-client](/graphql-kotlin-client) - Lightweight GraphQL Kotlin HTTP client
 * [graphql-kotlin-federation](/graphql-kotlin-federation) - Schema generator extension to build Apollo Federation GraphQL schemas
 * [graphql-kotlin-schema-generator](/graphql-kotlin-schema-generator) - Code only GraphQL schema generation for Kotlin
 * [graphql-kotlin-spring-server](/graphql-kotlin-spring-server) - Spring Boot auto-configuration library to create a GraphQL server

clients/graphql-kotlin-client/README.md

@@ -0,0 +1,28 @@
+# GraphQL Kotlin Client
+[![Maven Central](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-client.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.expediagroup%22%20AND%20a:%22graphql-kotlin-client%22)
+[![Javadocs](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-client.svg?label=javadoc&colorB=brightgreen)](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-client)
+
+This module defines an interface for a lightweight, typesafe GraphQL HTTP clients. See [graphql-kotlin-ktor-client](../graphql-kotlin-ktor-client)
+and [graphql-kotlin-spring-client](../graphql-kotlin-spring-client) for reference implementations.
+
+NOTE: GraphQL clients can be invoked directly by manually creating your corresponding data model but since at its core it
+ends up with simple POST request this mode of operation is not that useful. Instead, GraphQL Kotlin clients should be used
+together with one of the GraphQL Kotlin build plugins to auto-generate type safe data models based on the specified queries.
+
+## Features
+
+* Supports query and mutation operations
+* Automatic generation of type-safe Kotlin models
+* Custom scalar support - defaults to String but can be configured to deserialize to specific types
+* Supports default enum values to gracefully handle new/unknown server values
+* Native support for coroutines
+* Easily configurable Ktor and Spring WebClient based HTTP Clients
+* Documentation generated from the underlying GraphQL schema
+
+## Documentation
+
+Additional information can be found in our [documentation](https://expediagroup.github.io/graphql-kotlin/docs/client/client-overview)
+and the [Javadocs](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-client) of all published versions.
+
+If you have a question about something you can not find in our documentation or Javadocs, feel free to
+[create an issue](https://github.com/ExpediaGroup/graphql-kotlin/issues) and tag it with the question label.

graphql-kotlin-client/build.gradle.kts …s/graphql-kotlin-client/build.gradle.ktsgraphql-kotlin-client/build.gradle.kts renamed to clients/graphql-kotlin-client/build.gradle.kts graphql-kotlin-client/build.gradle.kts renamed to clients/graphql-kotlin-client/build.gradle.kts

@@ -1,12 +1,8 @@
 description = "A lightweight typesafe GraphQL HTTP Client"
 
-val ktorVersion: String by project
 val kotlinCoroutinesVersion: String by project
 
 dependencies {
     api(project(path = ":graphql-kotlin-types"))
     api("org.jetbrains.kotlinx:kotlinx-coroutines-core:$kotlinCoroutinesVersion")
-    api("io.ktor:ktor-client-cio:$ktorVersion")
-    api("io.ktor:ktor-client-json:$ktorVersion")
-    api("io.ktor:ktor-client-jackson:$ktorVersion")
 }

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

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2020 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
+
+import com.expediagroup.graphql.types.GraphQLResponse
+
+/**
+ * A lightweight typesafe GraphQL HTTP client.
+ */
+interface GraphQLClient {
+
+    /**
+     * Executes specified GraphQL query or mutation.
+     *
+     * NOTE: explicit result type Class parameter is required due to the type erasure at runtime, i.e. since generic type is erased at runtime our
+     * default serialization would attempt to serialize results back to Any object. As a workaround we get raw results as String which we then
+     * manually deserialize using passed in result type Class information.
+     */
+    suspend fun <T> execute(query: String, operationName: String?, variables: Any?, resultType: Class<T>): GraphQLResponse<T>
+}
+
+suspend inline fun <reified T> GraphQLClient.execute(query: String, operationName: String? = null, variables: Any? = null): GraphQLResponse<T> =
+    this.execute(query, operationName, variables, T::class.java)

…phql/client/converter/ScalarConverter.kt …phql/client/converter/ScalarConverter.ktgraphql-kotlin-client/src/main/kotlin/com/expediagroup/graphql/client/converter/ScalarConverter.kt renamed to clients/graphql-kotlin-client/src/main/kotlin/com/expediagroup/graphql/client/converter/ScalarConverter.kt graphql-kotlin-client/src/main/kotlin/com/expediagroup/graphql/client/converter/ScalarConverter.kt renamed to clients/graphql-kotlin-client/src/main/kotlin/com/expediagroup/graphql/client/converter/ScalarConverter.kt

@@ -1,41 +1,36 @@
-# GraphQL Kotlin Client
-[![Maven Central](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-client.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.expediagroup%22%20AND%20a:%22graphql-kotlin-client%22)
-[![Javadocs](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-client.svg?label=javadoc&colorB=brightgreen)](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-client)
+# GraphQL Kotlin Ktor HTTP Client
+[![Maven Central](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-ktor-client.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.expediagroup%22%20AND%20a:%22graphql-kotlin-ktor-client%22)
+[![Javadocs](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-ktor-client.svg?label=javadoc&colorB=brightgreen)](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-ktor-client)
 
-A lightweight, typesafe GraphQL HTTP client.
+`graphql-kotlin-ktor-client` provides Ktor HTTP client based reference implementation of `GraphQLClient`. `GraphQLKtorClient`
+is a thin wrapper on top of [Ktor HTTP Client](https://ktor.io/clients/index.html) and supports fully asynchronous non-blocking
+communication. It is highly customizable and can be configured with any supported Ktor HTTP [engine](https://ktor.io/clients/http-client/engines.html)
+and [features](https://ktor.io/clients/http-client/features.html).
 
-NOTE: GraphQL client can be invoked directly by manually creating your corresponding data model but since at its core it
-ends up with simple POST request this mode of operation is not that useful. Instead, GraphQL Kotlin client should be used
-together with one of the GraphQL Kotlin build plugins to auto-generate type safe data models based on the specified queries.
+`GraphQLKtorClient` uses the Ktor HTTP Client to execute the underlying queries. Clients can be customized with different
+engines (defaults to Coroutine-based IO) and HTTP client features. Custom configurations can be applied through Ktor DSL
+style builders.
 
-## Features
-
-* Supports query and mutation operations
-* Automatic generation of type-safe Kotlin models
-* Custom scalar support - defaults to String but can be configured to deserialize to specific types
-* Supports default enum values to gracefully handle new/unknown server values
-* Native support for coroutines
-* Easily configurable Ktor HTTP Client
-* Documentation generated from the underlying GraphQL schema
+See [Ktor HTTP Client documentation](https://ktor.io/clients/index.html) for additional details.
 
 ## Install it
 
-Using a JVM dependency manager, link `graphql-kotlin-client` to your project.
+Using a JVM dependency manager, link `graphql-kotlin-ktor-client` to your project.
 
 With Maven:
 
 ```xml
 <dependency>
   <groupId>com.expediagroup</groupId>
-  <artifactId>graphql-kotlin-client</artifactId>
+  <artifactId>graphql-kotlin-ktor-client</artifactId>
   <version>${latestVersion}</version>
 </dependency>
 ```
 
 With Gradle (example using kts):
 
 ```kotlin
-implementation("com.expediagroup:graphql-kotlin-client:$latestVersion")
+implementation("com.expediagroup:graphql-kotlin-ktor-client:$latestVersion")
 ```
 
 ## Use it
@@ -78,10 +73,12 @@ details and considerations while writing your GraphQL queries.
 
 GraphQL Kotlin build plugins will auto-generate your data classes based on your queries and the underlying GraphQL schema.
 In order to generate your client you will need to specify the target package name, schema file, and queries. If the queries
-parameter is omitted, it will default to using `*.graphql` files under your resources directory.
+parameter is omitted, it will default to using `*.graphql` files under your resources directory. In order to generate Ktor
+based client implementation you also need to specify client type.
 
 ```kotlin
 val graphqlGenerateClient by tasks.getting(GraphQLGenerateClientTask::class) {
+    clientType.set(GraphQLClientType.KTOR)
     packageName.set("com.expediagroup.graphql.generated")
     // use schema file generated by the introspection task
     schemaFile.set(graphqlIntrospectSchema.outputFile)
@@ -95,13 +92,13 @@ Additional information about Gradle and Maven plugins as well as their respectiv
 
 ### Execute Queries
 
-Your auto generated classes accept an instance of `GraphQLClient` which requires the target URL to be specified. `GraphQLClient`
+Your auto generated classes accept an instance of `GraphQLKtorClient` which requires the target URL to be specified. `GraphQLKtorClient`
 uses the Ktor HTTP client to execute the underlying queries and allows you to specify different engines (defaults to CIO) and
 HTTP client features. Please refer to [Ktor HTTP client documentation](https://ktor.io/clients/index.html) for additional
 details.
 
 ```kotlin
-val client = GraphQLClient(url = URL("http://localhost:8080/graphql"))
+val client = GraphQLKtorClient(url = URL("http://localhost:8080/graphql"))
 val query = MyAwesomeQuery(client)
 val result = query.execute()
 ```
@@ -114,7 +111,7 @@ Additional information about Gradle and Maven plugins as well as their respectiv
 ## Documentation
 
 Additional information can be found in our [documentation](https://expediagroup.github.io/graphql-kotlin/docs/client/client-overview)
-and the [Javadocs](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-client) of all published versions.
+and the [Javadocs](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-ktor-client) of all published versions.
 
 If you have a question about something you can not find in our documentation or Javadocs, feel free to
 [create an issue](https://github.com/ExpediaGroup/graphql-kotlin/issues) and tag it with the question label.

graphql-kotlin-client/README.md …nts/graphql-kotlin-ktor-client/README.mdgraphql-kotlin-client/README.md renamed to clients/graphql-kotlin-ktor-client/README.md graphql-kotlin-client/README.md renamed to clients/graphql-kotlin-ktor-client/README.md

@@ -0,0 +1,14 @@
+description = "A lightweight typesafe GraphQL HTTP Client"
+
+val ktorVersion: String by project
+val wireMockVersion: String by project
+
+dependencies {
+    api(project(path = ":graphql-kotlin-client"))
+    api("io.ktor:ktor-client-cio:$ktorVersion")
+    api("io.ktor:ktor-client-json:$ktorVersion")
+    api("io.ktor:ktor-client-jackson:$ktorVersion")
+    testImplementation("io.ktor:ktor-client-okhttp:$ktorVersion")
+    testImplementation("io.ktor:ktor-client-logging-jvm:$ktorVersion")
+    testImplementation("com.github.tomakehurst:wiremock-jre8:$wireMockVersion")
+}

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

@@ -39,15 +39,15 @@ import java.io.Closeable
 import java.net.URL
 
 /**
- * A lightweight typesafe GraphQL HTTP client.
+ * A lightweight typesafe GraphQL HTTP client using Ktor HTTP client engine.
  */
 @KtorExperimentalAPI
-open class GraphQLClient<in T : HttpClientEngineConfig>(
+open class GraphQLKtorClient<in T : HttpClientEngineConfig>(
     private val url: URL,
     engineFactory: HttpClientEngineFactory<T>,
     private val mapper: ObjectMapper = jacksonObjectMapper(),
     configuration: HttpClientConfig<T>.() -> Unit = {}
-) : Closeable {
+) : GraphQLClient, Closeable {
 
     private val typeCache = mutableMapOf<Class<*>, JavaType>()
 
@@ -71,7 +71,7 @@ open class GraphQLClient<in T : HttpClientEngineConfig>(
      * default serialization would attempt to serialize results back to Any object. As a workaround we get raw results as String which we then
      * manually deserialize using passed in result type Class information.
      */
-    open suspend fun <T> execute(query: String, operationName: String? = null, variables: Any? = null, resultType: Class<T>, requestBuilder: HttpRequestBuilder.() -> Unit = {}): GraphQLResponse<T> {
+    open suspend fun <T> execute(query: String, operationName: String? = null, variables: Any? = null, resultType: Class<T>, requestBuilder: HttpRequestBuilder.() -> Unit): GraphQLResponse<T> {
         // Variables are simple data classes which will be serialized as map.
         // By using map instead of typed object we can eliminate the need to explicitly convert variables to a map
         val graphQLRequest = mapOf(
@@ -91,25 +91,26 @@ open class GraphQLClient<in T : HttpClientEngineConfig>(
         return mapper.readValue(rawResult, parameterizedType(resultType))
     }
 
+    override suspend fun <T> execute(query: String, operationName: String?, variables: Any?, resultType: Class<T>): GraphQLResponse<T> =
+        execute(query, operationName, variables, resultType, {})
+
     /**
      * Executes specified GraphQL query or mutation operation.
      */
-    suspend inline fun <reified T> execute(query: String, operationName: String? = null, variables: Any? = null, noinline requestBuilder: HttpRequestBuilder.() -> Unit = {}): GraphQLResponse<T> {
-        return execute(query, operationName, variables, T::class.java, requestBuilder)
-    }
+    suspend inline fun <reified T> execute(query: String, operationName: String? = null, variables: Any? = null, noinline requestBuilder: HttpRequestBuilder.() -> Unit): GraphQLResponse<T> =
+        execute(query, operationName, variables, T::class.java, requestBuilder)
 
-    private fun <T> parameterizedType(resultType: Class<T>): JavaType {
-        return typeCache.computeIfAbsent(resultType) {
+    private fun <T> parameterizedType(resultType: Class<T>): JavaType =
+        typeCache.computeIfAbsent(resultType) {
             mapper.typeFactory.constructParametricType(GraphQLResponse::class.java, resultType)
         }
-    }
 
     override fun close() {
         client.close()
     }
 
     companion object {
         operator fun invoke(url: URL, mapper: ObjectMapper = jacksonObjectMapper(), config: HttpClientConfig<CIOEngineConfig>.() -> Unit = {}) =
-            GraphQLClient(url = url, engineFactory = CIO, mapper = mapper, configuration = config)
+            GraphQLKtorClient(url = url, engineFactory = CIO, mapper = mapper, configuration = config)
     }
 }