graphql-stitching 1.2.4 → 1.3.0

data/lib/graphql/stitching/executor/{boundary_source.rb → resolver_source.rb}

@@ -2,10 +2,11 @@
 
 module GraphQL::Stitching
   class Executor
-    class BoundarySource < GraphQL::Dataloader::Source
+    class ResolverSource < GraphQL::Dataloader::Source
       def initialize(executor, location)
         @executor = executor
         @location = location
+        @variables = {}
       end
 
       def fetch(ops)
@@ -28,7 +29,7 @@ module GraphQL::Stitching
             @executor.request.operation_name,
             @executor.request.operation_directives,
           )
-          variables = @executor.request.variables.slice(*variable_names)
+          variables = @variables.merge!(@executor.request.variables.slice(*variable_names))
           raw_result = @executor.request.supergraph.execute_at_location(@location, query_document, variables, @executor.request)
           @executor.query_count += 1
 
@@ -41,36 +42,40 @@ module GraphQL::Stitching
         ops.map { origin_sets_by_operation[_1] ? _1.step : nil }
       end
 
-      # 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... }
+      # Builds batched resolver queries
+      # "query MyOperation_2_3($var:VarType, $_0_key:[ID!]!, $_1_0_key:ID!, $_1_1_key:ID!, $_1_2_key:ID!) {
+      #   _0_result: list(keys: $_0_key) { resolverSelections... }
+      #   _1_0_result: item(key: $_1_0_key) { resolverSelections... }
+      #   _1_1_result: item(key: $_1_1_key) { resolverSelections... }
+      #   _1_2_result: item(key: $_1_2_key) { resolverSelections... }
       # }"
       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)
-          boundary = op.boundary
+          resolver = op.resolver
 
-          if boundary.list
-            input = origin_set.each_with_index.reduce(String.new) do |memo, (origin_obj, index)|
-              memo << "," if index > 0
-              memo << build_key(boundary.key, origin_obj, federation: boundary.federation)
-              memo
+          if resolver.list?
+            variable_name = "_#{batch_index}_key"
+
+            @variables[variable_name] = origin_set.map do |origin_obj|
+              build_key(resolver.key, origin_obj, as_representation: resolver.representations?)
             end
 
-            "_#{batch_index}_result: #{boundary.field}(#{boundary.arg}:[#{input}]) #{op.selections}"
+            variable_defs[variable_name] = "[#{resolver.arg_type_name}!]!"
+            "_#{batch_index}_result: #{resolver.field}(#{resolver.arg}:$#{variable_name}) #{op.selections}"
           else
             origin_set.map.with_index do |origin_obj, index|
-              input = build_key(boundary.key, origin_obj, federation: boundary.federation)
-              "_#{batch_index}_#{index}_result: #{boundary.field}(#{boundary.arg}:#{input}) #{op.selections}"
+              variable_name = "_#{batch_index}_#{index}_key"
+              @variables[variable_name] = build_key(resolver.key, origin_obj, as_representation: resolver.representations?)
+
+              variable_defs[variable_name] = "#{resolver.arg_type_name}!"
+              "_#{batch_index}_#{index}_result: #{resolver.field}(#{resolver.arg}:$#{variable_name}) #{op.selections}"
             end
           end
         end
 
-        doc = String.new("query") # << boundary fulfillment always uses query
+        doc = String.new("query") # << resolver fulfillment always uses query
 
         if operation_name
           doc << " #{operation_name}"
@@ -90,15 +95,19 @@ module GraphQL::Stitching
 
         doc << "{ #{query_fields.join(" ")} }"
 
-        return doc, variable_defs.keys
+        return doc, variable_defs.keys.tap do |names|
+          names.reject! { @variables.key?(_1) }
+        end
       end
 
-      def build_key(key, origin_obj, federation: false)
-        key_value = JSON.generate(origin_obj[ExportSelection.key(key)])
-        if federation
-          "{ __typename: \"#{origin_obj[ExportSelection.typename_node.alias]}\", #{key}: #{key_value} }"
+      def build_key(key, origin_obj, as_representation: false)
+        if as_representation
+          {
+            "__typename" => origin_obj[ExportSelection.typename_node.alias],
+            key => origin_obj[ExportSelection.key(key)],
+          }
         else
-          key_value
+          origin_obj[ExportSelection.key(key)]
         end
       end
 
@@ -106,7 +115,7 @@ module GraphQL::Stitching
         return unless raw_result
 
         origin_sets_by_operation.each_with_index do |(op, origin_set), batch_index|
