BREAKING CHANGE: Change GraphQLContext from annotation to interface

Instead of using an annotation and having to remember to include it in function arguments, we can create a marker interface for the GraphQLContext which library users can implement on a class to indicate that this class is the GraphQLContext. This moves the declaration from the arguments to the class itself which I think makes it more clear.

This is obviously a large breaking change to fundamental part of our library. It requires heavy documentation changes and review to take place before the 2.0 release. Please review and provided feedback on the interface package path as well

Author: Shane Myrick

examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/context/MyGraphQLContext.kt

@@ -16,11 +16,11 @@
 
 package com.expediagroup.graphql.examples.context
 
-import com.expediagroup.graphql.annotations.GraphQLContext
+import com.expediagroup.graphql.execution.GraphQLContext
 import org.springframework.http.server.reactive.ServerHttpRequest
 import org.springframework.http.server.reactive.ServerHttpResponse
 
 /**
  * Simple [GraphQLContext] that holds extra value.
  */
-class MyGraphQLContext(val myCustomValue: String, val request: ServerHttpRequest, val response: ServerHttpResponse, var subscriptionValue: String? = null)
+class MyGraphQLContext(val myCustomValue: String, val request: ServerHttpRequest, val response: ServerHttpResponse, var subscriptionValue: String? = null) : GraphQLContext

examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/query/ContextualQuery.kt

@@ -16,7 +16,6 @@
 
 package com.expediagroup.graphql.examples.query
 
-import com.expediagroup.graphql.annotations.GraphQLContext
 import com.expediagroup.graphql.annotations.GraphQLDescription
 import com.expediagroup.graphql.examples.context.MyGraphQLContext
 import com.expediagroup.graphql.examples.model.ContextualResponse
@@ -37,6 +36,6 @@ class ContextualQuery : Query {
     fun contextualQuery(
         @GraphQLDescription("some value that will be returned to the user")
         value: Int,
-        @GraphQLContext context: MyGraphQLContext
+        context: MyGraphQLContext
     ): ContextualResponse = ContextualResponse(value, context.myCustomValue)
 }

examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/subscriptions/SimpleSubscription.kt

@@ -16,7 +16,6 @@
 
 package com.expediagroup.graphql.examples.subscriptions
 
-import com.expediagroup.graphql.annotations.GraphQLContext
 import com.expediagroup.graphql.annotations.GraphQLDescription
 import com.expediagroup.graphql.examples.context.MyGraphQLContext
 import com.expediagroup.graphql.spring.operations.Subscription
@@ -62,6 +61,6 @@ class SimpleSubscription : Subscription {
     fun flow(): Publisher<Int> = flowOf(1, 2, 4).asPublisher()
 
     @GraphQLDescription("Returns a value from the subscription context")
-    fun subscriptionContext(@GraphQLContext myGraphQLContext: MyGraphQLContext): Publisher<String> =
+    fun subscriptionContext(myGraphQLContext: MyGraphQLContext): Publisher<String> =
         flowOf(myGraphQLContext.subscriptionValue ?: "", "value 2", "value3").asPublisher()
 }

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/annotations/GraphQLContext.kt renamed to graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/execution/GraphQLContext.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.
@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
-package com.expediagroup.graphql.annotations
+package com.expediagroup.graphql.execution
 
 /**
- * Mark something for the GraphQL context.
+ * Marker interface to indicate that the implementing class should be considered
+ * as the GraphQL context. This means the implementing class will not appear in the schema.
  */
-annotation class GraphQLContext
+interface GraphQLContext

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

@@ -16,18 +16,17 @@
 
 package com.expediagroup.graphql.generator.extensions
 
-import com.expediagroup.graphql.annotations.GraphQLContext
 import com.expediagroup.graphql.exceptions.CouldNotGetNameOfKParameterException
+import com.expediagroup.graphql.execution.GraphQLContext
 import graphql.schema.DataFetchingEnvironment
 import kotlin.reflect.KParameter
-import kotlin.reflect.full.findAnnotation
 import kotlin.reflect.full.isSubclassOf
 
 internal fun KParameter.isInterface() = this.type.getKClass().isInterface()
 
 internal fun KParameter.isList() = this.type.getKClass().isSubclassOf(List::class)
 
