graphql-stitching 0.1.0 → 0.2.2

data/lib/graphql/stitching/planner.rb

@@ -6,9 +6,9 @@ module GraphQL
       SUPERGRAPH_LOCATIONS = [Supergraph::LOCATION].freeze
       TYPENAME_NODE = GraphQL::Language::Nodes::Field.new(alias: "_STITCH_typename", name: "__typename")
 
-      def initialize(supergraph:, document:)
+      def initialize(supergraph:, request:)
         @supergraph = supergraph
-        @document = document
+        @request = request
         @sequence_key = 0
         @operations_by_grouping = {}
       end
@@ -31,44 +31,18 @@ module GraphQL
 
       private
 
-      def add_operation(location:, parent_type:, selections: nil, insertion_path: [], operation_type: "query", after_key: 0, boundary: nil)
-        parent_key = @sequence_key += 1
-        selection_set, variables = if selections&.any?
-          extract_locale_selections(location, parent_type, selections, insertion_path, parent_key)
-        end
-
-        grouping = [after_key, location, parent_type.graphql_name, *insertion_path].join("/")
-
-        if op = @operations_by_grouping[grouping]
-          op.selections += selection_set if selection_set
-          op.variables.merge!(variables) if variables
-          return op
-        end
-
-        type_conditional = !parent_type.kind.abstract? && parent_type != @supergraph.schema.query && parent_type != @supergraph.schema.mutation
-
-        @operations_by_grouping[grouping] = PlannerOperation.new(
-          key: parent_key,
-          after_key: after_key,
-          location: location,
-          parent_type: parent_type,
-          operation_type: operation_type,
-          insertion_path: insertion_path,
-          type_condition: type_conditional ? parent_type.graphql_name : nil,
-          selections: selection_set || [],
-          variables: variables || {},
-          boundary: boundary,
-        )
-      end
-
+      # groups root fields by operational strategy:
+      # - query immedaitely groups all root fields by location for async resolution
+      # - mutation groups sequential root fields by location for serial resolution
       def build_root_operations
-        case @document.operation.operation_type
+        case @request.operation.operation_type
         when "query"
-          # plan steps grouping all fields by location for async execution
           parent_type = @supergraph.schema.query
 
-          selections_by_location = @document.operation.selections.each_with_object({}) do |node, memo|
+          selections_by_location = @request.operation.selections.each_with_object({}) do |node, memo|
             locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name] || SUPERGRAPH_LOCATIONS
+
+            # root fields currently just delegate to the last location that defined them; this should probably be smarter
             memo[locations.last] ||= []
             memo[locations.last] << node
           end
@@ -78,20 +52,19 @@ module GraphQL
           end
 
         when "mutation"
-          # plan steps grouping sequential fields by location for serial execution
           parent_type = @supergraph.schema.mutation
           location_groups = []
 
-          @document.operation.selections.reduce(nil) do |last_location, node|
-            location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].last
-            if location != last_location
-              location_groups << {
-                location: location,
-                selections: [],
-              }
+          @request.operation.selections.reduce(nil) do |last_location, node|
+            # root fields currently just delegate to the last location that defined them; this should probably be smarter
+            next_location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].last
+
+            if next_location != last_location
+              location_groups << { location: next_location, selections: [] }
             end
+
             location_groups.last[:selections] << node
-            location
+            next_location
           end
 
           location_groups.reduce(0) do |after_key, group|
@@ -109,81 +82,114 @@ module GraphQL
         end
       end
 
-      def extract_locale_selections(current_location, parent_type, input_selections, insertion_path, after_key)
-        remote_selections = []
-        selections_result = []
-        variables_result = {}
-        implements_fragments = false
+      # adds an operation (data access) to the plan which maps a data selection to an insertion point.
+      # note that planned operations are NOT always 1:1 with executed requests, as the executor can
+      # frequently batch different insertion points with the same location into a single request.
+      def add_operation(
+        location:,
+        parent_type:,
+        selections:,
+        insertion_path: [],
+        operation_type: "query",
+        after_key: 0,
+        boundary: nil
+      )
+        parent_key = @sequence_key += 1
+        locale_variables = {}
+        locale_selections = if selections.any?
+          extract_locale_selections(location, parent_type, selections, insertion_path, parent_key, locale_variables)
+        else
+          selections
+        end
 