-          results = if op.dig("boundary", "list")
+          results = if op.resolver.list?
             raw_result["_#{batch_index}_result"]
           else
             origin_set.map.with_index { |_, index| raw_result["_#{batch_index}_#{index}_result"] }

data/lib/graphql/stitching/executor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
-require_relative "./executor/boundary_source"
+require_relative "./executor/resolver_source"
 require_relative "./executor/root_source"
 
 module GraphQL
@@ -55,9 +55,9 @@ module GraphQL
           tasks = @request.plan
             .ops
             .select { next_steps.include?(_1.after) }
-            .group_by { [_1.location, _1.boundary.nil?] }
+            .group_by { [_1.location, _1.resolver.nil?] }
             .map do |(location, root_source), ops|
-              source_type = root_source ? RootSource : BoundarySource
+              source_type = root_source ? RootSource : ResolverSource
               @dataloader.with(source_type, self, location).request_all(ops)
             end
 

data/lib/graphql/stitching/plan.rb

@@ -14,7 +14,7 @@ module GraphQL
         :variables,
         :path,
         :if_type,
-        :boundary,
+        :resolver,
         keyword_init: true
       ) do
         def as_json
@@ -27,7 +27,7 @@ module GraphQL
             variables: variables,
             path: path,
             if_type: if_type,
-            boundary: boundary&.as_json
+            resolver: resolver&.as_json
           }.tap(&:compact!)
         end
       end
@@ -36,7 +36,7 @@ module GraphQL
         def from_json(json)
           ops = json["ops"]
           ops = ops.map do |op|
-            boundary = op["boundary"]
+            resolver = op["resolver"]
             Op.new(
               step: op["step"],
               after: op["after"],
@@ -46,7 +46,7 @@ module GraphQL
               variables: op["variables"],
               path: op["path"],
               if_type: op["if_type"],
-              boundary: boundary ? GraphQL::Stitching::Boundary.new(**boundary) : nil,
+              resolver: resolver ? GraphQL::Stitching::Resolver.new(**resolver) : nil,
             )
           end
           new(ops: ops)

data/lib/graphql/stitching/planner.rb

@@ -18,7 +18,7 @@ module GraphQL
 
       def perform
         build_root_entrypoints
-        expand_abstract_boundaries
+        expand_abstract_resolvers
         Plan.new(ops: steps.map(&:to_plan_op))
       end
 
@@ -50,16 +50,16 @@ module GraphQL
       # 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) Create paths routing to new entrypoint locations via resolver queries.
       # D.1) Types joining through multiple keys route using A* search.
       # D.2) Types joining through a single key route via quick location match.
       # (D.2 is an optional optimization of D.1)
       #
-      # E) Translate boundary pathways into new entrypoints.
-      # E.1) Add the key of each boundary query into the prior location's selection set.
+      # E) Translate resolver pathways into new entrypoints.
+      # E.1) Add the key of each resolver query into the prior location's selection set.
       # 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.
+      # F) Wrap concrete selections targeting abstract resolvers in typed fragments.
       # **
 
       # adds a planning step for fetching and inserting data into the aggregate result.
@@ -71,10 +71,10 @@ module GraphQL
         variables: {},
         path: [],
         operation_type: QUERY_OP,
-        boundary: nil
+        resolver: nil
       )
         # coalesce repeat parameters into a single entrypoint
-        entrypoint = String.new("#{parent_index}/#{location}/#{parent_type.graphql_name}/#{boundary&.key}")
+        entrypoint = String.new("#{parent_index}/#{location}/#{parent_type.graphql_name}/#{resolver&.key}")
         path.each { entrypoint << "/#{_1}" }
 
         step = @steps_by_entrypoint[entrypoint]
@@ -94,7 +94,7 @@ module GraphQL
             selections: selections,
             variables: variables,
             path: path,
-            boundary: boundary,
+            resolver: resolver,
           )
         else
           step.selections.concat(selections)
@@ -269,15 +269,15 @@ module GraphQL
           # 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.
+          # D) Create paths routing to new entrypoint locations via resolver 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.
+          # E) Translate resolver 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.
-              if boundary.key
-                foreign_key = ExportSelection.key(boundary.key)
+            route.reduce(locale_selections) do |parent_selections, resolver|
+              # E.1) Add the key of each resolver query into the prior location's selection set.
+              if resolver.key
+                foreign_key = ExportSelection.key(resolver.key)
                 has_key = false
                 has_typename = false
 
