graphql-stitching 1.2.5 → 1.4.0

data/lib/graphql/stitching/resolver.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "./resolver/arguments"
+require_relative "./resolver/keys"
+
+module GraphQL
+  module Stitching
+    # Defines a root resolver query that provides direct access to an entity type.
+    class Resolver
+      extend ArgumentsParser
+      extend KeysParser
+
+      # location name providing the resolver query.
+      attr_reader :location
+
+      # name of merged type fulfilled through this resolver.
+      attr_reader :type_name
+
+      # name of the root field to query.
+      attr_reader :field
+
+      # a key field to select from prior locations, sent as resolver argument.
+      attr_reader :key
+
+      # parsed resolver Argument structures.
+      attr_reader :arguments
+
+      def initialize(
+        location:,
+        type_name: nil,
+        list: false,
+        field: nil,
+        key: nil,
+        arguments: nil
+      )
+        @location = location
+        @type_name = type_name
+        @list = list
+        @field = field
+        @key = key
+        @arguments = arguments
+      end
+
+      # specifies when the resolver is a list query.
+      def list?
+        @list
+      end
+
+      def version
+        @version ||= Digest::SHA2.hexdigest(as_json.to_json)
+      end
+
+      def ==(other)
+        self.class == other.class && self.as_json == other.as_json
+      end
+
+      def as_json
+        {
+          location: location,
+          type_name: type_name,
+          list: list?,
+          field: field,
+          key: key.to_definition,
+          arguments: arguments.map(&:to_definition).join(", "),
+          argument_types: arguments.map(&:to_type_definition).join(", "),
+        }.tap(&:compact!)
+      end
+    end
+  end
+end

data/lib/graphql/stitching/shaper.rb

@@ -23,8 +23,8 @@ module GraphQL
       def resolve_object_scope(raw_object, parent_type, selections, typename = nil)
         return nil if raw_object.nil?
 
-        typename ||= raw_object[ExportSelection.typename_node.alias]
-        raw_object.reject! { |key, _v| ExportSelection.key?(key) }
+        typename ||= raw_object[Resolver::TYPENAME_EXPORT_NODE.alias]
+        raw_object.reject! { |key, _v| Resolver.export_key?(key) }
 
         selections.each do |node|
           case node
@@ -64,7 +64,7 @@ module GraphQL
             return nil if result.nil?
 
           else
-            raise "Unexpected node of type #{node.class.name} in selection set."
+            raise StitchingError, "Unexpected node of type #{node.class.name} in selection set."
           end
         end
 

data/lib/graphql/stitching/skip_include.rb

@@ -40,7 +40,7 @@ module GraphQL
           end
 
           if filtered_selections.none?
-            filtered_selections << ExportSelection.typename_node
+            filtered_selections << Resolver::TYPENAME_EXPORT_NODE
           end
 
           if changed

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Supergraph
+    class KeyDirective < GraphQL::Schema::Directive
+      graphql_name "key"
+      locations OBJECT, INTERFACE, UNION
+      argument :key, String, required: true
+      argument :location, String, required: true
+      repeatable true
+    end
+  end
+end

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

@@ -5,13 +5,13 @@ module GraphQL::Stitching
     class ResolverDirective < GraphQL::Schema::Directive
       graphql_name "resolver"
       locations OBJECT, INTERFACE, UNION
-      argument :type_name, String, required: false
       argument :location, String, required: true
+      argument :list, Boolean, required: false
       argument :key, String, required: true
       argument :field, String, required: true
-      argument :arg, String, required: true
-      argument :list, Boolean, required: false
-      argument :federation, Boolean, required: false
+      argument :arguments, String, required: true
+      argument :argument_types, String, required: true
+      argument :type_name, String, required: false
       repeatable true
     end
   end

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,90 +1,26 @@
 # 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 = {}
-          boundary_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
-              boundary_map[type_name] ||= []
-              boundary_map[type_name] << Boundary.new(
-                type_name: kwargs.fetch(:type_name, type_name),
-                location: kwargs[:location],
-                key: kwargs[:key],
-                field: kwargs[:field],
-                arg: kwargs[:arg],
-                list: kwargs[:list] || false,
-                federation: kwargs[:federation] || 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,
-            boundaries: boundary_map,
-            executables: executables,
-          )
-        end
-      end
-
       # @return [GraphQL::Schema] the composed schema for the supergraph.
       attr_reader :schema
 
       # @return [Hash<String, Executable>] a map of executable resources by location.
       attr_reader :executables
 
-      attr_reader :boundaries, :locations_by_type_and_field
+      attr_reader :resolvers, :locations_by_type_and_field
 
