[generator] built-in support for optional input (#808)

In the GraphQL world, input types can be optional which means that the client can either:

* Not specify a value at all
* Send null explicitly
* Send the non-null type

This is in contrast with the JVM world where objects can either have some specific value or don't have any value (i.e. are `null`). As a result, when using default serialization logic it is not possible to distinguish between missing/unspecified value and explicit `null` value.

This PR introduces new `OptionalInput` sealed class wrapper that when used for query arguments will be automatically deserialized to `Undefined` object if argument was not specified OR to `Defined` wrapper class when argument was specified (including explicit null).

Resolves: #783

Author: dariuszkuc

docs/schema-generator/execution/optional-undefined-arguments.md

@@ -3,13 +3,44 @@ id: optional-undefined-arguments
 title: Optional Undefined Arguments
 ---
 
-In GraphQL, input types can be optional which means that the client can either:
+In the GraphQL world, input types can be optional which means that the client can either:
 
 * Not specify a value at all
-* Send null explictly
+* Send null explicitly
 * Send the non-null type
 
-Optional input types are represented as nullable parameters in Kotlin
+This is in contrast with the JVM world where objects can either have some specific value or don't have any value (i.e.
+are `null`). As a result, when using default serialization logic it is not possible to distinguish between missing/unspecified
+value and explicit `null` value.
+
+## Using OptionalInput wrapper
+
+`OptionalInput` sealed class is a convenient wrapper that provides easy distinction between unspecified, `null` and non-null
+value. If target argument is not specified in the request it will be represented as `Undefined` object, otherwise actual
+value will be wrapped in `Defined` class.
+
+```kotlin
+fun optionalInput(input: OptionalInput<String>): String = when (input) {
+    is OptionalInput.Undefined -> "input was not specified"
+    is OptionalInput.Defined<String> -> "input value: ${input.value}"
+}
+```
+
+```graphql
+query OptionalInputQuery {
+  undefined: optionalInput
+  null: optionalInput(value: null)
+  foo: optionalInput(value: "foo")
+}
+```
+
+> NOTE: Regardless whether generic type of `OptionalInput` is specified as nullable or not it will always result in nullable
+> value in `Defined` class.
+
+## Using DataFetchingEnvironment
+
+Optional input types can be represented as nullable parameters in Kotlin
+
 ```kotlin
 fun optionalInput(value: String?): String? = value
 ```