@@ -287,18 +287,18 @@ module GraphQL
                   has_typename ||= node.alias == ExportSelection.typename_node.alias
                 end
 
-                parent_selections << ExportSelection.key_node(boundary.key) unless has_key
+                parent_selections << ExportSelection.key_node(resolver.key) unless has_key
                 parent_selections << ExportSelection.typename_node unless has_typename
               end
 
               # E.2) Add a planner step for each new entrypoint location.
               add_step(
-                location: boundary.location,
+                location: resolver.location,
                 parent_index: parent_index,
                 parent_type: parent_type,
-                selections: remote_selections_by_location[boundary.location] || [],
+                selections: remote_selections_by_location[resolver.location] || [],
                 path: path.dup,
-                boundary: boundary.key ? boundary : nil,
+                resolver: resolver.key ? resolver : nil,
               ).selections
             end
           end
@@ -414,14 +414,14 @@ module GraphQL
         selections_by_location
       end
 
-      # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
-      def expand_abstract_boundaries
+      # F) Wrap concrete selections targeting abstract resolvers in typed fragments.
+      def expand_abstract_resolvers
         @steps_by_entrypoint.each_value do |step|
-          next unless step.boundary
+          next unless step.resolver
 
-          boundary_type = @supergraph.memoized_schema_types[step.boundary.type_name]
-          next unless boundary_type.kind.abstract?
-          next if boundary_type == step.parent_type
+          resolver_type = @supergraph.memoized_schema_types[step.resolver.type_name]
+          next unless resolver_type.kind.abstract?
+          next if resolver_type == step.parent_type
 
           expanded_selections = nil
           step.selections.reject! do |node|

data/lib/graphql/stitching/planner_step.rb

@@ -9,7 +9,7 @@ module GraphQL
       GRAPHQL_PRINTER = GraphQL::Language::Printer.new
 
       attr_reader :index, :location, :parent_type, :operation_type, :path
-      attr_accessor :after, :selections, :variables, :boundary
+      attr_accessor :after, :selections, :variables, :resolver
 
       def initialize(
         location:,
@@ -20,7 +20,7 @@ module GraphQL
         selections: [],
         variables: {},
         path: [],
-        boundary: nil
+        resolver: nil
       )
         @location = location
         @parent_type = parent_type
@@ -30,7 +30,7 @@ module GraphQL
         @selections = selections
         @variables = variables
         @path = path
-        @boundary = boundary
+        @resolver = resolver
       end
 
       def to_plan_op
@@ -43,17 +43,17 @@ module GraphQL
           variables: rendered_variables,
           path: @path,
           if_type: type_condition,
-          boundary: @boundary,
+          resolver: @resolver,
         )
       end
 
       private
 
-      # Concrete types going to a boundary report themselves as a type condition.
+      # Concrete types going to a resolver 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?
+        @parent_type.graphql_name if @resolver && !parent_type.kind.abstract?
       end
 
       def rendered_selections

data/lib/graphql/stitching/resolver.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    # Defines a root resolver query that provides direct access to an entity type.
+    Resolver = Struct.new(
+      # location name providing the resolver query.
+      :location,
+
+      # name of merged type fulfilled through this resolver.
+      :type_name,
+
+      # a key field to select from prior locations, sent as resolver argument.
+      :key,
+
+      # name of the root field to query.
+      :field,
+
+      # specifies when the resolver is a list query.
+      :list,
+
+      # name of the root field argument used to send the key.
+      :arg,
+
+      # type name of the root field argument used to send the key.
+      :arg_type_name,
+
+      # specifies that keys should be sent as JSON representations with __typename and key.
+      :representations,
+      keyword_init: true
+    ) do
+      alias_method :list?, :list
+      alias_method :representations?, :representations
+
+      def as_json
+        {
+          location: location,
+          type_name: type_name,
+          key: key,
+          field: field,
+          list: list,
+          arg: arg,
+          arg_type_name: arg_type_name,
+          representations: representations,
+        }.tap(&:compact!)
+      end
+    end
+  end
+end

data/lib/graphql/stitching/supergraph/resolver_directive.rb

@@ -10,8 +10,9 @@ module GraphQL::Stitching
       argument :key, String, required: true
       argument :field, String, required: true
       argument :arg, String, required: true
+      argument :arg_type_name, String, required: true
       argument :list, Boolean, required: false
-      argument :federation, Boolean, required: false
+      argument :representations, Boolean, required: false
       repeatable true
     end
   end

