Add valid locations annotation (ExpediaGroup#1132)

* Add valid locations annotation

* Update annotation input

* Mark function as interna;

Author: smyrick

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

@@ -0,0 +1,31 @@
+/*
+ * 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.generator.annotations
+
+/**
+ * Kotlin classes can be used as GraphQL input types, output types, or both.
+ * If you want to enforce that a Kotlin class only be used as an input or output type,
+ * include this annotation with the preferred location parameter.
+ *
+ * By default, classes will be allowed as both input and output types.
+ */
+annotation class GraphQLValidObjectLocations(val locations: Array<Locations>) {
+    enum class Locations {
+        OBJECT,
+        INPUT_OBJECT
+    }
+}

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

@@ -0,0 +1,26 @@
+/*
+ * 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.generator.exceptions
+
+import com.expediagroup.graphql.generator.annotations.GraphQLValidObjectLocations
+import kotlin.reflect.KClass
+
+/**
+ * Thrown when the schema is using a Kotlin class in an invalid location marked by [GraphQLValidObjectLocations].
+ */
+class InvalidObjectLocationException(kClass: KClass<*>, validLocations: Array<GraphQLValidObjectLocations.Locations>) :
+    GraphQLKotlinException("The class $kClass was used in an invalid location. Only $validLocations are allowed")

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

@@ -17,15 +17,19 @@
 package com.expediagroup.graphql.generator.internal.types
 
 import com.expediagroup.graphql.generator.SchemaGenerator
+import com.expediagroup.graphql.generator.annotations.GraphQLValidObjectLocations
 import com.expediagroup.graphql.generator.internal.extensions.getGraphQLDescription
 import com.expediagroup.graphql.generator.internal.extensions.getSimpleName
 import com.expediagroup.graphql.generator.internal.extensions.getValidProperties
 import com.expediagroup.graphql.generator.internal.extensions.safeCast
+import com.expediagroup.graphql.generator.internal.types.utils.validateObjectLocation
 import graphql.introspection.Introspection.DirectiveLocation
 import graphql.schema.GraphQLInputObjectType
 import kotlin.reflect.KClass
 
 internal fun generateInputObject(generator: SchemaGenerator, kClass: KClass<*>): GraphQLInputObjectType {
+    validateObjectLocation(kClass, GraphQLValidObjectLocations.Locations.INPUT_OBJECT)
+
     val builder = GraphQLInputObjectType.newInputObject()
 
     builder.name(kClass.getSimpleName(isInputClass = true))

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

@@ -17,13 +17,15 @@
 package com.expediagroup.graphql.generator.internal.types
 
 import com.expediagroup.graphql.generator.SchemaGenerator
+import com.expediagroup.graphql.generator.annotations.GraphQLValidObjectLocations
 import com.expediagroup.graphql.generator.extensions.unwrapType
 import com.expediagroup.graphql.generator.internal.extensions.getGraphQLDescription
 import com.expediagroup.graphql.generator.internal.extensions.getSimpleName
 import com.expediagroup.graphql.generator.internal.extensions.getValidFunctions
 import com.expediagroup.graphql.generator.internal.extensions.getValidProperties
 import com.expediagroup.graphql.generator.internal.extensions.getValidSuperclasses
 import com.expediagroup.graphql.generator.internal.extensions.safeCast
+import com.expediagroup.graphql.generator.internal.types.utils.validateObjectLocation
 import graphql.introspection.Introspection.DirectiveLocation
 import graphql.schema.GraphQLInterfaceType
 import graphql.schema.GraphQLObjectType
@@ -32,6 +34,8 @@ import kotlin.reflect.KClass
 import kotlin.reflect.full.createType
 
 internal fun generateObject(generator: SchemaGenerator, kClass: KClass<*>): GraphQLObjectType {
+    validateObjectLocation(kClass, GraphQLValidObjectLocations.Locations.OBJECT)
+
     val builder = GraphQLObjectType.newObject()
 
     val name = kClass.getSimpleName()

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

@@ -0,0 +1,34 @@
+/*
+ * 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.generator.internal.types.utils
+
+import com.expediagroup.graphql.generator.annotations.GraphQLValidObjectLocations
+import com.expediagroup.graphql.generator.exceptions.InvalidObjectLocationException
+import kotlin.reflect.KClass
+import kotlin.reflect.full.findAnnotation
+
+/**
+ * Throws an exception if this KClass was used in an invalid location
+ */
+internal fun validateObjectLocation(kClass: KClass<*>, location: GraphQLValidObjectLocations.Locations) {
+    kClass.findAnnotation<GraphQLValidObjectLocations>()?.let { annotation ->
+        val validLocations = annotation.locations
+        if (!validLocations.contains(location)) {
+            throw InvalidObjectLocationException(kClass, validLocations)
+        }
+    }
+}

generator/graphql-kotlin-schema-generator/src/test/kotlin/com/expediagroup/graphql/generator/internal/types/GenerateInputObjectTest.kt

@@ -18,27 +18,41 @@ package com.expediagroup.graphql.generator.internal.types
 
 import com.expediagroup.graphql.generator.annotations.GraphQLDescription
 import com.expediagroup.graphql.generator.annotations.GraphQLName
+import com.expediagroup.graphql.generator.annotations.GraphQLValidObjectLocations
+import com.expediagroup.graphql.generator.exceptions.InvalidObjectLocationException
 import com.expediagroup.graphql.generator.test.utils.SimpleDirective
 import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertDoesNotThrow
 import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
 
-internal class GenerateInputObjectTest : TypeTestHelper() {
+class GenerateInputObjectTest : TypeTestHelper() {
 
     @Suppress("Detekt.UnusedPrivateClass")
     @GraphQLDescription("The truth")
     @SimpleDirective
-    private class InputClass {
+    class InputClass {
         @SimpleDirective
         val myField: String = "car"
     }
 
     @Suppress("Detekt.UnusedPrivateClass")
     @GraphQLName("InputClassRenamed")
-    private class InputClassCustomName {
+    class InputClassCustomName {
         @GraphQLName("myFieldRenamed")
         val myField: String = "car"
     }
 
+    @GraphQLValidObjectLocations(locations = [GraphQLValidObjectLocations.Locations.INPUT_OBJECT])
+    class InputOnly {
+        val myField: String = "car"
+    }
+
+    @GraphQLValidObjectLocations(locations = [GraphQLValidObjectLocations.Locations.OBJECT])
+    class OutputOnly {
+        val myField: String = "car"
+    }
+
     @Test
     fun `Test naming`() {
         val result = generateInputObject(generator, InputClass::class)
@@ -77,4 +91,18 @@ internal class GenerateInputObjectTest : TypeTestHelper() {
         assertEquals(1, result.fields.first().directives.size)
         assertEquals("simpleDirective", result.fields.first().directives.first().name)
     }
+
+    @Test
+    fun `input only objects are generated`() {
+        assertDoesNotThrow {
+            generateInputObject(generator, InputOnly::class)
+        }
+    }
+
+    @Test
+    fun `output only objects throw an exception`() {
+        assertFailsWith(InvalidObjectLocationException::class) {
+            generateInputObject(generator, OutputOnly::class)
+        }
+    }
 }

generator/graphql-kotlin-schema-generator/src/test/kotlin/com/expediagroup/graphql/generator/internal/types/GenerateObjectTest.kt

@@ -19,33 +19,47 @@ package com.expediagroup.graphql.generator.internal.types
 import com.expediagroup.graphql.generator.annotations.GraphQLDescription
 import com.expediagroup.graphql.generator.annotations.GraphQLDirective
 import com.expediagroup.graphql.generator.annotations.GraphQLName
+import com.expediagroup.graphql.generator.annotations.GraphQLValidObjectLocations
+import com.expediagroup.graphql.generator.exceptions.InvalidObjectLocationException
 import graphql.Scalars
 import graphql.introspection.Introspection
 import graphql.schema.GraphQLNonNull
 import graphql.schema.GraphQLObjectType
 import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertDoesNotThrow
 import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
 import kotlin.test.assertNotNull
 import kotlin.test.assertTrue
 
 class GenerateObjectTest : TypeTestHelper() {
 
     @GraphQLDirective(locations = [Introspection.DirectiveLocation.OBJECT])
-    internal annotation class ObjectDirective(val arg: String)
+    annotation class ObjectDirective(val arg: String)
 
     @GraphQLDescription("The truth")
     @ObjectDirective("Don't worry")
-    private class BeHappy
+    class BeHappy
 
     @GraphQLName("BeHappyRenamed")
-    private class BeHappyCustomName
+    class BeHappyCustomName
 
     interface MyInterface {
         val foo: String
     }
 
     class ClassWithInterface(override val foo: String) : MyInterface
 
+    @GraphQLValidObjectLocations(locations = [GraphQLValidObjectLocations.Locations.INPUT_OBJECT])
+    class InputOnly {
+        val myField: String = "car"
+    }
+
+    @GraphQLValidObjectLocations(locations = [GraphQLValidObjectLocations.Locations.OBJECT])
+    class OutputOnly {
+        val myField: String = "car"
+    }
+
     @Test
     fun `Test naming`() {
         val result = generateObject(generator, BeHappy::class) as? GraphQLObjectType
@@ -91,4 +105,18 @@ class GenerateObjectTest : TypeTestHelper() {
         assertEquals(1, result.interfaces.size)
         assertEquals(1, result.fieldDefinitions.size)
     }
+
+    @Test
+    fun `input only objects are generated`() {
+        assertDoesNotThrow {
+            generateInputObject(generator, InputOnly::class)
+        }
+    }
+
+    @Test
+    fun `output only objects throw an exception`() {
+        assertFailsWith(InvalidObjectLocationException::class) {
+            generateInputObject(generator, OutputOnly::class)
+        }
+    }
 }

generator/graphql-kotlin-schema-generator/src/test/kotlin/com/expediagroup/graphql/generator/internal/types/utils/ValidateObjectLocationKtTest.kt

@@ -0,0 +1,74 @@
+/*
+ * 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.generator.internal.types.utils
+
+import com.expediagroup.graphql.generator.annotations.GraphQLValidObjectLocations
+import com.expediagroup.graphql.generator.annotations.GraphQLValidObjectLocations.Locations
+import com.expediagroup.graphql.generator.exceptions.InvalidObjectLocationException
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertDoesNotThrow
+import kotlin.test.assertFailsWith
+
+class ValidateObjectLocationKtTest {
+
+    class SimpleClass
+
+    @GraphQLValidObjectLocations([Locations.INPUT_OBJECT, Locations.OBJECT])
+    class InputAndOutput
+
+    @GraphQLValidObjectLocations([Locations.INPUT_OBJECT])
+    class InputOnly
+
+    @GraphQLValidObjectLocations([Locations.OBJECT])
+    class OutputOnly
+
+    @Test
+    fun `does nothing on class missing annotation`() {
+        assertDoesNotThrow {
+            validateObjectLocation(SimpleClass::class, Locations.INPUT_OBJECT)
+            validateObjectLocation(SimpleClass::class, Locations.OBJECT)
+        }
+    }
+
+    @Test
+    fun `allows all locations on class with all locations`() {
+        assertDoesNotThrow {
+            validateObjectLocation(InputAndOutput::class, Locations.INPUT_OBJECT)
+            validateObjectLocation(InputAndOutput::class, Locations.OBJECT)
+        }
+    }
+
+    @Test
+    fun `validates input only classes`() {
+        assertDoesNotThrow {
+            validateObjectLocation(InputOnly::class, Locations.INPUT_OBJECT)
+        }
+        assertFailsWith(InvalidObjectLocationException::class) {
+            validateObjectLocation(InputOnly::class, Locations.OBJECT)
+        }
+    }
+
+    @Test
+    fun `validates output only classes`() {
+        assertDoesNotThrow {
+            validateObjectLocation(OutputOnly::class, Locations.OBJECT)
+        }
+        assertFailsWith(InvalidObjectLocationException::class) {
+            validateObjectLocation(OutputOnly::class, Locations.INPUT_OBJECT)
+        }
+    }
+}

website/docs/schema-generator/customizing-schemas/restricting-input-output.md

@@ -0,0 +1,29 @@
+---
+id: restricting-input-output
+title: Restricting Input and Output Types
+---
+
+Since we are using Kotlin classes to represent both GraphQL input and output objects we can use the same class for both and the generator will handle type conflicts.
+
+If you want to enforce that a type should never be used as an input or output you can use the `@GraphQLValidObjectLocations` annotation.
+If the class was used in the schema in an invalid location an exception will be thrown.
+
+```kotlin
+class SimpleClass(val value: String)
+
+@GraphQLValidObjectLocations([Locations.INPUT_OBJECT])
+class InputOnly(val value: String)
+
+@GraphQLValidObjectLocations([Locations.OBJECT])
+class OutputOnly(val value: String)
+
+// Valid Usage
+fun output1() = SimpleClass("foo")
+fun output2() = OutputOnly("foo")
+fun input1(input: SimpleClass) = "value was ${input.value}"
+fun input2(input: InputOnly) = "value was ${input.value}"
+
+// Throws Exception
+fun output3() = InputOnly("foo")
+fun input3(input: OutputOnly) = "value was ${input.value}"
+```

website/sidebars.json

@@ -33,6 +33,7 @@
           "schema-generator/customizing-schemas/renaming-fields",
           "schema-generator/customizing-schemas/directives",
           "schema-generator/customizing-schemas/deprecating-schema",
+          "schema-generator/customizing-schemas/restricting-input-output",
           "schema-generator/customizing-schemas/advanced-features"
         ]
       },