-internal fun KParameter.isGraphQLContext() = this.findAnnotation<GraphQLContext>() != null
+internal fun KParameter.isGraphQLContext() = this.type.getKClass().isSubclassOf(GraphQLContext::class)
 
 internal fun KParameter.isDataFetchingEnvironment() = this.type.classifier == DataFetchingEnvironment::class
 

graphql-kotlin-schema-generator/src/test/kotlin/com/expediagroup/graphql/execution/FunctionDataFetcherTest.kt

@@ -16,7 +16,6 @@
 
 package com.expediagroup.graphql.execution
 
-import com.expediagroup.graphql.annotations.GraphQLContext
 import com.expediagroup.graphql.annotations.GraphQLName
 import com.fasterxml.jackson.annotation.JsonProperty
 import graphql.GraphQLException
@@ -34,14 +33,16 @@ import kotlin.test.assertTrue
 
 internal class FunctionDataFetcherTest {
 
+    internal class MyContext(val value: String) : GraphQLContext
+
     internal class MyClass {
         fun print(string: String) = string
 
         fun printArray(items: Array<String>) = items.joinToString(separator = ":")
 
         fun printList(items: List<String>) = items.joinToString(separator = ":")
 
-        fun context(@GraphQLContext string: String) = string
+        fun context(myContext: MyContext) = myContext.value
 
         fun dataFetchingEnvironment(environment: DataFetchingEnvironment): String = environment.field.name
 
@@ -95,7 +96,7 @@ internal class FunctionDataFetcherTest {
     fun `valid target with context`() {
         val dataFetcher = FunctionDataFetcher(target = MyClass(), fn = MyClass::context)
         val mockEnvironmet: DataFetchingEnvironment = mockk()
-        every { mockEnvironmet.getContext<String>() } returns "foo"
+        every { mockEnvironmet.getContext<MyContext>() } returns MyContext("foo")
         assertEquals(expected = "foo", actual = dataFetcher.get(mockEnvironmet))
     }
 

graphql-kotlin-schema-generator/src/test/kotlin/com/expediagroup/graphql/generator/extensions/KFunctionExtensionsKtTest.kt

@@ -16,8 +16,8 @@
 
 package com.expediagroup.graphql.generator.extensions
 
-import com.expediagroup.graphql.annotations.GraphQLContext
 import com.expediagroup.graphql.annotations.GraphQLIgnore
+import com.expediagroup.graphql.execution.GraphQLContext
 import graphql.schema.DataFetchingEnvironment
 import org.junit.jupiter.api.Test
 import kotlin.test.assertEquals
@@ -39,7 +39,7 @@ internal class KFunctionExtensionsKtTest {
     }
 
     @Test
-    fun `getValidArguments should ignore @GraphQLContext`() {
+    fun `getValidArguments should ignore GraphQLContext`() {
         val args = TestingClass::context.getValidArguments()
         assertEquals(expected = 1, actual = args.size)
         assertEquals(expected = "notContext", actual = args.first().getName())
@@ -57,7 +57,7 @@ internal class KFunctionExtensionsKtTest {
 
         fun ignored(@GraphQLIgnore ignoredArg: String, notIgnored: String) = "$ignoredArg and $notIgnored"
 
-        fun context(@GraphQLContext contextArg: String, notContext: String) = "$contextArg and $notContext"
+        fun context(contextArg: GraphQLContext, notContext: String) = "$contextArg and $notContext"
 
         fun dataFetchingEnvironment(environment: DataFetchingEnvironment, notEnvironment: String): String = "${environment.field.name} and $notEnvironment"
     }

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

@@ -16,15 +16,14 @@
 
 package com.expediagroup.graphql.generator.types
 
-import com.expediagroup.graphql.annotations.GraphQLContext
 import com.expediagroup.graphql.annotations.GraphQLDescription
 import com.expediagroup.graphql.annotations.GraphQLDirective
 import com.expediagroup.graphql.annotations.GraphQLIgnore
 import com.expediagroup.graphql.annotations.GraphQLName
 import com.expediagroup.graphql.exceptions.TypeNotSupportedException
 import com.expediagroup.graphql.execution.FunctionDataFetcher
+import com.expediagroup.graphql.execution.GraphQLContext
 import graphql.ExceptionWhileDataFetching
-import graphql.Scalars
 import graphql.Scalars.GraphQLInt
 import graphql.Scalars.GraphQLString
 import graphql.execution.DataFetcherResult
@@ -58,6 +57,8 @@ internal class GenerateFunctionTest : TypeTestHelper() {
         override fun nestedReturnType(): MyImplementation = MyImplementation()
     }
 
+    internal class MyContext(val value: String) : GraphQLContext
+
     @GraphQLDirective(locations = [Introspection.DirectiveLocation.FIELD_DEFINITION])
     internal annotation class FunctionDirective(val arg: String)
 
@@ -73,7 +74,7 @@ internal class GenerateFunctionTest : TypeTestHelper() {
         @GraphQLName("renamedFunction")
         fun originalName(input: String) = input
 
-        fun context(@GraphQLContext context: String, string: String) = "$context and $string"
+        fun context(context: MyContext, string: String) = "${context.value} and $string"
 
         fun ignoredParameter(color: String, @GraphQLIgnore ignoreMe: String) = "$color and $ignoreMe"
 
@@ -141,7 +142,7 @@ internal class GenerateFunctionTest : TypeTestHelper() {
         assertEquals("functionDirective", directive.name)
         assertEquals("happy", directive.arguments[0].value)
         assertEquals("arg", directive.arguments[0].name)
-        assertEquals(GraphQLNonNull(Scalars.GraphQLString), directive.arguments[0].type)
+        assertEquals(GraphQLNonNull(GraphQLString), directive.arguments[0].type)
         assertEquals(
             directive.validLocations()?.toSet(),
             setOf(Introspection.DirectiveLocation.FIELD_DEFINITION)

graphql-kotlin-spring-server/src/test/kotlin/com/expediagroup/graphql/spring/context/GraphQLContextFactoryIT.kt

@@ -16,7 +16,7 @@
 
 package com.expediagroup.graphql.spring.context
 
-import com.expediagroup.graphql.annotations.GraphQLContext
+import com.expediagroup.graphql.execution.GraphQLContext
 import com.expediagroup.graphql.spring.execution.GRAPHQL_CONTEXT_FILTER_ODER
 import com.expediagroup.graphql.spring.execution.GraphQLContextFactory
 import com.expediagroup.graphql.spring.model.GraphQLRequest
@@ -86,8 +86,8 @@ class GraphQLContextFactoryIT(@Autowired private val testClient: WebTestClient)
     }
 
     class ContextualQuery : Query {
-        fun context(@GraphQLContext ctx: CustomContext): CustomContext = ctx
+        fun context(ctx: CustomContext): CustomContext = ctx
     }
 
-    data class CustomContext(val first: String?, val second: String?)
+    data class CustomContext(val first: String?, val second: String?) : GraphQLContext
 }

graphql-kotlin-spring-server/src/test/kotlin/com/expediagroup/graphql/spring/execution/QueryHandlerTest.kt

@@ -18,8 +18,8 @@ package com.expediagroup.graphql.spring.execution
 
 import com.expediagroup.graphql.SchemaGeneratorConfig
 import com.expediagroup.graphql.TopLevelObject
-import com.expediagroup.graphql.annotations.GraphQLContext
 import com.expediagroup.graphql.exceptions.GraphQLKotlinException
+import com.expediagroup.graphql.execution.GraphQLContext
 import com.expediagroup.graphql.spring.exception.SimpleKotlinGraphQLError
 import com.expediagroup.graphql.spring.model.GraphQLRequest
 import com.expediagroup.graphql.toSchema
@@ -153,8 +153,8 @@ class QueryHandlerTest {
 
         fun alwaysThrows(): String = throw GraphQLKotlinException("JUNIT Failure")
 
-        fun contextualValue(@GraphQLContext context: MyContext): String = context.value ?: "default"
+        fun contextualValue(context: MyContext): String = context.value ?: "default"
     }
 
-    data class MyContext(val value: String? = null)
+    data class MyContext(val value: String? = null) : GraphQLContext
 }

graphql-kotlin-spring-server/src/test/kotlin/com/expediagroup/graphql/spring/execution/SubscriptionHandlerTest.kt

@@ -18,8 +18,8 @@ package com.expediagroup.graphql.spring.execution
 
 import com.expediagroup.graphql.SchemaGeneratorConfig
 import com.expediagroup.graphql.TopLevelObject
-import com.expediagroup.graphql.annotations.GraphQLContext
 import com.expediagroup.graphql.exceptions.GraphQLKotlinException
+import com.expediagroup.graphql.execution.GraphQLContext
 import com.expediagroup.graphql.spring.model.GraphQLRequest
 import com.expediagroup.graphql.toSchema
 import graphql.ErrorType
@@ -119,10 +119,10 @@ class SubscriptionHandlerTest {
 
         fun alwaysThrows(): Flux<String> = Flux.error(GraphQLKotlinException("JUNIT subscription failure"))
 
-        fun contextualTicker(@GraphQLContext context: SubscriptionContext): Flux<String> = Flux.range(1, 5)
+        fun contextualTicker(context: SubscriptionContext): Flux<String> = Flux.range(1, 5)
                 .delayElements(Duration.ofMillis(100))
                 .map { "${context.value}:${Random.nextInt(100)}" }
     }
 
-    data class SubscriptionContext(val value: String)
+    data class SubscriptionContext(val value: String) : GraphQLContext
 }

graphql-kotlin-spring-server/src/test/kotlin/com/expediagroup/graphql/spring/execution/SubscriptionWebSocketHandlerIT.kt

@@ -16,7 +16,7 @@
 
 package com.expediagroup.graphql.spring.execution
 
-import com.expediagroup.graphql.annotations.GraphQLContext
+import com.expediagroup.graphql.execution.GraphQLContext
 import com.expediagroup.graphql.spring.model.GraphQLRequest
 import com.expediagroup.graphql.spring.model.SubscriptionOperationMessage
 import com.expediagroup.graphql.spring.model.SubscriptionOperationMessage.ClientMessages.GQL_CONNECTION_INIT
@@ -196,10 +196,10 @@ class SubscriptionWebSocketHandlerIT(@LocalServerPort private var port: Int) {
             .delayElements(Duration.ofMillis(100))
             .map { Random.nextInt() }
 
-        fun ticker(@GraphQLContext ctx: SubscriptionContext): Flux<String> = Flux.just("${ctx.value}:${Random.nextInt()}")
+        fun ticker(ctx: SubscriptionContext): Flux<String> = Flux.just("${ctx.value}:${Random.nextInt()}")
     }
 
-    data class SubscriptionContext(val value: String)
+    data class SubscriptionContext(val value: String) : GraphQLContext
 
     private fun SubscriptionOperationMessage.toJson() = objectMapper.writeValueAsString(this)
 }

graphql-kotlin-spring-server/src/test/kotlin/com/expediagroup/graphql/spring/routes/RouteConfigurationIT.kt

@@ -16,7 +16,7 @@
 
 package com.expediagroup.graphql.spring.routes
 
-import com.expediagroup.graphql.annotations.GraphQLContext
+import com.expediagroup.graphql.execution.GraphQLContext
 import com.expediagroup.graphql.spring.REQUEST_PARAM_OPERATION_NAME
 import com.expediagroup.graphql.spring.REQUEST_PARAM_QUERY
 import com.expediagroup.graphql.spring.REQUEST_PARAM_VARIABLES
@@ -60,10 +60,10 @@ class RouteConfigurationIT(@Autowired private val testClient: WebTestClient) {
     class SimpleQuery : Query {
         fun hello(name: String) = "Hello $name!"
 
-        fun context(@GraphQLContext ctx: CustomContext) = ctx.value
+        fun context(ctx: CustomContext) = ctx.value
     }
 
-    data class CustomContext(val value: String)
+    data class CustomContext(val value: String) : GraphQLContext
 
     @Test
     fun `verify SDL route`() {