data/lib/graphql/stitching/supergraph.rb

@@ -18,7 +18,7 @@ module GraphQL
         def from_definition(schema, executables:)
           schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
           field_map = {}
-          boundary_map = {}
+          resolver_map = {}
           possible_locations = {}
           introspection_types = schema.introspection_system.types.keys
 
@@ -29,15 +29,16 @@ module GraphQL
               next unless directive.graphql_name == ResolverDirective.graphql_name
 
               kwargs = directive.arguments.keyword_arguments
-              boundary_map[type_name] ||= []
-              boundary_map[type_name] << Boundary.new(
+              resolver_map[type_name] ||= []
+              resolver_map[type_name] << Resolver.new(
                 type_name: kwargs.fetch(:type_name, type_name),
                 location: kwargs[:location],
                 key: kwargs[:key],
                 field: kwargs[:field],
-                arg: kwargs[:arg],
                 list: kwargs[:list] || false,
-                federation: kwargs[:federation] || false,
+                arg: kwargs[:arg],
+                arg_type_name: kwargs[:arg_type_name],
+                representations: kwargs[:representations] || false,
               )
             end
 
@@ -66,7 +67,7 @@ module GraphQL
           new(
             schema: schema,
             fields: field_map,
-            boundaries: boundary_map,
+            resolvers: resolver_map,
             executables: executables,
           )
         end
@@ -78,13 +79,13 @@ module GraphQL
       # @return [Hash<String, Executable>] a map of executable resources by location.
       attr_reader :executables
 
-      attr_reader :boundaries, :locations_by_type_and_field
+      attr_reader :resolvers, :locations_by_type_and_field
 
-      def initialize(schema:, fields: {}, boundaries: {}, executables: {})
+      def initialize(schema:, fields: {}, resolvers: {}, executables: {})
         @schema = schema
         @schema.use(GraphQL::Schema::AlwaysVisible)
 
-        @boundaries = boundaries
+        @resolvers = resolvers
         @fields_by_type_and_location = nil
         @locations_by_type = nil
         @memoized_introspection_types = nil
@@ -120,27 +121,28 @@ module GraphQL
         end
 
         @schema.types.each do |type_name, type|
-          if boundaries_for_type = @boundaries.dig(type_name)
-            boundaries_for_type.each do |boundary|
+          if resolvers_for_type = @resolvers.dig(type_name)
+            resolvers_for_type.each do |resolver|
               existing = type.directives.find do |d|
                 kwargs = d.arguments.keyword_arguments
                 d.graphql_name == ResolverDirective.graphql_name &&
-                  kwargs[:location] == boundary.location &&
-                  kwargs[:key] == boundary.key &&
-                  kwargs[:field] == boundary.field &&
-                  kwargs[:arg] == boundary.arg &&
-                  kwargs.fetch(:list, false) == boundary.list &&
-                  kwargs.fetch(:federation, false) == boundary.federation
+                  kwargs[:location] == resolver.location &&
+                  kwargs[:key] == resolver.key &&
+                  kwargs[:field] == resolver.field &&
+                  kwargs[:arg] == resolver.arg &&
+                  kwargs.fetch(:list, false) == resolver.list &&
+                  kwargs.fetch(:representations, false) == resolver.representations
               end
 
               type.directive(ResolverDirective, **{
-                type_name: (boundary.type_name if boundary.type_name != type_name),
-                location: boundary.location,
-                key: boundary.key,
-                field: boundary.field,
-                arg: boundary.arg,
-                list: boundary.list || nil,
-                federation: boundary.federation || nil,
+                type_name: (resolver.type_name if resolver.type_name != type_name),
+                location: resolver.location,
+                key: resolver.key,
+                field: resolver.field,
+                list: resolver.list || nil,
+                arg: resolver.arg,
+                arg_type_name: resolver.arg_type_name,
+                representations: resolver.representations || nil,
               }.tap(&:compact!)) if existing.nil?
             end
           end
@@ -242,19 +244,19 @@ module GraphQL
         end
       end
 
-      # collects all possible boundary keys for a given type
+      # collects all possible resolver keys for a given type
       # ("Type") => ["id", ...]
       def possible_keys_for_type(type_name)
         @possible_keys_by_type[type_name] ||= begin
           if type_name == @schema.query.graphql_name
             GraphQL::Stitching::EMPTY_ARRAY
           else
-            @boundaries[type_name].map(&:key).tap(&:uniq!)
+            @resolvers[type_name].map(&:key).tap(&:uniq!)
           end
         end
       end
 
-      # collects possible boundary keys for a given type and location
+      # collects possible resolver 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] ||= {}
@@ -265,14 +267,14 @@ module GraphQL
       end
 
       # 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
+      # used to connect a partial type across locations via resolver queries
       def route_type_to_locations(type_name, start_location, goal_locations)
         key_count = possible_keys_for_type(type_name).length
 
         if key_count.zero?
-          # nested root scopes have no boundary keys and just return a location
+          # nested root scopes have no resolver keys and just return a location
           goal_locations.each_with_object({}) do |goal_location, memo|
-            memo[goal_location] = [Boundary.new(location: goal_location)]
+            memo[goal_location] = [Resolver.new(location: goal_location)]
           end
 
         elsif key_count > 1
@@ -281,10 +283,10 @@ module GraphQL
 
         else
           # 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]
+          # so can use a simple match to collect resolvers for the goal locations.
+          @resolvers[type_name].each_with_object({}) do |resolver, memo|
+            if goal_locations.include?(resolver.location)
+              memo[resolver.location] = [resolver]
             end
           end
         end
@@ -292,7 +294,7 @@ module GraphQL
 
       private
 
-      PathNode = Struct.new(:location, :key, :cost, :boundary, keyword_init: true)
+      PathNode = Struct.new(:location, :key, :cost, :resolver, keyword_init: true)
 
       # tunes A* search to favor paths with fewest joining locations, ie:
       # favor longer paths through target locations over shorter paths with additional locations.
@@ -310,9 +312,9 @@ module GraphQL
           current_key = path.last.key
           current_cost = path.last.cost
 
-          @boundaries[type_name].each do |boundary|
-            forward_location = boundary.location
-            next if current_key != boundary.key
+          @resolvers[type_name].each do |resolver|
+            forward_location = resolver.location
+            next if current_key != resolver.key
             next if path.any? { _1.location == forward_location }
 
             best_cost = costs[forward_location] || Float::INFINITY
@@ -323,13 +325,13 @@ module GraphQL
               location: current_location,
               key: current_key,
               cost: current_cost,
-              boundary: boundary,
+              resolver: resolver,
             )
 
             if goal_locations.include?(forward_location)
               current_result = results[forward_location]
               if current_result.nil? || current_cost < best_cost || (current_cost == best_cost && path.length < current_result.length)
