BREAKING CHANGE(generator): make dependency on ClassGraphClass optional (#1733)

### 📝 Description

We are using `ClassScanner` (which wraps `ClassGraph`) to automatically resolve polymorphic types (i.e. given an interface we can find all implementing types that are available on classpath) and locate federated entities (i.e. types with `@key` directive). This is generally great as this information can be pulled in automatically but it is a blocker for using the library with GraalVM.

`ClassGraph` is incompatible with GraalVm because when compiling to native image, we will no longer have JARs on classpath so any metadata around resources in those files will be invalid. Since we only use classpath scanning for resolving polyrmophic types and federated entities, the simplest solution is to provide users ability to manually provide this information without relying on the `ClassGraph` (which is still used by default). By no longer relying on `ClassGraph` we can now generate valid GraalVM reflect metadata and compile GraphQL Kotlin servers to native images.

This PR introduces a breaking change that removes `SchemaGenerator#addAdditionalTypesWithAnnotation` function. This function was originally added to avoid exposing `ClassGraph` outside of `graphql-kotlin-schema-generator` module and allow federation module to easily locate entity types. By making `ClassGraph` dependency optional, function no longer makes sense.

### 🔗 Related Issues

* #1543
* #1441
* #1224

Author: dariuszkuc

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/FederatedGraphQLTypeResolver.kt

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2023 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.generator.federation
+
+import com.expediagroup.graphql.generator.ClasspathTypeResolver
+import com.expediagroup.graphql.generator.GraphQLTypeResolver
+import com.expediagroup.graphql.generator.SimpleTypeResolver
+import com.expediagroup.graphql.generator.federation.directives.KeyDirective
+import com.expediagroup.graphql.generator.internal.state.ClassScanner
+import kotlin.reflect.KClass
+
+/**
+ * Polymorphic GraphQL type resolver that can also locate federated entities.
+ */
+interface FederatedGraphQLTypeResolver : GraphQLTypeResolver {
+    /**
+     * Locate federated entities (i.e. types with `@key` directive)
+     */
+    fun locateEntities(): List<KClass<*>>
+}
+
+/**
+ * Simple federated polymorphic type resolver that relies on provided polymorphic map and
+ * list of entities.
+ */
+open class FederatedSimpleTypeResolver(
+    polymorphicMap: Map<KClass<*>, List<KClass<*>>>,
+    private val entities: List<KClass<*>>
+) : SimpleTypeResolver(polymorphicMap), FederatedGraphQLTypeResolver {
+    override fun locateEntities(): List<KClass<*>> = entities
+}
+
+/**
+ * Classpath based federated polymorphic type resolver. Relies on ClassScanner to obtain
+ * polymorphic info and to locate entities.
+ */
+open class FederatedClasspathTypeResolver(
+    private val scanner: ClassScanner
+) : ClasspathTypeResolver(scanner), FederatedGraphQLTypeResolver {
+    override fun locateEntities(): List<KClass<*>> = scanner.getClassesWithAnnotation(KeyDirective::class)
+}

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/FederatedSchemaGenerator.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Expedia, Inc
+ * Copyright 2023 Expedia, Inc
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,14 +18,16 @@ package com.expediagroup.graphql.generator.federation
 
 import com.expediagroup.graphql.generator.SchemaGenerator
 import com.expediagroup.graphql.generator.TopLevelObject
-import com.expediagroup.graphql.generator.federation.directives.KeyDirective
 import graphql.schema.GraphQLSchema
 import kotlin.reflect.KType
+import kotlin.reflect.full.createType
 
 /**
  * Generates federated GraphQL schemas based on the specified configuration.
  */
-open class FederatedSchemaGenerator(generatorConfig: FederatedSchemaGeneratorConfig) : SchemaGenerator(generatorConfig) {
+open class FederatedSchemaGenerator(
+    private val generatorConfig: FederatedSchemaGeneratorConfig
+) : SchemaGenerator(generatorConfig) {
 
     /**
      * Scans specified packages for all the federated (extended) types and adds them to the schema additional types,
@@ -39,7 +41,7 @@ open class FederatedSchemaGenerator(generatorConfig: FederatedSchemaGeneratorCon
         additionalInputTypes: Set<KType>,
         schemaObject: TopLevelObject?
     ): GraphQLSchema {
-        addAdditionalTypesWithAnnotation(KeyDirective::class, inputType = false)
-        return super.generateSchema(queries, mutations, subscriptions, additionalTypes, additionalInputTypes, schemaObject)
+        val entityTypes = generatorConfig.typeResolver.locateEntities().map { it.createType() }
+        return super.generateSchema(queries, mutations, subscriptions, additionalTypes + entityTypes, additionalInputTypes, schemaObject)
     }
 }

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/FederatedSchemaGeneratorConfig.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 Expedia, Inc
+ * Copyright 2023 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,14 +20,19 @@ import com.expediagroup.graphql.generator.SchemaGeneratorConfig
 import com.expediagroup.graphql.generator.TopLevelNames
 import com.expediagroup.graphql.generator.execution.KotlinDataFetcherFactoryProvider
 import com.expediagroup.graphql.generator.execution.SimpleKotlinDataFetcherFactoryProvider
+import com.expediagroup.graphql.generator.internal.state.ClassScanner
+import graphql.schema.GraphQLType
 
 /**
  * Settings for generating the federated schema.
  */
+@Suppress("LongParameterList")
 class FederatedSchemaGeneratorConfig(
     override val supportedPackages: List<String>,
     override val topLevelNames: TopLevelNames = TopLevelNames(),
     override val hooks: FederatedSchemaGeneratorHooks,
     override val dataFetcherFactoryProvider: KotlinDataFetcherFactoryProvider = SimpleKotlinDataFetcherFactoryProvider(),
-    override val introspectionEnabled: Boolean = true
-) : SchemaGeneratorConfig(supportedPackages, topLevelNames, hooks, dataFetcherFactoryProvider, introspectionEnabled)
+    override val introspectionEnabled: Boolean = true,
+    override val additionalTypes: Set<GraphQLType> = emptySet(),
+    override val typeResolver: FederatedGraphQLTypeResolver = FederatedClasspathTypeResolver(ClassScanner(supportedPackages))
+) : SchemaGeneratorConfig(supportedPackages, topLevelNames, hooks, dataFetcherFactoryProvider, introspectionEnabled, additionalTypes, typeResolver)

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

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2023 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.generator
+
+import com.expediagroup.graphql.generator.internal.state.ClassScanner
+import java.io.Closeable
+import kotlin.reflect.KClass
+
+/**
+ * Polymorphic types resolver.
+ */
+interface GraphQLTypeResolver : Closeable {
+    /**
+     * Given a class find all its subtypes.
+     */
+    fun getSubTypesOf(kclass: KClass<*>): List<KClass<*>>
+}
+
+/**
+ * Map based polymorphic types resolver.
+ */
+open class SimpleTypeResolver(
+    private val polymorphicMap: Map<KClass<*>, List<KClass<*>>>
+) : GraphQLTypeResolver {
+
+    override fun getSubTypesOf(kclass: KClass<*>): List<KClass<*>> = polymorphicMap[kclass] ?: emptyList()
+
+    override fun close() {
+        // no-op
+    }
+}
+
+/**
+ * Classpath based polymorphic type resolvers. Uses ClassScanner to find polymorphic info.
+ */
+open class ClasspathTypeResolver(
+    private val scanner: ClassScanner
+) : GraphQLTypeResolver {
+    override fun getSubTypesOf(kclass: KClass<*>): List<KClass<*>> = scanner.getSubTypesOf(kclass)
+
+    override fun close() {
+        scanner.close()
+    }
+}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Expedia, Inc
+ * Copyright 2023 Expedia, Inc
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,11 +16,9 @@
 
 package com.expediagroup.graphql.generator
 
-import com.expediagroup.graphql.generator.exceptions.InvalidPackagesException
 import com.expediagroup.graphql.generator.internal.extensions.getGraphQLDescription
 import com.expediagroup.graphql.generator.internal.extensions.getKClass
 import com.expediagroup.graphql.generator.internal.state.AdditionalType
-import com.expediagroup.graphql.generator.internal.state.ClassScanner
 import com.expediagroup.graphql.generator.internal.state.TypesCache
 import com.expediagroup.graphql.generator.internal.types.GraphQLKTypeMetadata
 import com.expediagroup.graphql.generator.internal.types.generateGraphQLType
@@ -36,9 +34,7 @@ import graphql.schema.GraphQLTypeUtil
 import graphql.schema.visibility.NoIntrospectionGraphqlFieldVisibility
 import java.io.Closeable
 import java.util.concurrent.ConcurrentHashMap
-import kotlin.reflect.KClass
 import kotlin.reflect.KType
-import kotlin.reflect.full.createType
 
 /**
  * Generate a schema object given some configuration and top level objects for the queries, mutations, and subscriptions.
@@ -52,20 +48,10 @@ import kotlin.reflect.full.createType
 open class SchemaGenerator(internal val config: SchemaGeneratorConfig) : Closeable {
 
     internal val additionalTypes: MutableSet<AdditionalType> = mutableSetOf()
-    internal val classScanner = ClassScanner(config.supportedPackages)
     internal val cache = TypesCache(config.supportedPackages)
-    internal val codeRegistry = GraphQLCodeRegistry.newCodeRegistry()
+    internal val codeRegistry: GraphQLCodeRegistry.Builder = GraphQLCodeRegistry.newCodeRegistry()
     internal val directives = ConcurrentHashMap<String, GraphQLDirective>()
 
-    /**
-     * Validate that the supported packages contain classes
-     */
-    init {
-        if (classScanner.isEmptyScan()) {
-            throw InvalidPackagesException(config.supportedPackages)
-        }
-    }
-
     /**
      * Generate a schema given a list of objects to parse for the queries, mutations, and subscriptions.
      */
@@ -77,7 +63,6 @@ open class SchemaGenerator(internal val config: SchemaGeneratorConfig) : Closeab
         additionalInputTypes: Set<KType> = emptySet(),
         schemaObject: TopLevelObject? = null
     ): GraphQLSchema {
-
         this.additionalTypes.addAll(additionalTypes.map { AdditionalType(it, inputType = false) })
         this.additionalTypes.addAll(additionalInputTypes.map { AdditionalType(it, inputType = true) })
 
@@ -106,19 +91,6 @@ open class SchemaGenerator(internal val config: SchemaGeneratorConfig) : Closeab
             }.build()
     }
 