-      def initialize(schema:, fields: {}, boundaries: {}, executables: {})
+      def initialize(schema:, fields: {}, resolvers: {}, executables: {})
         @schema = schema
         @schema.use(GraphQL::Schema::AlwaysVisible)
 
-        @boundaries = boundaries
+        @resolvers = resolvers
+        @resolvers_by_version = nil
         @fields_by_type_and_location = nil
         @locations_by_type = nil
         @memoized_introspection_types = nil
@@ -111,65 +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 boundaries_for_type = @boundaries.dig(type_name)
-            boundaries_for_type.each do |boundary|
-              existing = type.directives.find do |d|
-                kwargs = d.arguments.keyword_arguments
-                d.graphql_name == ResolverDirective.graphql_name &&
-                  kwargs[:location] == boundary.location &&
-                  kwargs[:key] == boundary.key &&
-                  kwargs[:field] == boundary.field &&
-                  kwargs[:arg] == boundary.arg &&
-                  kwargs.fetch(:list, false) == boundary.list &&
-                  kwargs.fetch(:federation, false) == boundary.federation
-              end
-
-              type.directive(ResolverDirective, **{
-                type_name: (boundary.type_name if boundary.type_name != type_name),
-                location: boundary.location,
-                key: boundary.key,
-                field: boundary.field,
-                arg: boundary.arg,
-                list: boundary.list || nil,
-                federation: boundary.federation || 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
@@ -242,37 +130,36 @@ module GraphQL
         end
       end
 
-      # collects all possible boundary keys for a given type
-      # ("Type") => ["id", ...]
+      # collects all possible resolver keys for a given type
+      # ("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
-            @boundaries[type_name].map(&:key).tap(&:uniq!)
+            @resolvers[type_name].map(&:key).uniq(&:to_definition)
           end
         end
       end
 
-      # collects possible boundary keys for a given type and location
-      # ("Type", "location") => ["id", ...]
+      # collects possible resolver keys for a given type and location
+      # ("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
 
       # For a given type, route from one origin location to one or more remote locations
-      # used to connect a partial type across locations via boundary queries
+      # used to connect a partial type across locations via resolver queries
       def route_type_to_locations(type_name, start_location, goal_locations)
         key_count = possible_keys_for_type(type_name).length
 
         if key_count.zero?
-          # nested root scopes have no boundary keys and just return a location
+          # nested root scopes have no resolver keys and just return a location
           goal_locations.each_with_object({}) do |goal_location, memo|
-            memo[goal_location] = [Boundary.new(location: goal_location)]
+            memo[goal_location] = [Resolver.new(location: goal_location)]
           end
 
         elsif key_count > 1
@@ -281,10 +168,10 @@ module GraphQL
 
         else
           # types with a single key attribute must all be within a single hop of each other,
-          # so can use a simple match to collect boundaries for the goal locations.
-          @boundaries[type_name].each_with_object({}) do |boundary, memo|
-            if goal_locations.include?(boundary.location)
-              memo[boundary.location] = [boundary]
+          # so can use a simple match to collect resolvers for the goal locations.
+          @resolvers[type_name].each_with_object({}) do |resolver, memo|
+            if goal_locations.include?(resolver.location)
+              memo[resolver.location] = [resolver]
             end
           end
         end
@@ -292,7 +179,7 @@ module GraphQL
 
       private
 
-      PathNode = Struct.new(:location, :key, :cost, :boundary, keyword_init: true)
+      PathNode = Struct.new(:location, :key, :cost, :resolver, keyword_init: true)
 
       # tunes A* search to favor paths with fewest joining locations, ie:
       # favor longer paths through target locations over shorter paths with additional locations.
@@ -310,9 +197,9 @@ module GraphQL
           current_key = path.last.key
           current_cost = path.last.cost
 
-          @boundaries[type_name].each do |boundary|
-            forward_location = boundary.location
-            next if current_key != boundary.key
+          @resolvers[type_name].each do |resolver|
+            forward_location = resolver.location
+            next if current_key != resolver.key
             next if path.any? { _1.location == forward_location }
 
             best_cost = costs[forward_location] || Float::INFINITY
@@ -323,13 +210,13 @@ module GraphQL
               location: current_location,
               key: current_key,
               cost: current_cost,
-              boundary: boundary,
+              resolver: resolver,
             )
 
             if goal_locations.include?(forward_location)
               current_result = results[forward_location]
               if current_result.nil? || current_cost < best_cost || (current_cost == best_cost && path.length < current_result.length)
-                results[forward_location] = path.map(&:boundary)
+                results[forward_location] = path.map(&:resolver)
               end
             else
               path.last.cost += 1

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.2.5"
+    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
@@ -24,11 +26,10 @@ module GraphQL
 end
 
 require_relative "stitching/supergraph"
-require_relative "stitching/boundary"
+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"