feat: First support for schema stitching (#195)

This adds first support for schema stitching without aiming for full
feature compatibility. And while I have a pretty extensive internal use
case, schema stitching is still to be considered experimental and
subject to change as needed.

Schema stitching is a way to combine multiple GraphQL schemas under a
single endpoint, so that clients can request data from different APIs in
a single query. It also allows to add links between these schemas to
e.g., automatically resolve references to actual types.

Main goals/limitations for the first implementation:

- Avoid interfering with existing code and to stick to existing architecture where possible
- Avoid introducing new dependencies for existing users of the library; in particular,
 kgraphql core should not get any ktor specific dependencies
- Have the stitching API as lean and close to the existing API as possible
- Focus on the non-experimental `ParallelRequestExecutor` first

Over the course of implementing schema stitching, several bugs were
resolved on the way but schema stitching is currently still impacted by
some major issues like incomplete error handling (#114) that need to be
addressed separately.

Resolves #9

Author: stuebingerb

buildSrc/src/main/kotlin/library-conventions.gradle.kts

@@ -1,5 +1,3 @@
-import com.vanniktech.maven.publish.JavadocJar
-import com.vanniktech.maven.publish.KotlinJvm
 import com.vanniktech.maven.publish.SonatypeHost
 import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
 

docs/content/Reference/Type System/objects-and-interfaces.md

@@ -252,6 +252,7 @@ Returns:
 This feature can be used in production but does currently have some issues:
 
 1. The `useDefaultPrettyPrint` doesn't work
-1. Order of fields are not guaranteed, to match the order that was requested
+1. Order of fields are not guaranteed to match the order that was requested
 1. Custom generic type resolvers are not supported
 1. Other than that it should work as expected
+1. Schema stitching is not supported

docs/content/Reference/stitching.md

@@ -0,0 +1,147 @@
+# Schema Stitching
+
+*This feature is still in experimental state.*
+
+## Overview
+
+Schema stitching is a method to take multiple GraphQL schemas and combine them into a single, unified schema. This can
+be useful when implementing an integration layer for a frontend that orchestrates multiple backend APIs to provide your
+UI with all the required data in a single request, without having to think about CORS.
+
+By linking properties to remote queries, one can also enhance individual schemas by e.g. automatically resolving
+identifiers. 
+
+In KGraphQL, schema stitching is configured via the `stitchedSchema` DSL. Each stitched schema has 1-n *remote* schemas,
+and up to one *local* schema.
+
+*Example*:
+
+```kotlin
+stitchedSchema {
+    configure {
+        remoteExecutor = TestRemoteRequestExecutor(client, objectMapper)
+    }
+    localSchema {
+        query("local") {
+            resolver { -> "local" }
+        }
+    }
+    remoteSchema("remote1") {
+        ...
+    }
+    remoteSchema("remote2") {
+        ...
+    }
+}
+```
+
+### Remote Schema Fetching
+
+Remote schemas are usually fetched via introspection query.
+
+*Example*:
+
+```kotlin
+remoteSchema(url) {
+    runBlocking {
+        val responseText = httpClient.post(url) {
+            setBody(
+                TextContent(
+                    text = graphQLJson.toJson(mapOf("query" to Introspection.query())),
+                    contentType = ContentType.Application.Json
+                )
+            )
+        }.bodyAsText()
+        IntrospectedSchema.fromIntrospectionResponse(responseText)
+    }
+}
+```
+
+### Duplicate Types
+
+Currently, if multiple schemas define types with the same name, the local type wins. For identical types from remote
+schemas there is no guaranteed order of precedence. Future versions may provide better tools to deal with such
+situations.
+
+### Remote Execution
+
+To execute remote queries, consumers need to provide a `RemoteRequestExecutor` that receives an `Execution.Remote` node
+and the current `Context`, and has to return the result as `JsonNode?`:
+
+```kotlin
+interface RemoteRequestExecutor {
+    // ParallelRequestExecutor expects a JsonNode as result of any execution
+    suspend fun execute(node: Execution.Remote, ctx: Context): JsonNode?
+}
+```
+
+To simplify implementation, consumers can extend the `AbstractRemoteRequestExecutor` and only provide the implementation
+for actually executing the HTTP request itself.
+
+### Fragments
+
+Fragments based on remote types work but cannot use Kotlin's type system to determine the correct condition type.
+Therefore, queries including fragments must also request the `__typename`. Future implementation might automatically
+include this.
+
+*Example*:
+
+```graphql
+query {
+    getRemote {
+        __typename
+        foo
+        child {
+            __typename
+            ...on RemoteA { specialA }
+            ...on RemoteB { specialB }
+        }
+    }
+}
+```
+
+### Local "Remote" Execution
+
+Due to current implementation details, properties stitched to a *local* query will also be handled by the
+`RemoteRequestExecutor`, and therefore the schema has to provide a `localUrl`. Future implementation will likely support
+actual local execution.
+
+*Example:*
+
+```kotlin
+stitchedSchema {
+    configure {
+        localUrl = "/graphql"
+    }
+}
+```
+
+### Linking Properties
+
+All (local and remote) types of a schema can be extended via stitched properties that are translated into remote query
+calls during execution. The following example adds two fields to the `Type1` type:
+
+- `stitched1`, which executes the remote query `getStitched1` and is marked as required
+- `stitched2`, which executes the remote query `getStitched2` and provides the value of the property `foo` from the
+  parent type as argument named `fooValue`
+
+*Example:*
+
+```kotlin
+type("Type1") {
+    stitchedProperty("stitched1") {
+        nullable = false
+        remoteQuery("getStitched1")
+    }
+    stitchedProperty("stitched2") {
+        remoteQuery("getStitched2").withArgs {
+            arg { name = "fooValue"; parentFieldName = "foo" }
+        }
+    }
+}
+```
+
+Stitched properties are nullable by default, and if a parent property is `null`, the remote execution is skipped and
+results in a value of `null` for the stitched property itself.
+
+See `StitchedSchemaExecutionTest.kt` for an extensive list of different examples.

gradle/libs.versions.toml

@@ -24,6 +24,8 @@ jackson-core-databind = { module = "com.fasterxml.jackson.core:jackson-databind"
 jackson-module-kotlin = { module = "com.fasterxml.jackson.module:jackson-module-kotlin", version.ref = "jackson" }
 caffeine = { module = "com.github.ben-manes.caffeine:caffeine", version = "3.2.0" }
 deferredJsonBuilder = { module = "com.apurebase:DeferredJsonBuilder", version = "1.0.0" }
+ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
+ktor-client-cio = { module = "io.ktor:ktor-client-cio", version.ref = "ktor" }
 ktor-server-core = { module = "io.ktor:ktor-server-core", version.ref = "ktor" }
 ktor-server-auth = { module = "io.ktor:ktor-server-auth", version.ref = "ktor" }
 ktor-server-test-host = { module = "io.ktor:ktor-server-test-host", version.ref = "ktor" }