graphql-stitching 1.3.0 → 1.4.0

data/lib/graphql/stitching/supergraph/to_definition.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+require_relative "./key_directive"
+require_relative "./resolver_directive"
+require_relative "./source_directive"
+
+module GraphQL::Stitching
+  class Supergraph
+    class << self
+      def validate_executable!(location, executable)
+        return true if executable.is_a?(Class) && executable <= GraphQL::Schema
+        return true if executable && executable.respond_to?(:call)
+        raise StitchingError, "Invalid executable provided for location `#{location}`."
+      end
+
+      def from_definition(schema, executables:)
+        schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
+        field_map = {}
+        resolver_map = {}
+        possible_locations = {}
+        introspection_types = schema.introspection_system.types.keys
+
+        schema.types.each do |type_name, type|
+          next if introspection_types.include?(type_name)
+
+          # Collect/build key definitions for each type
+          locations_by_key = type.directives.each_with_object({}) do |directive, memo|
+            next unless directive.graphql_name == KeyDirective.graphql_name
+
+            kwargs = directive.arguments.keyword_arguments
+            memo[kwargs[:key]] ||= []
+            memo[kwargs[:key]] << kwargs[:location]
+          end
+
+          key_definitions = locations_by_key.each_with_object({}) do |(key, locations), memo|
+            memo[key] = Resolver.parse_key(key, locations)
+          end
+
+          # Collect/build resolver definitions for each type
+          type.directives.each do |directive|
+            next unless directive.graphql_name == ResolverDirective.graphql_name
+
+            kwargs = directive.arguments.keyword_arguments
+            resolver_map[type_name] ||= []
+            resolver_map[type_name] << Resolver.new(
+              location: kwargs[:location],
+              type_name: kwargs.fetch(:type_name, type_name),
+              field: kwargs[:field],
+              list: kwargs[:list] || false,
+              key: key_definitions[kwargs[:key]],
+              arguments: Resolver.parse_arguments_with_type_defs(kwargs[:arguments], kwargs[:argument_types]),
+            )
+          end
+
+          next unless type.kind.fields?
+
+          type.fields.each do |field_name, field|
+            # Collection locations for each field definition
+            field.directives.each do |d|
+              next unless d.graphql_name == SourceDirective.graphql_name
+
+              location = d.arguments.keyword_arguments[:location]
+              field_map[type_name] ||= {}
+              field_map[type_name][field_name] ||= []
+              field_map[type_name][field_name] << location
+              possible_locations[location] = true
+            end
+          end
+        end
+
+        executables = possible_locations.keys.each_with_object({}) do |location, memo|
+          executable = executables[location] || executables[location.to_sym]
+          if validate_executable!(location, executable)
+            memo[location] = executable
+          end
+        end
+
+        new(
+          schema: schema,
+          fields: field_map,
+          resolvers: resolver_map,
+          executables: executables,
+        )
+      end
+    end
+
+    def to_definition
+      if @schema.directives[KeyDirective.graphql_name].nil?
+        @schema.directive(KeyDirective)
+      end
+      if @schema.directives[ResolverDirective.graphql_name].nil?
+        @schema.directive(ResolverDirective)
+      end
+      if @schema.directives[SourceDirective.graphql_name].nil?
+        @schema.directive(SourceDirective)
+      end
+
+      @schema.types.each do |type_name, type|
+        if resolvers_for_type = @resolvers.dig(type_name)
+          # Apply key directives for each unique type/key/location
+          # (this allows keys to be composite selections and/or omitted from the supergraph schema)
+          keys_for_type = resolvers_for_type.each_with_object({}) do |resolver, memo|
+            memo[resolver.key.to_definition] ||= Set.new
+            memo[resolver.key.to_definition].merge(resolver.key.locations)
+          end
+
+          keys_for_type.each do |key, locations|
+            locations.each do |location|
+              params = { key: key, location: location }
+
+              unless has_directive?(type, KeyDirective.graphql_name, params)
+                type.directive(KeyDirective, **params)
+              end
+            end
+          end
+
+          # Apply resolver directives for each unique query resolver
+          resolvers_for_type.each do |resolver|
+            params = {
+              location: resolver.location,
+              field: resolver.field,
+              list: resolver.list? || nil,
+              key: resolver.key.to_definition,
+              arguments: resolver.arguments.map(&:to_definition).join(", "),
+              argument_types: resolver.arguments.map(&:to_type_definition).join(", "),
+              type_name: (resolver.type_name if resolver.type_name != type_name),
+            }
+
+            unless has_directive?(type, ResolverDirective.graphql_name, params)
+              type.directive(ResolverDirective, **params.tap(&:compact!))
+            end
+          end
+        end
+
+        next unless type.kind.fields?
+
+        type.fields.each do |field_name, field|
+          locations_for_field = @locations_by_type_and_field.dig(type_name, field_name)
+          next if locations_for_field.nil?
+
+          # Apply source directives to annotate the possible locations of each field
+          locations_for_field.each do |location|
+            params = { location: location }
+
+            unless has_directive?(field, SourceDirective.graphql_name, params)
+              field.directive(SourceDirective, **params)
+            end
+          end
+        end
+      end
+
+      @schema.to_definition
+    end
+
+    private
+
+    def has_directive?(element, directive_name, params)
+      existing = element.directives.find do |d|
+        kwargs = d.arguments.keyword_arguments
+        d.graphql_name == directive_name && params.all? { |k, v| kwargs[k] == v }
+      end
+
+      !existing.nil?
+    end
+  end
+end

