Update spring-server to use FlowSubscriptionSchemaGeneratorHooks (ExpediaGroup#1479)

Currently the `spring-server` automatically configures the subscription strategy that supports Kotlin `Flow`  but does not configure the hooks neccessary to use it. Updating `SubscriptionAutoConfiguration` to create `FlowSubscriptionSchemaGeneratorHooks` if bean is not available.

Cleaned up the federation docs to highlight that both hooks and execution strategy are needed for using `Flow`s in subscriptions. Added a note that the subscription protocol implemented in `spring-server` is deprecated.

Author: dariuszkuc

servers/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/server/spring/SubscriptionAutoConfiguration.kt

@@ -17,6 +17,8 @@
 package com.expediagroup.graphql.server.spring
 
 import com.expediagroup.graphql.dataloader.KotlinDataLoaderRegistryFactory
+import com.expediagroup.graphql.generator.hooks.FlowSubscriptionSchemaGeneratorHooks
+import com.expediagroup.graphql.generator.hooks.SchemaGeneratorHooks
 import com.expediagroup.graphql.server.operations.Subscription
 import com.expediagroup.graphql.server.spring.subscriptions.ApolloSubscriptionHooks
 import com.expediagroup.graphql.server.spring.subscriptions.ApolloSubscriptionProtocolHandler
@@ -54,6 +56,10 @@ private const val URL_HANDLER_ORDER = 0
 @Import(GraphQLSchemaConfiguration::class)
 class SubscriptionAutoConfiguration {
 
+    @Bean
+    @ConditionalOnMissingBean
+    fun flowSubscriptionSchemaGeneratorHooks(): SchemaGeneratorHooks = FlowSubscriptionSchemaGeneratorHooks()
+
     @Bean
     @ConditionalOnMissingBean
     fun subscriptionHandler(

servers/graphql-kotlin-spring-server/src/test/kotlin/com/expediagroup/graphql/server/spring/SubscriptionConfigurationTest.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.
@@ -17,6 +17,8 @@
 package com.expediagroup.graphql.server.spring
 
 import com.expediagroup.graphql.generator.SchemaGeneratorConfig
+import com.expediagroup.graphql.generator.hooks.FlowSubscriptionSchemaGeneratorHooks
+import com.expediagroup.graphql.generator.hooks.SchemaGeneratorHooks
 import com.expediagroup.graphql.server.execution.GraphQLRequestHandler
 import com.expediagroup.graphql.server.operations.Query
 import com.expediagroup.graphql.server.operations.Subscription
@@ -41,6 +43,7 @@ import java.time.Duration
 import kotlin.random.Random
 import kotlin.test.assertEquals
 import kotlin.test.assertNotNull
+import kotlin.test.assertTrue
 
 class SubscriptionConfigurationTest {
 
@@ -55,6 +58,7 @@ class SubscriptionConfigurationTest {
                 assertThat(ctx).hasSingleBean(SchemaGeneratorConfig::class.java)
                 val schemaGeneratorConfig = ctx.getBean(SchemaGeneratorConfig::class.java)
                 assertEquals(listOf("com.expediagroup.graphql.server.spring"), schemaGeneratorConfig.supportedPackages)
+                assertTrue(schemaGeneratorConfig.hooks is FlowSubscriptionSchemaGeneratorHooks)
 
                 assertThat(ctx).hasSingleBean(GraphQLSchema::class.java)
                 val schema = ctx.getBean(GraphQLSchema::class.java)
@@ -80,6 +84,9 @@ class SubscriptionConfigurationTest {
             .run { ctx ->
                 val customConfiguration = ctx.getBean(CustomSubscriptionConfiguration::class.java)
 
+                assertThat(ctx).hasSingleBean(SchemaGeneratorHooks::class.java)
+                assertThat(ctx).getBean(SchemaGeneratorHooks::class.java)
+                    .isSameAs(customConfiguration.customHooks())
                 assertThat(ctx).hasSingleBean(SchemaGeneratorConfig::class.java)
                 assertThat(ctx).hasSingleBean(GraphQLSchema::class.java)
 
@@ -114,6 +121,11 @@ class SubscriptionConfigurationTest {
     @Configuration
     class CustomSubscriptionConfiguration {
 
+        @Bean
+        fun customHooks(): SchemaGeneratorHooks = object : FlowSubscriptionSchemaGeneratorHooks() {
+            // custom hooks
+        }
+
         // in regular apps object mapper will be created by JacksonAutoConfiguration
         @Bean
         fun objectMapper(): ObjectMapper = jacksonObjectMapper()

website/docs/schema-generator/execution/subscriptions.md

@@ -4,7 +4,7 @@ title: Subscriptions
 ---
 Subscriptions are supported with `graphql-java`. See their documentation first:
 
-https://www.graphql-java.com/documentation/v16/subscriptions/
+https://www.graphql-java.com/documentation/subscriptions
 
 To make a function a subscription function you just have to have the return type wrapped in an implementation of a
 reactive-streams `Publisher<T>`. As an example, here is a function that uses Spring WebFlux to return a random number every
@@ -26,23 +26,37 @@ toSchema(
 )
 ```
 
-### Flow Support
+## Flow Support
 
-`graphql-kotlin` provides support for Kotlin `Flow` through `FlowSubscriptionExecutionStrategy`. Thanks to the Kotlin
-coroutines interoperability, this strategy also works with any `Publisher` and will automatically convert them to a `Flow`.
+`graphql-kotlin` provides support for Kotlin `Flow` through `FlowSubscriptionSchemaGeneratorHooks` and `FlowSubscriptionExecutionStrategy`.
+Both hooks and execution strategy have to be configured in order to support `Flow` in your GraphQL server.
 
-### Subscription Hooks
+`FlowSubscriptionSchemaGeneratorHooks` are custom hooks that provide support for using `Flow` return type within the
+GraphQL server.
 
-#### `didGenerateSubscriptionType`
-This hook is called after a new subscription type is generated but before it is added to the schema. The other generator hooks are still called so you can add logic for the types and
-validation of subscriptions the same as queries and mutations.
+`FlowSubscriptionExecutionStrategy` is a reimplementation of the `graphql-java` default `SubscriptionExecutionStrategy`
+that adds support for handling Kotlin `Flow` types. Thanks to the Kotlin coroutines interoperability, this strategy works
+with any `Publisher` and will automatically convert any `Flow`s to a `Publisher`.
 
-#### `isValidSubscriptionReturnType`
-This hook is called when generating the functions for each subscription. It allows for changing the rules of what classes can be used as the return type. By default, graphql-java supports `org.reactivestreams.Publisher`.
+## Subscription Hooks
 
-To effectively use this hook, you should also override the `willResolveMonad` hook, and if you are using `graphql-kotlin-spring-server` you should override the `GraphQL` bean to specify a custom subscription execution strategy.
+### `willResolveMonad`
 
-### Server Implementation
+This hooks is called before resolving Kotlin return type to a GraphQL type and can be used to provide support for additional
+monads (e.g. Kotlin `Flow`).
+
+### `didGenerateSubscriptionType`
+This hook is called after a new subscription type is generated but before it is added to the schema. The other generator
+hooks are still called so you can add logic for the types and validation of subscriptions the same as queries and mutations.
+
+### `isValidSubscriptionReturnType`
+This hook is called when generating the functions for each subscription. It allows for changing the rules of what classes
+can be used as the return type. By default, graphql-java supports `org.reactivestreams.Publisher`.
+
+To effectively use this hook, you should also override the `willResolveMonad` hook to support the additional subscription
+return type. Your GraphQL server may also require a custom subscription execution strategy in order to process it at runtime.
+
+## Server Implementation
 
 The server that runs your GraphQL schema will have to support some method for subscriptions, like WebSockets.
 `graphql-kotlin-spring-server` provides a default WebSocket based implementation. See more details in the

website/docs/schema-generator/federation/apollo-federation.mdx

@@ -90,7 +90,7 @@ This class extends the [base configuration class](../customizing-schemas/generat
 You can see the definition for `toFederatedSchema` [in the
 source](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/toFederatedSchema.kt).
 
-## Example
+### Example
 
 ```kotlin
 @KeyDirective(fields = FieldSet("id"))
@@ -146,3 +146,8 @@ type User @key(fields : "id") {
    name: String!
 }
 ```
+
+## Limitations
+
+Apollo Federation currently does not support subscriptions. See [Apollo blog](https://www.apollographql.com/blog/backend/federation/using-subscriptions-with-your-federated-data-graph/)
+for a workaround.

website/docs/server/server-subscriptions.md

@@ -6,6 +6,6 @@ If you are using one of the official server implementations for GraphQL Kotlin,
 
 -   See `graphql-kotlin-spring-server` [subscriptions](spring-server/spring-subscriptions.md)
 
-Subscriptions require a more indepth knoweldge of how the specific server library handles protocols and streaming.
+Subscriptions require a more in-depth knowledge of how the specific server library handles protocols and streaming.
 Since we can only support `Publisher` from `graphql-java` in this common library, we can not provide any common logic for subscriptions.
-Therefore you will still need to implement the route and request handling for subscriptions separately if you are not using a provided server implementation.
+Therefore, you will still need to implement the route and request handling for subscriptions separately if you are not using a provided server implementation.

website/docs/server/spring-server/spring-subscriptions.md

@@ -7,12 +7,20 @@ This page lists the `graphql-kotlin-spring-server` specific features._
 
 ## Flow Support
 
-`graphql-kotlin-spring-server` provides automatic support for Kotlin `Flow` through `FlowSubscriptionExecutionStrategy`
-that supports existing `Publisher`s and relies on Kotlin reactive-streams interop to convert `Flow` to a `Publisher`.
+`graphql-kotlin-spring-server` provides automatic support for Kotlin `Flow` by automatically configuring `FlowSubscriptionSchemaGeneratorHooks`
+and `FlowSubscriptionExecutionStrategy` beans.
 
-## `graphql-ws` subprotocol
+:::info
+If you define your subscriptions using Kotlin `Flow`, make sure to extend `FlowSubscriptionSchemaGeneratorHooks` whenever you need to provide some custom hooks.
+:::
 
-We have implemented subscriptions in Spring WebSockets following the [`graphql-ws` subprotocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md) defined by Apollo.
+## `subscriptions-transport-ws` subprotocol
+
+:::caution
+`subscriptions-transport-ws` was deprecated in favor of [`graphql-ws` protocol](https://github.com/enisdenjo/graphql-ws).
+:::
+
+We have implemented subscriptions in Spring WebSockets following the [`subscriptions-transport-ws` subprotocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md) defined by Apollo.
 This requires that your client send and parse messages in a specific format.
 
 If you would like to implement your own subscription handler, you can provide a primary spring bean for `HandlerMapping` that overrides the [default one](./spring-beans.md) which sets the url for subscriptions to the Apollo subscription handler.