-                results[forward_location] = path.map(&:boundary)
+                results[forward_location] = path.map(&:resolver)
               end
             else
               path.last.cost += 1

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.2.4"
+    VERSION = "1.3.0"
   end
 end

data/lib/graphql/stitching.rb

@@ -24,7 +24,7 @@ module GraphQL
 end
 
 require_relative "stitching/supergraph"
-require_relative "stitching/boundary"
+require_relative "stitching/resolver"
 require_relative "stitching/client"
 require_relative "stitching/composer"
 require_relative "stitching/executor"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.3.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-07 00:00:00.000000000 Z
+date: 2024-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -110,15 +110,14 @@ files:
 - gemfiles/graphql_2.2.0.gemfile
 - graphql-stitching.gemspec
 - lib/graphql/stitching.rb
-- lib/graphql/stitching/boundary.rb
 - lib/graphql/stitching/client.rb
 - lib/graphql/stitching/composer.rb
 - lib/graphql/stitching/composer/base_validator.rb
-- lib/graphql/stitching/composer/boundary_config.rb
-- lib/graphql/stitching/composer/validate_boundaries.rb
+- lib/graphql/stitching/composer/resolver_config.rb
 - lib/graphql/stitching/composer/validate_interfaces.rb
+- lib/graphql/stitching/composer/validate_resolvers.rb
 - lib/graphql/stitching/executor.rb
-- lib/graphql/stitching/executor/boundary_source.rb
+- lib/graphql/stitching/executor/resolver_source.rb
 - lib/graphql/stitching/executor/root_source.rb
 - lib/graphql/stitching/export_selection.rb
 - lib/graphql/stitching/http_executable.rb
@@ -126,6 +125,7 @@ files:
 - lib/graphql/stitching/planner.rb
 - lib/graphql/stitching/planner_step.rb
 - lib/graphql/stitching/request.rb
+- lib/graphql/stitching/resolver.rb
 - lib/graphql/stitching/shaper.rb
 - lib/graphql/stitching/skip_include.rb
 - lib/graphql/stitching/supergraph.rb