Broken PoC of AST caching on Disk

Issue #1312 provided some good pointers of performance considerations.
One of which was not parsing the schema on every request. We've
previously tried to cache the AST in the database but the representation
just isn't very well suited for it. Instead we should use the PhpStorage
provided by Drupal to just cache the entire AST as an array on disk
which can be loaded quickly.

See https://webonyx.github.io/graphql-php/schema-definition-language/#performance-considerations

This commit makes an example proof of concept of what this could look
like but it has a few problems:

- For some reason the extensions (e.g. `extend type Query`) don't get
  parsed properly which makes our validator think the field has a
  resolver but no schema. This might be a bug in the validator but
  that's unclear for now.
- We make breaking changes to methods in SdlShcemaPluginBase which could
  be undesirable and might need some thought and care to make this
  forward compatible.
- There's no good way to get an AST from a Schema so we perform some
  hacks. However it looks like the underlying library actually loses
  some of our Source information. The whole point of processing each
  .graphql file indepdently was so we could get better error messages
  of where syntax errors exist. This might be fixed in newer versions
  of the graphql-php library though
- We must perform an extension sorting step, at least with the Open
  Social schema, to make sure that module dependencies are properly
  handled. For example a .base.graphql file might not `extend` something
  but might still reference a type defined in another module's
  .base.graphql file. If the files are processed out of order then this
  causes an error.
  Even if this is fixed with the sorting by module dependencies then
  this might still be a breaking change for people who do not currently
  build their schema with these constraints in mind (i.e. properly
  architecting their schema's dependencies).

Author: Kingdutch

graphql.services.yml

@@ -54,6 +54,14 @@ services:
       - { name: cache.bin }
     factory: cache_factory:get
     arguments: [graphql_ast]
+    deprecated: 'The "%service_id%" service is deprecated. There is no replacement. See https://drupal.org/node/'
+
+  # File cache for the complete GraphQL document.
+  # TODO: We don't benefit from auto-cachebin uninstall and need to implement clean-up
+  cache.graphql.document:
+    class: Drupal\Component\PhpStorage\PhpStorageInterface
+    factory: Drupal\Core\PhpStorage\PhpStorageFactory::get
+    arguments: [graphql_document]
 
   # Cache bin for graphql plugin definitions.
   cache.graphql.definitions:

src/Plugin/GraphQL/Schema/AlterableComposableSchema.php

@@ -59,7 +59,7 @@ public static function create(ContainerInterface $container, array $configuratio
    *   The plugin id.
    * @param array $pluginDefinition
    *   The plugin definition array.
-   * @param \Drupal\Core\Cache\CacheBackendInterface $astCache
+   * @param \Drupal\Core\Cache\CacheBackendInterface $documentCache
    *   The cache bin for caching the parsed SDL.
    * @param \Drupal\Core\Extension\ModuleHandlerInterface $moduleHandler
    *   The module handler service.
@@ -73,20 +73,20 @@ public static function create(ContainerInterface $container, array $configuratio
    * @codeCoverageIgnore
    */
   public function __construct(
-    array $configuration,
-    $pluginId,
-    array $pluginDefinition,
-    CacheBackendInterface $astCache,
-    ModuleHandlerInterface $moduleHandler,
-    SchemaExtensionPluginManager $extensionManager,
-    array $config,
+    array                         $configuration,
+                                  $pluginId,
+    array                         $pluginDefinition,
+    CacheBackendInterface         $documentCache,
+    ModuleHandlerInterface        $moduleHandler,
+    SchemaExtensionPluginManager  $extensionManager,
+    array                         $config,
     ContainerAwareEventDispatcher $dispatcher
   ) {
     parent::__construct(
       $configuration,
       $pluginId,
       $pluginDefinition,
-      $astCache,
+      $documentCache,
       $moduleHandler,
       $extensionManager,
       $config
@@ -114,7 +114,7 @@ public function __construct(
   protected function getSchemaDocument(array $extensions = []) {
     // Only use caching of the parsed document if we aren't in development mode.
     $cid = "schema:{$this->getPluginId()}";
-    if (empty($this->inDevelopment) && $cache = $this->astCache->get($cid)) {
+    if (empty($this->inDevelopment) && $cache = $this->documentCache->get($cid)) {
       return $cache->data;
     }
 
@@ -132,7 +132,7 @@ protected function getSchemaDocument(array $extensions = []) {
     );
     $ast = Parser::parse(implode("\n\n", $event->getSchemaData()));
     if (empty($this->inDevelopment)) {
-      $this->astCache->set($cid, $ast, CacheBackendInterface::CACHE_PERMANENT, ['graphql']);
+      $this->documentCache->set($cid, $ast, CacheBackendInterface::CACHE_PERMANENT, ['graphql']);
     }
     return $ast;
   }
@@ -156,7 +156,7 @@ protected function getSchemaDocument(array $extensions = []) {
   protected function getExtensionDocument(array $extensions = []) {
     // Only use caching of the parsed document if we aren't in development mode.
     $cid = "extension:{$this->getPluginId()}";
-    if (empty($this->inDevelopment) && $cache = $this->astCache->get($cid)) {
+    if (empty($this->inDevelopment) && $cache = $this->documentCache->get($cid)) {
       return $cache->data;
     }
 
@@ -174,7 +174,7 @@ protected function getExtensionDocument(array $extensions = []) {
     );
     $ast = !empty($extensions) ? Parser::parse(implode("\n\n", $event->getSchemaExtensionData())) : NULL;
     if (empty($this->inDevelopment)) {
-      $this->astCache->set($cid, $ast, CacheBackendInterface::CACHE_PERMANENT, ['graphql']);
+      $this->documentCache->set($cid, $ast, CacheBackendInterface::CACHE_PERMANENT, ['graphql']);
     }
 
     return $ast;

src/Plugin/GraphQL/Schema/SdlSchemaPluginBase.php

@@ -2,6 +2,7 @@
 
 namespace Drupal\graphql\Plugin\GraphQL\Schema;
 
+use Drupal\Component\PhpStorage\PhpStorageInterface;
 use Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException;
 use Drupal\Component\Plugin\PluginBase;
 use Drupal\Core\Cache\CacheableDependencyInterface;
@@ -13,12 +14,21 @@
 use Drupal\graphql\Plugin\SchemaExtensionPluginInterface;
 use Drupal\graphql\Plugin\SchemaExtensionPluginManager;
 use Drupal\graphql\Plugin\SchemaPluginInterface;
+use GraphQL\Error\Error;
+use GraphQL\Language\AST\DocumentNode;
 use GraphQL\Language\AST\InterfaceTypeDefinitionNode;
+use GraphQL\Language\AST\Node;
+use GraphQL\Language\AST\NodeList;
 use GraphQL\Language\AST\TypeDefinitionNode;
 use GraphQL\Language\AST\UnionTypeDefinitionNode;
 use GraphQL\Language\Parser;
+use GraphQL\Language\Source;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Schema;
+use GraphQL\Utils\AST;
 use GraphQL\Utils\BuildSchema;
 use GraphQL\Utils\SchemaExtender;
+use GraphQL\Utils\SchemaPrinter;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
@@ -28,11 +38,11 @@ abstract class SdlSchemaPluginBase extends PluginBase implements SchemaPluginInt
   use RefinableCacheableDependencyTrait;
 
   /**
-   * The cache bin for caching the parsed SDL.
+   * The file cache for caching the parsed SDL.
    *
-   * @var \Drupal\Core\Cache\CacheBackendInterface
+   * @var \Drupal\Component\PhpStorage\PhpStorageInterface
    */
-  protected $astCache;
+  protected $documentCache;
 
   /**
    * Whether the system is currently in development mode.
@@ -65,7 +75,7 @@ public static function create(ContainerInterface $container, array $configuratio
       $configuration,
       $plugin_id,
       $plugin_definition,
-      $container->get('cache.graphql.ast'),
+      $container->get('cache.graphql.document'),
       $container->get('module_handler'),
       $container->get('plugin.manager.graphql.schema_extension'),
       $container->getParameter('graphql.config')
@@ -81,8 +91,8 @@ public static function create(ContainerInterface $container, array $configuratio
    *   The plugin id.
    * @param array $pluginDefinition
    *   The plugin definition array.
-   * @param \Drupal\Core\Cache\CacheBackendInterface $astCache
-   *   The cache bin for caching the parsed SDL.
+   * @param \Drupal\Component\PhpStorage\PhpStorageInterface $documentCache
+   *   The file cache for caching the parsed SDL.
    * @param \Drupal\Core\Extension\ModuleHandlerInterface $moduleHandler
    *   The module handler service.
    * @param \Drupal\graphql\Plugin\SchemaExtensionPluginManager $extensionManager
@@ -93,17 +103,17 @@ public static function create(ContainerInterface $container, array $configuratio
    * @codeCoverageIgnore
    */
   public function __construct(
-    array $configuration,
-    $pluginId,
-    array $pluginDefinition,
-    CacheBackendInterface $astCache,
-    ModuleHandlerInterface $moduleHandler,
+    array                        $configuration,
+                                 $pluginId,
+    array                        $pluginDefinition,
+    PhpStorageInterface          $documentCache,
+    ModuleHandlerInterface       $moduleHandler,
     SchemaExtensionPluginManager $extensionManager,
-    array $config
+    array                        $config
   ) {
     parent::__construct($configuration, $pluginId, $pluginDefinition);
     $this->inDevelopment = !empty($config['development']);
-    $this->astCache = $astCache;
+    $this->documentCache = $documentCache;
     $this->extensionManager = $extensionManager;
     $this->moduleHandler = $moduleHandler;
   }
@@ -117,29 +127,68 @@ public function __construct(
    */
   public function getSchema(ResolverRegistryInterface $registry) {
     $extensions = $this->getExtensions();
+
+    // TODO: The fact that the registry gets extended here means we can't cache
+    //   all of it easily
+    foreach ($extensions as $extension) {
+      $extension->registerResolvers($registry);
+    }
+
+    // TODO: We might need to think about the naming to work with multiple webheads and configs?
     $resolver = [$registry, 'resolveType'];
-    $document = $this->getSchemaDocument($extensions);
-    $schema = BuildSchema::build($document, function ($config, TypeDefinitionNode $type) use ($resolver) {
+    $document = empty($this->inDevelopment) ? $this->loadCachedDocument() : NULL;
+    if ($document !== NULL) {
+      return BuildSchema::build($document, function ($config, TypeDefinitionNode $type) use ($resolver) {
+        if ($type instanceof InterfaceTypeDefinitionNode || $type instanceof UnionTypeDefinitionNode) {
+          $config['resolveType'] = $resolver;
+        }
+
+        return $config;
+      });
+    }
+
+    $schema = BuildSchema::build($this->getBaseSchemaAst(), function ($config, TypeDefinitionNode $type) use ($resolver) {
       if ($type instanceof InterfaceTypeDefinitionNode || $type instanceof UnionTypeDefinitionNode) {
         $config['resolveType'] = $resolver;
       }
 
       return $config;
     });
 
-    if (empty($extensions)) {
-      return $schema;
+    /** @var DocumentNode $extensionAst */
+    foreach ($this->getExtensionAsts($extensions) as $extensionAst) {
+      $schema = SchemaExtender::extend($schema, $extensionAst);
     }
 
-    foreach ($extensions as $extension) {
-      $extension->registerResolvers($registry);
+    // This does a full schema load, which is slow. But it's the most correct
+    // way to ensure we can get a cacheable AST that's quick.
+    // TODO: Move this to a drush command that can precalculate this.
+    $schemaDefinitions = [$schema->getAstNode(), ...$schema->extensionASTNodes];
+    foreach ($schema->getTypeMap() as $type) {
+      if ($type->astNode !== NULL) {
+        $schemaDefinitions[] = $type->astNode;
+      }
+      foreach ($type->extensionASTNodes ?? [] as $extensionNode) {
+        $schemaDefinitions[] = $extensionNode;
+      }
     }
+    $ast = new DocumentNode(
+      ['definitions' => new NodeList($schemaDefinitions)]
+    );
+    $this->storeCachedDocument($ast);
+
+    return $schema;
+  }
 
-    if ($extendSchema = $this->getExtensionDocument($extensions)) {
-      return SchemaExtender::extend($schema, $extendSchema);
+  private function loadCachedDocument() : ?Node {
+    if ($this->documentCache->load($this->getPluginId())) {
+      return AST::fromArray(__do_get_schema());
     }
+    return NULL;
+  }
 
-    return $schema;
+  private function storeCachedDocument(Node $document) : bool {
+    return $this->documentCache->save($this->getPluginId(), "<?php\nfunction __do_get_schema() { return " . var_export(AST::toArray($document), true) . "; }");
   }
 
   /**
@@ -149,6 +198,41 @@ protected function getExtensions() {
     return $this->extensionManager->getExtensions($this->getPluginId());
   }
 
+  protected function getBaseSchemaAst() {
+    $base_source = $this->getSchemaDefinition();
+    if (is_string($base_source)) {
+      @trigger_error("Returning a string from " . __CLASS__ . "::getSchemaDefinition is deprecated. Return an instance of Source or NULL instead.");
+      $base_source = new Source($base_source, __CLASS__);
+    }
+    return Parser::parse($base_source ?? "");
+  }
+
+  protected function getExtensionAsts(array $extensions = []) {
+    $extension_base_asts = [];
+    $extension_extend_asts = [];
+    foreach ($extensions as $id => $extension) {
+      $base_definition = $extension->getBaseDefinition();
+      if (is_string($base_definition)) {
+        @trigger_error("Returning a string from " . get_class($extension) . "::getBaseDefinition is deprecated. Return an instance of Source or NULL instead.");
+        $base_definition = new Source($base_definition, $id . "_base");
+      }
+      if ($base_definition !== NULL) {
+        $extension_base_asts[] = Parser::parse($base_definition);
+      }
+
+      $extend_definition = $extension->getExtensionDefinition();
+      if (is_string($extend_definition)) {
+        @trigger_error("Returning a string from " . get_class($extension) . "::getExtensionDefinition is deprecated. Return an instance of Source or NULL instead.");
+        $extend_definition = new Source($extend_definition, $id . "_extend");
+      }
+      if ($extend_definition !== NULL) {
+        $extension_extend_asts[] = Parser::parse($extend_definition);
+      }
+    }
+
+    return [...$extension_base_asts, ...$extension_extend_asts];
+  }
+
   /**
    * Retrieves the parsed AST of the schema definition.
    *
@@ -161,23 +245,27 @@ protected function getExtensions() {
    * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
    */
   protected function getSchemaDocument(array $extensions = []) {
-    // Only use caching of the parsed document if we aren't in development mode.
-    $cid = "schema:{$this->getPluginId()}";
-    if (empty($this->inDevelopment) && $cache = $this->astCache->get($cid)) {
-      return $cache->data;
-    }
 
-    $extensions = array_filter(array_map(function (SchemaExtensionPluginInterface $extension) {
-      return $extension->getBaseDefinition();
-    }, $extensions), function ($definition) {
-      return !empty($definition);
-    });
+    $extensions = array_filter(
+      array_map(
+        function (SchemaExtensionPluginInterface $extension) {
+          $definition = $extension->getBaseDefinition();
+          if (is_string($definition)) {
+            @trigger_error("Returning a string from " . get_class($extension) . "::getBaseDefinition is deprecated. Return an instance of Source or NULL instead.");
+            $definition = new Source($definition);
+          }
+          return $definition;
+        },
+        $extensions
+      ),
+      function ($definition) {
+        return !empty($definition);
+      }
+    );
+
 
     $schema = array_merge([$this->getSchemaDefinition()], $extensions);
     $ast = Parser::parse(implode("\n\n", $schema));
-    if (empty($this->inDevelopment)) {
-      $this->astCache->set($cid, $ast, CacheBackendInterface::CACHE_PERMANENT, ['graphql']);
-    }
 
     return $ast;
   }
@@ -193,30 +281,21 @@ protected function getSchemaDocument(array $extensions = []) {
    * @throws \GraphQL\Error\SyntaxError
    */
   protected function getExtensionDocument(array $extensions = []) {
-    // Only use caching of the parsed document if we aren't in development mode.
-    $cid = "extension:{$this->getPluginId()}";
-    if (empty($this->inDevelopment) && $cache = $this->astCache->get($cid)) {
-      return $cache->data;
-    }
-
     $extensions = array_filter(array_map(function (SchemaExtensionPluginInterface $extension) {
       return $extension->getExtensionDefinition();
     }, $extensions), function ($definition) {
       return !empty($definition);
     });
 
     $ast = !empty($extensions) ? Parser::parse(implode("\n\n", $extensions)) : NULL;
-    if (empty($this->inDevelopment)) {
-      $this->astCache->set($cid, $ast, CacheBackendInterface::CACHE_PERMANENT, ['graphql']);
-    }
 
     return $ast;
   }
 
   /**
    * Retrieves the raw schema definition string.
    *
-   * @return string
+   * @return \GraphQL\Language\Source|string
    *   The schema definition.
    *
    * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
@@ -236,7 +315,8 @@ protected function getSchemaDefinition() {
           $module->getName(), $path, $definition['class']));
     }
 
-    return file_get_contents($file) ?: NULL;
+    $contents = file_get_contents($file);
+    return $contents ? new Source($contents, $file) : NULL;
   }
 
 }

src/Plugin/SchemaExtensionPluginManager.php

@@ -78,6 +78,16 @@ public function getExtensions($id) {
       }, array_filter($this->getDefinitions(), function ($definition) use ($id) {
         return $definition['schema'] === $id;
       }));
+
+      // Sort the definitions by module weight which should respect dependencies
+      // between modules to ensure extensions requiring other extensions are
+      // processed in the right order.
+      // We use $2 <=> $1 to make sure we're from dependency -> dependee.
+      $module_data = \Drupal::service('extension.list.module')->getList();
+      uasort(
+        $this->extensions[$id],
+        fn (SchemaExtensionPluginInterface $definition1, SchemaExtensionPluginInterface $definition2) => $module_data[$this->extractProviderFromDefinition($definition2->getPluginDefinition())]->sort <=> $module_data[$this->extractProviderFromDefinition($definition1->getPluginDefinition())]->sort
+      );
     }
 
     return $this->extensions[$id];