graphql-stitching 0.3.4 → 1.0.0

data/lib/graphql/stitching/planner.rb

@@ -5,22 +5,23 @@ module GraphQL
     class Planner
       SUPERGRAPH_LOCATIONS = [Supergraph::LOCATION].freeze
       TYPENAME_NODE = GraphQL::Language::Nodes::Field.new(alias: "_STITCH_typename", name: "__typename")
+      ROOT_ORDER = 0
 
       def initialize(supergraph:, request:)
         @supergraph = supergraph
         @request = request
-        @sequence_key = 0
-        @operations_by_grouping = {}
+        @planning_order = ROOT_ORDER
+        @operations_by_entrypoint = {}
       end
 
       def perform
-        build_root_operations
+        build_root_entrypoints
         expand_abstract_boundaries
         self
       end
 
       def operations
-        @operations_by_grouping.values.sort_by!(&:key)
+        @operations_by_entrypoint.values.sort_by!(&:order)
       end
 
       def to_h
@@ -29,12 +30,96 @@ module GraphQL
 
       private
 
-      # 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
+      # **
+      # Algorithm:
+      #
+      # A) Group all root selections by their preferred entrypoint locations.
+      # A.1) Group query fields by location for parallel execution.
+      # 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.
+      #
+      # 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).
+      #
+      # 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.
+      #
+      # C) Delegate adjoining selections to new entrypoint locations.
+      # C.1) Distribute unique fields among their required locations.
+      # 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.1) Types joining through multiple keys route using a-star 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).
+      #
+      # 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(
+        location:,
+        parent_order:,
+        parent_type:,
+        selections:,
+        variables: {},
+        path: [],
+        operation_type: "query",
+        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}")
+        path.each { entrypoint << "/#{_1}" }
+
+        op = @operations_by_entrypoint[entrypoint]
+        next_order = op ? parent_order : @planning_order += 1
+
+        if selections.any?
+          selections = extract_locale_selections(location, parent_type, next_order, 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,
+            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
+        end
+      end
+
+      # A) Group all root selections by their preferred entrypoint locations.
+      def build_root_entrypoints
         case @request.operation.operation_type
         when "query"
+          # A.1) Group query fields by location for parallel execution.
           parent_type = @supergraph.schema.query
 
           selections_by_location = {}
@@ -45,31 +130,37 @@ module GraphQL
           end
 
           selections_by_location.each do |location, selections|
-            add_operation(location: location, parent_type: parent_type, selections: selections)
+            add_entrypoint(
+              location: location,
+              parent_order: ROOT_ORDER,
+              parent_type: parent_type,
+              selections: selections,
+            )
           end
 
         when "mutation"
+          # A.2) Partition mutation fields by consecutive location for serial execution.
           parent_type = @supergraph.schema.mutation
 
-          location_groups = []
+          partitions = []
           each_selection_in_type(parent_type, @request.operation.selections) do |node|
             next_location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].first
 
-            if location_groups.none? || location_groups.last[:location] != next_location
-              location_groups << { location: next_location, selections: [] }
+            if partitions.none? || partitions.last[:location] != next_location
+              partitions << { location: next_location, selections: [] }
             end
 
-            location_groups.last[:selections] << node
+            partitions.last[:selections] << node
           end
 
-          location_groups.reduce(0) do |after_key, group|
-            add_operation(
-              location: group[:location],
-              selections: group[:selections],
-              operation_type: "mutation",
+          partitions.reduce(ROOT_ORDER) do |parent_order, partition|
+            add_entrypoint(
+              location: partition[:location],
+              parent_order: parent_order,
               parent_type: parent_type,
-              after_key: after_key
-            ).key
+              selections: partition[:selections],
+              operation_type: "mutation",
+            ).order
           end
 
         else
@@ -84,7 +175,7 @@ module GraphQL
             yield(node)
 
           when GraphQL::Language::Nodes::InlineFragment
-            next unless parent_type.graphql_name == node.type.name
+            next unless node.type.nil? || parent_type.graphql_name == node.type.name
             each_selection_in_type(parent_type, node.selections, &block)
 
           when GraphQL::Language::Nodes::FragmentSpread
@@ -98,67 +189,23 @@ module GraphQL
         end
       end
 
-      # 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
+      # B) Contiguous selections are extracted for each entrypoint location.
+      def extract_locale_selections(
+        current_location,
+        parent_type,
+        parent_order,
+        input_selections,
+        path,
+        locale_variables,
+        locale_selections = []
       )
