graphql-stitching 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32918bd6b17708d712d3ac945f6007b0405299379372aabda8b0c3a5f0c246da
-  data.tar.gz: 608562f6b35cfe912e2388c6cbfce8c774bedc6f6518d257eb0de8b45fdc8b52
+  metadata.gz: 6753e205aac88d3dd3be1c906b743cc49ae0de84ff8ab56c7e9be6e889429aa3
+  data.tar.gz: 59440f9d70cb365ef124604c42012bf655934555dfb76905328368353f5e310b
 SHA512:
-  metadata.gz: c0f40d79e3b06c9477f5967f12f6e33c0534b916c3454669d2802357137ff78d7bb9bb7d99d7c82d43ea47f58fac1c4d0e5aa38243d4cbfcdec6ba192ef56c0e
-  data.tar.gz: eed8c018a8efde4500bb0eb93de78803f555c77fad284718e945648160442eea249439d2a2cb5b4c0a5121fc148197f48b9ea0d50a21e7cfa291499fe4533912
+  metadata.gz: ac218d2218c14b8debff552ffb11e83e00293dfebb404d25296ed9e408232e488c44575c701ee3fd933331d84755062517f2c2da8df2db98ac7c5e8594595846
+  data.tar.gz: ec4f5051ebd511e72536c8e3246302079b2eb65ab5edab37c7c7d7de5488cdc7581318c69a0ea54047bd79ff42bf9e9c5af3434a27fc5667cf029340527c8117

data/.yardopts

@@ -0,0 +1,5 @@
+--no-private
+--markup=markdown
+--readme=readme.md
+--title='GraphQL Stitching Ruby API Documentation'
+'lib/**/*.rb' - '*.md'

data/README.md

@@ -78,9 +78,7 @@ While the `Client` constructor is an easy quick start, the library also has seve
 
 - [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.
-- [Request](./docs/request.md) - prepares a requested GraphQL document and variables for stitching.
-- [Planner](./docs/planner.md) - builds a cacheable query plan for a request document.
-- [Executor](./docs/executor.md) - executes a query plan with given request variables.
+- [Request](./docs/request.md) - manages the lifecycle of a stitched GraphQL request.
 - [HttpExecutable](./docs/http_executable.md) - proxies requests to remotes with multipart file upload support.
 
 ## Merged types
@@ -134,7 +132,7 @@ client = GraphQL::Stitching::Client.new(locations: {
     executable:  GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
   },
   catalog: {
-    schema: GraphQL::Schema.from_definition(shipping_schema),
+    schema: GraphQL::Schema.from_definition(catalog_schema),
     executable:  GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
   },
 })
