graphql-stitching 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05c82abfcbec2db513d097c21424916bea46ebb0e4b434db0dc10a92ddfc2f9b
-  data.tar.gz: 79e4184f4ed237e2132f67389bb838fbbf18a8141b1d2ab30f8c5b710f47cb8f
+  metadata.gz: f67a4b892fba612e2e38552ae0a0f681ed0fdc136c04ecef4d2c01692eed9eb8
+  data.tar.gz: 3db164c53dc67d64b7364ba5a17186e3eb612074993b21df5f9a8b059fca9f89
 SHA512:
-  metadata.gz: e6c6ccb67c95df19b01bbeea1c0ed731a7153c3e4a184dab7dad6c2c52a22e22183075d123bf2dc78f431e73ff1fb4d31f0a21100072adb4f05bff2813ff9294
-  data.tar.gz: 2b9257ed86bdac5cb2403e527fc90893c961637d14bda2c4e5a16be7c8dc23206f860bdb596cc26f35ea704156b7443c5ef013efcc4c8cde251c9a865777e3ad
+  metadata.gz: 8d687747a19a25a69b1c998910265a183bdb22338fec5e9787412ca5c1cdfc5e0b838bb49ce4942ce41dec0e000e0ddc35bdf07368a7a772751ffc5342b7ee48
+  data.tar.gz: f4419aa525964b37db62ce2343d11914ac56677825c8f1450c5187465b2f28e3a740acf6779309bdb0a5fbd41829054101aed4c9d0eb764882759c50bbf1b641

data/README.md

@@ -214,12 +214,12 @@ type Product {
   upc: ID!
 }
 type Query {
-  productById(id: ID): Product @stitch(key: "id")
-  productByUpc(upc: ID): Product @stitch(key: "upc")
+  productById(id: ID!): Product @stitch(key: "id")
+  productByUpc(upc: ID!): Product @stitch(key: "upc")
 }
 ```
 
-The `@stitch` directive is also repeatable, allowing a single query to associate with multiple keys:
+The `@stitch` directive is also repeatable (_requires graphql-ruby v2.0.15_), allowing a single query to associate with multiple keys:
 
 ```graphql
 type Product {

data/docs/executor.md

@@ -12,7 +12,11 @@ query = <<~GRAPHQL
   }
 GRAPHQL
 