-        if parent_type.kind.interface?
-          # fields of a merged interface may not belong to the interface at the local level,
-          # so these non-local interface fields get expanded into typed fragments for planning
-          local_interface_fields = @supergraph.fields_by_type_and_location[parent_type.graphql_name][current_location]
-          extended_selections = []
-
-          input_selections.reject! do |node|
-            if node.is_a?(GraphQL::Language::Nodes::Field) && !local_interface_fields.include?(node.name)
-              extended_selections << node
-              true
-            end
-          end
+        # groupings coalesce similar operation parameters into a single operation
+        # multiple operations per service may still occur with different insertion points,
+        # but those will get query-batched together during execution.
+        grouping = String.new
+        grouping << after_key.to_s << "/" << location << "/" << parent_type.graphql_name
+        grouping = insertion_path.reduce(grouping) do |memo, segment|
+          memo << "/" << segment
+        end
+
+        if op = @operations_by_grouping[grouping]
+          op.selections.concat(locale_selections)
+          op.variables.merge!(locale_variables)
+          op
+        else
+          # concrete types that are not root Query/Mutation report themselves as a type condition
+          # executor must check the __typename of loaded objects to see if they match subsequent operations
+          # this prevents the executor from taking action on unused fragment selections
+          type_conditional = !parent_type.kind.abstract? && parent_type != @supergraph.schema.query && parent_type != @supergraph.schema.mutation
+
+          @operations_by_grouping[grouping] = PlannerOperation.new(
+            key: parent_key,
+            after_key: after_key,
+            location: location,
+            parent_type: parent_type,
+            operation_type: operation_type,
+            insertion_path: insertion_path,
+            type_condition: type_conditional ? parent_type.graphql_name : nil,
+            selections: locale_selections,
+            variables: locale_variables,
+            boundary: boundary,
+          )
+        end
+      end
 
-          if extended_selections.any?
-            possible_types = Util.get_possible_types(@supergraph.schema, parent_type)
-            possible_types.each do |possible_type|
-              next if possible_type.kind.abstract? # ignore child interfaces
-              next unless @supergraph.locations_by_type[possible_type.graphql_name].include?(current_location)
+      # extracts a selection tree that can all be fulfilled through the current planning location.
+      # adjoining remote selections will fork new insertion points and extract selections at those locations.
+      def extract_locale_selections(current_location, parent_type, input_selections, insertion_path, after_key, locale_variables)
+        remote_selections = nil
+        locale_selections = []
+        implements_fragments = false
 
-              type_name = GraphQL::Language::Nodes::TypeName.new(name: possible_type.graphql_name)
-              input_selections << GraphQL::Language::Nodes::InlineFragment.new(type: type_name, selections: extended_selections)
-            end
-          end
+        if parent_type.kind.interface?
+          expand_interface_selections(current_location, parent_type, input_selections)
         end
 
         input_selections.each do |node|
           case node
           when GraphQL::Language::Nodes::Field
             if node.name == "__typename"
-              selections_result << node
+              locale_selections << node
               next
             end
 
             possible_locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name] || SUPERGRAPH_LOCATIONS
             unless possible_locations.include?(current_location)
+              remote_selections ||= []
               remote_selections << node
               next
             end
 
-            field_type = Util.get_named_type_for_field_node(@supergraph.schema, parent_type, node)
-
-            extract_node_variables!(node, variables_result)
+            field_type = Util.named_type_for_field_node(@supergraph.schema, parent_type, node)
+            extract_node_variables(node, locale_variables)
 
             if Util.is_leaf_type?(field_type)
-              selections_result << node
+              locale_selections << node
             else
-              expanded_path = [*insertion_path, node.alias || node.name]
-              selection_set, variables = extract_locale_selections(current_location, field_type, node.selections, expanded_path, after_key)
-              selections_result << node.merge(selections: selection_set)
-              variables_result.merge!(variables)
+              insertion_path.push(node.alias || node.name)
+              selection_set = extract_locale_selections(current_location, field_type, node.selections, insertion_path, after_key, locale_variables)
+              insertion_path.pop
+
+              locale_selections << node.merge(selections: selection_set)
             end
 
           when GraphQL::Language::Nodes::InlineFragment
             next unless @supergraph.locations_by_type[node.type.name].include?(current_location)
 
             fragment_type = @supergraph.schema.types[node.type.name]
-            selection_set, variables = extract_locale_selections(current_location, fragment_type, node.selections, insertion_path, after_key)
-            selections_result << node.merge(selections: selection_set)
-            variables_result.merge!(variables)
+            selection_set = extract_locale_selections(current_location, fragment_type, node.selections, insertion_path, after_key, locale_variables)
+            locale_selections << node.merge(selections: selection_set)
             implements_fragments = true
 
           when GraphQL::Language::Nodes::FragmentSpread
-            fragment = @document.fragment_definitions[node.name]
+            fragment = @request.fragment_definitions[node.name]
             next unless @supergraph.locations_by_type[fragment.type.name].include?(current_location)
 
             fragment_type = @supergraph.schema.types[fragment.type.name]
