graphql-stitching 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33a2615122207bdf93a7df873fe1efe7a7f3c13050f59dabc6e85becd75cf96e
-  data.tar.gz: 9f203624ab5c26a3cb6ab4710759ef7cb76c1890fff8f4849ab31404875fe79a
+  metadata.gz: b07a54288795f5b321029340a61e97dd9209d395712dc9ac5921ebd5c52523a1
+  data.tar.gz: 83e4dea46c7b4ff7a3716c2936773893df58e732a50c36ee1a5af8e4e5cab4bd
 SHA512:
-  metadata.gz: ad1afa71d6525ea79857106eca6c347f77fab8141dd9a504f3da1a6631f598fe7fb154bc446e228e420fa46dff993140ff568fc3dc94af7a76f0cf29da550896
-  data.tar.gz: 2632af6a1347f1fb6513c79781c3959aacdd879583519cb31e69834a48f2ae70cafdb778d6915713d0d19bf535a67cac55763377cc27da0795b80ed6abc298d4
+  metadata.gz: 831a54675315529b6bc1d489296a15325f88bcccbbb8f480c786641410de853989425591f4e60a6249ef123a3aa9e204780388925f2a027d758ac5594ca6c306
+  data.tar.gz: f66ab6dfc996aa9982f6c5d09e2bf98b5a5de8b85220ea839f854e53edd3f55144404b5ddff91f2681f7d8fee21071bb54f20265951424840c527b7203dd9ace

data/README.md

@@ -5,7 +5,7 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 ![Stitched graph](./docs/images/stitching.png)
 
 **Supports:**
-- Merged object and interface types.
+- Merged object and abstract types.
 - Multiple keys per merged type.
 - Shared objects, fields, enums, and inputs across locations.
 - Combining local and remote schemas.
