graphql-stitching 1.2.5 → 1.4.0

data/lib/graphql/stitching/planner.rb

@@ -18,7 +18,7 @@ module GraphQL
 
       def perform
         build_root_entrypoints
-        expand_abstract_boundaries
+        expand_abstract_resolvers
         Plan.new(ops: steps.map(&:to_plan_op))
       end
 
@@ -50,16 +50,16 @@ module GraphQL
       # C.2) Distribute non-unique fields among locations that were added during C.1.
       # C.3) Distribute remaining fields among locations weighted by greatest availability.
       #
-      # D) Create paths routing to new entrypoint locations via boundary queries.
+      # D) Create paths routing to new entrypoint locations via resolver queries.
       # D.1) Types joining through multiple keys route using A* search.
       # D.2) Types joining through a single key route via quick location match.
       # (D.2 is an optional optimization of D.1)
       #
-      # E) Translate boundary pathways into new entrypoints.
-      # E.1) Add the key of each boundary query into the prior location's selection set.
+      # E) Translate resolver pathways into new entrypoints.
+      # E.1) Add the key of each resolver query into the prior location's selection set.
       # E.2) Add a planner step for each new entrypoint location, then extract it (B).
       #
-      # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
+      # F) Wrap concrete selections targeting abstract resolvers in typed fragments.
       # **
 
       # adds a planning step for fetching and inserting data into the aggregate result.
@@ -71,10 +71,10 @@ module GraphQL
         variables: {},
         path: [],
         operation_type: QUERY_OP,
-        boundary: nil
+        resolver: nil
       )
         # coalesce repeat parameters into a single entrypoint
-        entrypoint = String.new("#{parent_index}/#{location}/#{parent_type.graphql_name}/#{boundary&.key}")
+        entrypoint = String.new("#{parent_index}/#{location}/#{parent_type.graphql_name}/#{resolver&.key&.to_definition}")
         path.each { entrypoint << "/#{_1}" }
 
         step = @steps_by_entrypoint[entrypoint]
@@ -94,7 +94,7 @@ module GraphQL
             selections: selections,
             variables: variables,
             path: path,
-            boundary: boundary,
+            resolver: resolver,
           )
         else
           step.selections.concat(selections)
@@ -153,7 +153,7 @@ module GraphQL
           end
 
         else
-          raise "Invalid operation type."
+          raise StitchingError, "Invalid operation type."
         end
       end
 
@@ -173,7 +173,7 @@ module GraphQL
             each_field_in_scope(parent_type, fragment.selections, &block)
 
           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
       end
@@ -199,8 +199,8 @@ module GraphQL
         input_selections.each do |node|
           case node
           when GraphQL::Language::Nodes::Field
-            if node.alias&.start_with?(ExportSelection::EXPORT_PREFIX)
-              raise StitchingError, %(Alias "#{node.alias}" is not allowed because "#{ExportSelection::EXPORT_PREFIX}" is a reserved prefix.)
+            if node.alias&.start_with?(Resolver::EXPORT_PREFIX)
+              raise StitchingError, %(Alias "#{node.alias}" is not allowed because "#{Resolver::EXPORT_PREFIX}" is a reserved prefix.)
             elsif node.name == TYPENAME
               locale_selections << node
               next
@@ -255,53 +255,42 @@ module GraphQL
             end
 
           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
 
         # B.4) Add a `__typename` export to abstracts and types that implement
         # fragments so that resolved type information is available during execution.
         if requires_typename
-          locale_selections << ExportSelection.typename_node
+          locale_selections << Resolver::TYPENAME_EXPORT_NODE
         end
 
         if remote_selections
           # C) Delegate adjoining selections to new entrypoint locations.
           remote_selections_by_location = delegate_remote_selections(parent_type, remote_selections)
 
-          # D) Create paths routing to new entrypoint locations via boundary queries.
+          # D) Create paths routing to new entrypoint locations via resolver queries.
           routes = @supergraph.route_type_to_locations(parent_type.graphql_name, current_location, remote_selections_by_location.keys)
 
-          # E) Translate boundary pathways into new entrypoints.
+          # E) Translate resolver pathways into new entrypoints.
           routes.each_value do |route|
