graphql-stitching 1.0.0 → 1.0.2

data/lib/graphql/stitching/planner.rb

@@ -4,28 +4,26 @@ module GraphQL
   module Stitching
     class Planner
       SUPERGRAPH_LOCATIONS = [Supergraph::LOCATION].freeze
-      TYPENAME_NODE = GraphQL::Language::Nodes::Field.new(alias: "_STITCH_typename", name: "__typename")
-      ROOT_ORDER = 0
+      TYPENAME = "__typename"
+      QUERY_OP = "query"
+      MUTATION_OP = "mutation"
+      ROOT_INDEX = 0
 
       def initialize(supergraph:, request:)
         @supergraph = supergraph
         @request = request
-        @planning_order = ROOT_ORDER
-        @operations_by_entrypoint = {}
+        @planning_index = ROOT_INDEX
+        @steps_by_entrypoint = {}
       end
 
       def perform
         build_root_entrypoints
         expand_abstract_boundaries
-        self
+        Plan.new(ops: steps.map(&:to_plan_op))
       end
 
-      def operations
-        @operations_by_entrypoint.values.sort_by!(&:order)
-      end
-
-      def to_h
-        { "ops" => operations.map!(&:to_h) }
+      def steps
+        @steps_by_entrypoint.values.sort_by!(&:index)
       end
 
       private
@@ -38,18 +36,14 @@ module GraphQL
       # A.2) Partition mutation fields by consecutive location for serial execution.
       #
       # B) Extract contiguous selections for each entrypoint location.
-      #
       # B.1) Selections on interface types that do not belong to the interface at the
-      # entrypoint location are expanded into concrete type fragments prior to extraction.
-      #
+      #      entrypoint location are expanded into concrete type fragments prior to extraction.
       # B.2) Filter the selection tree down to just fields of the entrypoint location.
-      # Adjoining selections not available here get split off into new entrypoints (C).
-      #
+      #      Adjoining selections not available here get split off into new entrypoints (C).
       # B.3) Collect all variable definitions used within the filtered selection.
-      # These specify which request variables to pass along with the selection.
-      #
-      # B.4) Add a `__typename` selection to concrete types and abstracts that implement
-      # fragments. This provides resolved type information used during execution.
+      #      These specify which request variables to pass along with each step.
+      # B.4) Add a `__typename` hint to abstracts and types that implement fragments.
+      #      This provides resolved type information used during execution.
       #
       # C) Delegate adjoining selections to new entrypoint locations.
       # C.1) Distribute unique fields among their required locations.
@@ -57,110 +51,105 @@ module GraphQL
       # C.3) Distribute remaining fields among locations weighted by greatest availability.
       #
       # D) Create paths routing to new entrypoint locations via boundary queries.
-      # D.1) Types joining through multiple keys route using a-star search.
+      # 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.2) Add a planner operation for each new entrypoint location, then extract it (B).
+      # 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.
       # **
 