@@ -70,9 +70,9 @@ result = gateway.execute(
 )
 ```
 
-Schemas provided to the `Gateway` constructor may be class-based schemas with local resolvers (locally-executable schemas), or schemas built from SDL strings (schema definition language parsed using `GraphQL::Schema.from_definition`) and mapped to remote locations. See [composer docs](./docs/composer.md#merge-patterns) for more information on how schemas get merged.
+Schemas provided in [location settings](./docs/composer.md#performing-composition) may be class-based schemas with local resolvers (locally-executable schemas), or schemas built from SDL strings (schema definition language parsed using `GraphQL::Schema.from_definition`) and mapped to remote locations. See [composer docs](./docs/composer.md#merge-patterns) for more information on how schemas get merged.
 
-While the [`Gateway`](./docs/gateway.md) constructor is an easy quick start, the library also has several discrete components that can be assembled into custom workflows:
+While the `Gateway` constructor is an easy quick start, the library also has several discrete components that can be assembled into custom workflows:
 
 - [Composer](./docs/composer.md) - merges and validates many schemas into one supergraph.
 - [Supergraph](./docs/supergraph.md) - manages the combined schema, location routing maps, and executable resources. Can be exported, cached, and rehydrated.
@@ -148,7 +148,7 @@ type Query {
 * The `@stitch` directive is applied to a root query where the merged type may be accessed. The merged type identity is inferred from the field return.
 * The `key: "id"` parameter indicates that an `{ id }` must be selected from prior locations so it may be submitted as an argument to this query. The query argument used to send the key is inferred when possible (more on arguments later).
 
-Each location that provides a unique variant of a type must provide _exactly one_ stitching query per possible key (more on multiple keys later). The exception to this requirement are types that contain only a single key field:
+Each location that provides a unique variant of a type must provide one stitching query per key. The exception to this requirement are types that contain only a single key field:
 
 ```graphql
 type Product {
@@ -166,8 +166,13 @@ It's okay ([even preferable](https://www.youtube.com/watch?v=VmK0KBHTcWs) in man
 type Query {
   products(ids: [ID!]!): [Product]! @stitch(key: "id")
 }
+
+# input:  ["1", "2", "3"]
+# result: [{ id: "1" }, null, { id: "3" }]
 ```
 
+See [error handling](./docs/mechanics.md#stitched-errors) tips for list queries.
+
 #### Abstract queries
 
 It's okay for stitching queries to be implemented through abstract types. An abstract query will provide access to all of its possible types. For interfaces, the key selection should match a field within the interface. For unions, all possible types must implement the key selection individually.
@@ -334,6 +339,13 @@ The `GraphQL::Stitching::RemoteClient` class is provided as a simple executable
 
 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.
 
+## Additional topics
+
+- [Field selection routing](./docs/mechanics.md#field-selection-routing)
+- [Root selection routing](./docs/mechanics.md#root-selection-routing)
+- [Stitched errors](./docs/mechanics.md#stitched-errors)
+- [Null results](./docs/mechanics.md#null-results)
+
 ## Example
 
 This repo includes a working example of several stitched schemas running across small Rack servers. Try running it:

data/docs/README.md

@@ -12,3 +12,7 @@ Major components include:
 - [Request](./request.md) - prepares a requested GraphQL document and variables for stitching.
 - [Planner](./planner.md) - builds a cacheable query plan for a request document.
 - [Executor](./executor.md) - executes a query plan with given request variables.
+
+Additional topics:
+
+- [Stitching mechanics](./mechanics.md) - learn more about building for stitching.

data/docs/composer.md

@@ -13,6 +13,7 @@ composer = GraphQL::Stitching::Composer.new(
   description_merger: ->(values_by_location, info) { values_by_location.values.join("\n") },
   deprecation_merger: ->(values_by_location, info) { values_by_location.values.first },
   directive_kwarg_merger: ->(values_by_location, info) { values_by_location.values.last },
+  root_field_location_selector: ->(locations, info) { locations.last },
 )
 ```
 
@@ -28,12 +29,14 @@ Constructor arguments:
 
 - **`directive_kwarg_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging directive keyword arguments from across locations.
 
+- **`root_field_location_selector:`** _optional_, selects a default routing location for root fields with multiple locations. Use this to prioritize sending root fields to their primary data sources (only applies while routing the root operation scope). This handler receives an array of possible locations and an info object with field information, and should return the prioritized location. The last location is used by default.
+
 #### Value merger functions
 
 Static data values such as element descriptions and directive arguments must also merge across locations. By default, the first non-null value encountered for a given element attribute is used. A value merger function may customize this process by selecting a different value or computing a new one:
 
 ```ruby
-supergraph = GraphQL::Stitching::Composer.new(
+composer = GraphQL::Stitching::Composer.new(
   description_merger: ->(values_by_location, info) { values_by_location.values.compact.join("\n") },
 )
 ```

data/docs/mechanics.md

@@ -0,0 +1,209 @@
+## Schema Stitching, mechanics
+
+### Field selection routing
+
+Fields of a merged type may exist in multiple locations. For example, the `title` field below is provided by both locations:
+
+```graphql
+# -- Location A
+
+type Movie {
+  id: String!
+  title: String! # shared
+  rating: Int!
+}
+
+type Query {
+  movieA(id: ID!): Movie @stitch(key: "id")
+}
+
+# -- Location B
+
+type Movie {
+  id: String!
+  title: String! # shared
+  reviews: [String!]!
+}
+
+type Query {
+  movieB(id: ID!): Movie @stitch(key: "id")
+}
+```
+
+When planning a request, field selections always attempt to use the current routing location that originates from the selection root, for example:
+
+```graphql
+query GetTitleFromA {
+  movieA(id: "23") { # <- enter via Location A
+    title            # <- source from Location A
+  }
+}
+
+query GetTitleFromB {
+  movieB(id: "23") { # <- enter via Location B
+    title            # <- source from Location B
+  }
+}
+```
+
+Field selections that are NOT available in the current routing location delegate to new locations as follows:
+
+1. Fields with only one location automatically use that location.
+2. Fields with multiple locations attempt to use a location added during step-1.
+3. Any remaining fields pick a location based on their highest availability among locations.
+
+### Root selection routing
+
+Root fields should route to the primary locations of their provided types. This assures that the most common data for a type can be resolved via root access and thus avoid unnecessary stitching. Root fields can select their primary locations using the `root_field_location_selector` option in [composer configuration](./composer.md#configuring-composition):
+
+```ruby
+supergraph = GraphQL::Stitching::Composer.new(
+  root_field_location_selector: ->(locations) { locations.find { _1 == "a" } || locations.last },
+).perform({ ... })
+```
+
+It's okay if root field names are repeated across locations. The primary location will be used when routing root selections:
+
+```graphql
+# -- Location A
+
+type Movie {
+  id: String!
+  rating: Int!
+}
+
+type Query {
+  movie(id: ID!): Movie @stitch(key: "id") # shared, primary
+}
+
+# -- Location B
+
+type Movie {
+  id: String!
+  reviews: [String!]!
+}
+
+type Query {
+  movie(id: ID!): Movie @stitch(key: "id") # shared
+}
+
+# -- Request
+
+query {
+  movie(id: "23") { id } # routes to Location A
+}
+```
+
+Note that primary location routing _only_ applies to selections in the root scope. If the `Query` type appears again lower in the graph, then its fields are resolved as normal object fields outside of root context, for example:
+
+```graphql
+schema {
+  query: Query # << root query, uses primary locations
+}
+
+type Query {
+  subquery: Query # << subquery, acts as a normal object type
+}
+```
+
+Also note that stitching queries (denoted by the `@stitch` directive) are completely separate from field routing concerns. A `@stitch` directive establishes a contract for resolving a given type in a given location. This contract is always used to collect stitching data, regardless of how request routing selected the location for use.
+
+### Stitched errors
+
+Any [spec GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) returned by a stitching query will flow through the request. Stitching has two strategies for passing errors through to the final result:
+
+1. **Direct passthrough**, where subgraph errors are returned directly without modification. This strategy is used for errors without a `path` (ie: "base" errors), and errors pathed to root fields.
+
+2. **Mapped passthrough**, where the `path` attribute of a subgraph error is remapped to an insertion point in the stitched request. This strategy is used when merging stitching queries into the composed result.
+
+In either strategy, it's important that subgraphs provide properly pathed errors (GraphQL Ruby [can do this automatically](https://graphql-ruby.org/errors/overview.html)). For example:
+
+```json
+{
+  "data": { "shop": { "product": null } },
+  "errors": [{
+    "message": "Record not found.",
+    "path": ["shop", "product"]
+  }]
+}
+```
+
+When resolving [stitching list queries](../README.md#list-queries), it's important to only error out specific array positions rather than the entire array result, for example:
+
+```ruby
+def products
+  [
+    { id: "1" },
+    GraphQL::ExecutionError.new("Not found"),
+    { id: "3" },
+  ]
+end
+```
+
+Stitching expects list queries to pad their missing elements with null, and to report corresponding errors pathed down to list position:
+
+```json
+{
+  "data": {
+    "products": [{ "id": "1" }, null, { "id": "3" }]
+  },
+  "errors": [{
+    "message": "Record not found.",
+    "path": ["products", 1]
+  }]
+}
+```
+
+### Null results
+
+It's okay for a stitching query to return `null` for a merged type as long as all unique fields of the type allow null. For example, the following merge works:
+
+```graphql
+# -- Request
+
+query {
+  movieA(id: "23") {
+    id
+    title
+    rating
+  }
+}
+
+# -- Location A
+
+type Movie {
+  id: String!
+  title: String!
+}
+
+type Query {
+  movieA(id: ID!): Movie @stitch(key: "id")
+      # (id: "23") -> { id: "23", title: "Jurassic Park" }
+}
+
+# -- Location B
+
+type Movie {
+  id: String!
+  rating: Int
+}
+
+type Query {
+  movieB(id: ID!): Movie @stitch(key: "id")
+      # (id: "23") -> null
+}
+```
+
+And produces this result:
+
+```json
+{
+  "data": {
+    "id": "23",
+    "title": "Jurassic Park",
+    "rating": null
+  }
+}
+```
+
+Location B is allowed to return `null` here because its one unique field, `rating`, is nullable (the `id` field can be provided by Location A). If `rating` were non-null, then null bubbling would invalidate the response data.

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

@@ -12,21 +12,21 @@ module GraphQL
           next if type.graphql_name.start_with?("__")
 
           # multiple subschemas implement the type
-          subschema_types_by_location = composer.subschema_types_by_name_and_location[type_name]
-          next unless subschema_types_by_location.length > 1
+          candidate_types_by_location = composer.candidate_types_by_name_and_location[type_name]
+          next unless candidate_types_by_location.length > 1
 
           boundaries = ctx.boundaries[type_name]
           if boundaries&.any?
-            validate_as_boundary(ctx, type, subschema_types_by_location, boundaries)
+            validate_as_boundary(ctx, type, candidate_types_by_location, boundaries)
           elsif type.kind.object?
-            validate_as_shared(ctx, type, subschema_types_by_location)
+            validate_as_shared(ctx, type, candidate_types_by_location)
           end
         end
       end
 
       private
 
-      def validate_as_boundary(ctx, type, subschema_types_by_location, boundaries)
+      def validate_as_boundary(ctx, type, candidate_types_by_location, boundaries)
         # abstract boundaries are expanded with their concrete implementations, which each get validated. Ignore the abstract itself.
         return if type.kind.abstract?
 
@@ -42,19 +42,19 @@ module GraphQL
         end
 
         boundary_keys = boundaries.map { _1["selection"] }.uniq
-        key_only_types_by_location = subschema_types_by_location.select do |location, subschema_type|
+        key_only_types_by_location = candidate_types_by_location.select do |location, subschema_type|
           subschema_type.fields.keys.length == 1 && boundary_keys.include?(subschema_type.fields.keys.first)
         end
 
         # all locations have a boundary, or else are key-only
-        subschema_types_by_location.each do |location, subschema_type|
+        candidate_types_by_location.each do |location, subschema_type|
           unless boundaries_by_location_and_key[location] || key_only_types_by_location[location]
             raise Composer::ValidationError, "A boundary query is required for `#{type.graphql_name}` in #{location} because it provides unique fields."
           end
         end
 
         outbound_access_locations = key_only_types_by_location.keys
-        bidirectional_access_locations = subschema_types_by_location.keys - outbound_access_locations
+        bidirectional_access_locations = candidate_types_by_location.keys - outbound_access_locations
 
         # verify that all outbound locations can access all inbound locations
         (outbound_access_locations + bidirectional_access_locations).each do |location|
@@ -67,7 +67,7 @@ module GraphQL
         end
       end
 
-      def validate_as_shared(ctx, type, subschema_types_by_location)
+      def validate_as_shared(ctx, type, candidate_types_by_location)
         expected_fields = begin
           type.fields.keys.sort
         rescue StandardError => e
@@ -79,7 +79,7 @@ module GraphQL
           end
         end
 
-        subschema_types_by_location.each do |location, subschema_type|
+        candidate_types_by_location.each do |location, subschema_type|
           if subschema_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."

data/lib/graphql/stitching/composer.rb

@@ -6,9 +6,10 @@ module GraphQL
       class ComposerError < StitchingError; end
       class ValidationError < ComposerError; end
 
-      attr_reader :query_name, :mutation_name, :subschema_types_by_name_and_location, :schema_directives
+      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 }
 
       VALIDATORS = [
         "ValidateInterfaces",
@@ -20,13 +21,15 @@ module GraphQL
         mutation_name: "Mutation",
         description_merger: nil,
         deprecation_merger: nil,
-        directive_kwarg_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
       end
 
       def perform(locations_input)
@@ -34,7 +37,7 @@ module GraphQL
         schemas, executables = prepare_locations_input(locations_input)
 
         # "directive_name" => "location" => candidate_directive
-        @subschema_directives_by_name_and_location = schemas.each_with_object({}) do |(location, schema), memo|
+        @candidate_directives_by_name_and_location = schemas.each_with_object({}) do |(location, schema), memo|
           (schema.directives.keys - schema.default_directives.keys - GraphQL::Stitching.stitching_directive_names).each do |directive_name|
             memo[directive_name] ||= {}
             memo[directive_name][location] = schema.directives[directive_name]
@@ -42,14 +45,14 @@ module GraphQL
         end
 
         # "Typename" => merged_directive
-        @schema_directives = @subschema_directives_by_name_and_location.each_with_object({}) do |(directive_name, directives_by_location), memo|
+        @schema_directives = @candidate_directives_by_name_and_location.each_with_object({}) do |(directive_name, directives_by_location), memo|
           memo[directive_name] = build_directive(directive_name, directives_by_location)
         end
 
         @schema_directives.merge!(GraphQL::Schema.default_directives)
 
         # "Typename" => "location" => candidate_type
-        @subschema_types_by_name_and_location = schemas.each_with_object({}) do |(location, schema), memo|
+        @candidate_types_by_name_and_location = schemas.each_with_object({}) do |(location, schema), memo|
           raise ComposerError, "Location keys must be strings" unless location.is_a?(String)
           raise ComposerError, "The subscription operation is not supported." if schema.subscription
 
@@ -74,7 +77,7 @@ module GraphQL
         enum_usage = build_enum_usage_map(schemas.values)
 
         # "Typename" => merged_type
-        schema_types = @subschema_types_by_name_and_location.each_with_object({}) do |(type_name, types_by_location), memo|
+        schema_types = @candidate_types_by_name_and_location.each_with_object({}) do |(type_name, types_by_location), memo|
           kinds = types_by_location.values.map { _1.kind.name }.uniq
 
           if kinds.length > 1
@@ -110,6 +113,7 @@ module GraphQL
           own_orphan_types.clear
         end
 
+        select_root_field_locations(schema)
         expand_abstract_boundaries(schema)
 
         supergraph = Supergraph.new(
@@ -498,13 +502,31 @@ module GraphQL
         end
       end
 
+      def select_root_field_locations(schema)
+        [schema.query, schema.mutation].tap(&:compact!).each do |root_type|
+          root_type.fields.each do |root_field_name, root_field|
+            root_field_locations = @field_map[root_type.graphql_name][root_field_name]
+            next unless root_field_locations.length > 1
+
+            target_location = @root_field_location_selector.call(root_field_locations, {
+              type_name: root_type.graphql_name,
+              field_name: root_field_name,
+            })
+            next unless root_field_locations.include?(target_location)
+
+            root_field_locations.reject! { _1 == target_location }
+            root_field_locations.unshift(target_location)
+          end
+        end
+      end
+
       def expand_abstract_boundaries(schema)
         @boundary_map.keys.each do |type_name|
           boundary_type = schema.types[type_name]
           next unless boundary_type.kind.abstract?
 
           expanded_types = Util.expand_abstract_type(schema, boundary_type)
-          expanded_types.select { @subschema_types_by_name_and_location[_1.graphql_name].length > 1 }.each do |expanded_type|
+          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])
           end
@@ -555,7 +577,7 @@ module GraphQL
         @field_map = {}
         @boundary_map = {}
         @mapped_type_names = {}
-        @subschema_directives_by_name_and_location = nil
+        @candidate_directives_by_name_and_location = nil
         @schema_directives = nil
       end
     end

data/lib/graphql/stitching/executor.rb

@@ -58,9 +58,7 @@ module GraphQL
         def fetch(ops)
           origin_sets_by_operation = ops.each_with_object({}) do |op, memo|
             origin_set = op["insertion_path"].reduce([@executor.data]) do |set, path_segment|
-              mapped = set.flat_map { |obj| obj && obj[path_segment] }
-              mapped.compact!
-              mapped
+              set.flat_map { |obj| obj && obj[path_segment] }.tap(&:compact!)
             end
 
             if op["type_condition"]

data/lib/graphql/stitching/gateway.rb

@@ -35,25 +35,25 @@ module GraphQL
           return error_result(validation_errors) if validation_errors.any?
         end
 
-        begin
-          request.prepare!
+        request.prepare!
 
-          plan = fetch_plan(request) do
-            GraphQL::Stitching::Planner.new(
-              supergraph: @supergraph,
-              request: request,
-            ).perform.to_h
-          end
-
-          GraphQL::Stitching::Executor.new(
+        plan = fetch_plan(request) do
+          GraphQL::Stitching::Planner.new(
             supergraph: @supergraph,
             request: request,
-            plan: plan,
-          ).perform
-        rescue StandardError => e
-          custom_message = @on_error.call(e, request.context) if @on_error
-          error_result([{ "message" => custom_message || "An unexpected error occured." }])
+          ).perform.to_h
         end
+
+        GraphQL::Stitching::Executor.new(
+          supergraph: @supergraph,
+          request: request,
+          plan: plan,
+        ).perform
+      rescue GraphQL::ParseError, GraphQL::ExecutionError => e
+        error_result([e])
+      rescue StandardError => e
+        custom_message = @on_error.call(e, request.context) if @on_error
+        error_result([{ "message" => custom_message || "An unexpected error occured." }])
       end
 
       def on_cache_read(&block)
@@ -89,10 +89,8 @@ module GraphQL
       end
 
       def error_result(errors)
-        public_errors = errors.map do |e|
-          public_error = e.is_a?(Hash) ? e : e.to_h
-          public_error["path"] ||= []
-          public_error
+        public_errors = errors.map! do |e|
+          e.is_a?(Hash) ? e : e.to_h
         end
 
         { "errors" => public_errors }

data/lib/graphql/stitching/planner.rb

@@ -39,10 +39,8 @@ module GraphQL
 
           selections_by_location = @request.operation.selections.each_with_object({}) do |node, memo|
             locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name] || SUPERGRAPH_LOCATIONS
-
-            # root fields currently just delegate to the last location that defined them; this should probably be smarter
-            memo[locations.last] ||= []
-            memo[locations.last] << node
+            memo[locations.first] ||= []
+            memo[locations.first] << node
           end
 
           selections_by_location.each do |location, selections|
@@ -53,8 +51,7 @@ module GraphQL
           parent_type = @supergraph.schema.mutation
 
           location_groups = @request.operation.selections.each_with_object([]) do |node, memo|
-            # root fields currently just delegate to the last location that defined them; this should probably be smarter
-            next_location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].last
+            next_location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].first
 
             if memo.none? || memo.last[:location] != next_location
               memo << { location: next_location, selections: [] }
@@ -219,7 +216,7 @@ module GraphQL
         possible_locations_by_field = @supergraph.locations_by_type_and_field[parent_type.graphql_name]
         selections_by_location = {}
 
-        # distribute unique fields among required locations
+        # 1. distribute unique fields among required locations
         remote_selections.reject! do |node|
           possible_locations = possible_locations_by_field[node.name]
           if possible_locations.length == 1
@@ -229,13 +226,22 @@ module GraphQL
           end
         end
 
-        # distribute non-unique fields among available locations, preferring locations already used
+        # 2. distribute non-unique fields among locations that are already used
+        if selections_by_location.any? && remote_selections.any?
+          remote_selections.reject! do |node|
+            used_location = possible_locations_by_field[node.name].find { selections_by_location[_1] }
+            if used_location
+              selections_by_location[used_location] << node
+              true
+            end
+          end
+        end
+
+        # 3. distribute remaining fields among locations weighted by greatest availability
         if remote_selections.any?
-          # weight locations by number of required fields available, preferring greater availability
-          location_weights = if remote_selections.length > 1
+          field_count_by_location = if remote_selections.length > 1
             remote_selections.each_with_object({}) do |node, memo|
-              possible_locations = possible_locations_by_field[node.name]
-              possible_locations.each do |location|
+              possible_locations_by_field[node.name].each do |location|
                 memo[location] ||= 0
                 memo[location] += 1
               end
@@ -246,18 +252,16 @@ module GraphQL
 
           remote_selections.each do |node|
             possible_locations = possible_locations_by_field[node.name]
-            preferred_location_score = 0
+            preferred_location = possible_locations.first
 
-            # hill-climb to select highest scoring location for each field
-            preferred_location = possible_locations.reduce(possible_locations.first) do |best_location, possible_location|
-              score = selections_by_location[possible_location] ? remote_selections.length : 0
-              score += location_weights.fetch(possible_location, 0)
+            possible_locations.reduce(0) do |max_availability, possible_location|
+              available_fields = field_count_by_location.fetch(possible_location, 0)
 
-              if score > preferred_location_score
-                preferred_location_score = score
-                possible_location
+              if available_fields > max_availability
+                preferred_location = possible_location
+                available_fields
               else
-                best_location
+                max_availability
               end
             end
 