-            selection_set, variables = extract_locale_selections(current_location, fragment_type, fragment.selections, insertion_path, after_key)
-            selections_result << GraphQL::Language::Nodes::InlineFragment.new(type: fragment.type, selections: selection_set)
-            variables_result.merge!(variables)
+            selection_set = extract_locale_selections(current_location, fragment_type, fragment.selections, insertion_path, after_key, locale_variables)
+            locale_selections << GraphQL::Language::Nodes::InlineFragment.new(type: fragment.type, selections: selection_set)
             implements_fragments = true
 
           else
@@ -191,25 +197,35 @@ module GraphQL
           end
         end
 
-        if remote_selections.any?
-          selection_set = build_child_operations(current_location, parent_type, remote_selections, insertion_path, after_key)
-          selections_result.concat(selection_set)
+        if remote_selections
+          delegate_remote_selections(
+            current_location,
+            parent_type,
+            locale_selections,
+            remote_selections,
+            insertion_path,
+            after_key
+          )
         end
 
+        # always include a __typename on abstracts and scopes that implement fragments
+        # this provides type information to inspect while shaping the final result
         if parent_type.kind.abstract? || implements_fragments
-          selections_result << TYPENAME_NODE
+          locale_selections << TYPENAME_NODE
         end
 
-        return selections_result, variables_result
+        locale_selections
       end
 
-      def build_child_operations(current_location, parent_type, input_selections, insertion_path, after_key)
-        parent_selections_result = []
+      # distributes remote selections across locations,
+      # while spawning new operations for each new fulfillment.
+      def delegate_remote_selections(current_location, parent_type, locale_selections, remote_selections, insertion_path, after_key)
+        possible_locations_by_field = @supergraph.locations_by_type_and_field[parent_type.graphql_name]
         selections_by_location = {}
 
         # distribute unique fields among required locations
-        input_selections.reject! do |node|
-          possible_locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name]
+        remote_selections.reject! do |node|
+          possible_locations = possible_locations_by_field[node.name]
           if possible_locations.length == 1
             selections_by_location[possible_locations.first] ||= []
             selections_by_location[possible_locations.first] << node
@@ -217,31 +233,35 @@ module GraphQL
           end
         end
 
-        # distribute non-unique fields among available locations, preferring used locations
-        if input_selections.any?
-          # weight locations by number of needed fields available, prefer greater availability
-          location_weights = input_selections.each_with_object({}) do |node, memo|
-            possible_locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name]
-            possible_locations.each do |location|
-              memo[location] ||= 0
-              memo[location] += 1
+        # distribute non-unique fields among available locations, preferring locations already used
+        if remote_selections.any?
+          # weight locations by number of required fields available, preferring greater availability
+          location_weights = if remote_selections.length > 1
+            remote_selections.each_with_object({}) do |node, memo|
+              possible_locations = possible_locations_by_field[node.name]
+              possible_locations.each do |location|
+                memo[location] ||= 0
+                memo[location] += 1
+              end
             end
+          else
+            GraphQL::Stitching::EMPTY_OBJECT
           end
 
-          input_selections.each do |node|
-            possible_locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name]
-
-            perfect_location_score = input_selections.length
+          remote_selections.each do |node|
+            possible_locations = possible_locations_by_field[node.name]
             preferred_location_score = 0
-            preferred_location = possible_locations.reduce(possible_locations.first) do |current_loc, candidate_loc|
-              score = selections_by_location[location] ? perfect_location_score : 0
-              score += location_weights.fetch(candidate_loc, 0)
+
+            # hill climbing selects highest scoring locations to use
+            preferred_location = possible_locations.reduce(possible_locations.first) do |best_location, possible_location|
+              score = selections_by_location[location] ? remote_selections.length : 0
+              score += location_weights.fetch(possible_location, 0)
 
               if score > preferred_location_score
                 preferred_location_score = score
-                candidate_loc
+                possible_location
               else
-                current_loc
+                best_location
               end
             end
 
@@ -251,70 +271,103 @@ module GraphQL
         end
 
         routes = @supergraph.route_type_to_locations(parent_type.graphql_name, current_location, selections_by_location.keys)
-        routes.values.each_with_object({}) do |route, memo|
+        routes.values.each_with_object({}) do |route, ops_by_location|
           route.reduce(nil) do |parent_op, boundary|
             location = boundary["location"]
-            next memo[location] if memo[location]
+            new_operation = false
 