-        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
-
-        # 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("#{after_key}/#{location}/#{parent_type.graphql_name}")
-        insertion_path.each { grouping << "/#{_1}" }
-
-        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
+        # B.1) Expand selections on interface types that do not belong to this location.
+        input_selections = expand_interface_selections(current_location, parent_type, input_selections)
 
-          @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
-
-      # 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)
+        # 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).
         remote_selections = nil
-        locale_selections = []
-        implements_fragments = false
-
-        if parent_type.kind.interface?
-          input_selections = expand_interface_selections(current_location, parent_type, input_selections)
-        end
+        requires_typename = parent_type.kind.abstract?
 
         input_selections.each do |node|
           case node
@@ -175,68 +222,172 @@ module GraphQL
               next
             end
 
-            field_type = @supergraph.memoized_schema_fields(parent_type.graphql_name)[node.name].type.unwrap
+            # B.3) Collect all variable definitions used within the filtered selection.
             extract_node_variables(node, locale_variables)
+            field_type = @supergraph.memoized_schema_fields(parent_type.graphql_name)[node.name].type.unwrap
 
             if Util.is_leaf_type?(field_type)
               locale_selections << node
             else
-              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
+              path.push(node.alias || node.name)
+              selection_set = extract_locale_selections(current_location, field_type, parent_order, node.selections, path, locale_variables)
+              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 = node.type ? @supergraph.memoized_schema_types[node.type.name] : parent_type
+            next unless @supergraph.locations_by_type[fragment_type.graphql_name].include?(current_location)
 
-            fragment_type = @supergraph.memoized_schema_types[node.type.name]
-            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
+            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)
+
+            unless is_same_scope
+              locale_selections << node.merge(selections: selection_set)
+              requires_typename = true
+            end
 
           when GraphQL::Language::Nodes::FragmentSpread
             fragment = @request.fragment_definitions[node.name]
             next unless @supergraph.locations_by_type[fragment.type.name].include?(current_location)
 
             fragment_type = @supergraph.memoized_schema_types[fragment.type.name]
-            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
+            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)
+
+            unless is_same_scope
+              locale_selections << GraphQL::Language::Nodes::InlineFragment.new(type: fragment.type, selections: selection_set)
+              requires_typename = true
+            end
 
           else
             raise "Unexpected node of type #{node.class.name} in selection set."
           end
         end
 
-        if remote_selections
-          delegate_remote_selections(
-            current_location,
-            parent_type,
-            locale_selections,
-            remote_selections,
-            insertion_path,
-            after_key
-          )
+        # B.4) Add a `__typename` selection to concrete types and abstracts that implement
+        # fragments so that resolved type information is available during execution.
+        if requires_typename
+          locale_selections << TYPENAME_NODE
         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
-          locale_selections << TYPENAME_NODE
+        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.
+          routes = @supergraph.route_type_to_locations(parent_type.graphql_name, current_location, remote_selections_by_location.keys)
+
+          # E) Translate boundary 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.
+              foreign_key = "_STITCH_#{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
+              end
+
+              parent_selections << GraphQL::Language::Nodes::Field.new(alias: foreign_key, name: boundary["key"]) unless has_key
+              parent_selections << 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,
+                parent_type: parent_type,
+                selections: remote_selections_by_location[location] || [],
+                path: path.dup,
+                boundary: boundary,
+              ).selections
+            end
+          end
         end
 
         locale_selections
       end
 
-      # 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)
+      # 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.
+      def expand_interface_selections(current_location, parent_type, input_selections)
+        return input_selections unless parent_type.kind.interface?
+
+        local_interface_fields = @supergraph.fields_by_type_and_location[parent_type.graphql_name][current_location]
+
+        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)
+
+          end
+          node
+        end
+
+        if expanded_selections
+          @supergraph.memoized_schema_possible_types(parent_type.graphql_name).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
+
+        input_selections
+      end
+
+      # B.3) Collect all variable definitions used within the filtered selection.
+      # These specify which request variables to pass along with the selection.
+      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, variable_definitions)
+          when GraphQL::Language::Nodes::VariableIdentifier
+            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
+
+      # C) Delegate adjoining selections to new entrypoint locations.
+      def delegate_remote_selections(parent_type, remote_selections)
         possible_locations_by_field = @supergraph.locations_by_type_and_field[parent_type.graphql_name]
         selections_by_location = {}
 
