[client] generate fallback/default implementation for polymorphic types (#1382)

Currently our client generator requires exhaustive selection of all polymorphic type implementations. This behavior is limiting as there are valid use cases when end-users may not need to select all the types (e.g. they only select common interface fields). By adding default/fallback implementation we also make it more robust as clients could be long lived and underlying schema could add/remove some implementations.

Due to the `kotlinx-serialization` limitations, we won't be able to provide auto configuration to handle default deserialization logic. Users will have to explicitly configure serializers module. See Kotlin/kotlinx.serialization#1575 for details.

```kotlin
val client = GraphQLKtorClient(
    url = URL("http://localhost:8080/graphql"),
    serializer = GraphQLClientKotlinxSerializer(jsonBuilder = {
        serializersModule = SerializersModule {
            polymorphic(MyInterface::class) {
                defaultDeserializer { DefaultMyInterfaceImplementation.serializer() }
            }
        }
    })
)
```

Related Issues:

Resolves #1376

Author: Dariusz Kuc

gradle.properties

@@ -17,7 +17,7 @@ org.gradle.jvmargs=-Xmx2g -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError
 kotlinJvmVersion = 1.8
 kotlinVersion = 1.6.10
 kotlinCoroutinesVersion = 1.6.0
-kotlinxSerializationVersion = 1.3.1
+kotlinxSerializationVersion = 1.3.2
 
 androidPluginVersion = 7.0.1
 classGraphVersion = 4.8.138

plugins/client/graphql-kotlin-client-generator/build.gradle.kts

@@ -9,6 +9,7 @@ val kotlinVersion: String by project
 val kotlinPoetVersion: String by project
 val kotlinxSerializationVersion: String by project
 val ktorVersion: String by project
+val slf4jVersion: String by project
 val wireMockVersion: String by project
 
 dependencies {
@@ -18,12 +19,13 @@ dependencies {
     }
     api("com.squareup:kotlinpoet:$kotlinPoetVersion")
     api("org.jetbrains.kotlinx:kotlinx-serialization-json:$kotlinxSerializationVersion")
+    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:$jacksonVersion")
     implementation("io.ktor:ktor-client-apache:$ktorVersion")
     implementation("io.ktor:ktor-client-jackson:$ktorVersion") {
         exclude("com.fasterxml.jackson.core", "jackson-databind")
         exclude("com.fasterxml.jackson.module", "jackson-module-kotlin")
     }
-    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:$jacksonVersion")
+    implementation("org.slf4j:slf4j-api:$slf4jVersion")
     testImplementation(project(path = ":graphql-kotlin-client-jackson"))
     testImplementation(project(path = ":graphql-kotlin-client-serialization"))
     testImplementation("com.github.tomakehurst:wiremock-jre8:$wireMockVersion")

plugins/client/graphql-kotlin-client-generator/src/main/kotlin/com/expediagroup/graphql/plugin/client/generator/exceptions/InvalidPolymorphicQueryException.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 Expedia, Inc
+ * Copyright 2022 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,7 +20,6 @@ import com.expediagroup.graphql.client.Generated
 import com.expediagroup.graphql.plugin.client.generator.GraphQLClientGeneratorContext
 import com.expediagroup.graphql.plugin.client.generator.GraphQLSerializer
 import com.expediagroup.graphql.plugin.client.generator.exceptions.InvalidFragmentException
-import com.expediagroup.graphql.plugin.client.generator.exceptions.InvalidPolymorphicQueryException
 import com.expediagroup.graphql.plugin.client.generator.exceptions.MissingTypeNameException
 import com.fasterxml.jackson.annotation.JsonSubTypes
 import com.fasterxml.jackson.annotation.JsonTypeInfo
@@ -30,6 +29,8 @@ import com.squareup.kotlinpoet.CodeBlock
 import com.squareup.kotlinpoet.FunSpec
 import com.squareup.kotlinpoet.KModifier
 import com.squareup.kotlinpoet.MemberName
+import com.squareup.kotlinpoet.MemberName.Companion.member
+import com.squareup.kotlinpoet.ParameterSpec
 import com.squareup.kotlinpoet.PropertySpec
 import com.squareup.kotlinpoet.TypeSpec
 import graphql.language.Field
@@ -41,6 +42,10 @@ import graphql.language.Selection
 import graphql.language.SelectionSet
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
+
+private val logger: Logger = LoggerFactory.getLogger("com.expediagroup.graphql.plugin.client.generator.types.GenerateInterfaceTypeSpec")
 
 /**
  * Generate interface [TypeSpec] based on the available field definitions and selection set. Generates all implementing classes as well.
@@ -123,10 +128,10 @@ internal fun generateInterfaceTypeSpec(
         existing.second.addAll(fragment.selectionSet.selections)
     }
 
-    // check if all implementations are selected
+    // log warning if not all implementations are selected
     val notImplemented = implementations.minus(implementationSelections.keys)
     if (notImplemented.isNotEmpty()) {
-        throw InvalidPolymorphicQueryException(context.operationName, interfaceName, notImplemented)
+        logger.warn("Operation ${context.operationName} does not specify all polymorphic implementations - field selection on $interfaceName is missing $notImplemented")
     }
 
     // generate implementations with final selection set
@@ -152,6 +157,7 @@ internal fun generateInterfaceTypeSpec(
         jsonSubTypesCodeBlock.add("com.fasterxml.jackson.annotation.JsonSubTypes.Type(value = %T::class, name=%S)", unwrappedClassName, implementationName)
     }
 
+    val fallbackClassName = generateFallbackImplementation(context, interfaceName, commonProperties)
     if (context.serializer == GraphQLSerializer.JACKSON) {
         // add jackson annotations to handle deserialization
         val jsonTypeInfoIdName = MemberName("com.fasterxml.jackson.annotation", "JsonTypeInfo.Id.NAME")
@@ -161,6 +167,7 @@ internal fun generateInterfaceTypeSpec(
                 .addMember("use = %M", jsonTypeInfoIdName)
                 .addMember("include = %M", jsonTypeInfoAsProperty)
                 .addMember("property = %S", "__typename")
+                .addMember("defaultImpl = %T::class", fallbackClassName)
                 .build()
         )
         interfaceTypeSpec.addAnnotation(
@@ -216,3 +223,56 @@ private fun updateImplementationTypeSpecWithSuperInformation(
     context.polymorphicTypes[superClassName]?.add(implementationClassName)
     context.typeSpecs[implementationClassName] = updatedType
 }
+
+private fun generateFallbackImplementation(context: GraphQLClientGeneratorContext, interfaceName: String, commonProperties: List<PropertySpec>): ClassName {
+    val fallbackTypeName = "Default${interfaceName}Implementation"
+    val superClassName = ClassName("${context.packageName}.${context.operationName.lowercase()}", interfaceName)
+    val fallbackClassName = ClassName("${context.packageName}.${context.operationName.lowercase()}", fallbackTypeName)
+    val fallbackType = TypeSpec.classBuilder(fallbackTypeName)
+        .addAnnotation(Generated::class)
+        .addKdoc("Fallback $interfaceName implementation that will be used when unknown/unhandled type is encountered.")
+        .also {
+            if (context.serializer == GraphQLSerializer.KOTLINX) {
+                it.addAnnotation(Serializable::class)
+                    .superclass(superClassName)
+                    .addKdoc("\n\nNOTE: This fallback logic has to be manually registered with the instance of GraphQLClientKotlinxSerializer. See documentation for details.")
+            } else {
+                it.addSuperinterface(superClassName)
+            }
+
+            if (commonProperties.isNotEmpty()) {
+                it.addModifiers(KModifier.DATA)
+            }
+        }
+        .addProperties(
+            commonProperties.map { abstractProperty ->
+                abstractProperty.toBuilder()
+                    .initializer(abstractProperty.name)
+                    .addModifiers(KModifier.OVERRIDE)
+                    .also {
+                        it.modifiers.remove(KModifier.ABSTRACT)
+                    }
+                    .build()
+            }
+        )
+        .primaryConstructor(
+            FunSpec.constructorBuilder()
+                .addParameters(
+                    commonProperties.map { propertySpec ->
+                        val constructorParameter = ParameterSpec.builder(propertySpec.name, propertySpec.type)
+                        val className = propertySpec.type as? ClassName
+                        if (propertySpec.type.isNullable) {
+                            constructorParameter.defaultValue("null")
+                        } else if (className != null && context.enumClassToTypeSpecs.keys.contains(className)) {
+                            constructorParameter.defaultValue("%M", className.member(UNKNOWN_VALUE))
+                        }
+                        constructorParameter.build()
+                    }
+                )
+                .build()
+        )
+        .build()
+    context.polymorphicTypes[superClassName]?.add(fallbackClassName)
+    context.typeSpecs[fallbackClassName] = fallbackType
+    return fallbackClassName
+}

plugins/client/graphql-kotlin-client-generator/src/main/kotlin/com/expediagroup/graphql/plugin/client/generator/types/generateInterfaceTypeSpec.kt

@@ -16,7 +16,8 @@ import kotlin.String
 @JsonTypeInfo(
   use = JsonTypeInfo.Id.NAME,
   include = JsonTypeInfo.As.PROPERTY,
-  property = "__typename"
+  property = "__typename",
+  defaultImpl = DefaultBasicInterfaceImplementation::class
 )
 @JsonSubTypes(value = [com.fasterxml.jackson.annotation.JsonSubTypes.Type(value =
     FirstInterfaceImplementation::class,
@@ -71,3 +72,19 @@ public data class SecondInterfaceImplementation(
    */
   public val floatValue: Double
 ) : BasicInterface
+
+/**
+ * Fallback BasicInterface implementation that will be used when unknown/unhandled type is
+ * encountered.
+ */
+@Generated
+public data class DefaultBasicInterfaceImplementation(
+  /**
+   * Unique identifier of an interface
+   */
+  public override val id: Int,
+  /**
+   * Name field
+   */
+  public override val name: String
+) : BasicInterface

plugins/client/graphql-kotlin-client-generator/src/test/data/generator/interface_diff_selection_sets/differentselectionsetquery/BasicInterface.kt

@@ -16,7 +16,8 @@ import kotlin.String
 @JsonTypeInfo(
   use = JsonTypeInfo.Id.NAME,
   include = JsonTypeInfo.As.PROPERTY,
-  property = "__typename"
+  property = "__typename",
+  defaultImpl = DefaultBasicInterface2Implementation::class
 )
 @JsonSubTypes(value = [com.fasterxml.jackson.annotation.JsonSubTypes.Type(value =
     FirstInterfaceImplementation2::class,
@@ -58,3 +59,15 @@ public data class SecondInterfaceImplementation2(
    */
   public val floatValue: Double
 ) : BasicInterface2
+
+/**
+ * Fallback BasicInterface2 implementation that will be used when unknown/unhandled type is
+ * encountered.
+ */
+@Generated
+public data class DefaultBasicInterface2Implementation(
+  /**
+   * Name field
+   */
+  public override val name: String
+) : BasicInterface2

plugins/client/graphql-kotlin-client-generator/src/test/data/generator/interface_diff_selection_sets/differentselectionsetquery/BasicInterface2.kt

@@ -15,7 +15,8 @@ import kotlin.Int
 @JsonTypeInfo(
   use = JsonTypeInfo.Id.NAME,
   include = JsonTypeInfo.As.PROPERTY,
-  property = "__typename"
+  property = "__typename",
+  defaultImpl = DefaultBasicInterfaceImplementation::class
 )
 @JsonSubTypes(value = [com.fasterxml.jackson.annotation.JsonSubTypes.Type(value =
     FirstInterfaceImplementation::class,
@@ -57,3 +58,15 @@ public data class SecondInterfaceImplementation(
    */
   public val floatValue: Double
 ) : BasicInterface
+
+/**
+ * Fallback BasicInterface implementation that will be used when unknown/unhandled type is
+ * encountered.
+ */
+@Generated
+public data class DefaultBasicInterfaceImplementation(
+  /**
+   * Unique identifier of an interface
+   */
+  public override val id: Int
+) : BasicInterface

plugins/client/graphql-kotlin-client-generator/src/test/data/generator/interface_impl_diff_selection_sets/differentselectionsetquery/BasicInterface.kt

@@ -16,7 +16,8 @@ import kotlin.String
 @JsonTypeInfo(
   use = JsonTypeInfo.Id.NAME,
   include = JsonTypeInfo.As.PROPERTY,
-  property = "__typename"
+  property = "__typename",
+  defaultImpl = DefaultBasicInterface2Implementation::class
 )
 @JsonSubTypes(value = [com.fasterxml.jackson.annotation.JsonSubTypes.Type(value =
     FirstInterfaceImplementation2::class,
@@ -66,3 +67,15 @@ public data class SecondInterfaceImplementation2(
    */
   public val floatValue: Double
 ) : BasicInterface2
+
+/**
+ * Fallback BasicInterface2 implementation that will be used when unknown/unhandled type is
+ * encountered.
+ */
+@Generated
+public data class DefaultBasicInterface2Implementation(
+  /**
+   * Unique identifier of an interface
+   */
+  public override val id: Int
+) : BasicInterface2

plugins/client/graphql-kotlin-client-generator/src/test/data/generator/interface_impl_diff_selection_sets/differentselectionsetquery/BasicInterface2.kt

@@ -1,10 +1,10 @@
-query InvalidQueryMissingTypeSelection {
+query InterfaceMissingTypeSelection {
   interfaceQuery {
     __typename
     id
     name
     ... on FirstInterfaceImplementation {
-      value
+      intValue
     }
   }
 }

…InvalidQueryMissingTypeSelection.graphql …es/InterfaceMissingTypeSelection.graphqlplugins/client/graphql-kotlin-client-generator/src/test/data/invalid/interface_missing_types/InvalidQueryMissingTypeSelection.graphql renamed to plugins/client/graphql-kotlin-client-generator/src/test/data/generator/interface_missing_types/InterfaceMissingTypeSelection.graphql plugins/client/graphql-kotlin-client-generator/src/test/data/invalid/interface_missing_types/InvalidQueryMissingTypeSelection.graphql renamed to plugins/client/graphql-kotlin-client-generator/src/test/data/generator/interface_missing_types/InterfaceMissingTypeSelection.graphql

@@ -0,0 +1,29 @@
+package com.expediagroup.graphql.generated
+
+import com.expediagroup.graphql.client.Generated
+import com.expediagroup.graphql.client.types.GraphQLClientRequest
+import com.expediagroup.graphql.generated.interfacemissingtypeselection.BasicInterface
+import kotlin.String
+import kotlin.reflect.KClass
+
+public const val INTERFACE_MISSING_TYPE_SELECTION: String =
+    "query InterfaceMissingTypeSelection {\n  interfaceQuery {\n    __typename\n    id\n    name\n    ... on FirstInterfaceImplementation {\n      intValue\n    }\n  }\n}"
+
+@Generated
+public class InterfaceMissingTypeSelection :
+    GraphQLClientRequest<InterfaceMissingTypeSelection.Result> {
+  public override val query: String = INTERFACE_MISSING_TYPE_SELECTION
+
+  public override val operationName: String = "InterfaceMissingTypeSelection"
+
+  public override fun responseType(): KClass<InterfaceMissingTypeSelection.Result> =
+      InterfaceMissingTypeSelection.Result::class
+
+  @Generated
+  public data class Result(
+    /**
+     * Query returning an interface
+     */
+    public val interfaceQuery: BasicInterface
+  )
+}