-request = GraphQL::Stitching::Request.new(query, variables: { "id" => "123" }, operation_name: "MyQuery")
+request = GraphQL::Stitching::Request.new(
+  query,
+  variables: { "id" => "123" },
+  operation_name: "MyQuery",
+)
 
 plan = GraphQL::Stitching::Planner.new(
   supergraph: supergraph,
@@ -21,8 +25,8 @@ plan = GraphQL::Stitching::Planner.new(
 
 result = GraphQL::Stitching::Executor.new(
   supergraph: supergraph,
-  plan: plan.to_h,
   request: request,
+  plan: plan.to_h,
 ).perform
 ```
 
@@ -34,7 +38,21 @@ By default, execution results are always returned with document shaping (stitchi
 # get the raw result without shaping
 raw_result = GraphQL::Stitching::Executor.new(
   supergraph: supergraph,
-  plan: plan.to_h,
   request: request,
+  plan: plan.to_h,
 ).perform(raw: true)
 ```
+
+### Batching
+
+The Executor batches together as many requests as possible to a given location at a given time. Batched queries are written with the operation name suffixed by all operation keys in the batch, and root stitching fields are each prefixed by their batch index and collection index (for non-list fields):
+
+```graphql
+query MyOperation_2_3($lang:String!,$currency:Currency!){
+  _0_result: storefronts(ids:["7","8"]) { name(lang:$lang) }
+  _1_0_result: product(upc:"abc") { price(currency:$currency) }
+  _1_1_result: product(upc:"xyz") { price(currency:$currency) }
+}
+```
+
+All told, the executor will make one request per location per generation of data. Generations started on separate forks of the resolution tree will be resolved independently.

data/docs/planner.md

@@ -12,7 +12,11 @@ document = <<~GRAPHQL
   }
 GRAPHQL
 
-request = GraphQL::Stitching::Request.new(document, operation_name: "MyQuery").prepare!
+request = GraphQL::Stitching::Request.new(
+  document,
+  variables: { "id" => "1" },
+  operation_name: "MyQuery",
+).prepare!
 
 plan = GraphQL::Stitching::Planner.new(
   supergraph: supergraph,

data/docs/request.md

@@ -17,7 +17,7 @@ request.fragment_definitions # a mapping of fragment names to their fragment def
 
 ### Preparing requests
 
-A request should be prepared using the `prepare!` method before using it:
+A request should be prepared for stitching using the `prepare!` method _after_ validations have been run:
 
 ```ruby
 document = <<~GRAPHQL
@@ -38,6 +38,9 @@ request = GraphQL::Stitching::Request.new(
   operation_name: "FetchMovie",
 )
 
+errors = MySchema.validate(request.document)
+# return early with any static validation errors...
+
 request.prepare!
 ```
 

data/graphql-stitching.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'graphql', '~> 2.0.16'
+  spec.add_runtime_dependency 'graphql', '~> 2.0.3'
 
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 12.0'

data/lib/graphql/stitching/composer.rb

@@ -365,7 +365,7 @@ module GraphQL
 
       def merge_value_types(type_name, type_candidates, field_name: nil, argument_name: nil)
         path = [type_name, field_name, argument_name].compact.join(".")
-        named_types = type_candidates.map { Util.get_named_type(_1).graphql_name }.uniq
+        named_types = type_candidates.map { _1.unwrap.graphql_name }.uniq
 
         unless named_types.all? { _1 == named_types.first }
           raise ComposerError, "Cannot compose mixed types at `#{path}`. Found: #{named_types.join(", ")}."
@@ -422,7 +422,7 @@ module GraphQL
       def extract_boundaries(type_name, types_by_location)
         types_by_location.each do |location, type_candidate|
           type_candidate.fields.each do |field_name, field_candidate|
-            boundary_type_name = Util.get_named_type(field_candidate.type).graphql_name
+            boundary_type_name = field_candidate.type.unwrap.graphql_name
             boundary_list = Util.get_list_structure(field_candidate.type)
 
             field_candidate.directives.each do |directive|
@@ -470,10 +470,10 @@ module GraphQL
           boundary_type = schema.types[type_name]
           next unless boundary_type.kind.abstract?
 
-          possible_types = Util.get_possible_types(schema, boundary_type)
-          possible_types.select { @subschema_types_by_name_and_location[_1.graphql_name].length > 1 }.each do |possible_type|
-            @boundary_map[possible_type.graphql_name] ||= []
-            @boundary_map[possible_type.graphql_name].push(*@boundary_map[type_name])
+          expanded_types = Util.expand_abstract_type(schema, boundary_type)
+          expanded_types.select { @subschema_types_by_name_and_location[_1.graphql_name].length > 1 }.each do |expanded_type|
+            @boundary_map[expanded_type.graphql_name] ||= []
+            @boundary_map[expanded_type.graphql_name].push(*@boundary_map[type_name])
           end
         end
       end
@@ -488,18 +488,18 @@ module GraphQL
 
             if type.kind.object? || type.kind.interface?
               type.fields.values.each do |field|
-                field_type = Util.get_named_type(field.type)
+                field_type = field.type.unwrap
                 reads << field_type.graphql_name if field_type.kind.enum?
 
                 field.arguments.values.each do |argument|
-                  argument_type = Util.get_named_type(argument.type)
+                  argument_type = argument.type.unwrap
                   writes << argument_type.graphql_name if argument_type.kind.enum?
                 end
               end
 
             elsif type.kind.input_object?
               type.arguments.values.each do |argument|
-                argument_type = Util.get_named_type(argument.type)
+                argument_type = argument.type.unwrap
                 writes << argument_type.graphql_name if argument_type.kind.enum?
               end
             end

data/lib/graphql/stitching/executor.rb

@@ -15,7 +15,7 @@ module GraphQL
         def fetch(ops)
           op = ops.first # There should only ever be one per location at a time
 
-          query_document = build_query(op)
+          query_document = build_document(op, @executor.request.operation_name)
           query_variables = @executor.request.variables.slice(*op["variables"].keys)
           result = @executor.supergraph.execute_at_location(op["location"], query_document, query_variables, @executor.request.context)
           @executor.query_count += 1
@@ -29,13 +29,23 @@ module GraphQL
           ops.map { op["key"] }
         end
 
-        def build_query(op)
+        # Builds root source documents
+        # "query MyOperation_1($var:VarType) { rootSelections ... }"
+        def build_document(op, operation_name = nil)
+          doc = String.new
+          doc << op["operation_type"]
+
+          if operation_name
+            doc << " " << operation_name << "_" << op["key"].to_s
+          end
+
           if op["variables"].any?
             variable_defs = op["variables"].map { |k, v| "$#{k}:#{v}" }.join(",")
-            "#{op["operation_type"]}(#{variable_defs})#{op["selections"]}"
-          else
-            "#{op["operation_type"]}#{op["selections"]}"
+            doc << "(" << variable_defs << ")"
           end
+
+          doc << op["selections"]
+          doc
         end
       end
 
@@ -62,7 +72,7 @@ module GraphQL
           end
 
           if origin_sets_by_operation.any?
-            query_document, variable_names = build_query(origin_sets_by_operation)
+            query_document, variable_names = build_document(origin_sets_by_operation, @executor.request.operation_name)
             variables = @executor.request.variables.slice(*variable_names)
             raw_result = @executor.supergraph.execute_at_location(@location, query_document, variables, @executor.request.context)
             @executor.query_count += 1
@@ -76,7 +86,14 @@ module GraphQL
           ops.map { origin_sets_by_operation[_1] ? _1["key"] : nil }
         end
 
-        def build_query(origin_sets_by_operation)
+        # Builds batched boundary queries
+        # "query MyOperation_2_3($var:VarType) {
+        #   _0_result: list(keys:["a","b","c"]) { boundarySelections... }
+        #   _1_0_result: item(key:"x") { boundarySelections... }
+        #   _1_1_result: item(key:"y") { boundarySelections... }
+        #   _1_2_result: item(key:"z") { boundarySelections... }
+        # }"
+        def build_document(origin_sets_by_operation, operation_name = nil)
           variable_defs = {}
           query_fields = origin_sets_by_operation.map.with_index do |(op, origin_set), batch_index|
             variable_defs.merge!(op["variables"])
@@ -94,14 +111,24 @@ module GraphQL
             end
           end
 
-          query_document = if variable_defs.any?
-            query_variables = variable_defs.map { |k, v| "$#{k}:#{v}" }.join(",")
-            "query(#{query_variables}){ #{query_fields.join(" ")} }"
-          else
-            "query{ #{query_fields.join(" ")} }"
+          doc = String.new
+          doc << "query" # << boundary fulfillment always uses query
+
+          if operation_name
+            doc << " " << operation_name
+            origin_sets_by_operation.each_key do |op|
+              doc << "_" << op["key"].to_s
+            end
           end
 
-          return query_document, variable_defs.keys
+          if variable_defs.any?
+            variable_str = variable_defs.map { |k, v| "$#{k}:#{v}" }.join(",")
+            doc << "(" << variable_str << ")"
+          end
+
+          doc << "{ " << query_fields.join(" ") << " }"
+
+          return doc, variable_defs.keys
         end
 
         def merge_results!(origin_sets_by_operation, raw_result)

data/lib/graphql/stitching/planner.rb

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

data/lib/graphql/stitching/request.rb

@@ -4,7 +4,6 @@ module GraphQL
   module Stitching
     class Request
       SUPPORTED_OPERATIONS = ["query", "mutation"].freeze
-      EMPTY_CONTEXT = {}.freeze
 
       class ApplyRuntimeDirectives < GraphQL::Language::Visitor
         def initialize(document, variables)
@@ -68,7 +67,7 @@ module GraphQL
 
         @operation_name = operation_name
         @variables = variables || {}
-        @context = context || EMPTY_CONTEXT
+        @context = context || GraphQL::Stitching::EMPTY_OBJECT
       end
 
       def string
@@ -114,18 +113,19 @@ module GraphQL
           @variables[v.name] ||= v.default_value
         end
 
-        return self unless @may_contain_runtime_directives
+        if @may_contain_runtime_directives
+          visitor = ApplyRuntimeDirectives.new(@document, @variables)
+          @document = visitor.visit
 
-        visitor = ApplyRuntimeDirectives.new(@document, @variables)
-        @document = visitor.visit
-
-        if visitor.changed?
-          @string = nil
-          @digest = nil
-          @operation = nil
-          @variable_definitions = nil
-          @fragment_definitions = nil
+          if visitor.changed?
+            @string = nil
+            @digest = nil
+            @operation = nil
+            @variable_definitions = nil
+            @fragment_definitions = nil
+          end
         end
+
         self
       end
     end

data/lib/graphql/stitching/shaper.rb

@@ -29,7 +29,7 @@ module GraphQL
 
             field_name = node.alias || node.name
             node_type = parent_type.fields[node.name].type
-            named_type = Util.get_named_type_for_field_node(@schema, parent_type, node)
+            named_type = Util.named_type_for_field_node(@schema, parent_type, node)
 
             raw_object[field_name] = if node_type.list?
               resolve_list_scope(raw_object[field_name], Util.unwrap_non_null(node_type), node.selections)
@@ -67,7 +67,7 @@ module GraphQL
         return nil if raw_list.nil?
 
         next_node_type = Util.unwrap_non_null(current_node_type).of_type
-        named_type = Util.get_named_type(next_node_type)
+        named_type = next_node_type.unwrap
         contains_null = false
 
         resolved_list = raw_list.map! do |raw_list_element|

data/lib/graphql/stitching/supergraph.rb

@@ -29,6 +29,7 @@ module GraphQL
           end
         end
 
+        @possible_keys_by_type = {}
         @possible_keys_by_type_and_location = {}
         @executables = { LOCATION => @schema }.merge!(executables)
       end
@@ -72,7 +73,7 @@ module GraphQL
           executable.execute(
             query: query,
             variables: variables,
-            context: context,
+            context: context.frozen? ? context.dup : context,
             validate: false,
           )
         elsif executable.respond_to?(:call)
@@ -83,6 +84,7 @@ module GraphQL
       end
 
       # inverts fields map to provide fields for a type/location
+      # "Type" => "location" => ["field1", "field2", ...]
       def fields_by_type_and_location
         @fields_by_type_and_location ||= @locations_by_type_and_field.each_with_object({}) do |(type_name, fields), memo|
           memo[type_name] = fields.each_with_object({}) do |(field_name, locations), memo|
@@ -94,24 +96,55 @@ module GraphQL
         end
       end
 
+      # { "Type" => ["location1", "location2", ...] }
       def locations_by_type
         @locations_by_type ||= @locations_by_type_and_field.each_with_object({}) do |(type_name, fields), memo|
           memo[type_name] = fields.values.flatten.uniq
         end
       end
 
+      # collects all possible boundary keys for a given type
+      # { "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
+        end
+      end
+
+      # collects possible boundary keys for a given type and location
+      # ("Type", "location") => ["id", ...]
       def possible_keys_for_type_and_location(type_name, location)
         possible_keys_by_type = @possible_keys_by_type_and_location[type_name] ||= {}
         possible_keys_by_type[location] ||= begin
           location_fields = fields_by_type_and_location[type_name][location] || []
-          location_fields & @boundaries[type_name].map { _1["selection"] }
+          location_fields & possible_keys_for_type(type_name)
         end
       end
 
-      # For a given type, route from one origin service to one or more remote locations.
-      # Tunes a-star search to favor paths with fewest joining locations, ie:
-      # favor longer paths through target locations over shorter paths with additional locations.
+      # For a given type, route from one origin location to one or more remote locations
+      # used to connect a partial type across locations via boundary queries
       def route_type_to_locations(type_name, start_location, goal_locations)
+        if possible_keys_for_type(type_name).length > 1
+          # multiple keys use an a-star search to traverse intermediary locations
+          return route_type_to_locations_via_search(type_name, start_location, goal_locations)
+        end
+
+        # types with a single key attribute must all be within a single hop of each other,
+        # so can use a simple match to collect boundaries for the goal locations.
+        @boundaries[type_name].each_with_object({}) do |boundary, memo|
+          if goal_locations.include?(boundary["location"])
+            memo[boundary["location"]] = [boundary]
+          end
+        end
+      end
+
+      private
+
+      # tunes a-star search to favor paths with fewest joining locations, ie:
+      # favor longer paths through target locations over shorter paths with additional locations.
+      def route_type_to_locations_via_search(type_name, start_location, goal_locations)
         results = {}
         costs = {}
 

data/lib/graphql/stitching/util.rb

@@ -3,13 +3,9 @@
 module GraphQL
   module Stitching
     class Util
-
-      # gets the named type at the bottom of a non-null/list wrapper tree
-      def self.get_named_type(type)
-        while type.respond_to?(:of_type)
-          type = type.of_type
-        end
-        type
+      # specifies if a type is a primitive leaf value
+      def self.is_leaf_type?(type)
+        type.kind.scalar? || type.kind.enum?
       end
 
       # strips non-null wrappers from a type
@@ -20,6 +16,31 @@ module GraphQL
         type
       end
 
+      # gets a named type for a field node, including hidden root introspections
+      def self.named_type_for_field_node(schema, parent_type, node)
+        if node.name == "__schema" && parent_type == schema.query
+          schema.types["__Schema"]
+        else
+          parent_type.fields[node.name].type.unwrap
+        end
+      end
+
+      # expands interfaces and unions to an array of their memberships
+      # like `schema.possible_types`, but includes child interfaces
+      def self.expand_abstract_type(schema, parent_type)
+        return [] unless parent_type.kind.abstract?
+        return parent_type.possible_types if parent_type.kind.union?
+
+        result = []
+        schema.types.values.each do |type|
+          next unless type <= GraphQL::Schema::Interface && type != parent_type
+          next unless type.interfaces.include?(parent_type)
+          result << type
+          result.push(*expand_abstract_type(schema, type)) if type.kind.interface?
+        end
+        result.uniq
+      end
+
       # gets a deep structural description of a list value type
       def self.get_list_structure(type)
         structure = []
@@ -38,34 +59,6 @@ module GraphQL
         end
         structure
       end
-
-      # Gets all objects and interfaces that implement a given interface
-      def self.get_possible_types(schema, parent_type)
-        return [parent_type] unless parent_type.kind.abstract?
-        return parent_type.possible_types if parent_type.kind.union?
-
-        result = []
-        schema.types.values.each do |type|
-          next unless type <= GraphQL::Schema::Interface && type != parent_type
-          next unless type.interfaces.include?(parent_type)
-          result << type
-          result.push(*get_possible_types(schema, type)) if type.kind.interface?
-        end
-        result.uniq
-      end
-
-      # Specifies if a type is a leaf node (no children)
-      def self.is_leaf_type?(type)
-        type.kind.scalar? || type.kind.enum?
-      end
-
-      def self.get_named_type_for_field_node(schema, parent_type, node)
-        if node.name == "__schema" && parent_type == schema.query
-          schema.types["__Schema"] # type mapped to phantom introspection field
-        else
-          Util.get_named_type(parent_type.fields[node.name].type)
-        end
-      end
     end
   end
 end

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "0.2.1"
+    VERSION = "0.2.2"
   end
 end

data/lib/graphql/stitching.rb

@@ -4,6 +4,8 @@ require "graphql"
 
 module GraphQL
   module Stitching
+    EMPTY_OBJECT = {}.freeze
+
     class StitchingError < StandardError; end
 
     class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-15 00:00:00.000000000 Z
+date: 2023-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.16
+        version: 2.0.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.16
+        version: 2.0.3
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement