graphql-stitching 1.2.5 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 754e7a61df541f685ef50ec79039df9742e4a2589a30eadf93125d6e4ef47aed
-  data.tar.gz: e2ceb89be07b42dbffeaa75416055fa62ffafa001088fd47b2b4f156aee6123a
+  metadata.gz: d33ec469a7f4598bd9f198b25102bcb3453d034b124fb18bcfd8ec595b78a6ce
+  data.tar.gz: a6ef6c8e218045a508c22ade74fb83504d762c0a6cadb5ed3cd4f58a89bddcea
 SHA512:
-  metadata.gz: 561ecdc36e78b31e4f4fd2f85d4ff5e0f1ab23d44570de7d8ffe63c2e46b5856214eb07c25b98eafbd64857602ebd839e187175e9e3ec347caedf4651a00d332
-  data.tar.gz: dd7a98e1c97f7bd5a6ca2585c34b6538e94b6dfaaa83edf9b3f1bc287a79d04f62a29ebe2a6b6fae4d06e8af9f08bb20203a89f1b062f24dc622a66973f87abc
+  metadata.gz: dc753d25c70045d1f2f995a0bbc8329ab426e1c5426943fa88e03fa71128fe8c1da928a8c905c997396c4d248e26e4400a02e2b2bc56d9e26b4916b5c63a8a7b
+  data.tar.gz: fdea7099a1cb486df512bdb93e7d90cceef42e7ff875e4c72c8e4b1fb46836d9e15cf5ae6124ca81132ec2a0707aca08a0d2a80d35fc40b18cf036c12576ff43

data/README.md