data/lib/graphql/stitching/supergraph.rb

@@ -1,78 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "./supergraph/resolver_directive"
-require_relative "./supergraph/source_directive"
+require_relative "./supergraph/to_definition"
 
 module GraphQL
   module Stitching
     class Supergraph
       SUPERGRAPH_LOCATION = "__super"
 
-      class << self
-        def validate_executable!(location, executable)
-          return true if executable.is_a?(Class) && executable <= GraphQL::Schema
-          return true if executable && executable.respond_to?(:call)
-          raise StitchingError, "Invalid executable provided for location `#{location}`."
-        end
-
-        def from_definition(schema, executables:)
-          schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
-          field_map = {}
-          resolver_map = {}
-          possible_locations = {}
-          introspection_types = schema.introspection_system.types.keys
-
-          schema.types.each do |type_name, type|
-            next if introspection_types.include?(type_name)
-
-            type.directives.each do |directive|
-              next unless directive.graphql_name == ResolverDirective.graphql_name
-
-              kwargs = directive.arguments.keyword_arguments
-              resolver_map[type_name] ||= []
-              resolver_map[type_name] << Resolver.new(
-                type_name: kwargs.fetch(:type_name, type_name),
-                location: kwargs[:location],
-                key: kwargs[:key],
-                field: kwargs[:field],
-                list: kwargs[:list] || false,
-                arg: kwargs[:arg],
-                arg_type_name: kwargs[:arg_type_name],
-                representations: kwargs[:representations] || false,
-              )
-            end
-
-            next unless type.kind.fields?
-
-            type.fields.each do |field_name, field|
-              field.directives.each do |d|
-                next unless d.graphql_name == SourceDirective.graphql_name
-
-                location = d.arguments.keyword_arguments[:location]
-                field_map[type_name] ||= {}
-                field_map[type_name][field_name] ||= []
-                field_map[type_name][field_name] << location
-                possible_locations[location] = true
-              end
-            end
-          end
-
-          executables = possible_locations.keys.each_with_object({}) do |location, memo|
-            executable = executables[location] || executables[location.to_sym]
-            if validate_executable!(location, executable)
-              memo[location] = executable
-            end
-          end
-
-          new(
-            schema: schema,
-            fields: field_map,
-            resolvers: resolver_map,
-            executables: executables,
-          )
-        end
-      end
-
       # @return [GraphQL::Schema] the composed schema for the supergraph.
       attr_reader :schema
 
@@ -86,6 +20,7 @@ module GraphQL
         @schema.use(GraphQL::Schema::AlwaysVisible)
 
         @resolvers = resolvers
+        @resolvers_by_version = nil
         @fields_by_type_and_location = nil
         @locations_by_type = nil
         @memoized_introspection_types = nil