-            route.reduce(locale_selections) do |parent_selections, boundary|
-              # E.1) Add the key of each boundary query into the prior location's selection set.
-              if boundary.key
-                foreign_key = ExportSelection.key(boundary.key)
-                has_key = false
-                has_typename = false
-
-                parent_selections.each do |node|
-                  next unless node.is_a?(GraphQL::Language::Nodes::Field)
-                  has_key ||= node.alias == foreign_key
-                  has_typename ||= node.alias == ExportSelection.typename_node.alias
-                end
-
-                parent_selections << ExportSelection.key_node(boundary.key) unless has_key
-                parent_selections << ExportSelection.typename_node unless has_typename
-              end
+            route.reduce(locale_selections) do |parent_selections, resolver|
+              # E.1) Add the key of each resolver query into the prior location's selection set.
+              parent_selections.push(*resolver.key.export_nodes) if resolver.key
 
               # E.2) Add a planner step for each new entrypoint location.
               add_step(
-                location: boundary.location,
+                location: resolver.location,
                 parent_index: parent_index,
                 parent_type: parent_type,
-                selections: remote_selections_by_location[boundary.location] || [],
+                selections: remote_selections_by_location[resolver.location] || [],
                 path: path.dup,
-                boundary: boundary.key ? boundary : nil,
+                resolver: resolver.key ? resolver : nil,
               ).selections
             end
           end
+
+          locale_selections.uniq! { _1.alias || _1.name }
         end
 
         locale_selections
@@ -414,14 +403,14 @@ module GraphQL
         selections_by_location
       end
 
-      # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
-      def expand_abstract_boundaries
+      # F) Wrap concrete selections targeting abstract resolvers in typed fragments.
+      def expand_abstract_resolvers
         @steps_by_entrypoint.each_value do |step|
-          next unless step.boundary
+          next unless step.resolver
 
-          boundary_type = @supergraph.memoized_schema_types[step.boundary.type_name]
-          next unless boundary_type.kind.abstract?
-          next if boundary_type == step.parent_type
+          resolver_type = @supergraph.memoized_schema_types[step.resolver.type_name]
+          next unless resolver_type.kind.abstract?
+          next if resolver_type == step.parent_type
 
           expanded_selections = nil
           step.selections.reject! do |node|

data/lib/graphql/stitching/planner_step.rb

@@ -9,7 +9,7 @@ module GraphQL
       GRAPHQL_PRINTER = GraphQL::Language::Printer.new
 
       attr_reader :index, :location, :parent_type, :operation_type, :path
-      attr_accessor :after, :selections, :variables, :boundary
+      attr_accessor :after, :selections, :variables, :resolver
 
       def initialize(
         location:,
@@ -20,7 +20,7 @@ module GraphQL
         selections: [],
         variables: {},
         path: [],
-        boundary: nil
+        resolver: nil
       )
         @location = location
         @parent_type = parent_type
@@ -30,7 +30,7 @@ module GraphQL
         @selections = selections
         @variables = variables
         @path = path
-        @boundary = boundary
+        @resolver = resolver
       end
 
       def to_plan_op
@@ -43,17 +43,17 @@ module GraphQL
           variables: rendered_variables,
           path: @path,
           if_type: type_condition,
-          boundary: @boundary,
+          resolver: @resolver&.version,
         )
       end
 
       private
 
-      # Concrete types going to a boundary report themselves as a type condition.
+      # Concrete types going to a resolver report themselves as a type condition.
       # This is used by the executor to evalute which planned fragment selections
       # actually apply to the resolved object types.
       def type_condition
-        @parent_type.graphql_name if @boundary && !parent_type.kind.abstract?
+        @parent_type.graphql_name if @resolver && !parent_type.kind.abstract?
       end
 
       def rendered_selections