@@ -23,9 +54,10 @@ query OptionalInputQuery {
 ```
 
 By default, if an optional input value is not specified, then the execution engine will set the argument in Kotlin to `null`.
-This means that you can not tell, by just the value alone, whether the request did not contain any argument or the client explicitly passed in `null`.
+This means that you can not tell, by just the value alone, whether the request did not contain any argument or the client
+explicitly passed in `null`.
 
-Instead, you should inspect the [DataFetchingEnvironment](./data-fetching-environment.md) where you can see if the request had the variable defined and even check parent arguments as well.
+Instead, you can inspect all passed in arguments using the [DataFetchingEnvironment](./data-fetching-environment.md).
 
 ```kotlin
 fun optionalInput(value: String?, dataFetchingEnvironment: DataFetchingEnvironment): String =

graphql-kotlin-schema-generator/build.gradle.kts

@@ -6,6 +6,7 @@ val jacksonVersion: String by project
 val kotlinVersion: String by project
 val kotlinCoroutinesVersion: String by project
 val rxjavaVersion: String by project
+val junitVersion: String by project
 
 dependencies {
     api("com.graphql-java:graphql-java:$graphQLJavaVersion")
@@ -14,6 +15,7 @@ dependencies {
     implementation(kotlin("reflect", kotlinVersion))
     implementation("io.github.classgraph:classgraph:$classGraphVersion")
     testImplementation("io.reactivex.rxjava3:rxjava:$rxjavaVersion")
+    testImplementation("org.junit.jupiter:junit-jupiter-params:$junitVersion")
 }
 
 tasks {

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/execution/FunctionDataFetcher.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Expedia, Inc
+ * 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.
@@ -22,6 +22,7 @@ import com.expediagroup.graphql.generator.extensions.getTypeOfFirstArgument
 import com.expediagroup.graphql.generator.extensions.isDataFetchingEnvironment
 import com.expediagroup.graphql.generator.extensions.isGraphQLContext
 import com.expediagroup.graphql.generator.extensions.isList
+import com.expediagroup.graphql.generator.extensions.isOptionalInputType
 import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import graphql.schema.DataFetcher
@@ -103,13 +104,27 @@ open class FunctionDataFetcher(
         val name = param.getName()
         val argument = environment.arguments[name]
 
-        return if (param.isList()) {
-            val argumentClass = param.type.getTypeOfFirstArgument().getJavaClass()
-            val jacksonCollectionType = objectMapper.typeFactory.constructCollectionType(List::class.java, argumentClass)
-            objectMapper.convertValue(argument, jacksonCollectionType)
-        } else {
-            val javaClass = param.type.getJavaClass()
-            objectMapper.convertValue(argument, javaClass)
+        return when {
+            param.isList() -> {
+                val argumentClass = param.type.getTypeOfFirstArgument().getJavaClass()
+                val jacksonCollectionType = objectMapper.typeFactory.constructCollectionType(List::class.java, argumentClass)
+                objectMapper.convertValue(argument, jacksonCollectionType)
+            }
+            param.type.isOptionalInputType() -> {
+                when {
+                    !environment.containsArgument(name) -> OptionalInput.Undefined
+                    argument == null -> OptionalInput.Defined(null)
+                    else -> {
+                        val argumentClass = param.type.getTypeOfFirstArgument().getJavaClass()
+                        val value = objectMapper.convertValue(argument, argumentClass)
+                        OptionalInput.Defined(value)
+                    }
+                }
+            }
+            else -> {
+                val javaClass = param.type.getJavaClass()
+                objectMapper.convertValue(argument, javaClass)
+            }
         }
     }
 

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/execution/OptionalInput.kt

@@ -0,0 +1,74 @@
+/*
+ * 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.execution
+
+import com.fasterxml.jackson.annotation.JsonCreator
+import com.fasterxml.jackson.annotation.JsonValue
+import com.fasterxml.jackson.core.JsonParser
+import com.fasterxml.jackson.databind.BeanProperty
+import com.fasterxml.jackson.databind.DeserializationContext
+import com.fasterxml.jackson.databind.JsonDeserializer
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize
+import com.fasterxml.jackson.databind.deser.ContextualDeserializer
+import com.fasterxml.jackson.databind.util.AccessPattern
+
+/**
+ * Wrapper used to represent optionally defined input arguments that allows us to distinguish between undefined value, explicit NULL value
+ * and specified value.
+ */
+@JsonDeserialize(using = OptionalInputDeserializer::class)
+sealed class OptionalInput<out T> {
+
+    /**
+     * Represents missing/undefined value.
+     */
+    object Undefined : OptionalInput<Nothing>()
+
+    /**
+     * Wrapper holding explicitly specified value including NULL.
+     */
+    class Defined<out U> @JsonCreator constructor(@JsonValue val value: U?) : OptionalInput<U>()
+}
+
+/**
+ * Null aware deserializer that distinguishes between undefined value, explicit NULL value
+ * and specified value.
+ */
+class OptionalInputDeserializer(private val klazz: Class<*>? = null) : JsonDeserializer<OptionalInput<*>>(), ContextualDeserializer {
+
+    override fun createContextual(ctxt: DeserializationContext, property: BeanProperty?): JsonDeserializer<*> {
+        val type = if (property != null) {
+            property.type.containedType(0)
+        } else {
+            ctxt.contextualType
+        }
+        return OptionalInputDeserializer(type.rawClass)
+    }
+
+    override fun deserialize(p: JsonParser, ctxt: DeserializationContext): OptionalInput<*> {
+        val result: Any = ctxt.readValue(p, klazz)
+        return OptionalInput.Defined(result)
+    }
+
+    override fun getNullAccessPattern(): AccessPattern = AccessPattern.CONSTANT
+
+    override fun getNullValue(ctxt: DeserializationContext): OptionalInput<*> = if (ctxt.parser.parsingContext.currentName != null) {
+        OptionalInput.Defined(null)
+    } else {
+        OptionalInput.Undefined
+    }
+}

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/extensions/kTypeExtensions.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Expedia, Inc
+ * 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.
@@ -17,10 +17,12 @@
 package com.expediagroup.graphql.generator.extensions
 
 import com.expediagroup.graphql.exceptions.InvalidListTypeException
+import com.expediagroup.graphql.execution.OptionalInput
 import kotlin.reflect.KClass
 import kotlin.reflect.KType
 import kotlin.reflect.full.createType
 import kotlin.reflect.full.isSubclassOf
+import kotlin.reflect.full.withNullability
 import kotlin.reflect.jvm.jvmErasure
 
 private val primitiveArrayTypes = mapOf(
@@ -39,6 +41,16 @@ internal fun KType.getJavaClass(): Class<*> = this.getKClass().java
 
 internal fun KType.isSubclassOf(kClass: KClass<*>) = this.getKClass().isSubclassOf(kClass)
 
+internal fun KType.isListType() = this.isSubclassOf(List::class) || this.getJavaClass().isArray
+
+internal fun KType.isOptionalInputType() = this.isSubclassOf(OptionalInput::class)
+
+internal fun KType.unwrapOptionalInputType() = if (this.isOptionalInputType()) {
+    this.getWrappedType().withNullability(true)
+} else {
+    this
+}
+
 @Throws(InvalidListTypeException::class)
 internal fun KType.getTypeOfFirstArgument(): KType =
     this.arguments.firstOrNull()?.type ?: throw InvalidListTypeException(this)

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/types/generateArgument.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Expedia, Inc
+ * 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.
@@ -26,22 +26,27 @@ import com.expediagroup.graphql.generator.extensions.isInterface
 import com.expediagroup.graphql.generator.extensions.isListType
 import com.expediagroup.graphql.generator.extensions.isUnion
 import com.expediagroup.graphql.generator.extensions.safeCast
+import com.expediagroup.graphql.generator.extensions.unwrapOptionalInputType
 import graphql.schema.GraphQLArgument
 import kotlin.reflect.KClass
 import kotlin.reflect.KParameter
+import kotlin.reflect.KType
 
 @Throws(InvalidInputFieldTypeException::class)
 internal fun generateArgument(generator: SchemaGenerator, parameter: KParameter): GraphQLArgument {
 
+    val inputTypeFromHooks = generator.config.hooks.willResolveInputMonad(parameter.type)
+    val unwrappedType = inputTypeFromHooks.unwrapOptionalInputType()
+
     // Validate that the input is not a polymorphic type
     // This is not currently supported by the GraphQL spec
     // https://github.com/graphql/graphql-spec/blob/master/rfcs/InputUnion.md
-    val unwrappedClass = getUnwrappedClass(parameter)
+    val unwrappedClass = getUnwrappedClass(unwrappedType)
     if (unwrappedClass.isUnion() || unwrappedClass.isInterface()) {
         throw InvalidInputFieldTypeException(parameter)
     }
 
-    val graphQLType = generateGraphQLType(generator = generator, type = parameter.type, inputType = true)
+    val graphQLType = generateGraphQLType(generator = generator, type = unwrappedType, inputType = true)
 
     // Deprecation of arguments is currently unsupported: https://github.com/facebook/graphql/issues/197
     val builder = GraphQLArgument.newArgument()
@@ -56,9 +61,9 @@ internal fun generateArgument(generator: SchemaGenerator, parameter: KParameter)
     return generator.config.hooks.onRewireGraphQLType(builder.build()).safeCast()
 }
 
-private fun getUnwrappedClass(parameter: KParameter): KClass<*> =
-    if (parameter.isListType()) {
-        parameter.type.getWrappedType().getKClass()
+private fun getUnwrappedClass(parameterType: KType): KClass<*> =
+    if (parameterType.isListType()) {
+        parameterType.getWrappedType().getKClass()
     } else {
-        parameter.type.getKClass()
+        parameterType.getKClass()
     }

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/types/generateInputProperty.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Expedia, Inc
+ * 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.
@@ -20,6 +20,7 @@ import com.expediagroup.graphql.generator.SchemaGenerator
 import com.expediagroup.graphql.generator.extensions.getPropertyDescription
 import com.expediagroup.graphql.generator.extensions.getPropertyName
 import com.expediagroup.graphql.generator.extensions.safeCast
+import com.expediagroup.graphql.generator.extensions.unwrapOptionalInputType
 import graphql.schema.GraphQLInputObjectField
 import graphql.schema.GraphQLInputType
 import kotlin.reflect.KClass
@@ -29,7 +30,9 @@ internal fun generateInputProperty(generator: SchemaGenerator, prop: KProperty<*
     val builder = GraphQLInputObjectField.newInputObjectField()
 
     // Verfiy that the unwrapped GraphQL type is a valid input type
-    val graphQLInputType = generateGraphQLType(generator = generator, type = prop.returnType, inputType = true).safeCast<GraphQLInputType>()
+    val inputTypeFromHooks = generator.config.hooks.willResolveInputMonad(prop.returnType)
+    val unwrappedType = inputTypeFromHooks.unwrapOptionalInputType()
+    val graphQLInputType = generateGraphQLType(generator = generator, type = unwrappedType, inputType = true).safeCast<GraphQLInputType>()
 
     builder.description(prop.getPropertyDescription(parentClass))
     builder.name(prop.getPropertyName(parentClass))

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/hooks/SchemaGeneratorHooks.kt

@@ -73,6 +73,12 @@ interface SchemaGeneratorHooks {
      */
     fun willResolveMonad(type: KType): KType = type
 
+    /**
+     * Called before resolving a KType to the input GraphQL type.
+     * This allows resolvers for custom deserialization logic of wrapped input values, like in an Optional.
+     */
+    fun willResolveInputMonad(type: KType): KType = type
+
     /**
      * Called when looking at the KClass superclasses to determine if it valid for adding to the generated schema.
      * If any filter returns false, it is rejected.