@@ -112,66 +47,17 @@ module GraphQL
         end.freeze
       end
 
-      def to_definition
-        if @schema.directives[ResolverDirective.graphql_name].nil?
-          @schema.directive(ResolverDirective)
-        end
-        if @schema.directives[SourceDirective.graphql_name].nil?
-          @schema.directive(SourceDirective)
-        end
-
-        @schema.types.each do |type_name, type|
-          if resolvers_for_type = @resolvers.dig(type_name)
-            resolvers_for_type.each do |resolver|
-              existing = type.directives.find do |d|
-                kwargs = d.arguments.keyword_arguments
-                d.graphql_name == ResolverDirective.graphql_name &&
-                  kwargs[:location] == resolver.location &&
-                  kwargs[:key] == resolver.key &&
-                  kwargs[:field] == resolver.field &&
-                  kwargs[:arg] == resolver.arg &&
-                  kwargs.fetch(:list, false) == resolver.list &&
-                  kwargs.fetch(:representations, false) == resolver.representations
-              end
-
-              type.directive(ResolverDirective, **{
-                type_name: (resolver.type_name if resolver.type_name != type_name),
-                location: resolver.location,
-                key: resolver.key,
-                field: resolver.field,
-                list: resolver.list || nil,
-                arg: resolver.arg,
-                arg_type_name: resolver.arg_type_name,
-                representations: resolver.representations || nil,
-              }.tap(&:compact!)) if existing.nil?
-            end
-          end
-
-          next unless type.kind.fields?
-
-          type.fields.each do |field_name, field|
-            locations_for_field = @locations_by_type_and_field.dig(type_name, field_name)
-            next if locations_for_field.nil?
-
-            locations_for_field.each do |location|
-              existing = field.directives.find do |d|
-                d.graphql_name == SourceDirective.graphql_name &&
-                  d.arguments.keyword_arguments[:location] == location
-              end
-
-              field.directive(SourceDirective, location: location) if existing.nil?
-            end
-          end
-        end
-
-        @schema.to_definition
-      end
-
       # @return [GraphQL::StaticValidation::Validator] static validator for the supergraph schema.
       def static_validator
         @static_validator ||= @schema.static_validator
       end
 
+      def resolvers_by_version
+        @resolvers_by_version ||= resolvers.values.tap(&:flatten!).each_with_object({}) do |resolver, memo|
+          memo[resolver.version] = resolver
+        end
+      end
+
       def fields
         @locations_by_type_and_field.reject { |k, _v| memoized_introspection_types[k] }
       end
@@ -245,24 +131,23 @@ module GraphQL
       end
 
       # collects all possible resolver keys for a given type
-      # ("Type") => ["id", ...]
+      # ("Type") => [Key("id"), ...]
       def possible_keys_for_type(type_name)
         @possible_keys_by_type[type_name] ||= begin
           if type_name == @schema.query.graphql_name
             GraphQL::Stitching::EMPTY_ARRAY
           else
-            @resolvers[type_name].map(&:key).tap(&:uniq!)
+            @resolvers[type_name].map(&:key).uniq(&:to_definition)
           end
         end
       end
 
       # collects possible resolver keys for a given type and location
-      # ("Type", "location") => ["id", ...]
+      # ("Type", "location") => [Key("id"), ...]
       def possible_keys_for_type_and_location(type_name, location)
         possible_keys_by_type = @possible_keys_by_type_and_location[type_name] ||= {}
-        possible_keys_by_type[location] ||= begin
-          location_fields = fields_by_type_and_location[type_name][location] || []
-          location_fields & possible_keys_for_type(type_name)
+        possible_keys_by_type[location] ||= possible_keys_for_type(type_name).select do |key|
+          key.locations.include?(location)
         end
       end
 

data/lib/graphql/stitching/util.rb

@@ -47,6 +47,34 @@ module GraphQL
           structure
         end
 