@@ -265,7 +265,7 @@ type Query {
 The `@stitch` directive can be added to class-based schemas with a directive class:
 
 ```ruby
-class StitchField < GraphQL::Schema::Directive
+class StitchingResolver < GraphQL::Schema::Directive
   graphql_name "stitch"
   locations FIELD_DEFINITION
   repeatable true
@@ -274,7 +274,7 @@ end
 
 class Query < GraphQL::Schema::Object
   field :product, Product, null: false do
-    directive StitchField, key: "id"
+    directive StitchingResolver, key: "id"
     argument :id, ID, required: true
   end
 end
@@ -284,7 +284,7 @@ The `@stitch` directive can be exported from a class-based schema to an SDL stri
 
 #### SDL-based schemas
 
-A clean SDL string may also have stitching directives applied via static configuration by passing a `stitch` array in [location settings](./docs/composer.md#performing-composition):
+A clean schema may also have stitching directives applied via static configuration by passing a `stitch` array in [location settings](./docs/composer.md#performing-composition):
 
 ```ruby
 sdl_string = <<~GRAPHQL
@@ -316,7 +316,7 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
 The library is configured to use a `@stitch` directive by default. You may customize this by setting a new name during initialization:
 
 ```ruby
-GraphQL::Stitching.stitch_directive = "merge"
+GraphQL::Stitching.stitch_directive = "resolver"
 ```
 
 ## Executables
@@ -365,17 +365,17 @@ The `GraphQL::Stitching::HttpExecutable` class is provided as a simple executabl
 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
+query MyOperation_2($_0_key:[ID!]!, $_1_0_key:ID!, $_1_1_key:ID!, $_1_2_key:ID!) {
+  _0_result: widgets(ids: $_0_key) { ... } # << 3 Widget
+  _1_0_result: sprocket(id: $_1_0_key) { ... } # << 1 Sprocket
+  _1_1_result: sprocket(id: $_1_1_key) { ... } # << 1 Sprocket
+  _1_2_result: sprocket(id: $_1_2_key) { ... } # << 1 Sprocket
 }
 ```
 
 Tips:
 
-* List queries (like the `widgets` selection above) are more compact for accessing multiple records, and are therefore preferable as stitching accessors.
+* List queries (like the `widgets` selection above) are generally preferable as resolver queries because they keep the batched document consistent regardless of set size, and make for smaller documents that parse and validate faster.
 * 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.

data/docs/README.md

@@ -14,4 +14,5 @@ Major components include:
 
 Additional topics:
 
-- [Stitching mechanics](./mechanics.md) - learn more about building for stitching.
+- [Stitching mechanics](./mechanics.md) - more about building for stitching and how it operates.
+- [Federation entities](./federation_entities.md) - more about Apollo Federation compatibility.

data/docs/mechanics.md

@@ -314,6 +314,7 @@ Merged types do not always require a resolver query. For example:
 type Widget {
   id: ID!
   name: String
+  price: Float
 }
 
 type Query {
@@ -344,4 +345,4 @@ type Query {
 }
 ```
 
-In this graph, `Widget` is a merged type without a resolver query in location C. This works because all of its fields are resolvable in other locations; that means location C can provide outbound representations of this type without ever needing to resolve inbound requests for it. Outbound types do still require a key field (such as `id` above) that allow them to join with data in other resolver locations.
+In this graph, `Widget` is a merged type without a resolver query in location C. This works because all of its fields are resolvable in other locations; that means location C can provide outbound representations of this type without ever needing to resolve inbound requests for it. Outbound types do still require a shared key field (such as `id` above) that allow them to join with data in other resolver locations (such as `price` above).

data/lib/graphql/stitching/composer/{boundary_config.rb → resolver_config.rb}

@@ -2,7 +2,7 @@
 
 module GraphQL::Stitching
   class Composer
-    class BoundaryConfig
+    class ResolverConfig
       ENTITY_TYPENAME = "_Entity"
       ENTITIES_QUERY = "_entities"
 
@@ -38,7 +38,7 @@ module GraphQL::Stitching
               memo[field_path] << new(
                 key: key,
                 type_name: entity_type.graphql_name,
-                federation: true,
+                representations: true,
               )
             end
           end
@@ -48,7 +48,7 @@ module GraphQL::Stitching
           new(
             key: kwargs[:key],
             type_name: kwargs[:type_name] || kwargs[:typeName],
-            federation: kwargs[:federation] || false,
+            representations: kwargs[:representations] || false,
           )
         end
 
@@ -61,12 +61,12 @@ module GraphQL::Stitching
         end
       end
 
-      attr_reader :key, :type_name, :federation
+      attr_reader :key, :type_name, :representations
 
-      def initialize(key:, type_name:, federation: false)
+      def initialize(key:, type_name:, representations: false)
         @key = key
         @type_name = type_name
-        @federation = federation
+        @representations = representations
       end
     end
   end

data/lib/graphql/stitching/composer/{validate_boundaries.rb → validate_resolvers.rb}

@@ -2,7 +2,7 @@
 
 module GraphQL::Stitching
   class Composer
-    class ValidateBoundaries < BaseValidator
+    class ValidateResolvers < BaseValidator
 
       def perform(supergraph, composer)
         supergraph.schema.types.each do |type_name, type|
@@ -15,9 +15,9 @@ module GraphQL::Stitching
           candidate_types_by_location = composer.candidate_types_by_name_and_location[type_name]
           next unless candidate_types_by_location.length > 1
 
-          boundaries = supergraph.boundaries[type_name]
-          if boundaries&.any?
-            validate_as_boundary(supergraph, type, candidate_types_by_location, boundaries)
+          resolvers = supergraph.resolvers[type_name]
+          if resolvers&.any?
+            validate_as_resolver(supergraph, type, candidate_types_by_location, resolvers)
           elsif type.kind.object?
             validate_as_shared(supergraph, type, candidate_types_by_location)
           end
@@ -26,48 +26,48 @@ module GraphQL::Stitching
 
       private
 
-      def validate_as_boundary(supergraph, type, candidate_types_by_location, boundaries)
-        # abstract boundaries are expanded with their concrete implementations, which each get validated. Ignore the abstract itself.
+      def validate_as_resolver(supergraph, type, candidate_types_by_location, resolvers)
+        # abstract resolvers are expanded with their concrete implementations, which each get validated. Ignore the abstract itself.
         return if type.kind.abstract?
 
-        # only one boundary allowed per type/location/key
-        boundaries_by_location_and_key = boundaries.each_with_object({}) do |boundary, memo|
-          if memo.dig(boundary.location, boundary.key)
-            raise Composer::ValidationError, "Multiple boundary queries for `#{type.graphql_name}.#{boundary.key}` "\
-              "found in #{boundary.location}. Limit one boundary query per type and key in each location. "\
-              "Abstract boundaries provide all possible types."
+        # only one resolver allowed per type/location/key
+        resolvers_by_location_and_key = resolvers.each_with_object({}) do |resolver, memo|
+          if memo.dig(resolver.location, resolver.key)
+            raise Composer::ValidationError, "Multiple resolver queries for `#{type.graphql_name}.#{resolver.key}` "\
+              "found in #{resolver.location}. Limit one resolver query per type and key in each location. "\
+              "Abstract resolvers provide all possible types."
           end
-          memo[boundary.location] ||= {}
-          memo[boundary.location][boundary.key] = boundary
+          memo[resolver.location] ||= {}
+          memo[resolver.location][resolver.key] = resolver
         end
 
-        boundary_keys = boundaries.map(&:key).to_set
+        resolver_keys = resolvers.map(&:key).to_set
 
-        # All non-key fields must be resolvable in at least one boundary location
+        # All non-key fields must be resolvable in at least one resolver location
         supergraph.locations_by_type_and_field[type.graphql_name].each do |field_name, locations|
-          next if boundary_keys.include?(field_name)
+          next if resolver_keys.include?(field_name)
 
-          if locations.none? { boundaries_by_location_and_key[_1] }
+          if locations.none? { resolvers_by_location_and_key[_1] }
             where = locations.length > 1 ? "one of #{locations.join(", ")} locations" : locations.first
-            raise Composer::ValidationError, "A boundary query is required for `#{type.graphql_name}` in #{where} to resolve field `#{field_name}`."
+            raise Composer::ValidationError, "A resolver query is required for `#{type.graphql_name}` in #{where} to resolve field `#{field_name}`."
           end
         end
 
-        # All locations of a boundary type must include at least one key field
+        # All locations of a resolver type must include at least one key field
         supergraph.fields_by_type_and_location[type.graphql_name].each do |location, field_names|
-          if field_names.none? { boundary_keys.include?(_1) }
-            raise Composer::ValidationError, "A boundary key is required for `#{type.graphql_name}` in #{location} to join with other locations."
+          if field_names.none? { resolver_keys.include?(_1) }
+            raise Composer::ValidationError, "A resolver key is required for `#{type.graphql_name}` in #{location} to join with other locations."
           end
         end
 
         # verify that all outbound locations can access all inbound locations
-        resolver_locations = boundaries_by_location_and_key.keys
+        resolver_locations = resolvers_by_location_and_key.keys
         candidate_types_by_location.each_key do |location|
           remote_locations = resolver_locations.reject { _1 == location }
           paths = supergraph.route_type_to_locations(type.graphql_name, location, remote_locations)
           if paths.length != remote_locations.length || paths.any? { |_loc, path| path.nil? }
-            raise Composer::ValidationError, "Cannot route `#{type.graphql_name}` boundaries in #{location} to all other locations. "\
-              "All locations must provide a boundary accessor that uses a conjoining key."
+            raise Composer::ValidationError, "Cannot route `#{type.graphql_name}` resolvers in #{location} to all other locations. "\
+              "All locations must provide a resolver query with a joining key."
           end
         end
       end
@@ -87,7 +87,7 @@ module GraphQL::Stitching
         candidate_types_by_location.each do |location, candidate_type|
           if candidate_type.fields.keys.sort != expected_fields
             raise Composer::ValidationError, "Shared type `#{type.graphql_name}` must have consistent fields across locations, "\
-              "or else define boundary queries so that its unique fields may be accessed remotely."
+              "or else define resolver queries so that its unique fields may be accessed remotely."
           end
         end
       end

data/lib/graphql/stitching/composer.rb

@@ -2,8 +2,8 @@
 
 require_relative "./composer/base_validator"
 require_relative "./composer/validate_interfaces"
-require_relative "./composer/validate_boundaries"
-require_relative "./composer/boundary_config"
+require_relative "./composer/validate_resolvers"
+require_relative "./composer/resolver_config"
 
 module GraphQL
   module Stitching
@@ -31,7 +31,7 @@ module GraphQL
       # @api private
       VALIDATORS = [
         "ValidateInterfaces",
-        "ValidateBoundaries",
+        "ValidateResolvers",
       ].freeze
 
       # @return [String] name of the Query type in the composed schema.
@@ -62,10 +62,10 @@ module GraphQL
         @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
-        @boundary_configs = {}
+        @resolver_configs = {}
 
         @field_map = nil
-        @boundary_map = nil
+        @resolver_map = nil
         @mapped_type_names = nil
         @candidate_directives_by_name_and_location = nil
         @candidate_types_by_name_and_location = nil
@@ -125,7 +125,7 @@ module GraphQL
             raise ComposerError, "Cannot merge different kinds for `#{type_name}`. Found: #{kinds.join(", ")}."
           end
 
-          extract_boundaries(type_name, types_by_location) if type_name == @query_name
+          extract_resolvers(type_name, types_by_location) if type_name == @query_name
 
           memo[type_name] = case kinds.first
           when "SCALAR"
@@ -157,12 +157,12 @@ module GraphQL
         end
 
         select_root_field_locations(schema)
-        expand_abstract_boundaries(schema)
+        expand_abstract_resolvers(schema)
 
         supergraph = Supergraph.new(
           schema: schema,
           fields: @field_map,
-          boundaries: @boundary_map,
+          resolvers: @resolver_map,
           executables: executables,
         )
 
@@ -189,8 +189,8 @@ module GraphQL
             raise ComposerError, "The schema for `#{location}` location must be a GraphQL::Schema class."
           end
 
-          @boundary_configs.merge!(BoundaryConfig.extract_directive_assignments(schema, location, input[:stitch]))
-          @boundary_configs.merge!(BoundaryConfig.extract_federation_entities(schema, location))
+          @resolver_configs.merge!(ResolverConfig.extract_directive_assignments(schema, location, input[:stitch]))
+          @resolver_configs.merge!(ResolverConfig.extract_federation_entities(schema, location))
 
           schemas[location.to_s] = schema
           executables[location.to_s] = input[:executable] || schema
@@ -527,63 +527,64 @@ module GraphQL
 
       # @!scope class
       # @!visibility private
-      def extract_boundaries(type_name, types_by_location)
+      def extract_resolvers(type_name, types_by_location)
         types_by_location.each do |location, type_candidate|
           type_candidate.fields.each do |field_name, field_candidate|
-            boundary_type = field_candidate.type.unwrap
-            boundary_structure = Util.flatten_type_structure(field_candidate.type)
-            boundary_configs = @boundary_configs.fetch("#{location}.#{field_name}",  [])
+            resolver_type = field_candidate.type.unwrap
+            resolver_structure = Util.flatten_type_structure(field_candidate.type)
+            resolver_configs = @resolver_configs.fetch("#{location}.#{field_name}",  [])
 
             field_candidate.directives.each do |directive|
               next unless directive.graphql_name == GraphQL::Stitching.stitch_directive
-              boundary_configs << BoundaryConfig.from_kwargs(directive.arguments.keyword_arguments)
+              resolver_configs << ResolverConfig.from_kwargs(directive.arguments.keyword_arguments)
             end
 
-            boundary_configs.each do |config|
+            resolver_configs.each do |config|
               key_selections = GraphQL.parse("{ #{config.key} }").definitions[0].selections
 
               if key_selections.length != 1
-                raise ComposerError, "Boundary key at #{type_name}.#{field_name} must specify exactly one key."
+                raise ComposerError, "Resolver key at #{type_name}.#{field_name} must specify exactly one key."
               end
 
-              argument_name = key_selections[0].alias
-              argument_name ||= if field_candidate.arguments.size == 1
-                field_candidate.arguments.keys.first
-              elsif field_candidate.arguments[config.key]
-                config.key
+              argument = field_candidate.arguments[key_selections[0].alias]
+              argument ||= if field_candidate.arguments.size == 1
+                field_candidate.arguments.values.first
+              else
+                field_candidate.arguments[config.key]
               end
 
-              argument = field_candidate.arguments[argument_name]
               unless argument
-                # contextualize this... "boundaries with multiple args need mapping aliases."
-                raise ComposerError, "Invalid boundary argument `#{argument_name}` for #{type_name}.#{field_name}."
+                raise ComposerError, "No resolver argument matched for #{type_name}.#{field_name}. " \
+                  "Add an alias to the key that specifies its intended argument, ex: `arg:key`"
               end
 
               argument_structure = Util.flatten_type_structure(argument.type)
-              if argument_structure.length != boundary_structure.length
-                raise ComposerError, "Mismatched input/output for #{type_name}.#{field_name}.#{argument_name} boundary. Arguments must map directly to results."
+              if argument_structure.length != resolver_structure.length
+                raise ComposerError, "Mismatched input/output for #{type_name}.#{field_name}.#{argument.graphql_name} resolver. " \
+                  "Arguments must map directly to results."
               end
 
-              boundary_type_name = if config.type_name
-                if !boundary_type.kind.abstract?
+              resolver_type_name = if config.type_name
+                if !resolver_type.kind.abstract?
                   raise ComposerError, "Resolver config may only specify a type name for abstract resolvers."
-                elsif !boundary_type.possible_types.find { _1.graphql_name == config.type_name }
+                elsif !resolver_type.possible_types.find { _1.graphql_name == config.type_name }
                   raise ComposerError, "Type `#{config.type_name}` is not a possible return type for query `#{field_name}`."
                 end
                 config.type_name
               else
-                boundary_type.graphql_name
+                resolver_type.graphql_name
               end
 
-              @boundary_map[boundary_type_name] ||= []
-              @boundary_map[boundary_type_name] << Boundary.new(
+              @resolver_map[resolver_type_name] ||= []
+              @resolver_map[resolver_type_name] << Resolver.new(
                 location: location,
-                type_name: boundary_type_name,
+                type_name: resolver_type_name,
                 key: key_selections[0].name,
                 field: field_candidate.name,
-                arg: argument_name,
-                list: boundary_structure.first.list?,
-                federation: config.federation,
+                arg: argument.graphql_name,
+                arg_type_name: argument.type.unwrap.graphql_name,
+                list: resolver_structure.first.list?,
+                representations: config.representations,
               )
             end
           end
@@ -612,15 +613,15 @@ module GraphQL
 
       # @!scope class
       # @!visibility private
-      def expand_abstract_boundaries(schema)
-        @boundary_map.keys.each do |type_name|
-          boundary_type = schema.types[type_name]
-          next unless boundary_type.kind.abstract?
+      def expand_abstract_resolvers(schema)
+        @resolver_map.keys.each do |type_name|
+          resolver_type = schema.types[type_name]
+          next unless resolver_type.kind.abstract?
 
-          expanded_types = Util.expand_abstract_type(schema, boundary_type)
+          expanded_types = Util.expand_abstract_type(schema, resolver_type)
           expanded_types.select { @candidate_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])
+            @resolver_map[expanded_type.graphql_name] ||= []
+            @resolver_map[expanded_type.graphql_name].push(*@resolver_map[type_name])
           end
         end
       end
@@ -670,7 +671,7 @@ module GraphQL
 
       def reset!
         @field_map = {}
-        @boundary_map = {}
+        @resolver_map = {}
         @mapped_type_names = {}
         @candidate_directives_by_name_and_location = nil
         @schema_directives = nil

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.5"
+    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.5
+  version: 1.3.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-31 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

data/lib/graphql/stitching/boundary.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module GraphQL
-  module Stitching
-    # Defines a boundary query that provides direct access to an entity type.
-    Boundary = Struct.new(
-      :location,
-      :type_name,
-      :key,
-      :field,
-      :arg,
-      :list,
-      :federation,
-      keyword_init: true
-    ) do
-      def as_json
-        {
-          location: location,
-          type_name: type_name,
-          key: key,
-          field: field,
-          arg: arg,
-          list: list,
-          federation: federation,
-        }.tap(&:compact!)
-      end
-    end
-  end
-end