@@ -155,7 +153,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](#multiple-query-arguments) later).
 
-Each location that provides a unique variant of a type must provide at least one stitching query. 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 at least one stitching query for the type. The exception to this requirement are [foreign key types](./docs/mechanics.md##modeling-foreign-keys-for-stitching) that contain only a single key field:
 
 ```graphql
 type Product {
@@ -163,7 +161,7 @@ type Product {
 }
 ```
 
-The above representation of a `Product` type provides no unique data beyond a key that is available in other locations. Thus, this representation will never require an inbound request to fetch it, and its stitching query may be omitted. This pattern of providing key-only types is very common in stitching: it allows a foreign key to be represented as an object stub that may be enriched by data collected from other locations.
+The above representation of a `Product` type provides no unique data beyond a key that is available in other locations. Thus, this representation will never require an inbound request to fetch it, and its stitching query may be omitted.
 
 #### List queries
 
@@ -427,6 +425,7 @@ The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based im
 
 ## Additional topics
 
+- [Modeling foreign keys for stitching](./docs/mechanics.md##modeling-foreign-keys-for-stitching)
 - [Deploying a stitched schema](./docs/mechanics.md#deploying-a-stitched-schema)
 - [Field selection routing](./docs/mechanics.md#field-selection-routing)
 - [Root selection routing](./docs/mechanics.md#root-selection-routing)

data/docs/README.md

@@ -10,8 +10,6 @@ Major components include:
 - [Composer](./composer.md) - merges and validates many schemas into one graph.
 - [Supergraph](./supergraph.md) - manages the combined schema and location routing maps. Can be exported, cached, and rehydrated.
 - [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.
 - [HttpExecutable](./http_executable.md) - proxies requests to remotes with multipart file upload support.
 
 Additional topics:

data/docs/mechanics.md

@@ -1,5 +1,47 @@
 ## Schema Stitching, mechanics
 
+### Modeling foreign keys for stitching
+
+Foreign keys in a GraphQL schema typically look like the `Product.imageId` field here:
+
+```graphql
+# -- Products schema:
+
+type Product {
+  id: ID!
+  imageId: ID!
+}
+
+# -- Images schema:
+
+type Image {
+  id: ID!
+  url: String!
+}
+```
+
+However, this design does not lend itself to stitching where types need to _merge_ across locations. A simple schema refactor makes this foreign key more expressive as an entity type, and turns the key into an _object_ that will merge with analogous object types in other locations:
+
+```graphql
+# -- Products schema:
+
+type Product {
+  id: ID!
+  image: Image!
+}
+
+type Image {
+  id: ID!
+}
+
+# -- Images schema:
+
+type Image {
+  id: ID!
+  url: String!
+}
+```
+
 ### Deploying a stitched schema
 
 Among the simplest and most effective ways to manage a stitched schema is to compose it locally, write the composed SDL as a `.graphql` file in your repo, and then load the composed schema into a stitching client at runtime. For example, setup a `rake` task that loads/fetches subgraph schemas, composes them, and then writes the composed schema definition as a file committed to the repo:

data/docs/request.md

@@ -25,37 +25,12 @@ A `Request` provides the following information:
 - `req.variable_definitions`: a mapping of variable names to their type definitions
 - `req.fragment_definitions`: a mapping of fragment names to their fragment definitions
 
-### Preparing requests
+### Request lifecycle
 
-A request should be prepared for stitching using the `prepare!` method _after_ validations have been run:
+A request manages the flow of stitching behaviors. These are sequenced by the `Client`
+component, or you may invoke them manually:
 
-```ruby
-document = <<~GRAPHQL
-  query FetchMovie($id: ID!, $lang: String = "en", $withShowtimes: Boolean = true) {
-    movie(id:$id) {
-      id
-      title(lang: $lang)
-      showtimes @include(if: $withShowtimes) {
-        time
-      }
-    }
-  }
-GRAPHQL
-
-request = GraphQL::Stitching::Request.new(
-  supergraph,
-  document,
-  variables: { "id" => "1" },
-  operation_name: "FetchMovie",
-)
-
-errors = MySchema.validate(request.document)
-# return early with any static validation errors...
-
-request.prepare!
-```
-
-Preparing a request will apply several destructive transformations:
-
-- Default values from variable definitions will be added to request variables.
-- The document will be pre-shaped based on `@skip` and `@include` directives.
+1. `request.validate`: runs static validations on the request using the combined schema.
+2. `request.prepare!`: inserts variable defaults and pre-renders skip/include conditional shaping.
+3. `request.plan`: builds a plan for the request. May act as a setting for plans pulled from cache.
+4. `request.execute`: executes the request, and returns the resulting data.

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module GraphQL
-  module Stitching
-    class Composer::BaseValidator
+module GraphQL::Stitching
+  class Composer
+    class BaseValidator
       def perform(ctx, composer)
         raise "not implemented"
       end

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module GraphQL
-  module Stitching
-    class Composer::ValidateBoundaries < Composer::BaseValidator
+module GraphQL::Stitching
+  class Composer
+    class ValidateBoundaries < BaseValidator
 
       def perform(ctx, composer)
         ctx.schema.types.each do |type_name, type|

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

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-module GraphQL
-  module Stitching
-    class Composer::ValidateInterfaces < Composer::BaseValidator
-
+module GraphQL::Stitching
+  class Composer
+    class ValidateInterfaces < 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.

data/lib/graphql/stitching/composer.rb

@@ -1,26 +1,49 @@
 # frozen_string_literal: true
 
+require_relative "./composer/base_validator"
+require_relative "./composer/validate_interfaces"
+require_relative "./composer/validate_boundaries"
+
 module GraphQL
   module Stitching
     class Composer
       class ComposerError < StitchingError; end
       class ValidationError < ComposerError; end
-      class ReferenceType < GraphQL::Schema::Object
-        field(:f, String) do
-          argument(:a, String)
+
+      # @api private
+      NO_DEFAULT_VALUE = begin
+        class T < GraphQL::Schema::Object
+          field(:f, String) do
+            argument(:a, String)
+          end
         end
+
+        T.get_field("f").get_argument("a").default_value
       end
 
-      NO_DEFAULT_VALUE = ReferenceType.get_field("f").get_argument("a").default_value
+      # @api private
       BASIC_VALUE_MERGER = ->(values_by_location, _info) { values_by_location.values.find { !_1.nil? } }
+
+      # @api private
       BASIC_ROOT_FIELD_LOCATION_SELECTOR = ->(locations, _info) { locations.last }
 
+      # @api private
       VALIDATORS = [
         "ValidateInterfaces",
         "ValidateBoundaries",
       ].freeze
 
-      attr_reader :query_name, :mutation_name, :candidate_types_by_name_and_location, :schema_directives
+      # @return [String] name of the Query type in the composed schema.
+      attr_reader :query_name
+
+      # @return [String] name of the Mutation type in the composed schema.
+      attr_reader :mutation_name
+
+      # @api private
+      attr_reader :candidate_types_by_name_and_location
+
+      # @api private
+      attr_reader :schema_directives
 
       def initialize(
         query_name: "Query",
@@ -148,6 +171,8 @@ module GraphQL
         supergraph
       end
 
+      # @!scope class
+      # @!visibility private
       def prepare_locations_input(locations_input)
         schemas = {}
         executables = {}
@@ -200,6 +225,8 @@ module GraphQL
         return schemas, executables
       end
 
+      # @!scope class
+      # @!visibility private
       def build_directive(directive_name, directives_by_location)
         builder = self
 
@@ -212,6 +239,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_scalar_type(type_name, types_by_location)
         built_in_type = GraphQL::Schema::BUILT_IN_TYPES[type_name]
         return built_in_type if built_in_type
@@ -225,6 +254,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_enum_type(type_name, types_by_location, enum_usage)
         builder = self
 
@@ -232,7 +263,6 @@ module GraphQL
         enum_values_by_name_location = types_by_location.each_with_object({}) do |(location, type_candidate), memo|
           type_candidate.enum_values.each do |enum_value_candidate|
             memo[enum_value_candidate.graphql_name] ||= {}
-            memo[enum_value_candidate.graphql_name][location] ||= {}
             memo[enum_value_candidate.graphql_name][location] = enum_value_candidate
           end
         end
@@ -261,6 +291,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_object_type(type_name, types_by_location)
         builder = self
 
@@ -278,6 +310,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_interface_type(type_name, types_by_location)
         builder = self
 
@@ -296,6 +330,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_union_type(type_name, types_by_location)
         builder = self
 
@@ -309,6 +345,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_input_object_type(type_name, types_by_location)
         builder = self
 
@@ -320,10 +358,14 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_type_binding(type_name)
         GraphQL::Schema::LateBoundType.new(@mapped_type_names.fetch(type_name, type_name))
       end
 
+      # @!scope class
+      # @!visibility private
       def build_merged_fields(type_name, types_by_location, owner)
         # "field_name" => "location" => field
         fields_by_name_location = types_by_location.each_with_object({}) do |(location, type_candidate), memo|
@@ -333,7 +375,6 @@ module GraphQL
             @field_map[type_name][field_candidate.name] << location
 
             memo[field_name] ||= {}
-            memo[field_name][location] ||= {}
             memo[field_name][location] = field_candidate
           end
         end
@@ -356,12 +397,13 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_merged_arguments(type_name, members_by_location, owner, field_name: nil, directive_name: nil)
         # "argument_name" => "location" => argument
         args_by_name_location = members_by_location.each_with_object({}) do |(location, member_candidate), memo|
           member_candidate.arguments.each do |argument_name, argument|
             memo[argument_name] ||= {}
-            memo[argument_name][location] ||= {}
             memo[argument_name][location] = argument
           end
         end
@@ -410,11 +452,12 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_merged_directives(type_name, members_by_location, owner, field_name: nil, argument_name: nil, enum_value: nil)
         directives_by_name_location = members_by_location.each_with_object({}) do |(location, member_candidate), memo|
           member_candidate.directives.each do |directive|
             memo[directive.graphql_name] ||= {}
-            memo[directive.graphql_name][location] ||= {}
             memo[directive.graphql_name][location] = directive
           end
         end
@@ -451,6 +494,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def merge_value_types(type_name, type_candidates, field_name: nil, argument_name: nil)
         path = [type_name, field_name, argument_name].tap(&:compact!).join(".")
         alt_structures = type_candidates.map { Util.flatten_type_structure(_1) }
@@ -482,6 +527,8 @@ module GraphQL
         type
       end
 
+      # @!scope class
+      # @!visibility private
       def merge_descriptions(type_name, members_by_location, field_name: nil, argument_name: nil, enum_value: nil)
         strings_by_location = members_by_location.each_with_object({}) { |(l, m), memo| memo[l] = m.description }
         @description_merger.call(strings_by_location, {
@@ -492,6 +539,8 @@ module GraphQL
         }.tap(&:compact!))
       end
 
+      # @!scope class
+      # @!visibility private
       def merge_deprecations(type_name, members_by_location, field_name: nil, argument_name: nil, enum_value: nil)
         strings_by_location = members_by_location.each_with_object({}) { |(l, m), memo| memo[l] = m.deprecation_reason }
         @deprecation_merger.call(strings_by_location, {
@@ -502,6 +551,8 @@ module GraphQL
         }.tap(&:compact!))
       end
 
+      # @!scope class
+      # @!visibility private
       def extract_boundaries(type_name, types_by_location)
         types_by_location.each do |location, type_candidate|
           type_candidate.fields.each do |field_name, field_candidate|
@@ -554,6 +605,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       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|
@@ -572,6 +625,8 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def expand_abstract_boundaries(schema)
         @boundary_map.keys.each do |type_name|
           boundary_type = schema.types[type_name]
@@ -585,28 +640,30 @@ module GraphQL
         end
       end
 
+      # @!scope class
+      # @!visibility private
       def build_enum_usage_map(schemas)
         reads = []
         writes = []
 
         schemas.each do |schema|
           introspection_types = schema.introspection_system.types.keys
-          schema.types.values.each do |type|
+          schema.types.each_value do |type|
             next if introspection_types.include?(type.graphql_name)
 
             if type.kind.object? || type.kind.interface?
-              type.fields.values.each do |field|
+              type.fields.each_value do |field|
                 field_type = field.type.unwrap
                 reads << field_type.graphql_name if field_type.kind.enum?
 
-                field.arguments.values.each do |argument|
+                field.arguments.each_value do |argument|
                   argument_type = argument.type.unwrap
                   writes << argument_type.graphql_name if argument_type.kind.enum?
                 end
               end
 
             elsif type.kind.input_object?
-              type.arguments.values.each do |argument|
+              type.arguments.each_value do |argument|
                 argument_type = argument.type.unwrap
                 writes << argument_type.graphql_name if argument_type.kind.enum?
               end
@@ -636,7 +693,3 @@ module GraphQL
     end
   end
 end
-
-require_relative "./composer/base_validator"
-require_relative "./composer/validate_interfaces"
-require_relative "./composer/validate_boundaries"

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module GraphQL
-  module Stitching
-    class Executor::BoundarySource < GraphQL::Dataloader::Source
+module GraphQL::Stitching
+  class Executor
+    class BoundarySource < GraphQL::Dataloader::Source
       def initialize(executor, location)
         @executor = executor
         @location = location
@@ -29,7 +29,7 @@ module GraphQL
             @executor.request.operation_directives,
           )
           variables = @executor.request.variables.slice(*variable_names)
-          raw_result = @executor.supergraph.execute_at_location(@location, query_document, variables, @executor.request)
+          raw_result = @executor.request.supergraph.execute_at_location(@location, query_document, variables, @executor.request)
           @executor.query_count += 1
 
           merge_results!(origin_sets_by_operation, raw_result.dig("data"))
@@ -183,9 +183,7 @@ module GraphQL
           end
 
         elsif forward_path.any?
-          current_path << index
           repath_errors!(pathed_errors_by_object_id, forward_path, current_path, scope)
-          current_path.pop
 
         elsif scope.is_a?(Array)
           scope.each_with_index do |element, index|

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module GraphQL
-  module Stitching
-    class Executor::RootSource < GraphQL::Dataloader::Source
+module GraphQL::Stitching
+  class Executor
+    class RootSource < GraphQL::Dataloader::Source
       def initialize(executor, location)
         @executor = executor
         @location = location
@@ -17,13 +17,25 @@ module GraphQL
           @executor.request.operation_directives,
         )
         query_variables = @executor.request.variables.slice(*op.variables.keys)
-        result = @executor.supergraph.execute_at_location(op.location, query_document, query_variables, @executor.request)
+        result = @executor.request.supergraph.execute_at_location(op.location, query_document, query_variables, @executor.request)
         @executor.query_count += 1
 
-        @executor.data.merge!(result["data"]) if result["data"]
+        if result["data"]
+          if op.path.any?
+            # Nested root scopes must expand their pathed origin set
+            origin_set = op.path.reduce([@executor.data]) do |set, ns|
+              set.flat_map { |obj| obj && obj[ns] }.tap(&:compact!)
+            end
+
+            origin_set.each { _1.merge!(result["data"]) }
+          else
+            # Actual root scopes merge directly into results data
+            @executor.data.merge!(result["data"])
+          end
+        end
+
         if result["errors"]&.any?
-          result["errors"].each { _1.delete("locations") }
-          @executor.errors.concat(result["errors"])
+          @executor.errors.concat(format_errors!(result["errors"], op.path))
         end
 
         ops.map(&:step)
@@ -51,6 +63,16 @@ module GraphQL
         doc << op.selections
         doc
       end
+
+      # Format response errors without a document location (because it won't match the request doc),
+      # and prepend any insertion path for the scope into error paths.
+      def format_errors!(errors, path)
+        errors.each do |err|
+          err.delete("locations")
+          err["path"].unshift(*path) if err["path"] && path.any?
+        end
+        errors
+      end
     end
   end
 end

data/lib/graphql/stitching/executor.rb

@@ -1,17 +1,26 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "./executor/boundary_source"
+require_relative "./executor/root_source"
 
 module GraphQL
   module Stitching
     class Executor
-      attr_reader :supergraph, :request, :plan, :data, :errors
+      # @return [Request] the stitching request to execute.
+      attr_reader :request
+
+      # @return [Hash] an aggregate data payload to return.
+      attr_reader :data
+
+      # @return [Array<Hash>] aggregate GraphQL errors to return.
+      attr_reader :errors
+
+      # @return [Integer] tally of queries performed while executing.
       attr_accessor :query_count
 
       def initialize(request, nonblocking: false)
         @request = request
-        @supergraph = request.supergraph
-        @plan = request.plan
         @data = {}
         @errors = []
         @query_count = 0
@@ -37,13 +46,13 @@ module GraphQL
       private
 
       def exec!(next_steps = [0])
-        if @exec_cycles > @plan.ops.length
+        if @exec_cycles > @request.plan.ops.length
           # sanity check... if we've exceeded queue size, then something went wrong.
           raise StitchingError, "Too many execution requests attempted."
         end
 
         @dataloader.append_job do
-          tasks = @plan
+          tasks = @request.plan
             .ops
             .select { next_steps.include?(_1.after) }
             .group_by { [_1.location, _1.boundary.nil?] }
@@ -66,6 +75,3 @@ module GraphQL
     end
   end
 end
-
-require_relative "./executor/boundary_source"
-require_relative "./executor/root_source"

data/lib/graphql/stitching/http_executable.rb

@@ -7,27 +7,33 @@ require "json"
 module GraphQL
   module Stitching
     class HttpExecutable
-      def initialize(url:, headers:{}, upload_types: nil)
+      # Builds a new executable for proxying subgraph requests via HTTP.
+      # @param url [String] the url of the remote location to proxy.
+      # @param headers [Hash] headers to include in upstream requests.
+      # @param upload_types [Array<String>, nil] a list of scalar names that represent file uploads. These types extract into multipart forms.
+      def initialize(url:, headers: {}, upload_types: nil)
         @url = url
         @headers = { "Content-Type" => "application/json" }.merge!(headers)
         @upload_types = upload_types
       end
 
       def call(request, document, variables)
-        multipart_form = if request.variable_definitions.any? && variables&.any?
-          extract_multipart_form(request, document, variables)
-        end
+        form_data = extract_multipart_form(request, document, variables)
 
-        response = if multipart_form
-          post_multipart(multipart_form)
+        response = if form_data
+          send_multipart_form(request, form_data)
         else
-          post(document, variables)
+          send(request, document, variables)
         end
 
         JSON.parse(response.body)
       end
 
-      def post(document, variables)
+      # Sends a POST request to the remote location.
+      # @param request [Request] the original supergraph request.
+      # @param document [String] the location-specific subgraph document to send.
+      # @param variables [Hash] a hash of variables specific to the subgraph document.
+      def send(_request, document, variables)
         Net::HTTP.post(
           URI(@url),
           JSON.generate({ "query" => document, "variables" => variables }),
@@ -35,7 +41,10 @@ module GraphQL
         )
       end
 
-      def post_multipart(form_data)
+      # Sends a POST request to the remote location with multipart form data.
+      # @param request [Request] the original supergraph request.
+      # @param form_data [Hash] a rendered multipart form with an "operations", "map", and file sections.
+      def send_multipart_form(_request, form_data)
         uri = URI(@url)
         req = Net::HTTP::Post.new(uri)
         @headers.each_pair do |key, value|
@@ -48,16 +57,18 @@ module GraphQL
         end
       end
 
-      # extract multipart upload forms
-      # spec: https://github.com/jaydenseric/graphql-multipart-request-spec
+      # Extracts multipart upload forms per the spec:
+      # https://github.com/jaydenseric/graphql-multipart-request-spec
+      # @param request [Request] the original supergraph request.
+      # @param document [String] the location-specific subgraph document to send.
+      # @param variables [Hash] a hash of variables specific to the subgraph document.
       def extract_multipart_form(request, document, variables)
-        return unless @upload_types
+        return unless @upload_types && request.variable_definitions.any? && variables&.any?
 
-        path = []
         files_by_path = {}
 
         # extract all upload scalar values mapped by their input path
-        variables.each do |key, value|
+        variables.each_with_object([]) do |(key, value), path|
           ast_node = request.variable_definitions[key]
           path << key
           extract_ast_node(ast_node, value, files_by_path, path, request) if ast_node
@@ -70,14 +81,14 @@ module GraphQL
         files = files_by_path.values.tap(&:uniq!)
         variables_copy = variables.dup
 
-        files_by_path.keys.each do |path|
+        files_by_path.each_key do |path|
           orig = variables
           copy = variables_copy
           path.each_with_index do |key, i|
             if i == path.length - 1
-              map_key = files.index(copy[key]).to_s
-              map[map_key] ||= []
-              map[map_key] << "variables.#{path.join(".")}"
+              file_index = files.index(copy[key]).to_s
+              map[file_index] ||= []
+              map[file_index] << "variables.#{path.join(".")}"
               copy[key] = nil
             elsif orig[key].object_id == copy[key].object_id
               copy[key] = copy[key].dup

data/lib/graphql/stitching/planner.rb

@@ -276,19 +276,21 @@ module GraphQL
           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.
-              foreign_key = ExportSelection.key(boundary.key)
-              has_key = false
-              has_typename = false
-
-              parent_selections.each do |node|
-                next unless node.is_a?(GraphQL::Language::Nodes::Field)
-                has_key ||= node.alias == foreign_key
-                has_typename ||= node.alias == ExportSelection.typename_node.alias
+              if boundary.key
+                foreign_key = ExportSelection.key(boundary.key)
+                has_key = false
+                has_typename = false
+
+                parent_selections.each do |node|
+                  next unless node.is_a?(GraphQL::Language::Nodes::Field)
+                  has_key ||= node.alias == foreign_key
+                  has_typename ||= node.alias == ExportSelection.typename_node.alias
+                end
+
+                parent_selections << ExportSelection.key_node(boundary.key) unless has_key
+                parent_selections << ExportSelection.typename_node unless has_typename
               end
 
-              parent_selections << ExportSelection.key_node(boundary.key) unless has_key
-              parent_selections << ExportSelection.typename_node unless has_typename
-
               # E.2) Add a planner step for each new entrypoint location.
               add_step(
                 location: boundary.location,
@@ -296,7 +298,7 @@ module GraphQL
                 parent_type: parent_type,
                 selections: remote_selections_by_location[boundary.location] || [],
                 path: path.dup,
-                boundary: boundary,
+                boundary: boundary.key ? boundary : nil,
               ).selections
             end
           end
@@ -324,7 +326,7 @@ module GraphQL
         end
 
         if expanded_selections
-          @supergraph.memoized_schema_possible_types(parent_type.graphql_name).each do |possible_type|
+          @request.warden.possible_types(parent_type).each do |possible_type|
             next unless @supergraph.locations_by_type[possible_type.graphql_name].include?(current_location)
 
             type_name = GraphQL::Language::Nodes::TypeName.new(name: possible_type.graphql_name)

data/lib/graphql/stitching/request.rb

@@ -6,8 +6,30 @@ module GraphQL
       SUPPORTED_OPERATIONS = ["query", "mutation"].freeze
       SKIP_INCLUDE_DIRECTIVE = /@(?:skip|include)/
 
-      attr_reader :supergraph, :document, :variables, :operation_name, :context
+      # @return [Supergraph] supergraph instance that resolves the request.
+      attr_reader :supergraph
 
+      # @return [GraphQL::Language::Nodes::Document] the parsed GraphQL AST document.
+      attr_reader :document
+
+      # @return [Hash] input variables for the request.
+      attr_reader :variables
+
+      # @return [String] operation name selected for the request.
+      attr_reader :operation_name
+
+      # @return [Hash] contextual object passed through resolver flows.
+      attr_reader :context
+
+      # @return [GraphQL::Schema::Warden] a visibility warden for this request.
+      attr_reader :warden
+
+      # Creates a new supergraph request.
+      # @param supergraph [Supergraph] supergraph instance that resolves the request.
+      # @param document [String, GraphQL::Language::Nodes::Document] the request string or parsed AST.
+      # @param operation_name [String, nil] operation name selected for the request.
+      # @param variables [Hash, nil] input variables for the request.
+      # @param context [Hash, nil] a contextual object passed through resolver flows.
       def initialize(supergraph, document, operation_name: nil, variables: nil, context: nil)
         @supergraph = supergraph
         @string = nil
@@ -29,25 +51,34 @@ module GraphQL
 
         @operation_name = operation_name
         @variables = variables || {}
-        @context = context || GraphQL::Stitching::EMPTY_OBJECT
+
+        @query = GraphQL::Query.new(@supergraph.schema, document: @document, context: context)
+        @warden = @query.warden
+        @context = @query.context
+        @context[:request] = self
       end
 
+      # @return [String] the original document string, or a print of the parsed AST document.
       def string
         @string || normalized_string
       end
 
+      # @return [String] a print of the parsed AST document with consistent whitespace.
       def normalized_string
         @normalized_string ||= @document.to_query_string
       end
 
+      # @return [String] a digest of the original document string. Generally faster but less consistent.
       def digest
         @digest ||= Digest::SHA2.hexdigest(string)
       end
 
+      # @return [String] a digest of the normalized document string. Slower but more consistent.
       def normalized_digest
         @normalized_digest ||= Digest::SHA2.hexdigest(normalized_string)
       end
 
+      # @return [GraphQL::Language::Nodes::OperationDefinition] The selected root operation for the request.
       def operation
         @operation ||= begin
           operation_defs = @document.definitions.select do |d|
@@ -66,6 +97,7 @@ module GraphQL
         end
       end
 
+      # @return [String] A string of directives applied to the root operation. These are passed through in all subgraph requests.
       def operation_directives
         @operation_directives ||= if operation.directives.any?
           printer = GraphQL::Language::Printer.new
@@ -73,22 +105,28 @@ module GraphQL
         end
       end
 
+      # @return [Hash<String, GraphQL::Language::Nodes::AbstractNode>] map of variable names to AST type definitions.
       def variable_definitions
         @variable_definitions ||= operation.variables.each_with_object({}) do |v, memo|
           memo[v.name] = v.type
         end
       end
 
+      # @return [Hash<String, GraphQL::Language::Nodes::FragmentDefinition>] map of fragment names to their AST definitions.
       def fragment_definitions
         @fragment_definitions ||= @document.definitions.each_with_object({}) do |d, memo|
           memo[d.name] = d if d.is_a?(GraphQL::Language::Nodes::FragmentDefinition)
         end
       end
 
+      # Validates the request using the combined supergraph schema.
+      # @return [Array<GraphQL::ExecutionError>] an array of static validation errors
       def validate
-        @supergraph.schema.validate(@document, context: @context)
+        result = @supergraph.static_validator.validate(@query)
+        result[:errors]
       end
 
+      # Prepares the request for stitching by inserting variable defaults and applying @skip/@include conditionals.
       def prepare!
         operation.variables.each do |v|
           @variables[v.name] = v.default_value if @variables[v.name].nil? && !v.default_value.nil?
@@ -106,6 +144,19 @@ module GraphQL
         self
       end
 
+      # Gets and sets the query plan for the request. Assigned query plans may pull from a cache,
+      # which is useful for redundant GraphQL documents (commonly sent by frontend clients).
+      # ```ruby
+      # if cached_plan = $cache.get(request.digest)
+      #   plan = GraphQL::Stitching::Plan.from_json(JSON.parse(cached_plan))
+      #   request.plan(plan)
+      # else
+      #   plan = request.plan
+      #   $cache.set(request.digest, JSON.generate(plan.as_json))
+      # end
+      # ```
+      # @param new_plan [Plan, nil] a cached query plan for the request.
+      # @return [Plan] query plan for the request.
       def plan(new_plan = nil)
         if new_plan
           raise StitchingError, "Plan must be a `GraphQL::Stitching::Plan`." unless new_plan.is_a?(Plan)
@@ -115,6 +166,9 @@ module GraphQL
         end
       end
 
+      # Executes the request and returns the rendered response.
+      # @param raw [Boolean] specifies the result should be unshaped without pruning or null bubbling. Useful for debugging.
+      # @return [Hash] the rendered GraphQL response with "data" and "errors" sections.
       def execute(raw: false)
         GraphQL::Stitching::Executor.new(self).perform(raw: raw)
       end

data/lib/graphql/stitching/shaper.rb

@@ -5,6 +5,7 @@ module GraphQL
   module Stitching
     # Shapes the final results payload to the request selection and schema definition.
     # This eliminates unrequested export selections and applies null bubbling.
+    # @api private
     class Shaper
       def initialize(request)
         @request = request
@@ -117,7 +118,7 @@ module GraphQL
       def typename_in_type?(typename, type)
         return true if type.graphql_name == typename
 
-        type.kind.abstract? && @supergraph.memoized_schema_possible_types(type.graphql_name).any? do |t|
+        type.kind.abstract? && @request.warden.possible_types(type).any? do |t|
           t.graphql_name == typename
         end
       end

data/lib/graphql/stitching/skip_include.rb

@@ -2,11 +2,12 @@
 
 module GraphQL
   module Stitching
+    # Faster implementation of an AST visitor for prerendering
+    # @skip and @include conditional directives into a document.
+    # This avoids unnecessary planning steps, and prepares result shaping.
+    # @api private
     class SkipInclude
       class << self
-        # Faster implementation of an AST visitor for prerendering
-        # @skip and @include conditional directives into a document.
-        # This avoids unnecessary planning steps, and prepares result shaping.
         def render(document, variables)
           changed = false
           definitions = document.definitions.map do |original_definition|

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Supergraph
+    class ResolverDirective < GraphQL::Schema::Directive
+      graphql_name "resolver"
+      locations OBJECT, INTERFACE, UNION
+      argument :location, String, required: true
+      argument :key, String, required: true
+      argument :field, String, required: true
+      argument :arg, String, required: true
+      argument :list, Boolean, required: false
+      argument :federation, Boolean, required: false
+      repeatable true
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Supergraph
+    class SourceDirective < GraphQL::Schema::Directive
+      graphql_name "source"
+      locations FIELD_DEFINITION
+      argument :location, String, required: true
+      repeatable true
+    end
+  end
+end

data/lib/graphql/stitching/supergraph.rb

@@ -1,29 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "./supergraph/resolver_directive"
+require_relative "./supergraph/source_directive"
+
 module GraphQL
   module Stitching
     class Supergraph
       SUPERGRAPH_LOCATION = "__super"
 
-      class ResolverDirective < GraphQL::Schema::Directive
-        graphql_name "resolver"
-        locations OBJECT, INTERFACE, UNION
-        argument :location, String, required: true
-        argument :key, String, required: true
-        argument :field, String, required: true
-        argument :arg, String, required: true
-        argument :list, Boolean, required: false
-        argument :federation, Boolean, required: false
-        repeatable true
-      end
-
-      class SourceDirective < GraphQL::Schema::Directive
-        graphql_name "source"
-        locations FIELD_DEFINITION
-        argument :location, String, required: true
-        repeatable true
-      end
-
       class << self
         def validate_executable!(location, executable)
           return true if executable.is_a?(Class) && executable <= GraphQL::Schema
@@ -88,19 +72,27 @@ module GraphQL
         end
       end
 
-      attr_reader :schema, :boundaries, :locations_by_type_and_field, :executables
+      # @return [GraphQL::Schema] the composed schema for the supergraph.
+      attr_reader :schema
+
+      # @return [Hash<String, Executable>] a map of executable resources by location.
+      attr_reader :executables
+
+      attr_reader :boundaries, :locations_by_type_and_field
 
       def initialize(schema:, fields: {}, boundaries: {}, executables: {})
         @schema = schema
+        @schema.use(GraphQL::Schema::AlwaysVisible)
+
         @boundaries = boundaries
-        @possible_keys_by_type = {}
-        @possible_keys_by_type_and_location = {}
-        @memoized_schema_possible_types = {}
-        @memoized_schema_fields = {}
-        @memoized_introspection_types = nil
-        @memoized_schema_types = nil
         @fields_by_type_and_location = nil
         @locations_by_type = nil
+        @memoized_introspection_types = nil
+        @memoized_schema_fields = {}
+        @memoized_schema_types = nil
+        @possible_keys_by_type = {}
+        @possible_keys_by_type_and_location = {}
+        @static_validator = nil
 
         # add introspection types into the fields mapping
         @locations_by_type_and_field = memoized_introspection_types.each_with_object(fields) do |(type_name, type), memo|
@@ -172,6 +164,11 @@ module GraphQL
         @schema.to_definition
       end
 
+      # @return [GraphQL::StaticValidation::Validator] static validator for the supergraph schema.
+      def static_validator
+        @static_validator ||= @schema.static_validator
+      end
+
       def fields
         @locations_by_type_and_field.reject { |k, _v| memoized_introspection_types[k] }
       end
@@ -188,10 +185,6 @@ module GraphQL
         @memoized_schema_types ||= @schema.types
       end
 
-      def memoized_schema_possible_types(type_name)
-        @memoized_schema_possible_types[type_name] ||= @schema.possible_types(memoized_schema_types[type_name])
-      end
-
       def memoized_schema_fields(type_name)
         @memoized_schema_fields[type_name] ||= begin
           fields = memoized_schema_types[type_name].fields
@@ -252,7 +245,11 @@ module GraphQL
       # ("Type") => ["id", ...]
       def possible_keys_for_type(type_name)
         @possible_keys_by_type[type_name] ||= begin
-          @boundaries[type_name].map(&:key).tap(&:uniq!)
+          if type_name == @schema.query.graphql_name
+            GraphQL::Stitching::EMPTY_ARRAY
+          else
+            @boundaries[type_name].map(&:key).tap(&:uniq!)
+          end
         end
       end
 
@@ -269,16 +266,25 @@ module GraphQL
       # 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
       def route_type_to_locations(type_name, start_location, goal_locations)
-        if possible_keys_for_type(type_name).length > 1
+        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
+          goal_locations.each_with_object({}) do |goal_location, memo|
+            memo[goal_location] = [Boundary.new(location: goal_location)]
+          end
+
+        elsif key_count > 1
           # multiple keys use an A* search to traverse intermediary locations
-          return route_type_to_locations_via_search(type_name, start_location, goal_locations)
-        end
+          route_type_to_locations_via_search(type_name, start_location, goal_locations)
 
-        # 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]
+        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]
+            end
           end
         end
       end

data/lib/graphql/stitching/util.rb

@@ -54,7 +54,7 @@ module GraphQL
           return parent_type.possible_types if parent_type.kind.union?
 
           result = []
-          schema.types.values.each do |type|
+          schema.types.each_value do |type|
             next unless type <= GraphQL::Schema::Interface && type != parent_type
             next unless type.interfaces.include?(parent_type)
             result << type

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.2.0"
+    VERSION = "1.2.2"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.2
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-29 00:00:00.000000000 Z
+date: 2024-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -74,6 +74,7 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
 - ".gitignore"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - README.md
@@ -81,13 +82,11 @@ files:
 - docs/README.md
 - docs/client.md
 - docs/composer.md
-- docs/executor.md
 - docs/http_executable.md
 - docs/images/library.png
 - docs/images/merging.png
 - docs/images/stitching.png
 - docs/mechanics.md
-- docs/planner.md
 - docs/request.md
 - docs/supergraph.md
 - examples/file_uploads/Gemfile
@@ -125,6 +124,8 @@ files:
 - lib/graphql/stitching/shaper.rb
 - lib/graphql/stitching/skip_include.rb
 - lib/graphql/stitching/supergraph.rb
+- lib/graphql/stitching/supergraph/resolver_directive.rb
+- lib/graphql/stitching/supergraph/source_directive.rb
 - lib/graphql/stitching/util.rb
 - lib/graphql/stitching/version.rb
 homepage: https://github.com/gmac/graphql-stitching-ruby

data/docs/executor.md

@@ -1,68 +0,0 @@
-## GraphQL::Stitching::Executor
-
-An `Executor` accepts a [`Supergraph`](./supergraph.md), a [query plan hash](./planner.md), and optional request variables. It handles executing requests and merging results collected from across graph locations.
-
-```ruby
-query = <<~GRAPHQL
-  query MyQuery($id: ID!) {
-    product(id:$id) {
-      title
-      brands { name }
-    }
-  }
-GRAPHQL
-
-request = GraphQL::Stitching::Request.new(
-  supergraph,
-  query,
-  variables: { "id" => "123" },
-  operation_name: "MyQuery",
-  context: { ... },
-)
-
-# Via Request:
-result = request.execute
-
-# Via Executor:
-result = GraphQL::Stitching::Executor.new(request).perform
-```
-
-### Raw results
-
-By default, execution results are always returned with document shaping (stitching additions removed, missing fields added, null bubbling applied). You may access the raw execution result by calling the `perform` method with a `raw: true` argument:
-
-```ruby
-# get the raw result without shaping using either form:
-raw_result = request.execute(raw: true)
-raw_result = GraphQL::Stitching::Executor.new(request).perform(raw: true)
-```
-
-The raw result will contain many irregularities from the stitching process, however may be insightful when debugging inconsistencies in results:
-
-```ruby
-{
-  "data" => {
-    "product" => {
-      "upc" => "1",
-      "_export_upc" => "1",
-      "_export_typename" => "Product",
-      "name" => "iPhone",
-      "price" => nil,
-    }
-  }
-}
-```
-
-### Batching
-
-The Executor batches together as many requests as possible to a given location at a given time. Batched queries are written with the operation name suffixed by all operation keys in the batch, and root stitching fields are each prefixed by their batch index and collection index (for non-list fields):
-
-```graphql
-query MyOperation_2_3($lang:String!,$currency:Currency!){
-  _0_result: storefronts(ids:["7","8"]) { name(lang:$lang) }
-  _1_0_result: product(upc:"abc") { price(currency:$currency) }
-  _1_1_result: product(upc:"xyz") { price(currency:$currency) }
-}
-```
-
-All told, the executor will make one request per location per generation of data. Generations started on separate forks of the resolution tree will be resolved independently.

data/docs/planner.md

@@ -1,45 +0,0 @@
-## GraphQL::Stitching::Planner
-
-A `Planner` generates a query plan for a given [`Supergraph`](./supergraph.md) and [`Request`](./request.md). The generated plan breaks down all the discrete GraphQL operations that must be delegated across locations and their sequencing.
-
-```ruby
-document = <<~GRAPHQL
-  query MyQuery($id: ID!) {
-    product(id:$id) {
-      title
-      brands { name }
-    }
-  }
-GRAPHQL
-
-request = GraphQL::Stitching::Request.new(
-  supergraph,
-  document,
-  variables: { "id" => "1" },
-  operation_name: "MyQuery",
-).prepare!
-
-# Via Request:
-plan = request.plan
-
-# Via Planner:
-plan = GraphQL::Stitching::Planner.new(request).perform
-```
-
-### Caching
-
-Plans are designed to be cacheable. This is very useful for redundant GraphQL documents (commonly sent by frontend clients) where there's no sense in planning every request individually. It's far more efficient to generate a plan once and cache it, then simply retreive the plan and execute it for future requests.
-
-```ruby
-cached_plan = $cache.get(request.digest)
-
-if cached_plan
-  plan = GraphQL::Stitching::Plan.from_json(JSON.parse(cached_plan))
-  request.plan(plan)
-else
-  plan = request.plan
-  $cache.set(request.digest, JSON.generate(plan.as_json))
-end
-
-# execute the plan...
-```