[executions] Apollo Automatic Persisted Queries (APQ) support (ExpediaGroup#1474)

* feat: async implementation of APQ
Co-authored-by: samvazquez <samvazquez@expedia.com>

Author: samuelAndalon

executions/graphql-kotlin-automatic-persisted-queries/README.md

@@ -0,0 +1,76 @@
+# GraphQL Kotlin Automatic Persisted Queries Support (APQ)
+[![Maven Central](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-automatic-persisted-queries.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.expediagroup%22%20AND%20a:%22graphql-kotlin-automatic-persisted-queries%22)
+[![Javadocs](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-automatic-persisted-queries.svg?label=javadoc&colorB=brightgreen)](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-automatic-persisted-queries)
+
+`graphql-kotlin-automatic-persisted-queries` is the `graphql-kotlin` implementation of Automatic Persisted Queries (APQ).
+
+[APQ is technique created by Apollo](https://www.apollographql.com/docs/apollo-server/performance/apq/) to improve
+GraphQL network performance with zero build-time configuration by sending smaller [GraphQL HTTP requests](https://github.com/graphql/graphql-over-http/blob/main/spec/GraphQLOverHTTP.md),
+a smaller request payload reduces bandwidth utilization and speeds up GraphQL client loading times.
+
+A persisted query is a query string that is cached on a GraphQL server, along with a unique identifier (SHA-256 hash), that way,
+Clients can send this identifier instead of his corresponding query which will drastically reduce the request size.
+
+To persist a query, a GraphQL Server must first receive it from a client, then, subsequent requests can just include the identifier
+instead of the query.
+
+```mermaid
+sequenceDiagram;
+  Client->>GraphQL Kotlin Server: Sends SHA-256 hash of query to execute
+  Note over GraphQL Kotlin Server: Fails to find persisted query
+  GraphQL Kotlin Server->>Client: Responds with error
+  Client->>GraphQL Kotlin Server: Sends both query AND hash
+  Note over GraphQL Kotlin Server: Persists query and hash
+ GraphQL Kotlin Server->>Client: Executes query and returns result
+  Note over Client: Time passes
+  Client->>GraphQL Kotlin Server: Sends SHA-256 hash of query to execute
+  Note over GraphQL Kotlin Server: Finds persisted query
+GraphQL Kotlin Server->>Client: Executes query and returns result
+```
+
+The `APQ` implementation of `graphql-kotlin` relies on the [graphql-java PreparsedDocumentProvider](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/execution/preparsed/PreparsedDocumentProvider.java)
+which is an interface that allows clients to cache GraphQL Documents (AST) that were parsed and validated.
+
+The `AutomaticPersistedQueriesProvider` class implements `PreparsedDocumentProvider` and contains all the logic required to fulfil the APQ spec.
+
+## Install it
+
+Using a JVM dependency manager, link `graphql-kotlin-automatic-persisted-queries` to your project.
+
+With Maven:
+
+```xml
+<dependency>
+  <groupId>com.expediagroup</groupId>
+  <artifactId>graphql-kotlin-automatic-persisted-queries</artifactId>
+  <version>${latestVersion}</version>
+</dependency>
+```
+
+With Gradle (example using kts):
+
+```kotlin
+implementation("com.expediagroup:graphql-kotlin-automatic-persisted-queries:$latestVersion")
+```
+
+## Use it
+
+1. Create an instance of `AutomaticPersistedQueriesProvider` by specifying as a constructor argument an implementation of an
+`AutomaticPersistedQueriesCache` interface, which is the place where the queries will be persisted by their unique identifier.
+
+**Note:** `graphql-kotlin` provides a default in-memory cache implementation of `AutomaticPersistedQueriesCache` called `DefaultAutomaticPersistedQueriesCache`.
+
+2. Provide the instance of `AutomaticPersistedQueriesProvider` to the [GraphQLBuilder preparsedDocumentProvider method](https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/GraphQL.java#L261).
+
+**Note:** In order to take full advantage of APQ it's recommended to use a different cache mechanism like REDIS.
+
+```kotlin
+val schema = "your schema"
+val runtimeWiring =  RuntimeWiring.newRuntimeWiring().build() // your runtime wiring
+val automaticPersistedQueryProvider = AutomaticPersistedQueriesProvider(DefaultAutomaticPersistedQueriesCache())
+
+val graphQL = GraphQL
+    .newGraphQL(SchemaGenerator().makeExecutableSchema(SchemaParser().parse(schema), runtimeWiring))
+    .preparsedDocumentProvider(automaticPersistedQueryProvider)
+    .build()
+```

executions/graphql-kotlin-automatic-persisted-queries/build.gradle.kts

@@ -0,0 +1,29 @@
+description = "Automatic Persisted Queries"
+
+val junitVersion: String by project
+val graphQLJavaVersion: String by project
+
+dependencies {
+    api("com.graphql-java:graphql-java:$graphQLJavaVersion")
+    testImplementation("org.junit.jupiter:junit-jupiter-api:$junitVersion")
+    testImplementation("org.junit.jupiter:junit-jupiter-engine:$junitVersion")
+}
+
+tasks {
+    jacocoTestCoverageVerification {
+        violationRules {
+            rule {
+                limit {
+                    counter = "INSTRUCTION"
+                    value = "COVEREDRATIO"
+                    minimum = "0.76".toBigDecimal()
+                }
+                limit {
+                    counter = "BRANCH"
+                    value = "COVEREDRATIO"
+                    minimum = "0.50".toBigDecimal()
+                }
+            }
+        }
+    }
+}

executions/graphql-kotlin-automatic-persisted-queries/src/main/kotlin/com/expediagroup/graphql/apq/cache/AutomaticPersistedQueriesCache.kt

@@ -0,0 +1,60 @@
+/*
+ * 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.
+ * 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.apq.cache
+
+import graphql.ExecutionInput
+import graphql.execution.preparsed.PreparsedDocumentEntry
+import graphql.execution.preparsed.persisted.PersistedQueryCache
+import graphql.execution.preparsed.persisted.PersistedQueryCacheMiss
+import java.util.concurrent.CompletableFuture
+
+interface AutomaticPersistedQueriesCache : PersistedQueryCache {
+
+    @Deprecated(
+        message = "deprecated in favor of async retrieval of PreparsedDocumentEntry",
+        replaceWith = ReplaceWith("getPersistedQueryDocumentAsync(persistedQueryId, executionInput, onCacheMiss)")
+    )
+    override fun getPersistedQueryDocument(
+        persistedQueryId: Any,
+        executionInput: ExecutionInput,
+        onCacheMiss: PersistedQueryCacheMiss
+    ): PreparsedDocumentEntry =
+        getPersistedQueryDocumentAsync(persistedQueryId, executionInput, onCacheMiss).get()
+
+    override fun getPersistedQueryDocumentAsync(
+        persistedQueryId: Any,
+        executionInput: ExecutionInput,
+        onCacheMiss: PersistedQueryCacheMiss
+    ): CompletableFuture<PreparsedDocumentEntry> =
+        getOrElse(persistedQueryId.toString()) {
+            onCacheMiss.apply(executionInput.query)
+        }
+
+    /**
+     * Get the [PreparsedDocumentEntry] associated with the [key] from the cache.
+     *
+     * If the [PreparsedDocumentEntry] is missing in the cache, the [supplier] will provide one,
+     * and then it should be added to the cache.
+     *
+     * @param key The hash of the requested query.
+     * @param supplier that will provide the document in case there is a cache miss.
+     */
+    fun getOrElse(
+        key: String,
+        supplier: () -> PreparsedDocumentEntry
+    ): CompletableFuture<PreparsedDocumentEntry>
+}

executions/graphql-kotlin-automatic-persisted-queries/src/main/kotlin/com/expediagroup/graphql/apq/cache/DefaultAutomaticPersistedQueriesCache.kt

@@ -0,0 +1,38 @@
+/*
+ * 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.
+ * 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.apq.cache
+
+import graphql.execution.preparsed.PreparsedDocumentEntry
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.ConcurrentHashMap
+
+class DefaultAutomaticPersistedQueriesCache : AutomaticPersistedQueriesCache {
+
+    private val cache: ConcurrentHashMap<String, PreparsedDocumentEntry> = ConcurrentHashMap()
+
+    override fun getOrElse(
+        key: String,
+        supplier: () -> PreparsedDocumentEntry
+    ): CompletableFuture<PreparsedDocumentEntry> =
+        cache[key]?.let { entry ->
+            CompletableFuture.completedFuture(entry)
+        } ?: run {
+            val entry = supplier.invoke()
+            cache[key] = entry
+            CompletableFuture.completedFuture(supplier.invoke())
+        }
+}

executions/graphql-kotlin-automatic-persisted-queries/src/main/kotlin/com/expediagroup/graphql/apq/extensions/executionInputExtensions.kt

@@ -0,0 +1,48 @@
+/*
+ * 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.
+ * 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.apq.extensions
+
+import com.expediagroup.graphql.apq.provider.AutomaticPersistedQueriesExtension
+import graphql.ExecutionInput
+import java.math.BigInteger
+import java.nio.charset.StandardCharsets
+import java.security.MessageDigest
+
+internal const val APQ_EXTENSION_KEY: String = "persistedQuery"
+internal val MESSAGE_DIGEST: MessageDigest = MessageDigest.getInstance("SHA-256")
+
+@Suppress("UNCHECKED_CAST")
+fun ExecutionInput.getAutomaticPersistedQueriesExtension(): AutomaticPersistedQueriesExtension? =
+    try {
+        (this.extensions[APQ_EXTENSION_KEY] as? Map<String, Any?>)?.let(::AutomaticPersistedQueriesExtension)
+    } catch (e: NoSuchElementException) {
+        // could not create persistedQuery extension
+        null
+    }
+
+fun ExecutionInput.getQueryId(): String =
+    String.format(
+        "%064x",
+        BigInteger(1, MESSAGE_DIGEST.digest(this.query.toByteArray(StandardCharsets.UTF_8)))
+    ).also {
+        MESSAGE_DIGEST.reset()
+    }
+
+fun ExecutionInput.isAutomaticPersistedQueriesExtensionInvalid(
+    extension: AutomaticPersistedQueriesExtension
+): Boolean =
+    !this.getQueryId().equals(extension.sha256Hash, ignoreCase = true)

executions/graphql-kotlin-automatic-persisted-queries/src/main/kotlin/com/expediagroup/graphql/apq/provider/AutomaticPersistedQueriesExtension.kt

@@ -0,0 +1,6 @@
+package com.expediagroup.graphql.apq.provider
+
+class AutomaticPersistedQueriesExtension(map: Map<String, Any?>) {
+    val version: Int by map
+    val sha256Hash: String by map
+}

executions/graphql-kotlin-automatic-persisted-queries/src/main/kotlin/com/expediagroup/graphql/apq/provider/AutomaticPersistedQueriesProvider.kt

@@ -0,0 +1,96 @@
+/*
+ * 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.
+ * 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.apq.provider
+
+import com.expediagroup.graphql.apq.cache.AutomaticPersistedQueriesCache
+import com.expediagroup.graphql.apq.extensions.getAutomaticPersistedQueriesExtension
+import com.expediagroup.graphql.apq.extensions.getQueryId
+import com.expediagroup.graphql.apq.extensions.isAutomaticPersistedQueriesExtensionInvalid
+import graphql.ExecutionInput
+import graphql.GraphqlErrorBuilder
+import graphql.execution.preparsed.PreparsedDocumentEntry
+import graphql.execution.preparsed.PreparsedDocumentProvider
+import graphql.execution.preparsed.persisted.PersistedQueryError
+import graphql.execution.preparsed.persisted.PersistedQueryIdInvalid
+import graphql.execution.preparsed.persisted.PersistedQueryNotFound
+import java.util.concurrent.CompletableFuture
+import java.util.function.Function
+
+class AutomaticPersistedQueriesProvider(
+    private val cache: AutomaticPersistedQueriesCache
+) : PreparsedDocumentProvider {
+
+    @Deprecated(
+        "deprecated in favor of async retrieval of Document",
+        ReplaceWith("this.getDocumentAsync(executionInput, parseAndValidateFunction).get()")
+    )
+    override fun getDocument(
+        executionInput: ExecutionInput,
+        parseAndValidateFunction: Function<ExecutionInput, PreparsedDocumentEntry>
+    ): PreparsedDocumentEntry =
+        this.getDocumentAsync(
+            executionInput,
+            parseAndValidateFunction
+        ).get()
+
+    override fun getDocumentAsync(
+        executionInput: ExecutionInput,
+        parseAndValidateFunction: Function<ExecutionInput, PreparsedDocumentEntry>
+    ): CompletableFuture<PreparsedDocumentEntry> =
+        try {
+            executionInput.getAutomaticPersistedQueriesExtension()?.let { apqExtension ->
+                cache.getPersistedQueryDocumentAsync(apqExtension.sha256Hash, executionInput) { query ->
+                    when {
+                        query.isBlank() -> {
+                            throw PersistedQueryNotFound(apqExtension.sha256Hash)
+                        }
+                        executionInput.isAutomaticPersistedQueriesExtensionInvalid(apqExtension) -> {
+                            throw PersistedQueryIdInvalid(apqExtension.sha256Hash)
+                        }
+                        else -> {
+                            parseAndValidateFunction.apply(
+                                executionInput.transform { builder -> builder.query(query) }
+                            )
+                        }
+                    }
+                }
+            } ?: run {
+                // no apqExtension, not a persisted query,
+                // but we still want to cache the parsed and validated document
+                cache.getOrElse(executionInput.getQueryId()) {
+                    parseAndValidateFunction.apply(executionInput)
+                }
+            }
+        } catch (persistedQueryError: PersistedQueryError) {
+            CompletableFuture.completedFuture(
+                PreparsedDocumentEntry(
+                    GraphqlErrorBuilder.newError()
+                        .errorType(persistedQueryError)
+                        .message(persistedQueryError.message)
+                        .extensions(
+                            when (persistedQueryError) {
+                                // persistedQueryError.getExtensions()
+                                // Cannot access 'getExtensions': it is package-private in 'PersistedQueryError'
+                                is PersistedQueryNotFound -> persistedQueryError.extensions
+                                is PersistedQueryIdInvalid -> persistedQueryError.extensions
+                                else -> emptyMap()
+                            }
+                        ).build()
+                )
+            )
+        }
+}

executions/graphql-kotlin-automatic-persisted-queries/src/test/kotlin/com/expediagroup/graphql/apq/fixture/Product.kt

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ * 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.apq.fixture
+
+data class Product(
+    val id: Int,
+    val summary: ProductSummary,
+    val details: ProductDetails
+)
+
+data class ProductSummary(val name: String)
+data class ProductDetails(val rating: String)