graphql-stitching 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b8fbbdd8c300982092ee9297953f87e014420801e1a6058a49e36d5de8fb85b
-  data.tar.gz: 1fbd9b21161e8452a2fa55c4617ffabe8834c49e1b0635a58e17ed9b0cb43315
+  metadata.gz: d3cb133db35cdb705f296a2fe67909bfe2f07baefc873cf502ba48dbd53e8c6a
+  data.tar.gz: c81040a57f364a1a8a045bf079428cfae3c8a5886d2f7d0aaae45844c055b92e
 SHA512:
-  metadata.gz: 9eb747176cb0b39ced4ce35a10bab8f4a8e0b7448a5d6a9a74e8e74f484aba7f1bea46c1eff3ca3b118ee3be5fd2f8e7f5ebffb23dd5e6480a92abe620af9523
-  data.tar.gz: 64d935449b052d52b1068f22cc7df4b33608bb2b05bb5f8670da0e045f1c0faa06e44aa137acedab469312db5cda5144755a8d99b116a1c7ac09f809759ef198
+  metadata.gz: dc2a8d99942c2a5e1558ded0fbb467dd96d4bdb30c5a2ff9aa2348161ae28073cf36b2b56e51b0d92b757f68a87366ab1750e716bf0939d1645bf1ddee2049f5
+  data.tar.gz: 599760134f3f59f6ec5285e0d0976e1e9c07ba4103a74341bb35d1dacb89d0026383da2f4c2ca47d33ce3971510d9dddcc61d90a5248342406a4787f650d6126

data/README.md

@@ -1,6 +1,6 @@
 ## GraphQL Stitching for Ruby
 
-GraphQL stitching composes a single schema from multiple underlying GraphQL resources, then smartly delegates portions of incoming requests to their respective service locations in dependency order and returns the merged results. This allows an entire location graph to be queried through one combined GraphQL surface area.
+GraphQL stitching composes a single schema from multiple underlying GraphQL resources, then smartly proxies portions of incoming requests to their respective locations in dependency order and returns the merged results. This allows an entire location graph to be queried through one combined GraphQL surface area.
 
 ![Stitched graph](./docs/images/stitching.png)
 
@@ -14,7 +14,7 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 - Computed fields (ie: federation-style `@requires`).
 - Subscriptions, defer/stream.
 
