graphql-stitching 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10489fd6a8670d5a23a7afa132d7941a242848783f3697a4d3ddd519b208a4d8
-  data.tar.gz: 7a2e8dda124bdc6e96da43e1a4ed64bbb4baeaf0065f6d8411edaeba2c52e064
+  metadata.gz: b07a54288795f5b321029340a61e97dd9209d395712dc9ac5921ebd5c52523a1
+  data.tar.gz: 83e4dea46c7b4ff7a3716c2936773893df58e732a50c36ee1a5af8e4e5cab4bd
 SHA512:
-  metadata.gz: 4c9243880e3b41fcede7fddb5947a962f1d4c43882ba07cc0ab63d1ba154527ef4cc8e5cc130bb2524b40fcbe093ecfd2f3b8fb0bafc9a2a7324050c30d2af00
-  data.tar.gz: a2b37c3ab8b98065a0910a458e177b71576c5d8f52c6f6eba0e31d25ae7797f1517a168aeef2f39c7295d27e4f981373b7a90066dc7ab8651670ecbd41fc70d5
+  metadata.gz: 831a54675315529b6bc1d489296a15325f88bcccbbb8f480c786641410de853989425591f4e60a6249ef123a3aa9e204780388925f2a027d758ac5594ca6c306
+  data.tar.gz: f66ab6dfc996aa9982f6c5d09e2bf98b5a5de8b85220ea839f854e53edd3f55144404b5ddff91f2681f7d8fee21071bb54f20265951424840c527b7203dd9ace

data/.gitignore

@@ -25,6 +25,8 @@ Gemfile.lock
 .dat*
 .repl_history
 build/
+node_modules/
+package-lock.json
 *.bridgesupport
 build-iPhoneOS/
 build-iPhoneSimulator/

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.
@@ -32,7 +32,7 @@ require "graphql/stitching"
 
 ## Usage
 
-The quickest way to start is to use the provided [`Gateway`](./docs/gateway.md) component that assembles a stitched graph ready to execute requests:
+The quickest way to start is to use the provided [`Gateway`](./docs/gateway.md) component that wraps a stitched graph in an executable workflow with [caching hooks](./docs/gateway.md#cache-hooks):
 
 ```ruby
 movies_schema = <<~GRAPHQL
@@ -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,61 +12,62 @@ 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?
 
         # 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["selection"])
-            raise Composer::ValidationError, "Multiple boundary queries for `#{type.graphql_name}.#{boundary["selection"]}` found in #{boundary["location"]}.
-            Limit one boundary query per type and key in each location. Abstract boundaries provide all possible types."
+            raise Composer::ValidationError, "Multiple boundary queries for `#{type.graphql_name}.#{boundary["selection"]}` "\
+              "found in #{boundary["location"]}. Limit one boundary query per type and key in each location. "\
+              "Abstract boundaries provide all possible types."
           end
           memo[boundary["location"]] ||= {}
           memo[boundary["location"]][boundary["selection"]] = boundary
         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|
           remote_locations = bidirectional_access_locations.reject { _1 == location }
           paths = ctx.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}` boundaries in #{location} to all other locations. "\
+              "All locations must provide a boundary accessor that uses a conjoining key."
           end
         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
@@ -78,10 +79,10 @@ 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."
+            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."
           end
         end
       end

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

@@ -4,19 +4,47 @@ module GraphQL
   module Stitching
     class Composer::ValidateInterfaces < Composer::BaseValidator
 
+      # For each composed interface, check the interface against each possible type
+      # to assure that intersecting fields have compatible types, structures, and nullability.
+      # Verifies compatibility of types that inherit interface contracts through merging.
       def perform(supergraph, composer)
-        # @todo
-        # Validate all supergraph interface fields
-        # match possible types in all locations...
-        # - Traverse supergraph types (supergraph.types)
-        # - For each interface (.kind.interface?), get possible types (Util.get_possible_types)
-        # - For each possible type, traverse type candidates (composer.subschema_types_by_name_and_location)
-        # - For each type candidate, compare interface fields to type candidate fields
-        # - For each type candidate field that matches an interface field...
-        #   - Named types must match
-        #   - List structures must match
-        #   - Nullabilities must be >= interface field
-        # - It's OKAY if a type candidate does not implement the full interface
+        supergraph.schema.types.each do |type_name, interface_type|
+          next unless interface_type.kind.interface?
+
+          supergraph.schema.possible_types(interface_type).each do |possible_type|
+            interface_type.fields.each do |field_name, interface_field|
+              # graphql-ruby will dynamically apply interface fields on a type implementation,
+              # so check the delegation map to assure that all materialized fields have resolver locations.
+              unless supergraph.locations_by_type_and_field[possible_type.graphql_name][field_name]&.any?
+                raise Composer::ValidationError, "Type #{possible_type.graphql_name} does not implement a `#{field_name}` field in any location, "\
+                  "which is required by interface #{interface_type.graphql_name}."
+              end
+
+              intersecting_field = possible_type.fields[field_name]
+              interface_type_structure = Util.flatten_type_structure(interface_field.type)
+              possible_type_structure = Util.flatten_type_structure(intersecting_field.type)
+
+              if possible_type_structure.length != interface_type_structure.length
+                raise Composer::ValidationError, "Incompatible list structures between field #{possible_type.graphql_name}.#{field_name} of type "\
+                  "#{intersecting_field.type.to_type_signature} and interface #{interface_type.graphql_name}.#{field_name} of type #{interface_field.type.to_type_signature}."
+              end
+
+              interface_type_structure.each_with_index do |interface_struct, index|
+                possible_struct = possible_type_structure[index]
+
+                if possible_struct[:name] != interface_struct[:name]
+                  raise Composer::ValidationError, "Incompatible named types between field #{possible_type.graphql_name}.#{field_name} of type "\
+                    "#{intersecting_field.type.to_type_signature} and interface #{interface_type.graphql_name}.#{field_name} of type #{interface_field.type.to_type_signature}."
+                end
+
+                if possible_struct[:null] && !interface_struct[:null]
+                  raise Composer::ValidationError, "Incompatible nullability between field #{possible_type.graphql_name}.#{field_name} of type "\
+                    "#{intersecting_field.type.to_type_signature} and interface #{interface_type.graphql_name}.#{field_name} of type #{interface_field.type.to_type_signature}."
+                end
+              end
+            end
+          end
+        end
       end
 
     end

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,10 +77,10 @@ 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
 
-          unless kinds.all? { _1 == kinds.first }
+          if kinds.length > 1
             raise ComposerError, "Cannot merge different kinds for `#{type_name}`. Found: #{kinds.join(", ")}."
           end
 
@@ -96,7 +99,7 @@ module GraphQL
           when "INPUT_OBJECT"
             build_input_object_type(type_name, types_by_location)
           else
-            raise ComposerError, "Unexpected kind encountered for `#{type_name}`. Found: #{kind}."
+            raise ComposerError, "Unexpected kind encountered for `#{type_name}`. Found: #{kinds.first}."
           end
         end
 
@@ -110,6 +113,7 @@ module GraphQL
           own_orphan_types.clear
         end
 
+        select_root_field_locations(schema)
         expand_abstract_boundaries(schema)
 
         supergraph = Supergraph.new(
@@ -307,12 +311,13 @@ module GraphQL
         fields_by_name_location.each do |field_name, fields_by_location|
           value_types = fields_by_location.values.map(&:type)
 
+          type = merge_value_types(type_name, value_types, field_name: field_name)
           schema_field = owner.field(
             field_name,
             description: merge_descriptions(type_name, fields_by_location, field_name: field_name),
             deprecation_reason: merge_deprecations(type_name, fields_by_location, field_name: field_name),
-            type: merge_value_types(type_name, value_types, field_name: field_name),
-            null: !value_types.all?(&:non_null?),
+            type: Util.unwrap_non_null(type),
+            null: !type.non_null?,
             camelize: false,
           )
 
@@ -345,12 +350,13 @@ module GraphQL
           # Getting double args sometimes... why?
           return if owner.arguments.any? { _1.first == argument_name }
 
+          type = merge_value_types(type_name, value_types, argument_name: argument_name, field_name: field_name)
           schema_argument = owner.argument(
             argument_name,
             description: merge_descriptions(type_name, arguments_by_location, argument_name: argument_name, field_name: field_name),
             deprecation_reason: merge_deprecations(type_name, arguments_by_location, argument_name: argument_name, field_name: field_name),
-            type: merge_value_types(type_name, value_types, argument_name: argument_name, field_name: field_name),
-            required: value_types.any?(&:non_null?),
+            type: Util.unwrap_non_null(type),
+            required: type.non_null?,
             camelize: false,
           )
 
@@ -401,37 +407,32 @@ module GraphQL
 
       def merge_value_types(type_name, type_candidates, field_name: nil, argument_name: nil)
         path = [type_name, field_name, argument_name].compact.join(".")
-        named_types = type_candidates.map { _1.unwrap.graphql_name }.uniq
+        alt_structures = type_candidates.map { Util.flatten_type_structure(_1) }
+        basis_structure = alt_structures.shift
 
-        unless named_types.all? { _1 == named_types.first }
-          raise ComposerError, "Cannot compose mixed types at `#{path}`. Found: #{named_types.join(", ")}."
-        end
-
-        type = GraphQL::Schema::BUILT_IN_TYPES.fetch(named_types.first, build_type_binding(named_types.first))
-        list_structures = type_candidates.map { Util.get_list_structure(_1) }
-
-        if list_structures.any?(&:any?)
-          if list_structures.any? { _1.length != list_structures.first.length }
+        alt_structures.each do |alt_structure|
+          if alt_structure.length != basis_structure.length
             raise ComposerError, "Cannot compose mixed list structures at `#{path}`."
           end
 
-          list_structures.each(&:reverse!)
-          list_structures.first.each_with_index do |current, index|
-            # input arguments use strongest nullability, readonly fields use weakest
-            non_null = list_structures.public_send(argument_name ? :any? : :all?) do |list_structure|
-              list_structure[index].start_with?("non_null")
-            end
-
-            case current
-            when "list", "non_null_list"
-              type = type.to_list_type
-              type = type.to_non_null_type if non_null
-            when "element", "non_null_element"
-              type = type.to_non_null_type if non_null
-            end
+          if alt_structure.last[:name] != basis_structure.last[:name]
+            raise ComposerError, "Cannot compose mixed types at `#{path}`."
           end
         end
 
+        type = GraphQL::Schema::BUILT_IN_TYPES.fetch(
+          basis_structure.last[:name],
+          build_type_binding(basis_structure.last[:name])
+        )
+
+        basis_structure.reverse!.each_with_index do |basis, index|
+          rev_index = basis_structure.length - index - 1
+          non_null = alt_structures.each_with_object([!basis[:null]]) { |s, m| m << !s[rev_index][:null] }
+
+          type = type.to_list_type if basis[:list]
+          type = type.to_non_null_type if argument_name ? non_null.any? : non_null.all?
+        end
+
         type
       end
 
@@ -459,7 +460,7 @@ module GraphQL
         types_by_location.each do |location, type_candidate|
           type_candidate.fields.each do |field_name, field_candidate|
             boundary_type_name = field_candidate.type.unwrap.graphql_name
-            boundary_list = Util.get_list_structure(field_candidate.type)
+            boundary_structure = Util.flatten_type_structure(field_candidate.type)
 
             field_candidate.directives.each do |directive|
               next unless directive.graphql_name == GraphQL::Stitching.stitch_directive
@@ -482,8 +483,8 @@ module GraphQL
                 raise ComposerError, "Invalid boundary argument `#{argument_name}` for #{type_name}.#{field_name}."
               end
 
-              argument_list = Util.get_list_structure(argument.type)
-              if argument_list.length != boundary_list.length
+              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."
               end
 
@@ -493,7 +494,7 @@ module GraphQL
                 "selection" => key_selections[0].name,
                 "field" => field_candidate.name,
                 "arg" => argument_name,
-                "list" => boundary_list.any?,
+                "list" => boundary_structure.first[:list],
                 "type_name" => boundary_type_name,
               }
             end
@@ -501,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
@@ -558,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

@@ -37,23 +37,23 @@ module GraphQL
 
         request.prepare!
 
-        begin
-          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

@@ -20,13 +20,11 @@ module GraphQL
       end
 
       def operations
-        ops = @operations_by_grouping.values
-        ops.sort_by!(&:key)
-        ops
+        @operations_by_grouping.values.sort_by!(&:key)
       end
 
       def to_h
-        { "ops" => operations.map(&:to_h) }
+        { "ops" => operations.map!(&:to_h) }
       end
 
       private
@@ -41,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|
@@ -55,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: [] }
@@ -221,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
@@ -231,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
@@ -248,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 climbing selects highest scoring locations to use
-            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
 
@@ -268,14 +270,14 @@ module GraphQL
           end
         end
 
+        # route from current location to target locations via boundary queries,
+        # then translate those routes into planner operations
         routes = @supergraph.route_type_to_locations(parent_type.graphql_name, current_location, selections_by_location.keys)
         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/planner_operation.rb

@@ -3,6 +3,8 @@
 module GraphQL
   module Stitching
     class PlannerOperation
+      LANGUAGE_PRINTER = GraphQL::Language::Printer.new
+
       attr_reader :key, :location, :parent_type, :type_condition, :operation_type, :insertion_path
       attr_accessor :after_key, :selections, :variables, :boundary
 
@@ -32,12 +34,12 @@ module GraphQL
 
       def selection_set
         op = GraphQL::Language::Nodes::OperationDefinition.new(selections: @selections)
-        GraphQL::Language::Printer.new.print(op).gsub!(/\s+/, " ").strip!
+        LANGUAGE_PRINTER.print(op).gsub!(/\s+/, " ").strip!
       end
 
       def variable_set
         @variables.each_with_object({}) do |(variable_name, value_type), memo|
-          memo[variable_name] = GraphQL::Language::Printer.new.print(value_type)
+          memo[variable_name] = LANGUAGE_PRINTER.print(value_type)
         end
       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/shaper.rb

@@ -43,7 +43,7 @@ module GraphQL
 
           when GraphQL::Language::Nodes::InlineFragment
             fragment_type = @schema.types[node.type.name]
-            next unless fragment_matches_typename?(fragment_type, typename)
+            next unless typename_in_type?(typename, fragment_type)
 
             result = resolve_object_scope(raw_object, fragment_type, node.selections, typename)
             return nil if result.nil?
@@ -51,7 +51,7 @@ module GraphQL
           when GraphQL::Language::Nodes::FragmentSpread
             fragment = @request.fragment_definitions[node.name]
             fragment_type = @schema.types[fragment.type.name]
-            next unless fragment_matches_typename?(fragment_type, typename)
+            next unless typename_in_type?(typename, fragment_type)
 
             result = resolve_object_scope(raw_object, fragment_type, fragment.selections, typename)
             return nil if result.nil?
@@ -93,9 +93,9 @@ module GraphQL
         resolved_list
       end
 
-      def fragment_matches_typename?(fragment_type, typename)
-        return true if fragment_type.graphql_name == typename
-        fragment_type.kind.interface? && @schema.possible_types(fragment_type).any? { _1.graphql_name == typename }
+      def typename_in_type?(typename, type)
+        return true if type.graphql_name == typename
+        type.kind.abstract? && @schema.possible_types(type).any? { _1.graphql_name == typename }
       end
     end
   end

data/lib/graphql/stitching/util.rb

@@ -10,12 +10,33 @@ module GraphQL
 
       # strips non-null wrappers from a type
       def self.unwrap_non_null(type)
-        while type.is_a?(GraphQL::Schema::NonNull)
-          type = type.of_type
-        end
+        type = type.of_type while type.non_null?
         type
       end
 
+      # builds a single-dimensional representation of a wrapped type structure
+      def self.flatten_type_structure(type)
+        structure = []
+
+        while type.list?
+          structure << {
+            list: true,
+            null: !type.non_null?,
+            name: nil,
+          }
+
+          type = unwrap_non_null(type).of_type
+        end
+
+        structure << {
+          list: false,
+          null: !type.non_null?,
+          name: type.unwrap.graphql_name,
+        }
+
+        structure
+      end
+
       # gets a named type for a field node, including hidden root introspections
       def self.named_type_for_field_node(schema, parent_type, node)
         if node.name == "__schema" && parent_type == schema.query
@@ -40,25 +61,6 @@ module GraphQL
         end
         result.uniq
       end
-
-      # gets a deep structural description of a list value type
-      def self.get_list_structure(type)
-        structure = []
-        previous = nil
-        while type.respond_to?(:of_type)
-          if type.is_a?(GraphQL::Schema::List)
-            structure.push(previous.is_a?(GraphQL::Schema::NonNull) ? "non_null_list" : "list")
-          end
-          if structure.any?
-            previous = type
-            if !type.of_type.respond_to?(:of_type)
-              structure.push(previous.is_a?(GraphQL::Schema::NonNull) ? "non_null_element" : "element")
-            end
-          end
-          type = type.of_type
-        end
-        structure
-      end
     end
   end
 end

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "0.3.1"
+    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.1
+  version: 0.3.3
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-03 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