-            child_op = memo[location] = add_operation(
-              location: location,
-              selections: selections_by_location[location],
-              parent_type: parent_type,
-              insertion_path: insertion_path,
-              boundary: boundary,
-              after_key: after_key,
-            )
-
-            foreign_key_node = GraphQL::Language::Nodes::Field.new(
-              alias: "_STITCH_#{boundary["selection"]}",
-              name: boundary["selection"]
-            )
-
-            if parent_op
-              parent_op.selections << foreign_key_node << TYPENAME_NODE
-            else
-              parent_selections_result << foreign_key_node << TYPENAME_NODE
+            unless op = ops_by_location[location]
+              new_operation = true
+              op = ops_by_location[location] = add_operation(
+                location: location,
+                # routing locations added as intermediaries have no initial selections,
+                # but will be given foreign keys by subsequent operations
+                selections: selections_by_location[location] || [],
+                parent_type: parent_type,
+                insertion_path: insertion_path.dup,
+                boundary: boundary,
+                after_key: after_key,
+              )
+            end
+
+            foreign_key = "_STITCH_#{boundary["selection"]}"
+            parent_selections = parent_op ? parent_op.selections : locale_selections
+
+            if new_operation || parent_selections.none? { _1.is_a?(GraphQL::Language::Nodes::Field) && _1.alias == foreign_key }
+              foreign_key_node = GraphQL::Language::Nodes::Field.new(alias: foreign_key, name: boundary["selection"])
+              parent_selections << foreign_key_node << TYPENAME_NODE
             end
 
-            child_op
+            op
           end
         end
-
-        parent_selections_result
       end
 
-      def extract_node_variables!(node_with_args, variables={})
-        node_with_args.arguments.each_with_object(variables) do |argument, memo|
+      # extracts variable definitions used by a node
+      # (each operation tracks the specific variables used in its tree)
+      def extract_node_variables(node_with_args, variable_definitions)
+        node_with_args.arguments.each do |argument|
           case argument.value
           when GraphQL::Language::Nodes::InputObject
-            extract_node_variables!(argument.value, memo)
+            extract_node_variables(argument.value, variable_definitions)
           when GraphQL::Language::Nodes::VariableIdentifier
-            memo[argument.value.name] ||= @document.variable_definitions[argument.value.name]
+            variable_definitions[argument.value.name] ||= @request.variable_definitions[argument.value.name]
+          end
+        end
+
+        if node_with_args.respond_to?(:directives)
+          node_with_args.directives.each do |directive|
+            extract_node_variables(directive, variable_definitions)
+          end
+        end
+      end
+
+      # fields of a merged interface may not belong to the interface at the local level,
+      # so any non-local interface fields get expanded into typed fragments before planning
+      def expand_interface_selections(current_location, parent_type, input_selections)
+        local_interface_fields = @supergraph.fields_by_type_and_location[parent_type.graphql_name][current_location]
+
+        expanded_selections = nil
+        input_selections.reject! do |node|
+          if node.is_a?(GraphQL::Language::Nodes::Field) && !local_interface_fields.include?(node.name)
+            expanded_selections ||= []
+            expanded_selections << node
+            true
+          end
+        end
+
+        if expanded_selections
+          @supergraph.schema.possible_types(parent_type).each do |possible_type|
+            next unless @supergraph.locations_by_type[possible_type.graphql_name].include?(current_location)
+
+            type_name = GraphQL::Language::Nodes::TypeName.new(name: possible_type.graphql_name)
+            input_selections << GraphQL::Language::Nodes::InlineFragment.new(type: type_name, selections: expanded_selections)
           end
         end
       end
 
       # expand concrete type selections into typed fragments when sending to abstract boundaries
+      # this shifts all loose selection fields into a wrapping concrete type fragment
       def expand_abstract_boundaries
         @operations_by_grouping.each do |_grouping, op|
           next unless op.boundary
 
-          boundary_type = @supergraph.schema.get_type(op.boundary["type_name"])
+          boundary_type = @supergraph.schema.types[op.boundary["type_name"]]
           next unless boundary_type.kind.abstract?
+          next if boundary_type == op.parent_type
 
-          unless op.parent_type == boundary_type
-            to_typed_selections = []
-            op.selections.reject! do |node|
-              if node.is_a?(GraphQL::Language::Nodes::Field)
-                to_typed_selections << node
-                true
-              end
+          expanded_selections = nil
+          op.selections.reject! do |node|
+            if node.is_a?(GraphQL::Language::Nodes::Field)
+              expanded_selections ||= []
+              expanded_selections << node
+              true
             end
+          end
 
-            if to_typed_selections.any?
-              type_name = GraphQL::Language::Nodes::TypeName.new(name: op.parent_type.graphql_name)
-              op.selections << GraphQL::Language::Nodes::InlineFragment.new(type: type_name, selections: to_typed_selections)
-            end
+          if expanded_selections
+            type_name = GraphQL::Language::Nodes::TypeName.new(name: op.parent_type.graphql_name)
+            op.selections << GraphQL::Language::Nodes::InlineFragment.new(type: type_name, selections: expanded_selections)
           end
         end
       end

data/lib/graphql/stitching/remote_client.rb

@@ -9,14 +9,14 @@ module GraphQL
     class RemoteClient
       def initialize(url:, headers:{})
         @url = url
-        @headers = headers
+        @headers = { "Content-Type" => "application/json" }.merge!(headers)
       end
 
-      def call(location, document, variables)
+      def call(_location, document, variables, _context)
         response = Net::HTTP.post(
           URI(@url),
-          { "query" => document, "variables" => variables }.to_json,
-          { "Content-Type" => "application/json" }.merge!(@headers)
+          JSON.generate({ "query" => document, "variables" => variables }),
+          @headers,
         )
         JSON.parse(response.body)
       end

data/lib/graphql/stitching/request.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class Request
+      SUPPORTED_OPERATIONS = ["query", "mutation"].freeze
+
+      class ApplyRuntimeDirectives < GraphQL::Language::Visitor
+        def initialize(document, variables)
+          @changed = false
+          @variables = variables
+          super(document)
+        end
+
+        def changed?
+          @changed
+        end
+
+        def on_field(node, parent)
+          delete_node = false
+          filtered_directives = if node.directives.any?
+            node.directives.select do |directive|
+              if directive.name == "skip"
+                delete_node = assess_argument_value(directive.arguments.first)
+                false
+              elsif directive.name == "include"
+                delete_node = !assess_argument_value(directive.arguments.first)
+                false
+              else
+                true
+              end
+            end
+          end
+
+          if delete_node
+            @changed = true
+            super(DELETE_NODE, parent)
+          elsif filtered_directives && filtered_directives.length != node.directives.length
+            @changed = true
+            super(node.merge(directives: filtered_directives), parent)
+          else
+            super
+          end
+        end
+
+        private
+
+        def assess_argument_value(arg)
+          if arg.value.is_a?(GraphQL::Language::Nodes::VariableIdentifier)
+            return @variables[arg.value.name]
+          end
+          arg.value
+        end
+      end
+
+      attr_reader :document, :variables, :operation_name, :context
+
+      def initialize(document, operation_name: nil, variables: nil, context: nil)
+        @may_contain_runtime_directives = true
+
+        @document = if document.is_a?(String)
+          @may_contain_runtime_directives = document.include?("@")
+          GraphQL.parse(document)
+        else
+          document
+        end
+
+        @operation_name = operation_name
+        @variables = variables || {}
+        @context = context || GraphQL::Stitching::EMPTY_OBJECT
+      end
+
+      def string
+        @string ||= @document.to_query_string
+      end
+
+      def digest
+        @digest ||= Digest::SHA2.hexdigest(string)
+      end
+
+      def operation
+        @operation ||= begin
+          operation_defs = @document.definitions.select do |d|
+            next unless d.is_a?(GraphQL::Language::Nodes::OperationDefinition)
+            next unless SUPPORTED_OPERATIONS.include?(d.operation_type)
+            @operation_name ? d.name == @operation_name : true
+          end
+
+          if operation_defs.length < 1
+            raise GraphQL::ExecutionError, "Invalid root operation."
+          elsif operation_defs.length > 1
+            raise GraphQL::ExecutionError, "An operation name is required when sending multiple operations."
+          end
+
+          operation_defs.first
+        end
+      end
+
+      def variable_definitions
+        @variable_definitions ||= operation.variables.each_with_object({}) do |v, memo|
+          memo[v.name] = v.type
+        end
+      end
+
+      def fragment_definitions
+        @fragment_definitions ||= @document.definitions.each_with_object({}) do |d, memo|
+          memo[d.name] = d if d.is_a?(GraphQL::Language::Nodes::FragmentDefinition)
+        end
+      end
+
+      def prepare!
+        operation.variables.each do |v|
+          @variables[v.name] ||= v.default_value
+        end
+
+        if @may_contain_runtime_directives
+          visitor = ApplyRuntimeDirectives.new(@document, @variables)
+          @document = visitor.visit
+
+          if visitor.changed?
+            @string = nil
+            @digest = nil
+            @operation = nil
+            @variable_definitions = nil
+            @fragment_definitions = nil
+          end
+        end
+
+        self
+      end
+    end
+  end
+end