data/lib/graphql/stitching/resolver/arguments.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Resolver
+    # Defines a single resolver argument structure
+    # @api private
+    class Argument
+      attr_reader :name
+      attr_reader :value
+      attr_reader :type_name
+
+      def initialize(name:, value:, list: false, type_name: nil)
+        @name = name
+        @value = value
+        @list = list
+        @type_name = type_name
+      end
+
+      def list?
+        @list
+      end
+
+      def key?
+        value.key?
+      end
+
+      def verify_key(key)
+        if key?
+          value.verify_key(self, key)
+          true
+        else
+          false
+        end
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @name == other.name &&
+          @value == other.value &&
+          @type_name == other.type_name &&
+          @list == other.list?
+      end
+
+      def build(origin_obj)
+        value.build(origin_obj)
+      end
+
+      def print
+        "#{name}: #{value.print}"
+      end
+
+      def to_definition
+        print.gsub(%|"|, "'")
+      end
+
+      alias_method :to_s, :to_definition
+
+      def to_type_definition
+        "#{name}: #{to_type_signature}"
+      end
+
+      def to_type_signature
+        # need to derive nullability...
+        list? ? "[#{@type_name}!]!" : "#{@type_name}!"
+      end
+    end
+
+    # An abstract argument input value
+    # @api private
+    class ArgumentValue
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      def key?
+        false
+      end
+
+      def verify_key(arg, key)
+        nil
+      end
+
+      def ==(other)
+        self.class == other.class && value == other.value
+      end
+
+      def build(origin_obj)
+        value
+      end
+
+      def print
+        value
+      end
+    end
+
+    # An object input value
+    # @api private
+    class ObjectArgumentValue < ArgumentValue
+      def key?
+        value.any?(&:key?)
+      end
+
+      def verify_key(arg, key)
+        value.each { _1.verify_key(key) }
+      end
+
+      def build(origin_obj)
+        value.each_with_object({}) do |arg, memo|
+          memo[arg.name] = arg.build(origin_obj)
+        end
+      end
+
+      def print
+        "{#{value.map(&:print).join(", ")}}"
+      end
+    end
+
+    # A key input value
+    # @api private
+    class KeyArgumentValue < ArgumentValue
+      def initialize(value)
+        super(Array(value))
+      end
+
+      def key?
+        true
+      end
+
+      def verify_key(arg, key)
+        key_field = value.reduce(Resolver::KeyField.new("", inner: key)) do |field, ns|
+          if ns == Resolver::TYPE_NAME
+            Resolver::KeyField.new(Resolver::TYPE_NAME)
+          elsif field
+            field.inner.find { _1.name == ns }
+          end
+        end
+
+        # still not capturing enough type information to accurately compare key/arg types...
+        # best we can do for now is to verify the argument insertion matches a key path.
+        if key_field.nil?
+          raise CompositionError, "Argument `#{arg.name}: #{print}` cannot insert key `#{key.to_definition}`."
+        end
+      end
+
+      def build(origin_obj)
+        value.each_with_index.reduce(origin_obj) do |obj, (ns, idx)|
+          obj[idx.zero? ? Resolver.export_key(ns) : ns]
+        end
+      end
+
+      def print
+        "$.#{value.join(".")}"
+      end
+    end
+
+    # A typed enum input value
+    # @api private
+    class EnumArgumentValue < ArgumentValue
+    end
+
+    # A primitive input value literal
+    # @api private
+    class LiteralArgumentValue < ArgumentValue
+      def print
+        JSON.generate(value)
+      end
+    end
+
+    # Parser for building argument templates into resolver structures
+    # @api private
+    module ArgumentsParser
+      # Parses an argument template string into resolver arguments via schema casting.
+      # @param template [String] the template string to parse.
+      # @param field_def [GraphQL::Schema::FieldDefinition] a field definition providing arguments schema.
+      # @return [[GraphQL::Stitching::Resolver::Argument]] an array of resolver arguments.
+      def parse_arguments_with_field(template, field_def)
+        ast = parse_arg_defs(template)
+        args = build_argument_set(ast, field_def.arguments)
+        args.each do |arg|
+          next unless arg.key?
+
+          if field_def.type.list? && !arg.list?
+            raise CompositionError, "Cannot use repeatable key for `#{field_def.owner.graphql_name}.#{field_def.graphql_name}` " \
+              "in non-list argument `#{arg.name}`."
+          elsif !field_def.type.list? && arg.list?
+            raise CompositionError, "Cannot use non-repeatable key for `#{field_def.owner.graphql_name}.#{field_def.graphql_name}` " \
+              "in list argument `#{arg.name}`."
+          end
+        end
+
+        args
+      end
+
+      # Parses an argument template string into resolver arguments via SDL casting.
+      # @param template [String] the template string to parse.
+      # @param type_defs [String] the type definition string declaring argument types.
+      # @return [[GraphQL::Stitching::Resolver::Argument]] an array of resolver arguments.
+      def parse_arguments_with_type_defs(template, type_defs)
+        type_map = parse_type_defs(type_defs)
+        parse_arg_defs(template).map { build_argument(_1, type_struct: type_map[_1.name]) }
+      end
+
+      private
+
+      def parse_arg_defs(template)
+        template = template
+          .gsub("'", %|"|) # 'sfoo' -> "sfoo"
+          .gsub(/(\$[\w\.]+)/) { %|"#{_1}"| } # $.key -> "$.key"
+          .tap(&:strip!)
+
+        template = template[1..-2] if template.start_with?("(") && template.end_with?(")")
+
+        GraphQL.parse("{ f(#{template}) }")
+          .definitions.first
+          .selections.first
+          .arguments
+      end
+
+      def parse_type_defs(template)
+        GraphQL.parse("type T { #{template} }")
+          .definitions.first
+          .fields.each_with_object({}) do |node, memo|
+            memo[node.name] = GraphQL::Stitching::Util.flatten_ast_type_structure(node.type)
+          end
+      end
+
+      def build_argument_set(nodes, argument_defs)
+        if argument_defs
+          argument_defs.each_value do |argument_def|
+            if argument_def.type.non_null? && !nodes.find { _1.name == argument_def.graphql_name }
+              raise CompositionError, "Required argument `#{argument_def.graphql_name}` has no input."
+            end
+          end
+        end
+
+        nodes.map do |node|
+          argument_def = if argument_defs
+            arg = argument_defs[node.name]
+            raise CompositionError, "Input `#{node.name}` is not a valid argument." unless arg
+            arg
+          end
+
+          build_argument(node, argument_def: argument_def)
+        end
+      end
+
+      def build_argument(node, argument_def: nil, type_struct: nil)
+        value = if node.value.is_a?(GraphQL::Language::Nodes::InputObject)
+          build_object_value(node.value, argument_def ? argument_def.type.unwrap : nil)
+        elsif node.value.is_a?(GraphQL::Language::Nodes::Enum)
+          EnumArgumentValue.new(node.value.name)
+        elsif node.value.is_a?(String) && node.value.start_with?("$.")
+          KeyArgumentValue.new(node.value.sub(/^\$\./, "").split("."))
+        else
+          LiteralArgumentValue.new(node.value)
+        end
+
+        Argument.new(
+          name: node.name,
+          value: value,
+          # doesn't support nested lists...?
+          list: argument_def ? argument_def.type.list? : (type_struct&.first&.list? || false),
+          type_name: argument_def ? argument_def.type.unwrap.graphql_name : type_struct&.last&.name,
+        )
+      end
+
+      def build_object_value(node, object_def)
+        if object_def
+          if !object_def.kind.input_object? && !object_def.kind.scalar?
+            raise CompositionError, "Objects can only be built into input object and scalar positions."
+          elsif object_def.kind.scalar? && GraphQL::Schema::BUILT_IN_TYPES[object_def.graphql_name]
+            raise CompositionError, "Objects can only be built into custom scalar types."
+          elsif object_def.kind.scalar?
+            object_def = nil
+          end
+        end
+
+        ObjectArgumentValue.new(build_argument_set(node.arguments, object_def&.arguments))
+      end
+    end
+  end
+end

data/lib/graphql/stitching/resolver/keys.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Resolver
+    EXPORT_PREFIX = "_export_"
+    TYPE_NAME = "__typename"
+
+    class FieldNode
+      # GraphQL Ruby changed the argument assigning Field.alias from
+      # a generic `alias` hash key to a structured `field_alias` kwarg
+      # in https://github.com/rmosolgo/graphql-ruby/pull/4718.
+      # This adapts to the library implementation present.
+      GRAPHQL_RUBY_FIELD_ALIAS_KWARG = !GraphQL::Language::Nodes::Field.new(field_alias: "a").alias.nil?
+
+      class << self
+        def build(field_name:, field_alias: nil, selections: GraphQL::Stitching::EMPTY_ARRAY)
+          if GRAPHQL_RUBY_FIELD_ALIAS_KWARG
+            GraphQL::Language::Nodes::Field.new(
+              field_alias: field_alias,
+              name: field_name,
+              selections: selections,
+            )
+          else
+            GraphQL::Language::Nodes::Field.new(
+              alias: field_alias,
+              name: field_name,
+              selections: selections,
+            )
+          end
+        end
+      end
+    end
+
+    class KeyFieldSet < Array
+      def initialize(fields)
+        super(fields.sort_by(&:name))
+        @to_definition = nil
+        @export_nodes = nil
+      end
+
+      def ==(other)
+        to_definition == other.to_definition
+      end
+
+      def default_argument_name
+        length == 1 ? first.name : nil
+      end
+
+      def to_definition
+        @to_definition ||= map(&:to_definition).join(" ").freeze
+      end
+
+      alias_method :to_s, :to_definition
+
+      def export_nodes
+        @export_nodes ||= map(&:export_node)
+      end
+    end
+
+    EMPTY_FIELD_SET = KeyFieldSet.new(GraphQL::Stitching::EMPTY_ARRAY)
+    TYPENAME_EXPORT_NODE = FieldNode.build(
+      field_alias: "#{EXPORT_PREFIX}#{TYPE_NAME}",
+      field_name: TYPE_NAME,
+    )
+
+    class Key < KeyFieldSet
+      attr_reader :locations
+
+      def initialize(fields, locations: GraphQL::Stitching::EMPTY_ARRAY)
+        super(fields)
+        @locations = locations
+        to_definition
+        export_nodes
+        freeze
+      end
+
+      def export_nodes
+        @export_nodes ||= begin
+          nodes = map(&:export_node)
+          nodes << TYPENAME_EXPORT_NODE
+          nodes
+        end
+      end
+    end
+
+    class KeyField
+      # name of the key, may be a field alias
+      attr_reader :name
+
+      # inner key selections
+      attr_reader :inner
+
+      # optional information about location and typing, used during composition
+      attr_accessor :type_name
+      attr_accessor :list
+      alias_method :list?, :list
+
+      def initialize(name, root: false, inner: EMPTY_FIELD_SET)
+        @name = name
+        @inner = inner
+        @root = root
+      end
+
+      def to_definition
+        @inner.empty? ? @name : "#{@name} { #{@inner.to_definition} }"
+      end
+
+      def export_node
+        FieldNode.build(
+          field_alias: @root ? "#{EXPORT_PREFIX}#{@name}" : nil,
+          field_name: @name,
+          selections: @inner.export_nodes,
+        )
+      end
+    end
+
+    module KeysParser
+      def export_key(name)
+        "#{EXPORT_PREFIX}#{name}"
+      end
+
+      def export_key?(name)
+        return false unless name
+
+        name.start_with?(EXPORT_PREFIX)
+      end
+
+      def parse_key(template, locations = GraphQL::Stitching::EMPTY_ARRAY)
+        Key.new(parse_field_set(template), locations: locations)
+      end
+
+      def parse_key_with_types(template, subgraph_types_by_location)
+        field_set = parse_field_set(template)
+        locations = subgraph_types_by_location.filter_map do |location, subgraph_type|
+          location if field_set_matches_type?(field_set, subgraph_type)
+        end
+
+        if locations.none?
+          message = "Key `#{field_set.to_definition}` does not exist in any location."
+          message += " Composite key selections may not be distributed." if field_set.length > 1
+          raise CompositionError, message
+        end
+
+        assign_field_set_info!(field_set, subgraph_types_by_location[locations.first])
+        Key.new(field_set, locations: locations)
+      end
+
+      private
+
+      def parse_field_set(template)
+        template = template.strip
+        template = template[1..-2] if template.start_with?("{") && template.end_with?("}")
+
+        ast = GraphQL.parse("{ #{template} }").definitions.first.selections
+        build_field_set(ast, root: true)
+      end
+
+      def build_field_set(selections, root: false)
+        return EMPTY_FIELD_SET if selections.empty?
+
+        fields = selections.map do |node|
+          raise CompositionError, "Key selections must be fields." unless node.is_a?(GraphQL::Language::Nodes::Field)
+          raise CompositionError, "Key fields may not specify aliases." unless node.alias.nil?
+
+          KeyField.new(node.name, inner: build_field_set(node.selections), root: root)
+        end
+
+        KeyFieldSet.new(fields)
+      end
+
+      def field_set_matches_type?(field_set, subgraph_type)
+        subgraph_type = subgraph_type.unwrap
+        field_set.all? do |field|
+          # fixme: union doesn't have fields, but may support these selections...
+          next true if subgraph_type.kind.union?
+          field_matches_type?(field, subgraph_type.get_field(field.name)&.type&.unwrap)
+        end
+      end
+
+      def field_matches_type?(field, subgraph_type)
+        return false if subgraph_type.nil?
+
+        if field.inner.empty? && subgraph_type.kind.composite?
+          raise CompositionError, "Composite key fields must contain nested selections."
+        end
+
+        field.inner.empty? || field_set_matches_type?(field.inner, subgraph_type)
+      end
+
+      def assign_field_set_info!(field_set, subgraph_type)
+        subgraph_type = subgraph_type.unwrap
+        field_set.each do |field|
+          # fixme: union doesn't have fields, but may support these selections...
+          next if subgraph_type.kind.union?
+          assign_field_info!(field, subgraph_type.get_field(field.name).type)
+        end
+      end
+
+      def assign_field_info!(field, subgraph_type)
+        field.list = subgraph_type.list?
+        field.type_name = subgraph_type.unwrap.graphql_name
+        assign_field_set_info!(field.inner, subgraph_type)
+      end
+    end
+  end
+end