-    /**
-     * Add all types with the following annotation to the schema.
-     *
-     * This is helpful for things like federation or combining external schemas.
-     */
-    protected fun addAdditionalTypesWithAnnotation(annotation: KClass<*>, inputType: Boolean = false) {
-        classScanner.getClassesWithAnnotation(annotation).forEach { kClass ->
-            if (config.hooks.isValidAdditionalType(kClass, inputType)) {
-                additionalTypes.add(AdditionalType(kClass.createType(), inputType))
-            }
-        }
-    }
-
     /**
      * Generate the GraphQL type for all the `additionalTypes`.
      *
@@ -127,7 +99,7 @@ open class SchemaGenerator(internal val config: SchemaGeneratorConfig) : Closeab
      *
      * This function loops because while generating the additionalTypes it is possible to create more additional types that need to be processed.
      */
-    protected fun generateAdditionalTypes(): Set<GraphQLType> {
+    internal fun generateAdditionalTypes(): Set<GraphQLType> {
         val graphqlTypes = this.config.additionalTypes.toMutableSet()
         while (this.additionalTypes.isNotEmpty()) {
             val currentlyProcessedTypes = LinkedHashSet(this.additionalTypes)
@@ -152,7 +124,7 @@ open class SchemaGenerator(internal val config: SchemaGeneratorConfig) : Closeab
      * clean up of resources for you.
      */
     override fun close() {
-        classScanner.close()
+        config.close()
         cache.close()
         additionalTypes.clear()
         directives.clear()

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 Expedia, Inc
+ * Copyright 2023 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,16 +20,24 @@ import com.expediagroup.graphql.generator.execution.KotlinDataFetcherFactoryProv
 import com.expediagroup.graphql.generator.execution.SimpleKotlinDataFetcherFactoryProvider
 import com.expediagroup.graphql.generator.hooks.NoopSchemaGeneratorHooks
 import com.expediagroup.graphql.generator.hooks.SchemaGeneratorHooks
+import com.expediagroup.graphql.generator.internal.state.ClassScanner
 import graphql.schema.GraphQLType
+import java.io.Closeable
 
 /**
  * Settings for generating the schema.
  */
+@Suppress("LongParameterList")
 open class SchemaGeneratorConfig(
     open val supportedPackages: List<String>,
     open val topLevelNames: TopLevelNames = TopLevelNames(),
     open val hooks: SchemaGeneratorHooks = NoopSchemaGeneratorHooks,
     open val dataFetcherFactoryProvider: KotlinDataFetcherFactoryProvider = SimpleKotlinDataFetcherFactoryProvider(),
     open val introspectionEnabled: Boolean = true,
-    open val additionalTypes: Set<GraphQLType> = emptySet()
-)
+    open val additionalTypes: Set<GraphQLType> = emptySet(),
+    open val typeResolver: GraphQLTypeResolver = ClasspathTypeResolver(ClassScanner(supportedPackages))
+) : Closeable {
+    override fun close() {
+        typeResolver.close()
+    }
+}

generator/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/generator/internal/state/ClassScanner.kt

@@ -16,6 +16,7 @@
 
 package com.expediagroup.graphql.generator.internal.state
 
+import com.expediagroup.graphql.generator.exceptions.InvalidPackagesException
 import io.github.classgraph.ClassGraph
 import io.github.classgraph.ClassInfo
 import io.github.classgraph.ClassInfoList
@@ -27,14 +28,23 @@ import kotlin.reflect.jvm.jvmName
  * This class should be used from a try-with-resouces block
  * or another closable object as the internal scan result can take up a lot of resources.
  */
-internal class ClassScanner(supportedPackages: List<String>) : Closeable {
+open class ClassScanner(supportedPackages: List<String>) : Closeable {
 
     @Suppress("Detekt.SpreadOperator")
     private val scanResult = ClassGraph()
         .enableAllInfo()
         .acceptPackages(*supportedPackages.toTypedArray())
         .scan()
 
+    /**
+     * Validate that the supported packages contain classes
+     */
+    init {
+        if (isEmptyScan()) {
+            throw InvalidPackagesException(supportedPackages)
+        }
+    }
+
     /**
      * Return true if there are no valid packages scanned
      */

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

@@ -60,7 +60,7 @@ internal fun generateInterface(generator: SchemaGenerator, kClass: KClass<*>): G
     kClass.getValidFunctions(generator.config.hooks)
         .forEach { builder.field(generateFunction(generator, kClass, it, kClass.getSimpleName(), null, abstract = true)) }
 
-    generator.classScanner.getSubTypesOf(kClass)
+    generator.config.typeResolver.getSubTypesOf(kClass)
         .filter { generator.config.hooks.isValidAdditionalType(it, inputType = false) }
         .forEach { generator.additionalTypes.add(AdditionalType(it.createType(), inputType = false)) }
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Expedia, Inc
+ * Copyright 2023 Expedia, Inc
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -71,7 +71,7 @@ private fun generateUnionFromKClass(generator: SchemaGenerator, kClass: KClass<*
         builder.withAppliedDirective(it)
     }
 
-    val types = generator.classScanner.getSubTypesOf(kClass)
+    val types = generator.config.typeResolver.getSubTypesOf(kClass)
 
     return createUnion(name, generator, builder, types)
 }