@@ -272,10 +276,8 @@ module GraphQL
         routes.values.each_with_object({}) do |route, ops_by_location|
           route.reduce(nil) do |parent_op, boundary|
             location = boundary["location"]
-            new_operation = false
 
             unless op = ops_by_location[location]
-              new_operation = true
               op = ops_by_location[location] = add_operation(
                 location: location,
                 # routing locations added as intermediaries have no initial selections,
@@ -291,7 +293,7 @@ module GraphQL
             foreign_key = "_STITCH_#{boundary["selection"]}"
             parent_selections = parent_op ? parent_op.selections : locale_selections
 
-            if new_operation || parent_selections.none? { _1.is_a?(GraphQL::Language::Nodes::Field) && _1.alias == foreign_key }
+            if parent_selections.none? { _1.is_a?(GraphQL::Language::Nodes::Field) && _1.alias == foreign_key }
               foreign_key_node = GraphQL::Language::Nodes::Field.new(alias: foreign_key, name: boundary["selection"])
               parent_selections << foreign_key_node << TYPENAME_NODE
             end

data/lib/graphql/stitching/request.rb

@@ -87,7 +87,7 @@ module GraphQL
           end
 
           if operation_defs.length < 1
-            raise GraphQL::ExecutionError, "Invalid root operation."
+            raise GraphQL::ExecutionError, "Invalid root operation for given name and operation type."
           elsif operation_defs.length > 1
             raise GraphQL::ExecutionError, "An operation name is required when sending multiple operations."
           end

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "0.3.2"
+    VERSION = "0.3.3"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-09 00:00:00.000000000 Z
+date: 2023-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -86,6 +86,7 @@ files:
 - docs/images/library.png
 - docs/images/merging.png
 - docs/images/stitching.png
+- docs/mechanics.md
 - docs/planner.md
 - docs/request.md
 - docs/supergraph.md