+        # builds a single-dimensional representation of a wrapped type structure from AST
+        def flatten_ast_type_structure(ast, structure: [])
+          null = true
+
+          while ast.is_a?(GraphQL::Language::Nodes::NonNullType)
+            ast = ast.of_type
+            null = false
+          end
+
+          if ast.is_a?(GraphQL::Language::Nodes::ListType)
+            structure << TypeStructure.new(
+              list: true,
+              null: null,
+              name: nil,
+            )
+
+            flatten_ast_type_structure(ast.of_type, structure: structure)
+          else
+            structure << TypeStructure.new(
+              list: false,
+              null: null,
+              name: ast.name,
+            )
+          end
+
+          structure
+        end
+
         # expands interfaces and unions to an array of their memberships
         # like `schema.possible_types`, but includes child interfaces
         def expand_abstract_type(schema, parent_type)

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.3.0"
+    VERSION = "1.4.0"
   end
 end

data/lib/graphql/stitching.rb

@@ -8,6 +8,8 @@ module GraphQL
     EMPTY_ARRAY = [].freeze
 
     class StitchingError < StandardError; end
+    class CompositionError < StitchingError; end
+    class ValidationError < CompositionError; end
 
     class << self
       def stitch_directive
@@ -28,7 +30,6 @@ require_relative "stitching/resolver"
 require_relative "stitching/client"
 require_relative "stitching/composer"
 require_relative "stitching/executor"
-require_relative "stitching/export_selection"
 require_relative "stitching/http_executable"
 require_relative "stitching/plan"
 require_relative "stitching/planner_step"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-04 00:00:00.000000000 Z
+date: 2024-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -89,6 +89,7 @@ files:
 - docs/images/stitching.png
 - docs/mechanics.md
 - docs/request.md
+- docs/resolver.md
 - docs/supergraph.md
 - examples/file_uploads/Gemfile
 - examples/file_uploads/Procfile
@@ -119,18 +120,21 @@ files:
 - lib/graphql/stitching/executor.rb
 - lib/graphql/stitching/executor/resolver_source.rb
 - lib/graphql/stitching/executor/root_source.rb
-- lib/graphql/stitching/export_selection.rb
 - lib/graphql/stitching/http_executable.rb
 - lib/graphql/stitching/plan.rb
 - lib/graphql/stitching/planner.rb
 - lib/graphql/stitching/planner_step.rb
 - lib/graphql/stitching/request.rb
 - lib/graphql/stitching/resolver.rb
+- lib/graphql/stitching/resolver/arguments.rb
+- lib/graphql/stitching/resolver/keys.rb
 - lib/graphql/stitching/shaper.rb
 - lib/graphql/stitching/skip_include.rb
 - lib/graphql/stitching/supergraph.rb
+- lib/graphql/stitching/supergraph/key_directive.rb
 - lib/graphql/stitching/supergraph/resolver_directive.rb
 - lib/graphql/stitching/supergraph/source_directive.rb
+- lib/graphql/stitching/supergraph/to_definition.rb
 - lib/graphql/stitching/util.rb
 - lib/graphql/stitching/version.rb
 homepage: https://github.com/gmac/graphql-stitching-ruby

data/lib/graphql/stitching/export_selection.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module GraphQL
-  module Stitching
-    # Builds hidden selection fields added by stitiching code,
-    # used to request operational data about resolved objects.
-    class ExportSelection
-      EXPORT_PREFIX = "_export_"
-
-      class << self
-        @typename_node = nil
-
-        def key?(name)
-          return false unless name
-
-          name.start_with?(EXPORT_PREFIX)
-        end
-
-        def key(name)
-          "#{EXPORT_PREFIX}#{name}"
-        end
-
-        # The argument assigning Field.alias changed from
-        # a generic `alias` hash key to a structured `field_alias` kwarg.
-        # See https://github.com/rmosolgo/graphql-ruby/pull/4718
-        FIELD_ALIAS_KWARG = !GraphQL::Language::Nodes::Field.new(field_alias: "a").alias.nil?
-
-        def key_node(field_name)
-          if FIELD_ALIAS_KWARG
-            GraphQL::Language::Nodes::Field.new(field_alias: key(field_name), name: field_name)
-          else
-            GraphQL::Language::Nodes::Field.new(alias: key(field_name), name: field_name)
-          end
-        end
-
-        def typename_node
-          @typename_node ||= key_node("__typename")
-        end
-      end
-    end
-  end
-end