-This Ruby implementation is a sibling to [GraphQL Tools](https://the-guild.dev/graphql/stitching) (JS) and [Bramble](https://movio.github.io/bramble/) (Go), and its capabilities fall somewhere in between them. GraphQL stitching is similar in concept to [Apollo Federation](https://www.apollographql.com/docs/federation/), though more generic. While Ruby is not the fastest language for a high-throughput API gateway, the opportunity here is for a Ruby application to stitch its local schema onto a remote schema (making itself a superset of the remote) without requiring an additional gateway service.
+This Ruby implementation is a sibling to [GraphQL Tools](https://the-guild.dev/graphql/stitching) (JS) and [Bramble](https://movio.github.io/bramble/) (Go), and its capabilities fall somewhere in between them. GraphQL stitching is similar in concept to [Apollo Federation](https://www.apollographql.com/docs/federation/), though more generic. While Ruby is not the fastest language for a purely high-throughput API gateway, the opportunity here is for a Ruby application to stitch its local schemas together or onto remote sources without requiring an additional proxy service running in another language.
 
 ## Getting started
 

data/lib/graphql/stitching/composer/validate_boundaries.rb

@@ -32,16 +32,16 @@ module GraphQL
 
         # only one boundary allowed per type/location/key
         boundaries_by_location_and_key = boundaries.each_with_object({}) do |boundary, memo|
-          if memo.dig(boundary["location"], boundary["selection"])
-            raise Composer::ValidationError, "Multiple boundary queries for `#{type.graphql_name}.#{boundary["selection"]}` "\
+          if memo.dig(boundary["location"], boundary["key"])
+            raise Composer::ValidationError, "Multiple boundary queries for `#{type.graphql_name}.#{boundary["key"]}` "\
               "found in #{boundary["location"]}. Limit one boundary query per type and key in each location. "\
               "Abstract boundaries provide all possible types."
           end
           memo[boundary["location"]] ||= {}
-          memo[boundary["location"]][boundary["selection"]] = boundary
+          memo[boundary["location"]][boundary["key"]] = boundary
         end
 
-        boundary_keys = boundaries.map { _1["selection"] }.uniq
+        boundary_keys = boundaries.map { _1["key"] }.uniq
         key_only_types_by_location = candidate_types_by_location.select do |location, subschema_type|
           subschema_type.fields.keys.length == 1 && boundary_keys.include?(subschema_type.fields.keys.first)
         end

data/lib/graphql/stitching/composer.rb

@@ -56,8 +56,9 @@ module GraphQL
           raise ComposerError, "Location keys must be strings" unless location.is_a?(String)
           raise ComposerError, "The subscription operation is not supported." if schema.subscription
 
+          introspection_types = schema.introspection_system.types.keys
           schema.types.each do |type_name, type_candidate|
-            next if Supergraph::INTROSPECTION_TYPES.include?(type_name)
+            next if introspection_types.include?(type_name)
 
             if type_name == @query_name && type_candidate != schema.query
               raise ComposerError, "Query name \"#{@query_name}\" is used by non-query type in #{location} schema."
@@ -491,7 +492,7 @@ module GraphQL
               @boundary_map[boundary_type_name] ||= []
               @boundary_map[boundary_type_name] << {
                 "location" => location,
-                "selection" => key_selections[0].name,
+                "key" => key_selections[0].name,
                 "field" => field_candidate.name,
                 "arg" => argument_name,
                 "list" => boundary_structure.first[:list],
@@ -538,8 +539,9 @@ module GraphQL
         writes = []
 
         schemas.each do |schema|
+          introspection_types = schema.introspection_system.types.keys
           schema.types.values.each do |type|
-            next if Supergraph::INTROSPECTION_TYPES.include?(type.graphql_name)
+            next if introspection_types.include?(type.graphql_name)
 
             if type.kind.object? || type.kind.interface?
               type.fields.values.each do |field|

data/lib/graphql/stitching/executor.rb

@@ -26,7 +26,7 @@ module GraphQL
             @executor.errors.concat(result["errors"])
           end
 
-          ops.map { op["key"] }
+          ops.map { op["order"] }
         end
 
         # Builds root source documents
@@ -36,12 +36,12 @@ module GraphQL
           doc << op["operation_type"]
 
           if operation_name
-            doc << " " << operation_name << "_" << op["key"].to_s
+            doc << " #{operation_name}_#{op["order"]}"
           end
 
           if op["variables"].any?
             variable_defs = op["variables"].map { |k, v| "$#{k}:#{v}" }.join(",")
-            doc << "(" << variable_defs << ")"
+            doc << "(#{variable_defs})"
           end
 
           doc << op["selections"]
@@ -57,13 +57,13 @@ module GraphQL
 
         def fetch(ops)
           origin_sets_by_operation = ops.each_with_object({}) do |op, memo|
-            origin_set = op["insertion_path"].reduce([@executor.data]) do |set, path_segment|
+            origin_set = op["path"].reduce([@executor.data]) do |set, path_segment|
               set.flat_map { |obj| obj && obj[path_segment] }.tap(&:compact!)
             end
 
-            if op["type_condition"]
+            if op["if_type"]
               # operations planned around unused fragment conditions should not trigger requests
-              origin_set.select! { _1["_STITCH_typename"] == op["type_condition"] }
+              origin_set.select! { _1["_STITCH_typename"] == op["if_type"] }
             end
 
             memo[op] = origin_set if origin_set.any?
@@ -81,7 +81,7 @@ module GraphQL
             @executor.errors.concat(extract_errors!(origin_sets_by_operation, errors)) if errors&.any?
           end
 
-          ops.map { origin_sets_by_operation[_1] ? _1["key"] : nil }
+          ops.map { origin_sets_by_operation[_1] ? _1["order"] : nil }
         end
 
         # Builds batched boundary queries
@@ -96,7 +96,7 @@ module GraphQL
           query_fields = origin_sets_by_operation.map.with_index do |(op, origin_set), batch_index|
             variable_defs.merge!(op["variables"])
             boundary = op["boundary"]
-            key_selection = "_STITCH_#{boundary["selection"]}"
+            key_selection = "_STITCH_#{boundary["key"]}"
 
             if boundary["list"]
               input = JSON.generate(origin_set.map { _1[key_selection] })
@@ -113,18 +113,18 @@ module GraphQL
           doc << "query" # << boundary fulfillment always uses query
 
           if operation_name
-            doc << " " << operation_name
+            doc << " #{operation_name}"
             origin_sets_by_operation.each_key do |op|
-              doc << "_" << op["key"].to_s
+              doc << "_#{op["order"]}"
             end
           end
 
           if variable_defs.any?
             variable_str = variable_defs.map { |k, v| "$#{k}:#{v}" }.join(",")
-            doc << "(" << variable_str << ")"
+            doc << "(#{variable_str})"
           end
 
-          doc << "{ " << query_fields.join(" ") << " }"
+          doc << "{ #{query_fields.join(" ")} }"
 
           return doc, variable_defs.keys
         end
@@ -183,7 +183,7 @@ module GraphQL
 
           if pathed_errors_by_op_index_and_object_id.any?
             pathed_errors_by_op_index_and_object_id.each do |op_index, pathed_errors_by_object_id|
-              repath_errors!(pathed_errors_by_object_id, ops.dig(op_index, "insertion_path"))
+              repath_errors!(pathed_errors_by_object_id, ops.dig(op_index, "path"))
               errors_result.concat(pathed_errors_by_object_id.values)
             end
           end
@@ -265,7 +265,7 @@ module GraphQL
 
       private
 
-      def exec!(after_keys = [0])
+      def exec!(next_ordinals = [0])
         if @exec_cycles > @queue.length
           # sanity check... if we've exceeded queue size, then something went wrong.
           raise StitchingError, "Too many execution requests attempted."
@@ -273,7 +273,7 @@ module GraphQL
 
         @dataloader.append_job do
           tasks = @queue
-            .select { after_keys.include?(_1["after_key"]) }
+            .select { next_ordinals.include?(_1["after"]) }
             .group_by { [_1["location"], _1["boundary"].nil?] }
             .map do |(location, root_source), ops|
               if root_source
@@ -291,9 +291,8 @@ module GraphQL
       end
 
       def exec_task(task)
-        next_keys = task.load
-        next_keys.compact!
-        exec!(next_keys) if next_keys.any?
+        next_ordinals = task.load.tap(&:compact!)
+        exec!(next_ordinals) if next_ordinals.any?
       end
     end
   end

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)

data/lib/graphql/stitching/supergraph.rb

@@ -4,16 +4,6 @@ module GraphQL
   module Stitching
     class Supergraph
       LOCATION = "__super"
-      INTROSPECTION_TYPES = [
-        "__Schema",
-        "__Type",
-        "__Field",
-        "__Directive",
-        "__EnumValue",
-        "__InputValue",
-        "__TypeKind",
-        "__DirectiveLocation",
-      ].freeze
 
       def self.validate_executable!(location, executable)
         return true if executable.is_a?(Class) && executable <= GraphQL::Schema
@@ -50,11 +40,10 @@ module GraphQL
         @memoized_schema_fields = {}
 
         # add introspection types into the fields mapping
-        @locations_by_type_and_field = INTROSPECTION_TYPES.each_with_object(fields) do |type_name, memo|
-          introspection_type = schema.get_type(type_name)
-          next unless introspection_type.kind.fields?
+        @locations_by_type_and_field = memoized_introspection_types.each_with_object(fields) do |(type_name, type), memo|
+          next unless type.kind.fields?
 
-          memo[type_name] = introspection_type.fields.keys.each_with_object({}) do |field_name, m|
+          memo[type_name] = type.fields.keys.each_with_object({}) do |field_name, m|
             m[field_name] = [LOCATION]
           end
         end.freeze
@@ -68,7 +57,7 @@ module GraphQL
       end
 
       def fields
-        @locations_by_type_and_field.reject { |k, _v| INTROSPECTION_TYPES.include?(k) }
+        @locations_by_type_and_field.reject { |k, _v| memoized_introspection_types[k] }
       end
 
       def locations
@@ -83,6 +72,10 @@ module GraphQL
         }
       end
 
+      def memoized_introspection_types
+        @memoized_introspection_types ||= schema.introspection_system.types
+      end
+
       def memoized_schema_types
         @memoized_schema_types ||= @schema.types
       end
@@ -94,11 +87,14 @@ module GraphQL
       def memoized_schema_fields(type_name)
         @memoized_schema_fields[type_name] ||= begin
           fields = memoized_schema_types[type_name].fields
-          fields["__typename"] = @schema.introspection_system.dynamic_field(name: "__typename")
+          @schema.introspection_system.dynamic_fields.each do |field|
+            fields[field.name] ||= field # adds __typename
+          end
 
           if type_name == @schema.query.graphql_name
-            fields["__schema"] = @schema.introspection_system.entry_point(name: "__schema")
-            fields["__type"] = @schema.introspection_system.entry_point(name: "__type")
+            @schema.introspection_system.entry_points.each do |field|
+              fields[field.name] ||= field # adds __schema, __type
+            end
           end
 
           fields
@@ -148,9 +144,7 @@ module GraphQL
       # ("Type") => ["id", ...]
       def possible_keys_for_type(type_name)
         @possible_keys_by_type[type_name] ||= begin
-          keys = @boundaries[type_name].map { _1["selection"] }
-          keys.uniq!
-          keys
+          @boundaries[type_name].map { _1["key"] }.tap(&:uniq!)
         end
       end
 
@@ -190,18 +184,18 @@ module GraphQL
         costs = {}
 
         paths = possible_keys_for_type_and_location(type_name, start_location).map do |possible_key|
-          [{ location: start_location, selection: possible_key, cost: 0 }]
+          [{ location: start_location, key: possible_key, cost: 0 }]
         end
 
         while paths.any?
           path = paths.pop
           current_location = path.last[:location]
-          current_selection = path.last[:selection]
+          current_key = path.last[:key]
           current_cost = path.last[:cost]
 
           @boundaries[type_name].each do |boundary|
             forward_location = boundary["location"]
-            next if current_selection != boundary["selection"]
+            next if current_key != boundary["key"]
             next if path.any? { _1[:location] == forward_location }
 
             best_cost = costs[forward_location] || Float::INFINITY
@@ -210,7 +204,7 @@ module GraphQL
             path.pop
             path << {
               location: current_location,
-              selection: current_selection,
+              key: current_key,
               cost: current_cost,
               boundary: boundary,
             }
@@ -228,14 +222,13 @@ module GraphQL
             costs[forward_location] = forward_cost if forward_cost < best_cost
 
             possible_keys_for_type_and_location(type_name, forward_location).each do |possible_key|
-              paths << [*path, { location: forward_location, selection: possible_key, cost: forward_cost }]
+              paths << [*path, { location: forward_location, key: possible_key, cost: forward_cost }]
             end
           end
 
           paths.sort! do |a, b|
             cost_diff = a.last[:cost] - b.last[:cost]
-            next cost_diff unless cost_diff.zero?
-            a.length - b.length
+            cost_diff.zero? ? a.length - b.length : cost_diff
           end.reverse!
         end
 

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "0.3.4"
+    VERSION = "0.3.6"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.6
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-27 00:00:00.000000000 Z
+date: 2023-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql