graphql-stitching 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ce8bb1075d536f01aa63487df3e1686bc0c2899b58ca14e95383caef38812e2
-  data.tar.gz: ae39e685bdb31cbf3962216cfce263b2970aa2aeac6be1901a7397cee6eb1656
+  metadata.gz: 665232d15bf3a10517a645afee2c74823221dd848d188681a86a482975031189
+  data.tar.gz: 746ee25d066ff080f7b63320aa2c0d5de4162c1a2119120db811f4f6acfc20dc
 SHA512:
-  metadata.gz: e718527102969773accf28b2323cbde1d2c467339c44bb876144ae5387a7aaec64143b35b6dfff21401fb087c64ed8742f79cda78e743518ba045871c320f51f
-  data.tar.gz: 74bc97f475b61ea51dd8ce9e42a1ff2783d0c1717a38ff812e256962d64b97ef0ccc092de11e529a22e274d8ad5cf77af9fd7ed2fd680e20e0c058534942a5d6
+  metadata.gz: 704cbc2753e452d2aa6fa5ec9bd55231754ee0c21cbd581b01d91d2af7f68c192a570922676e07143202b71564db674f6d5b8078ba276340c4863621547c7372
+  data.tar.gz: 255a20c78357854973e5d5818e4bbbcf8eb6f89bf01bc6ad9185306948a6e643dafe713e0943811d4e5841f3289b5fe7c9033683dd0ab97db282721e9d892109

data/README.md

@@ -400,6 +400,26 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
 
 The `GraphQL::Stitching::HttpExecutable` class is provided as a simple executable wrapper around `Net::HTTP.post`. You should build your own executables to leverage your existing libraries and to add instrumentation. Note that you must manually assign all executables to a `Supergraph` when rehydrating it from cache ([see docs](./docs/supergraph.md)).
 
+## Batching
+
+The stitching executor automatically batches subgraph requests so that only one request is made per location per generation of data. This is done using batched queries that combine all data access for a given a location. For example:
+
+```graphql
+query MyOperation_2 {
+  _0_result: widgets(ids:["a","b","c"]) { ... } # << 3 Widget
+  _1_0_result: sprocket(id:"x") { ... } # << 1 Sprocket
+  _1_1_result: sprocket(id:"y") { ... } # << 1 Sprocket
+  _1_2_result: sprocket(id:"z") { ... } # << 1 Sprocket
+}
+```
+
+Tips:
+
+* List queries (like the `widgets` selection above) are more compact for accessing multiple records, and are therefore preferable as stitching accessors.
+* Assure that root field resolvers across your subgraph implement batching to anticipate cases like the three `sprocket` selections above.
+
+Otherwise, there's no developer intervention necessary (or generally possible) to improve upon data access. Note that multiple generations of data may still force the executor to return to a previous location for more data.
+
 ## Concurrency
 
 The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based implementation of `GraphQL::Dataloader`. Non-blocking concurrency requires setting a fiber scheduler via `Fiber.set_scheduler`, see [graphql-ruby docs](https://graphql-ruby.org/dataloader/nonblocking.html). You may also need to build your own remote clients using corresponding HTTP libraries.

data/lib/graphql/stitching/boundary.rb

@@ -2,6 +2,7 @@
 
 module GraphQL
   module Stitching
+    # Defines a boundary query that provides direct access to an entity type.
     Boundary = Struct.new(
       :location,
       :type_name,

data/lib/graphql/stitching/composer.rb

@@ -8,8 +8,8 @@ module GraphQL
 
       attr_reader :query_name, :mutation_name, :candidate_types_by_name_and_location, :schema_directives
 
-      DEFAULT_VALUE_MERGER = ->(values_by_location, _info) { values_by_location.values.find { !_1.nil? } }
-      DEFAULT_ROOT_FIELD_LOCATION_SELECTOR = ->(locations, _info) { locations.last }
+      BASIC_VALUE_MERGER = ->(values_by_location, _info) { values_by_location.values.find { !_1.nil? } }
+      BASIC_ROOT_FIELD_LOCATION_SELECTOR = ->(locations, _info) { locations.last }
 
       VALIDATORS = [
         "ValidateInterfaces",
@@ -21,15 +21,17 @@ module GraphQL
         mutation_name: "Mutation",
         description_merger: nil,
         deprecation_merger: nil,
+        default_value_merger: nil,
         directive_kwarg_merger: nil,
         root_field_location_selector: nil
       )
         @query_name = query_name
         @mutation_name = mutation_name
-        @description_merger = description_merger || DEFAULT_VALUE_MERGER
-        @deprecation_merger = deprecation_merger || DEFAULT_VALUE_MERGER
-        @directive_kwarg_merger = directive_kwarg_merger || DEFAULT_VALUE_MERGER
-        @root_field_location_selector = root_field_location_selector || DEFAULT_ROOT_FIELD_LOCATION_SELECTOR
+        @description_merger = description_merger || BASIC_VALUE_MERGER
+        @deprecation_merger = deprecation_merger || BASIC_VALUE_MERGER
+        @default_value_merger = default_value_merger || BASIC_VALUE_MERGER
+        @directive_kwarg_merger = directive_kwarg_merger || BASIC_VALUE_MERGER
+        @root_field_location_selector = root_field_location_selector || BASIC_ROOT_FIELD_LOCATION_SELECTOR
         @stitch_directives = {}
       end
 
@@ -362,8 +364,22 @@ module GraphQL
             next
           end
 
-          # Getting double args sometimes... why?
-          return if owner.arguments.any? { _1.first == argument_name }
+          # Getting double args sometimes on auto-generated connection types... why?
+          next if owner.arguments.any? { _1.first == argument_name }
+
+          kwargs = {}
+          default_values_by_location = arguments_by_location.each_with_object({}) do |(location, argument), memo|
+            next if argument.default_value.class == Object # << pass on NOT_CONFIGURED (todo: improve this check)
+            memo[location] = argument.default_value
+          end
+
+          if default_values_by_location.any?
+            kwargs[:default_value] = @default_value_merger.call(default_values_by_location, {
+              type_name: type_name,
+              field_name: field_name,
+              argument_name: argument_name,
+            })
+          end
 
           type = merge_value_types(type_name, value_types, argument_name: argument_name, field_name: field_name)
           schema_argument = owner.argument(
@@ -373,6 +389,7 @@ module GraphQL
             type: Util.unwrap_non_null(type),
             required: type.non_null?,
             camelize: false,
+            **kwargs,
           )
 
           build_merged_directives(type_name, arguments_by_location, schema_argument, field_name: field_name, argument_name: argument_name)

data/lib/graphql/stitching/executor/boundary_source.rb

@@ -23,7 +23,11 @@ module GraphQL
         end
 
         if origin_sets_by_operation.any?
-          query_document, variable_names = build_document(origin_sets_by_operation, @executor.request.operation_name)
+          query_document, variable_names = build_document(
+            origin_sets_by_operation,
+            @executor.request.operation_name,
+            @executor.request.operation_directives,
+          )
           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
@@ -44,7 +48,7 @@ module GraphQL
       #   _1_1_result: item(key:"y") { boundarySelections... }
       #   _1_2_result: item(key:"z") { boundarySelections... }
       # }"
-      def build_document(origin_sets_by_operation, operation_name = nil)
+      def build_document(origin_sets_by_operation, operation_name = nil, operation_directives = nil)
         variable_defs = {}
         query_fields = origin_sets_by_operation.map.with_index do |(op, origin_set), batch_index|
           variable_defs.merge!(op.variables)
@@ -80,6 +84,10 @@ module GraphQL
           doc << "(#{variable_str})"
         end
 
+        if operation_directives
+          doc << " #{operation_directives} "
+        end
+
         doc << "{ #{query_fields.join(" ")} }"
 
         return doc, variable_defs.keys

data/lib/graphql/stitching/executor/root_source.rb

@@ -11,7 +11,11 @@ module GraphQL
       def fetch(ops)
         op = ops.first # There should only ever be one per location at a time
 
-        query_document = build_document(op, @executor.request.operation_name)
+        query_document = build_document(
+          op,
+          @executor.request.operation_name,
+          @executor.request.operation_directives,
+        )
         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
@@ -27,7 +31,7 @@ module GraphQL
 
       # Builds root source documents
       # "query MyOperation_1($var:VarType) { rootSelections ... }"
-      def build_document(op, operation_name = nil)
+      def build_document(op, operation_name = nil, operation_directives = nil)
         doc = String.new
         doc << op.operation_type
 
@@ -40,6 +44,10 @@ module GraphQL
           doc << "(#{variable_defs})"
         end
 
+        if operation_directives
+          doc << " #{operation_directives} "
+        end
+
         doc << op.selections
         doc
       end

data/lib/graphql/stitching/executor.rb

@@ -5,13 +5,13 @@ require "json"
 module GraphQL
   module Stitching
     class Executor
-      attr_reader :supergraph, :request, :data, :errors
+      attr_reader :supergraph, :request, :plan, :data, :errors
       attr_accessor :query_count
 
       def initialize(supergraph:, request:, plan:, nonblocking: false)
         @supergraph = supergraph
         @request = request
-        @queue = plan.ops
+        @plan = plan
         @data = {}
         @errors = []
         @query_count = 0
@@ -39,22 +39,20 @@ module GraphQL
 
       private
 
-      def exec!(next_ordinals = [0])
-        if @exec_cycles > @queue.length
+      def exec!(next_steps = [0])
+        if @exec_cycles > @plan.ops.length
           # sanity check... if we've exceeded queue size, then something went wrong.
           raise StitchingError, "Too many execution requests attempted."
         end
 
         @dataloader.append_job do
-          tasks = @queue
-            .select { next_ordinals.include?(_1.after) }
+          tasks = @plan
+            .ops
+            .select { next_steps.include?(_1.after) }
             .group_by { [_1.location, _1.boundary.nil?] }
             .map do |(location, root_source), ops|
-              if root_source
-                @dataloader.with(RootSource, self, location).request_all(ops)
-              else
-                @dataloader.with(BoundarySource, self, location).request_all(ops)
-              end
+              source_type = root_source ? RootSource : BoundarySource
+              @dataloader.with(source_type, self, location).request_all(ops)
             end
 
           tasks.each(&method(:exec_task))
@@ -65,8 +63,8 @@ module GraphQL
       end
 
       def exec_task(task)
-        next_ordinals = task.load.tap(&:compact!)
-        exec!(next_ordinals) if next_ordinals.any?
+        next_steps = task.load.tap(&:compact!)
+        exec!(next_steps) if next_steps.any?
       end
     end
   end

data/lib/graphql/stitching/plan.rb

@@ -2,6 +2,8 @@
 
 module GraphQL
   module Stitching
+    # Immutable structures representing a query plan.
+    # May serialize to/from JSON.
     class Plan
       Op = Struct.new(
         :step,

data/lib/graphql/stitching/planner.rb

@@ -4,6 +4,7 @@ module GraphQL
   module Stitching
     class Planner
       SUPERGRAPH_LOCATIONS = [Supergraph::LOCATION].freeze
+      TYPENAME = "__typename"
       QUERY_OP = "query"
       MUTATION_OP = "mutation"
       ROOT_INDEX = 0
@@ -35,18 +36,14 @@ module GraphQL
       # A.2) Partition mutation fields by consecutive location for serial execution.
       #
       # B) Extract contiguous selections for each entrypoint location.
-      #
       # B.1) Selections on interface types that do not belong to the interface at the
-      # entrypoint location are expanded into concrete type fragments prior to extraction.
-      #
+      #      entrypoint location are expanded into concrete type fragments prior to extraction.
       # B.2) Filter the selection tree down to just fields of the entrypoint location.
-      # Adjoining selections not available here get split off into new entrypoints (C).
-      #
+      #      Adjoining selections not available here get split off into new entrypoints (C).
       # B.3) Collect all variable definitions used within the filtered selection.
-      # These specify which request variables to pass along with the selection.
-      #
-      # B.4) Add a `__typename` selection to abstracts and concrete types that implement
-      # fragments. This provides resolved type information used during execution.
+      #      These specify which request variables to pass along with each step.
+      # B.4) Add a `__typename` hint to abstracts and types that implement fragments.
+      #      This provides resolved type information used during execution.
       #
       # C) Delegate adjoining selections to new entrypoint locations.
       # C.1) Distribute unique fields among their required locations.
@@ -60,7 +57,7 @@ module GraphQL
       #
       # E) Translate boundary pathways into new entrypoints.
       # E.1) Add the key of each boundary query into the prior location's selection set.
-      # E.2) Add a planner operation for each new entrypoint location, then extract it (B).
+      # E.2) Add a planner step for each new entrypoint location, then extract it (B).
       #
       # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
       # **
@@ -77,8 +74,7 @@ module GraphQL
         boundary: nil
       )
         # coalesce repeat parameters into a single entrypoint
-        boundary_key = boundary ? boundary.key : "_"
-        entrypoint = String.new("#{parent_index}/#{location}/#{parent_type.graphql_name}/#{boundary_key}")
+        entrypoint = String.new("#{parent_index}/#{location}/#{parent_type.graphql_name}/#{boundary&.key}")
         path.each { entrypoint << "/#{_1}" }
 
         step = @steps_by_entrypoint[entrypoint]
@@ -89,11 +85,6 @@ module GraphQL
         end
 
         if step.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)
-
           @steps_by_entrypoint[entrypoint] = PlannerStep.new(
             index: next_index,
             after: parent_index,
@@ -103,7 +94,6 @@ module GraphQL
             selections: selections,
             variables: variables,
             path: path,
-            if_type: conditional ? parent_type.graphql_name : nil,
             boundary: boundary,
           )
         else
@@ -209,7 +199,7 @@ module GraphQL
         input_selections.each do |node|
           case node
           when GraphQL::Language::Nodes::Field
-            if node.name == "__typename"
+            if node.name == TYPENAME
               locale_selections << node
               next
             end
@@ -267,7 +257,7 @@ module GraphQL
           end
         end
 
-        # B.4) Add a `__typename` selection to abstracts and concrete types that implement
+        # B.4) Add a `__typename` hint to abstracts and types that implement
         # fragments so that resolved type information is available during execution.
         if requires_typename
           locale_selections << SelectionHint.typename_node
@@ -297,13 +287,12 @@ module GraphQL
               parent_selections << SelectionHint.key_node(boundary.key) unless has_key
               parent_selections << SelectionHint.typename_node unless has_typename
 
-              # E.2) Add a planner operation for each new entrypoint location.
-              location = boundary.location
+              # E.2) Add a planner step for each new entrypoint location.
               add_step(
-                location: location,
+                location: boundary.location,
                 parent_index: parent_index,
                 parent_type: parent_type,
-                selections: remote_selections_by_location[location] || [],
+                selections: remote_selections_by_location[boundary.location] || [],
                 path: path.dup,
                 boundary: boundary,
               ).selections
@@ -323,7 +312,7 @@ module GraphQL
 
         expanded_selections = nil
         input_selections = input_selections.filter_map do |node|
-          if node.is_a?(GraphQL::Language::Nodes::Field) && node.name != "__typename" && !local_interface_fields.include?(node.name)
+          if node.is_a?(GraphQL::Language::Nodes::Field) && node.name != TYPENAME && !local_interface_fields.include?(node.name)
             expanded_selections ||= []
             expanded_selections << node
             nil
@@ -345,7 +334,7 @@ module GraphQL
       end
 
       # B.3) Collect all variable definitions used within the filtered selection.
-      # These specify which request variables to pass along with the selection.
+      # These specify which request variables to pass along with each step.
       def extract_node_variables(node_with_args, variable_definitions)
         node_with_args.arguments.each do |argument|
           case argument.value
@@ -391,15 +380,11 @@ module GraphQL
 
         # C.3) Distribute remaining fields among locations weighted by greatest availability.
         if remote_selections.any?
-          field_count_by_location = if remote_selections.length > 1
-            remote_selections.each_with_object({}) do |node, memo|
-              possible_locations_by_field[node.name].each do |location|
-                memo[location] ||= 0
-                memo[location] += 1
-              end
+          field_count_by_location = remote_selections.each_with_object({}) do |node, memo|
+            possible_locations_by_field[node.name].each do |location|
+              memo[location] ||= 0
+              memo[location] += 1
             end
-          else
-            GraphQL::Stitching::EMPTY_OBJECT
           end
 
           remote_selections.each do |node|
@@ -407,11 +392,11 @@ module GraphQL
             preferred_location = possible_locations.first
 
             possible_locations.reduce(0) do |max_availability, possible_location|
-              available_fields = field_count_by_location.fetch(possible_location, 0)
+              availability = field_count_by_location.fetch(possible_location, 0)
 
-              if available_fields > max_availability
+              if availability > max_availability
                 preferred_location = possible_location
-                available_fields
+                availability
               else
                 max_availability
               end
@@ -427,15 +412,15 @@ module GraphQL
 
       # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
       def expand_abstract_boundaries
-        @steps_by_entrypoint.each_value do |op|
-          next unless op.boundary
+        @steps_by_entrypoint.each_value do |step|
+          next unless step.boundary
 
-          boundary_type = @supergraph.memoized_schema_types[op.boundary.type_name]
+          boundary_type = @supergraph.memoized_schema_types[step.boundary.type_name]
           next unless boundary_type.kind.abstract?
-          next if boundary_type == op.parent_type
+          next if boundary_type == step.parent_type
 
           expanded_selections = nil
-          op.selections.reject! do |node|
+          step.selections.reject! do |node|
             if node.is_a?(GraphQL::Language::Nodes::Field)
               expanded_selections ||= []
               expanded_selections << node
@@ -444,8 +429,8 @@ module GraphQL
           end
 
           if expanded_selections
-            type_name = GraphQL::Language::Nodes::TypeName.new(name: op.parent_type.graphql_name)
-            op.selections << GraphQL::Language::Nodes::InlineFragment.new(type: type_name, selections: expanded_selections)
+            type_name = GraphQL::Language::Nodes::TypeName.new(name: step.parent_type.graphql_name)
+            step.selections << GraphQL::Language::Nodes::InlineFragment.new(type: type_name, selections: expanded_selections)
           end
         end
       end

data/lib/graphql/stitching/planner_step.rb

@@ -2,10 +2,13 @@
 
 module GraphQL
   module Stitching
+    # A planned step in the sequence of stitching entrypoints together.
+    # This is a mutable object that may change throughout the planning process.
+    # It ultimately builds an immutable Plan::Op at the end of planning.
     class PlannerStep
       GRAPHQL_PRINTER = GraphQL::Language::Printer.new
 
-      attr_reader :index, :location, :parent_type, :if_type, :operation_type, :path
+      attr_reader :index, :location, :parent_type, :operation_type, :path
       attr_accessor :after, :selections, :variables, :boundary
 
       def initialize(
@@ -17,7 +20,6 @@ module GraphQL
         selections: [],
         variables: {},
         path: [],
-        if_type: nil,
         boundary: nil
       )
         @location = location
@@ -28,7 +30,6 @@ module GraphQL
         @selections = selections
         @variables = variables
         @path = path
-        @if_type = if_type
         @boundary = boundary
       end
 
@@ -41,13 +42,20 @@ module GraphQL
           selections: rendered_selections,
           variables: rendered_variables,
           path: @path,
-          if_type: @if_type,
+          if_type: type_condition,
           boundary: @boundary,
         )
       end
 
       private
 
+      # Concrete types going to a boundary report themselves as a type condition.
+      # This is used by the executor to evalute which planned fragment selections
+      # actually apply to the resolved object types.
+      def type_condition
+        @parent_type.graphql_name if @boundary && !parent_type.kind.abstract?
+      end
+
       def rendered_selections
         op = GraphQL::Language::Nodes::OperationDefinition.new(operation_type: "", selections: @selections)
         GRAPHQL_PRINTER.print(op).gsub!(/\s+/, " ").strip!

data/lib/graphql/stitching/request.rb

@@ -48,6 +48,13 @@ module GraphQL
         end
       end
 
+      def operation_directives
+        @operation_directives ||= if operation.directives.any?
+          printer = GraphQL::Language::Printer.new
+          operation.directives.map { printer.print(_1) }.join(" ")
+        end
+      end
+
       def variable_definitions
         @variable_definitions ||= operation.variables.each_with_object({}) do |v, memo|
           memo[v.name] = v.type

data/lib/graphql/stitching/selection_hint.rb

@@ -2,6 +2,8 @@
 
 module GraphQL
   module Stitching
+    # Builds hidden selection fields added by stitiching code,
+    # used to request operational data about resolved objects.
     class SelectionHint
       HINT_PREFIX = "_STITCH_"
 

data/lib/graphql/stitching/shaper.rb

@@ -3,6 +3,8 @@
 
 module GraphQL
   module Stitching
+    # Shapes the final results payload to the request selection and schema definition.
+    # This eliminates unrequested selection hints and applies null bubbling.
     class Shaper
       def initialize(supergraph:, request:)
         @supergraph = supergraph

data/lib/graphql/stitching/util.rb

@@ -60,7 +60,7 @@ module GraphQL
             result << type
             result.push(*expand_abstract_type(schema, type)) if type.kind.interface?
           end
-          result.uniq
+          result.tap(&:uniq!)
         end
       end
     end

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.0.1"
+    VERSION = "1.0.3"
   end
 end

metadata

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