-      # adds an entrypoint for fetching and inserting data into the aggregate result.
-      def add_entrypoint(
+      # adds a planning step for fetching and inserting data into the aggregate result.
+      def add_step(
         location:,
-        parent_order:,
+        parent_index:,
         parent_type:,
         selections:,
         variables: {},
         path: [],
-        operation_type: "query",
+        operation_type: QUERY_OP,
         boundary: nil
       )
         # coalesce repeat parameters into a single entrypoint
-        boundary_key = boundary ? boundary["key"] : "_"
-        entrypoint = String.new("#{parent_order}/#{location}/#{parent_type.graphql_name}/#{boundary_key}")
+        entrypoint = String.new("#{parent_index}/#{location}/#{parent_type.graphql_name}/#{boundary&.key}")
         path.each { entrypoint << "/#{_1}" }
 
-        op = @operations_by_entrypoint[entrypoint]
-        next_order = op ? parent_order : @planning_order += 1
+        step = @steps_by_entrypoint[entrypoint]
+        next_index = step ? parent_index : @planning_index += 1
 
         if selections.any?
-          selections = extract_locale_selections(location, parent_type, next_order, selections, path, variables)
+          selections = extract_locale_selections(location, parent_type, next_index, selections, path, variables)
         end
 
-        if op.nil?
-          # 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
-          conditional = !parent_type.kind.abstract? && parent_type != @supergraph.schema.root_type_for_operation(operation_type)
-
-          @operations_by_entrypoint[entrypoint] = PlannerOperation.new(
-            order: next_order,
-            after: parent_order,
+        if step.nil?
+          @steps_by_entrypoint[entrypoint] = PlannerStep.new(
+            index: next_index,
+            after: parent_index,
             location: location,
             parent_type: parent_type,
             operation_type: operation_type,
             selections: selections,
             variables: variables,
             path: path,
-            if_type: conditional ? parent_type.graphql_name : nil,
             boundary: boundary,
           )
         else
-          op.selections.concat(selections)
-          op
+          step.selections.concat(selections)
+          step
         end
       end
 
+      ScopePartition = Struct.new(:location, :selections, keyword_init: true)
+
       # A) Group all root selections by their preferred entrypoint locations.
       def build_root_entrypoints
         case @request.operation.operation_type
-        when "query"
+        when QUERY_OP
           # A.1) Group query fields by location for parallel execution.
           parent_type = @supergraph.schema.query
 
           selections_by_location = {}
-          each_selection_in_type(parent_type, @request.operation.selections) do |node|
+          each_field_in_scope(parent_type, @request.operation.selections) do |node|
             locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name] || SUPERGRAPH_LOCATIONS
             selections_by_location[locations.first] ||= []
             selections_by_location[locations.first] << node
           end
 
           selections_by_location.each do |location, selections|
-            add_entrypoint(
+            add_step(
               location: location,
-              parent_order: ROOT_ORDER,
+              parent_index: ROOT_INDEX,
               parent_type: parent_type,
               selections: selections,
             )
           end
 
-        when "mutation"
+        when MUTATION_OP
           # A.2) Partition mutation fields by consecutive location for serial execution.
           parent_type = @supergraph.schema.mutation
 
           partitions = []
-          each_selection_in_type(parent_type, @request.operation.selections) do |node|
+          each_field_in_scope(parent_type, @request.operation.selections) do |node|
             next_location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].first
 
-            if partitions.none? || partitions.last[:location] != next_location
-              partitions << { location: next_location, selections: [] }
+            if partitions.none? || partitions.last.location != next_location
+              partitions << ScopePartition.new(location: next_location, selections: [])
             end
 
-            partitions.last[:selections] << node
+            partitions.last.selections << node
           end
 
-          partitions.reduce(ROOT_ORDER) do |parent_order, partition|
-            add_entrypoint(
-              location: partition[:location],
-              parent_order: parent_order,
+          partitions.reduce(ROOT_INDEX) do |parent_index, partition|
+            add_step(
+              location: partition.location,
+              parent_index: parent_index,
               parent_type: parent_type,
-              selections: partition[:selections],
-              operation_type: "mutation",
-            ).order
+              selections: partition.selections,
+              operation_type: MUTATION_OP,
+            ).index
           end
 
         else
@@ -168,7 +157,7 @@ module GraphQL
         end
       end
 
-      def each_selection_in_type(parent_type, input_selections, &block)
+      def each_field_in_scope(parent_type, input_selections, &block)
         input_selections.each do |node|
           case node
           when GraphQL::Language::Nodes::Field
@@ -176,12 +165,12 @@ module GraphQL
 
           when GraphQL::Language::Nodes::InlineFragment
             next unless node.type.nil? || parent_type.graphql_name == node.type.name
-            each_selection_in_type(parent_type, node.selections, &block)
+            each_field_in_scope(parent_type, node.selections, &block)
 
           when GraphQL::Language::Nodes::FragmentSpread
             fragment = @request.fragment_definitions[node.name]
             next unless parent_type.graphql_name == fragment.type.name
-            each_selection_in_type(parent_type, fragment.selections, &block)
+            each_field_in_scope(parent_type, fragment.selections, &block)
 
           else
             raise "Unexpected node of type #{node.class.name} in selection set."
@@ -193,7 +182,7 @@ module GraphQL
       def extract_locale_selections(
         current_location,
         parent_type,
-        parent_order,
+        parent_index,
         input_selections,
         path,
         locale_variables,
@@ -210,7 +199,7 @@ module GraphQL
         input_selections.each do |node|
           case node
           when GraphQL::Language::Nodes::Field
-            if node.name == "__typename"
+            if node.name == TYPENAME
               locale_selections << node
               next
             end
@@ -230,7 +219,7 @@ module GraphQL
               locale_selections << node
             else
               path.push(node.alias || node.name)
-              selection_set = extract_locale_selections(current_location, field_type, parent_order, node.selections, path, locale_variables)
+              selection_set = extract_locale_selections(current_location, field_type, parent_index, node.selections, path, locale_variables)
               path.pop
 
               locale_selections << node.merge(selections: selection_set)
@@ -242,7 +231,7 @@ module GraphQL
 
             is_same_scope = fragment_type == parent_type
             selection_set = is_same_scope ? locale_selections : []
-            extract_locale_selections(current_location, fragment_type, parent_order, node.selections, path, locale_variables, selection_set)
+            extract_locale_selections(current_location, fragment_type, parent_index, node.selections, path, locale_variables, selection_set)
 
             unless is_same_scope
               locale_selections << node.merge(selections: selection_set)
@@ -256,7 +245,7 @@ module GraphQL
             fragment_type = @supergraph.memoized_schema_types[fragment.type.name]
             is_same_scope = fragment_type == parent_type
             selection_set = is_same_scope ? locale_selections : []
-            extract_locale_selections(current_location, fragment_type, parent_order, fragment.selections, path, locale_variables, selection_set)
+            extract_locale_selections(current_location, fragment_type, parent_index, fragment.selections, path, locale_variables, selection_set)
 
             unless is_same_scope
               locale_selections << GraphQL::Language::Nodes::InlineFragment.new(type: fragment.type, selections: selection_set)
@@ -268,10 +257,10 @@ module GraphQL
           end
         end
 
-        # B.4) Add a `__typename` selection to concrete types and abstracts that implement
+        # B.4) Add a `__typename` hint to abstracts and types that implement
         # fragments so that resolved type information is available during execution.
         if requires_typename
-          locale_selections << TYPENAME_NODE
+          locale_selections << SelectionHint.typename_node
         end
 
         if remote_selections
@@ -285,30 +274,25 @@ module GraphQL
           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.
-              foreign_key = "_STITCH_#{boundary["key"]}"
+              foreign_key = SelectionHint.key(boundary.key)
               has_key = false
               has_typename = false
 
-              parent_selections.each do |selection|
-                next unless selection.is_a?(GraphQL::Language::Nodes::Field)
-                case selection.alias
-                when foreign_key
-                  has_key = true
-                when TYPENAME_NODE.alias
-                  has_typename = true
-                end
+              parent_selections.each do |node|
+                next unless node.is_a?(GraphQL::Language::Nodes::Field)
+                has_key ||= node.alias == foreign_key
+                has_typename ||= node.alias == SelectionHint.typename_node.alias
               end
 
-              parent_selections << GraphQL::Language::Nodes::Field.new(alias: foreign_key, name: boundary["key"]) unless has_key
-              parent_selections << TYPENAME_NODE unless has_typename
+              parent_selections << SelectionHint.key_node(boundary.key) unless has_key
+              parent_selections << SelectionHint.typename_node unless has_typename
 
-              # E.2) Add a planner operation for each new entrypoint location.
-              location = boundary["location"]
-              add_entrypoint(
-                location: location,
-                parent_order: parent_order,
+              # E.2) Add a planner step for each new entrypoint location.
+              add_step(
+                location: boundary.location,
+                parent_index: parent_index,
                 parent_type: parent_type,
-                selections: remote_selections_by_location[location] || [],
+                selections: remote_selections_by_location[boundary.location] || [],
                 path: path.dup,
                 boundary: boundary,
               ).selections
@@ -328,27 +312,13 @@ module GraphQL
 
         expanded_selections = nil
         input_selections = input_selections.filter_map do |node|
-          case node
-          when GraphQL::Language::Nodes::Field
-            if node.name != "__typename" && !local_interface_fields.include?(node.name)
-              expanded_selections ||= []
-              expanded_selections << node
-              next nil
-            end
-
-          when GraphQL::Language::Nodes::InlineFragment
-            fragment_type = node.type ? @supergraph.memoized_schema_types[node.type.name] : parent_type
-            selection_set = expand_interface_selections(current_location, fragment_type, node.selections)
-            node = node.merge(selections: selection_set)
-
-          when GraphQL::Language::Nodes::FragmentSpread
-            fragment = @request.fragment_definitions[node.name]
-            fragment_type = @supergraph.memoized_schema_types[fragment.type.name]
-            selection_set = expand_interface_selections(current_location, fragment_type, fragment.selections)
-            node = GraphQL::Language::Nodes::InlineFragment.new(type: fragment.type, selections: selection_set)
-
+          if node.is_a?(GraphQL::Language::Nodes::Field) && node.name != TYPENAME && !local_interface_fields.include?(node.name)
+            expanded_selections ||= []
+            expanded_selections << node
+            nil
+          else
+            node
           end
-          node
         end
 
         if expanded_selections
@@ -364,7 +334,7 @@ module GraphQL
       end
 
       # B.3) Collect all variable definitions used within the filtered selection.
-      # These specify which request variables to pass along with the selection.
+      # These specify which request variables to pass along with each step.
       def extract_node_variables(node_with_args, variable_definitions)
         node_with_args.arguments.each do |argument|
           case argument.value
@@ -410,15 +380,11 @@ module GraphQL
 
         # C.3) Distribute remaining fields among locations weighted by greatest availability.
         if remote_selections.any?
-          field_count_by_location = if remote_selections.length > 1
-            remote_selections.each_with_object({}) do |node, memo|
-              possible_locations_by_field[node.name].each do |location|
-                memo[location] ||= 0
-                memo[location] += 1
-              end
+          field_count_by_location = remote_selections.each_with_object({}) do |node, memo|
+            possible_locations_by_field[node.name].each do |location|
+              memo[location] ||= 0
+              memo[location] += 1
             end
-          else
-            GraphQL::Stitching::EMPTY_OBJECT
           end
 
           remote_selections.each do |node|
@@ -426,11 +392,11 @@ module GraphQL
             preferred_location = possible_locations.first
 
             possible_locations.reduce(0) do |max_availability, possible_location|
-              available_fields = field_count_by_location.fetch(possible_location, 0)
+              availability = field_count_by_location.fetch(possible_location, 0)
 
-              if available_fields > max_availability
+              if availability > max_availability
                 preferred_location = possible_location
-                available_fields
+                availability
               else
                 max_availability
               end
@@ -446,15 +412,15 @@ module GraphQL
 
       # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
       def expand_abstract_boundaries
-        @operations_by_entrypoint.each_value do |op|
-          next unless op.boundary
+        @steps_by_entrypoint.each_value do |step|
+          next unless step.boundary
 
-          boundary_type = @supergraph.memoized_schema_types[op.boundary["type_name"]]
+          boundary_type = @supergraph.memoized_schema_types[step.boundary.type_name]
           next unless boundary_type.kind.abstract?
-          next if boundary_type == op.parent_type
+          next if boundary_type == step.parent_type
 
           expanded_selections = nil
-          op.selections.reject! do |node|
+          step.selections.reject! do |node|
             if node.is_a?(GraphQL::Language::Nodes::Field)
               expanded_selections ||= []
               expanded_selections << node
@@ -463,8 +429,8 @@ module GraphQL
           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)
+            type_name = GraphQL::Language::Nodes::TypeName.new(name: step.parent_type.graphql_name)
+            step.selections << GraphQL::Language::Nodes::InlineFragment.new(type: type_name, selections: expanded_selections)
           end
         end
       end

data/lib/graphql/stitching/planner_step.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    # A planned step in the sequence of stitching entrypoints together.
+    # This is a mutable object that may change throughout the planning process.
+    # It ultimately builds an immutable Plan::Op at the end of planning.
+    class PlannerStep
+      GRAPHQL_PRINTER = GraphQL::Language::Printer.new
+
+      attr_reader :index, :location, :parent_type, :operation_type, :path
+      attr_accessor :after, :selections, :variables, :boundary
+
+      def initialize(
+        location:,
+        parent_type:,
+        index:,
+        after: nil,
+        operation_type: "query",
+        selections: [],
+        variables: {},
+        path: [],
+        boundary: nil
+      )
+        @location = location
+        @parent_type = parent_type
+        @index = index
+        @after = after
+        @operation_type = operation_type
+        @selections = selections
+        @variables = variables
+        @path = path
+        @boundary = boundary
+      end
+
+      def to_plan_op
+        GraphQL::Stitching::Plan::Op.new(
+          step: @index,
+          after: @after,
+          location: @location,
+          operation_type: @operation_type,
+          selections: rendered_selections,
+          variables: rendered_variables,
+          path: @path,
+          if_type: type_condition,
+          boundary: @boundary,
+        )
+      end
+
+      private
+
+      # Concrete types going to a boundary 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?
+      end
+
+      def rendered_selections
+        op = GraphQL::Language::Nodes::OperationDefinition.new(operation_type: "", selections: @selections)
+        GRAPHQL_PRINTER.print(op).gsub!(/\s+/, " ").strip!
+      end
+
+      def rendered_variables
+        @variables.each_with_object({}) do |(variable_name, value_type), memo|
+          memo[variable_name] = GRAPHQL_PRINTER.print(value_type)
+        end
+      end
+    end
+  end
+end

data/lib/graphql/stitching/request.rb

@@ -5,54 +5,6 @@ module GraphQL
     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)
@@ -96,6 +48,13 @@ module GraphQL
         end
       end
 
+      def operation_directives
+        @operation_directives ||= if operation.directives.any?
+          printer = GraphQL::Language::Printer.new
+          operation.directives.map { printer.print(_1) }.join(" ")
+        end
+      end
+
       def variable_definitions
         @variable_definitions ||= operation.variables.each_with_object({}) do |v, memo|
           memo[v.name] = v.type
@@ -114,10 +73,9 @@ module GraphQL
         end
 
         if @may_contain_runtime_directives
-          visitor = ApplyRuntimeDirectives.new(@document, @variables)
-          @document = visitor.visit
+          @document, modified = SkipInclude.render(@document, @variables)
 
-          if visitor.changed?
+          if modified
             @string = nil
             @digest = nil
             @operation = nil

data/lib/graphql/stitching/selection_hint.rb

@@ -0,0 +1,31 @@
+# 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 SelectionHint
+      HINT_PREFIX = "_STITCH_"
+
+      class << self
+        def key?(name)
+          return false unless name
+
+          name.start_with?(HINT_PREFIX)
+        end
+
+        def key(name)
+          "#{HINT_PREFIX}#{name}"
+        end
+
+        def key_node(field_name)
+          GraphQL::Language::Nodes::Field.new(alias: key(field_name), name: field_name)
+        end
+
+        def typename_node
+          @typename_node ||= key_node("__typename")
+        end
+      end
+    end
+  end
+end

data/lib/graphql/stitching/shaper.rb

@@ -3,6 +3,8 @@
 
 module GraphQL
   module Stitching
+    # Shapes the final results payload to the request selection and schema definition.
+    # This eliminates unrequested selection hints and applies null bubbling.
     class Shaper
       def initialize(supergraph:, request:)
         @supergraph = supergraph
@@ -19,8 +21,8 @@ module GraphQL
       def resolve_object_scope(raw_object, parent_type, selections, typename = nil)
         return nil if raw_object.nil?
 
-        typename ||= raw_object["_STITCH_typename"]
-        raw_object.reject! { |k, _v| k.start_with?("_STITCH_") }
+        typename ||= raw_object[SelectionHint.typename_node.alias]
+        raw_object.reject! { |key, _v| SelectionHint.key?(key) }
 
         selections.each do |node|
           case node