Basic Automatic Persisted Queries (APQ) support

CHANGELOG.md

@@ -4,6 +4,9 @@ CHANGELOG
 [Next release](https://github.com/rebing/graphql-laravel/compare/7.0.1...master)
 --------------
 
+### Added
+- Basic Automatic Persisted Queries (APQ) support [\#701 / illambo](https://github.com/rebing/graphql-laravel/pull/701)
+
 2021-04-03, 7.0.1
 -----------------
 ### Added

README.md

@@ -130,6 +130,7 @@ To work this around:
     - [Field deprecation](#field-deprecation)
     - [Default field resolver](#default-field-resolver)
     - [Macros](#macros)
+    - [Basic Automatic Persisted Queries support](#basic-automatic-persisted-queries-support) 
   - [Guides](#guides)
     - [Upgrading from v1 to v2](#upgrading-from-v1-to-v2)
     - [Migrating from Folklore](#migrating-from-folklore)
@@ -2394,6 +2395,105 @@ class AppServiceProvider extends ServiceProvider
 
 The `macro` function accepts a name as its first argument, and a `Closure` as its second.
 
+### Basic Automatic Persisted Queries support
+
+Automatic Persisted Queries (APQ) improve network performance by sending smaller requests, with zero build-time configuration.
+
+APQ is disabled by default and can be enabled in the config via `apc.enabled=true` or by setting the environment variable `GRAPHQL_APQ_ENABLE=true`.
+
+A persisted query is an ID or hash that can be generated on the client sent to the server instead of the entire GraphQL query string. 
+This smaller signature reduces bandwidth utilization and speeds up client loading times.
+Persisted queries pair especially with GET requests, enabling the browser cache and integration with a CDN.
+
+Behind the scenes, APQ uses Laravels cache for storing / retrieving queries.
+Please see the various options there for which cache, prefix, TTL, etc. to use.
+
+For more information see: 
+ - [Apollo - Automatic persisted queries](https://www.apollographql.com/docs/apollo-server/performance/apq/) 
+ - [Apollo link persisted queries - protocol](https://github.com/apollographql/apollo-link-persisted-queries#protocol)
+
+> Note: the APQ protocol requires the hash sent by the client being compared
+> with the computed hash on the server. In case a mutating middleware like
+> `TrimStrings` is active and the query sent contains leading/trailing
+> whitespaces, these hashes can never match resulting in an error.
+> 
+> In such case either disable the middleware or trim the query on the client
+> before hashing.
+
+#### Why "basic support" ?
+
+Currently, only the GraphQL query string representation will be cached and still
+needs to be re-parsed after retrieving form the cache.
+
+#### Notes
+ - The error descriptions are aligned with [apollo-server](https://github.com/apollographql/apollo-server).
+
+#### Client example
+
+Below a simple integration example with Vue/Apollo, the `createPersistedQueryLink`
+automatically manages the APQ flow.
+
+```js
+// [example app.js]
+
+require('./bootstrap');
+
+window.Vue = require('vue');
+
+Vue.component('example-component', require('./components/ExampleComponent.vue').default);
+
+import { ApolloClient } from 'apollo-client';
+import { ApolloLink } from 'apollo-link';
+import { createHttpLink } from 'apollo-link-http';
+import { createPersistedQueryLink } from 'apollo-link-persisted-queries';
+import { InMemoryCache } from 'apollo-cache-inmemory';
+import VueApollo from 'vue-apollo';
+
+const httpLinkWithPersistedQuery = createPersistedQueryLink().concat(createHttpLink({
+    uri: '/graphql',
+}));
+
+// Create the apollo client
+const apolloClient = new ApolloClient({
+    link: ApolloLink.from([httpLinkWithPersistedQuery]),
+    cache: new InMemoryCache(),
+    connectToDevTools: true,
+})
+
+const apolloProvider = new VueApollo({
+    defaultClient: apolloClient,
+});
+
+Vue.use(VueApollo);
+
+const app = new Vue({
+    el: '#app',
+    apolloProvider,
+});
+```
+```vue 
+<!-- [example TestComponent.vue] -->
+
+<template>
+    <div>
+        <p>Test APQ</p>
+        <p>-> <span v-if="$apollo.queries.hello.loading">Loading...</span>{{ hello }}</p>
+    </div>
+</template>
+
+<script>
+    import gql from 'graphql-tag';
+    export default {
+        apollo: {
+            hello: gql`query{hello}`,
+        },
+        mounted() {
+            console.log('Component mounted.')
+        }
+    }
+</script>
+```
+
 ## Guides
 
 ### Upgrading from v1 to v2

config/config.php

@@ -211,4 +211,22 @@
      * See http://php.net/manual/function.json-encode.php for the full list of options
      */
     'json_encoding_options' => 0,
+
+    /*
+     * Automatic Persisted Queries (APQ)
+     * See https://www.apollographql.com/docs/apollo-server/performance/apq/
+     */
+    'apq' => [
+        // Enable/Disable APQ - See https://www.apollographql.com/docs/apollo-server/performance/apq/#disabling-apq
+        'enable' => env('GRAPHQL_APQ_ENABLE', false),
+
+        // The cache driver used for APQ
+        'cache_driver' => env('GRAPHQL_APQ_CACHE_DRIVER', config('cache.default')),
+
+        // The cache prefix
+        'cache_prefix' => config('cache.prefix') . ':graphql.apq',
+
+        // The cache ttl in minutes - See https://www.apollographql.com/docs/apollo-server/performance/apq/#adjusting-cache-time-to-live-ttl
+        'cache_ttl' => 300,
+    ],
 ];

src/Error/AutomaticPersistedQueriesError.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rebing\GraphQL\Error;
+
+use GraphQL\Error\Error;
+
+class AutomaticPersistedQueriesError extends Error
+{
+    public const CODE_PERSISTED_QUERY_NOT_SUPPORTED = 'PERSISTED_QUERY_NOT_SUPPORTED';
+    public const CODE_PERSISTED_QUERY_NOT_FOUND = 'PERSISTED_QUERY_NOT_FOUND';
+    public const CODE_INTERNAL_SERVER_ERROR = 'INTERNAL_SERVER_ERROR';
+    public const MESSAGE_PERSISTED_QUERY_NOT_SUPPORTED = 'PersistedQueryNotSupported';
+    public const MESSAGE_PERSISTED_QUERY_NOT_FOUND = 'PersistedQueryNotFound';
+    public const MESSAGE_INVALID_HASH = 'provided sha does not match query';
+    public const CATEGORY_APQ = 'apq';
+
+    public static function persistedQueriesNotSupported(): self
+    {
+        return new self(
+            self::MESSAGE_PERSISTED_QUERY_NOT_SUPPORTED,
+            $nodes = null,
+            $source = null,
+            $positions = [],
+            $path = null,
+            $previous = null,
+            $extensions = [
+                'code' => self::CODE_PERSISTED_QUERY_NOT_SUPPORTED,
+            ]
+        );
+    }
+
+    public static function persistedQueriesNotFound(): self
+    {
+        return new self(
+            self::MESSAGE_PERSISTED_QUERY_NOT_FOUND,
+            $nodes = null,
+            $source = null,
+            $positions = [],
+            $path = null,
+            $previous = null,
+            $extensions = [
+                'code' => self::CODE_PERSISTED_QUERY_NOT_FOUND,
+            ]
+        );
+    }
+
+    /**
+     * @param  string|null  $message
+     */
+    public static function internalServerError($message = null): self
+    {
+        return new self(
+            $message ?? '',
+            $nodes = null,
+            $source = null,
+            $positions = [],
+            $path = null,
+            $previous = null,
+            $extensions = [
+                'code' => self::CODE_INTERNAL_SERVER_ERROR,
+            ]
+        );
+    }
+
+    public static function invalidHash(): self
+    {
+        return self::internalServerError(self::MESSAGE_INVALID_HASH);
+    }
+
+    public function isClientSafe(): bool
+    {
+        return true;
+    }
+
+    public function getCategory(): string
+    {
+        return self::CATEGORY_APQ;
+    }
+}

src/GraphQL.php

@@ -136,15 +136,11 @@ public function queryAndReturnResult(string $query, ?array $params = [], array $
 
         $schema = $this->schema($schemaName);
 
-        $errorFormatter = config('graphql.error_formatter', [static::class, 'formatError']);
-        $errorsHandler = config('graphql.errors_handler', [static::class, 'handleErrors']);
         $defaultFieldResolver = config('graphql.defaultFieldResolver', null);
 
-        $result = GraphQLBase::executeQuery($schema, $query, $rootValue, $context, $params, $operationName, $defaultFieldResolver)
-            ->setErrorsHandler($errorsHandler)
-            ->setErrorFormatter($errorFormatter);
+        $result = GraphQLBase::executeQuery($schema, $query, $rootValue, $context, $params, $operationName, $defaultFieldResolver);
 
-        return $result;
+        return $this->decorateExecutionResult($result);
     }
 
     public function addTypes(array $types): void
@@ -556,4 +552,14 @@ public static function getNormalizedSchemaConfiguration($schema)
 
         return $instance->toConfig();
     }
+
+    public function decorateExecutionResult(ExecutionResult $executionResult): ExecutionResult
+    {
+        $errorFormatter = config('graphql.error_formatter', [static::class, 'formatError']);
+        $errorsHandler = config('graphql.errors_handler', [static::class, 'handleErrors']);
+
+        return $executionResult
+            ->setErrorsHandler($errorsHandler)
+            ->setErrorFormatter($errorFormatter);
+    }
 }

src/GraphQLController.php

@@ -5,11 +5,14 @@
 namespace Rebing\GraphQL;
 
 use Exception;
+use GraphQL\Executor\ExecutionResult;
 use Illuminate\Container\Container;
 use Illuminate\Contracts\View\View;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Routing\Controller;
+use Illuminate\Support\Arr;
+use Rebing\GraphQL\Error\AutomaticPersistedQueriesError;
 
 class GraphQLController extends Controller
 {
@@ -37,8 +40,8 @@ public function query(Request $request, string $schema = null): JsonResponse
             $schema = config('graphql.default_schema');
         }
 
-        // If a singular query was not found, it means the queries are in batch
-        $isBatch = ! $request->has('query');
+        // check if is batch (check if the array is associative)
+        $isBatch = ! Arr::isAssoc($request->input());
         $inputs = $isBatch ? $request->input() : [$request->input()];
 
         $completedQueries = [];
@@ -58,15 +61,24 @@ public function query(Request $request, string $schema = null): JsonResponse
 
     protected function executeQuery(string $schema, array $input): array
     {
-        $query = $input['query'] ?? '';
+        /** @var GraphQL $graphql */
+        $graphql = $this->app->make('graphql');
+
+        try {
+            $query = $this->handleAutomaticPersistQueries($schema, $input);
+        } catch (AutomaticPersistedQueriesError $e) {
+            return $graphql
+                ->decorateExecutionResult(new ExecutionResult(null, [$e]))
+                ->toArray();
+        }
 
         $paramsKey = config('graphql.params_key', 'variables');
         $params = $input[$paramsKey] ?? null;
         if (is_string($params)) {
             $params = json_decode($params, true);
         }
 
-        return $this->app->make('graphql')->query(
+        return $graphql->query(
             $query,
             $params,
             [
@@ -86,6 +98,61 @@ protected function queryContext(string $query, ?array $params, string $schema)
         }
     }
 
+    /**
+     * Note: it's expected this is called even when APQ is disabled to adhere
+     *       to the negotiation protocol.
+     *
+     * @param  string  $schemaName
+     * @param  array<string,mixed>  $input
+     * @return string
+     */
+    protected function handleAutomaticPersistQueries(string $schemaName, array $input): string
+    {
+        $query = $input['query'] ?? '';
+        $apqEnabled = config('graphql.apq.enable', false);
+
+        // Even if APQ is disabled, we keep this logic for the negotiation protocol
+        $persistedQuery = $input['extensions']['persistedQuery'] ?? null;
+        if ($persistedQuery && !$apqEnabled) {
+            throw AutomaticPersistedQueriesError::persistedQueriesNotSupported();
+        }
+
+        // APQ disabled? Nothing to be done
+        if (!$apqEnabled) {
+            return $query;
+        }
+
+        // No hash? Nothing to be done
+        $hash = $persistedQuery['sha256Hash'] ?? null;
+        if (null === $hash) {
+            return $query;
+        }
+
+        $apqCacheDriver = config('graphql.apq.cache_driver');
+        $apqCachePrefix = config('graphql.apq.cache_prefix');
+        $apqCacheIdentifier = "$apqCachePrefix:$schemaName:$hash";
+
+        $cache = cache();
+
+        // store in cache
+        if ($query) {
+            if ($hash !== hash('sha256', $query)) {
+                throw AutomaticPersistedQueriesError::invalidHash();
+            }
+            $ttl = config('graphql.apq.cache_ttl', 300);
+            $cache->driver($apqCacheDriver)->set($apqCacheIdentifier, $query, $ttl);
+
+            return $query;
+        }
+
+        // retrieve from cache
+        if (!$cache->has($apqCacheIdentifier)) {
+            throw AutomaticPersistedQueriesError::persistedQueriesNotFound();
+        }
+
+        return $cache->driver($apqCacheDriver)->get($apqCacheIdentifier);
+    }
+
     public function graphiql(Request $request, string $schema = null): View
     {
         $graphqlPath = '/'.config('graphql.prefix');