-        # 1. distribute unique fields among required locations
+        # C.1) Distribute unique fields among their required locations.
         remote_selections.reject! do |node|
           possible_locations = possible_locations_by_field[node.name]
           if possible_locations.length == 1
@@ -246,7 +397,7 @@ module GraphQL
           end
         end
 
-        # 2. distribute non-unique fields among locations that are already used
+        # C.2) Distribute non-unique fields among locations that were added during C.1.
         if selections_by_location.any? && remote_selections.any?
           remote_selections.reject! do |node|
             used_location = possible_locations_by_field[node.name].find { selections_by_location[_1] }
@@ -257,7 +408,7 @@ module GraphQL
           end
         end
 
-        # 3. distribute remaining fields among locations weighted by greatest availability
+        # 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|
@@ -290,88 +441,12 @@ module GraphQL
           end
         end
 
-        # route from current location to target locations via boundary queries,
-        # then translate those routes into planner operations
-        routes = @supergraph.route_type_to_locations(parent_type.graphql_name, current_location, selections_by_location.keys)
-        routes.values.each_with_object({}) do |route, ops_by_location|
-          route.reduce(nil) do |parent_op, boundary|
-            location = boundary["location"]
-
-            unless op = ops_by_location[location]
-              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 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
-
-            op
-          end
-        end
-      end
-
-      # 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, variable_definitions)
-          when GraphQL::Language::Nodes::VariableIdentifier
-            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 = input_selections.reject do |node|
-          if node.is_a?(GraphQL::Language::Nodes::Field) && node.name != "__typename" && !local_interface_fields.include?(node.name)
-            expanded_selections ||= []
-            expanded_selections << node
-            true
-          end
-        end
-
-        if expanded_selections
-          @supergraph.memoized_schema_possible_types(parent_type.graphql_name).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
-
-        input_selections
+        selections_by_location
       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
+      # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
       def expand_abstract_boundaries
-        @operations_by_grouping.each do |_grouping, op|
+        @operations_by_entrypoint.each_value do |op|
           next unless op.boundary
 
           boundary_type = @supergraph.memoized_schema_types[op.boundary["type_name"]]

data/lib/graphql/stitching/planner_operation.rb

@@ -5,30 +5,30 @@ module GraphQL
     class PlannerOperation
       LANGUAGE_PRINTER = GraphQL::Language::Printer.new
 
-      attr_reader :key, :location, :parent_type, :type_condition, :operation_type, :insertion_path
-      attr_accessor :after_key, :selections, :variables, :boundary
+      attr_reader :order, :location, :parent_type, :if_type, :operation_type, :path
+      attr_accessor :after, :selections, :variables, :boundary
 
       def initialize(
-        key:,
         location:,
         parent_type:,
+        order:,
+        after: nil,
         operation_type: "query",
-        insertion_path: [],
-        type_condition: nil,
-        after_key: nil,
         selections: [],
         variables: [],
+        path: [],
+        if_type: nil,
         boundary: nil
       )
-        @key = key
-        @after_key = after_key
         @location = location
         @parent_type = parent_type
+        @order = order
+        @after = after
         @operation_type = operation_type
-        @insertion_path = insertion_path
-        @type_condition = type_condition
         @selections = selections
         @variables = variables
+        @path = path
+        @if_type = if_type
         @boundary = boundary
       end
 
@@ -44,17 +44,19 @@ module GraphQL
       end
 
       def to_h
-        {
-          "key" => @key,
-          "after_key" => @after_key,
+        data = {
+          "order" => @order,
+          "after" => @after,
           "location" => @location,
           "operation_type" => @operation_type,
-          "insertion_path" => @insertion_path,
-          "type_condition" => @type_condition,
           "selections" => selection_set,
           "variables" => variable_set,
-          "boundary" => @boundary,
+          "path" => @path,
         }
+
+        data["if_type"] = @if_type if @if_type
+        data["boundary"] = @boundary if @boundary
+        data
       end
     end
   end

data/lib/graphql/stitching/shaper.rb

@@ -45,7 +45,7 @@ module GraphQL
             return nil if raw_object[field_name].nil? && node_type.non_null?
 
           when GraphQL::Language::Nodes::InlineFragment
-            fragment_type = @supergraph.memoized_schema_types[node.type.name]
+            fragment_type = node.type ? @supergraph.memoized_schema_types[node.type.name] : parent_type
             next unless typename_in_type?(typename, fragment_type)
 
             result = resolve_object_scope(raw_object, fragment_type, node.selections, typename)