graphql-stitching 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ff6bbdb8e949da02a0ed58f6db5ab56a6e622d9befc436042dcaaed6556a0f0
-  data.tar.gz: ecb682677bb576a3742e1a0ebf8eabe4d17e2dfbc214120aed4cbef09db881df
+  metadata.gz: 4a0b6a79a253614edadb1151490e42e32164e9f10c8e110806978160efd8b482
+  data.tar.gz: ff9d5a50b4bc41392a2777fc7bbdf401820a0fea899ef43736047f0efb196742
 SHA512:
-  metadata.gz: 506a02bced23940043c43bfb59b4a3cba9cf98c7177f0f0abe58b16b0543498cb7acdeecac4d44d22d867d3dd12f3be756236b36ac534e22eb3ed2f347f16984
-  data.tar.gz: b409cbe17f3d4792bb8aa4ae0553d8d15dcb5a5316999248a66644fabae67133036804f9a34d805b3bed58e11e40158ca36444365f80773e945c2b586588fd39
+  metadata.gz: ffb8d232df37ff5b858f95344566774c314132c89bd4353b84ad603d54f1242581df452aef50db0ec4193428a6de72179063bf1213cd74ce0038b0a5cd5aad9b
+  data.tar.gz: 585e94aaaf146a642f36cb184c91e69aacd8ed9988fd4c4cfc350feb83662b4955cb72d5efe2bdf7606f198a5f03b51d0f809fade8ba8e25367479d3d5902c44

data/README.md

@@ -9,7 +9,7 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 - Multiple keys per merged type.
 - Shared objects, fields, enums, and inputs across locations.
 - Combining local and remote schemas.
-- Type merging via federation `_entities` protocol.
+- Type merging via arbitrary queries or federation `_entities` protocol.
 
 **NOT Supported:**
 - Computed fields (ie: federation-style `@requires`).
@@ -400,6 +400,26 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
 
 The `GraphQL::Stitching::HttpExecutable` class is provided as a simple executable wrapper around `Net::HTTP.post`. You should build your own executables to leverage your existing libraries and to add instrumentation. Note that you must manually assign all executables to a `Supergraph` when rehydrating it from cache ([see docs](./docs/supergraph.md)).
 
+## Batching
+
+The stitching executor automatically batches subgraph requests so that only one request is made per location per generation of data. This is done using batched queries that combine all data access for a given a location. For example:
+
+```graphql
+query MyOperation_2 {
+  _0_result: widgets(ids:["a","b","c"]) { ... } # << 3 Widget
+  _1_0_result: sprocket(id:"x") { ... } # << 1 Sprocket
+  _1_1_result: sprocket(id:"y") { ... } # << 1 Sprocket
+  _1_2_result: sprocket(id:"z") { ... } # << 1 Sprocket
+}
+```
+
+Tips:
+
+* List queries (like the `widgets` selection above) are more compact for accessing multiple records, and are therefore preferable as stitching accessors.
+* Assure that root field resolvers across your subgraph implement batching to anticipate cases like the three `sprocket` selections above.
+
+Otherwise, there's no developer intervention necessary (or generally possible) to improve upon data access. Note that multiple generations of data may still force the executor to return to a previous location for more data.
+
 ## Concurrency
 
 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.

data/lib/graphql/stitching/boundary.rb

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

data/lib/graphql/stitching/client.rb

@@ -41,7 +41,7 @@ module GraphQL
           GraphQL::Stitching::Planner.new(
             supergraph: @supergraph,
             request: request,
-          ).perform.to_h
+          ).perform
         end
 
         GraphQL::Stitching::Executor.new(
@@ -76,16 +76,16 @@ module GraphQL
       def fetch_plan(request)
         if @on_cache_read
           cached_plan = @on_cache_read.call(request.digest, request.context)
-          return JSON.parse(cached_plan) if cached_plan
+          return GraphQL::Stitching::Plan.from_json(JSON.parse(cached_plan)) if cached_plan
         end
 
-        plan_json = yield
+        plan = yield
 
         if @on_cache_write
-          @on_cache_write.call(request.digest, JSON.generate(plan_json), request.context)
+          @on_cache_write.call(request.digest, JSON.generate(plan.as_json), request.context)
         end
 
-        plan_json
+        plan
       end
 
       def error_result(errors)

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

@@ -32,16 +32,16 @@ module GraphQL
 
         # only one boundary allowed per type/location/key
         boundaries_by_location_and_key = boundaries.each_with_object({}) do |boundary, memo|
-          if memo.dig(boundary["location"], boundary["key"])
-            raise Composer::ValidationError, "Multiple boundary queries for `#{type.graphql_name}.#{boundary["key"]}` "\
-              "found in #{boundary["location"]}. Limit one boundary query per type and key in each location. "\
+          if memo.dig(boundary.location, boundary.key)
+            raise Composer::ValidationError, "Multiple boundary queries for `#{type.graphql_name}.#{boundary.key}` "\
+              "found in #{boundary.location}. Limit one boundary query per type and key in each location. "\
               "Abstract boundaries provide all possible types."
           end
-          memo[boundary["location"]] ||= {}
-          memo[boundary["location"]][boundary["key"]] = boundary
+          memo[boundary.location] ||= {}
+          memo[boundary.location][boundary.key] = boundary
         end
 
-        boundary_keys = boundaries.map { _1["key"] }.uniq
+        boundary_keys = boundaries.map { _1.key }.uniq
         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

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

@@ -32,12 +32,12 @@ module GraphQL
               interface_type_structure.each_with_index do |interface_struct, index|
                 possible_struct = possible_type_structure[index]
 
-                if possible_struct[:name] != interface_struct[:name]
+                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]
+                if possible_struct.null? && interface_struct.non_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

data/lib/graphql/stitching/composer.rb

@@ -430,21 +430,21 @@ module GraphQL
             raise ComposerError, "Cannot compose mixed list structures at `#{path}`."
           end
 
-          if alt_structure.last[:name] != basis_structure.last[:name]
+          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.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] }
+          non_null = alt_structures.each_with_object([basis.non_null?]) { |s, m| m << s[rev_index].non_null? }
 
-          type = type.to_list_type if basis[:list]
+          type = type.to_list_type if basis.list?
           type = type.to_non_null_type if argument_name ? non_null.any? : non_null.all?
         end
 
@@ -509,15 +509,15 @@ module GraphQL
               end
 
               @boundary_map[impl_type_name] ||= []
-              @boundary_map[impl_type_name] << {
-                "location" => location,
-                "type_name" => impl_type_name,
-                "key" => key_selections[0].name,
-                "field" => field_candidate.name,
-                "arg" => argument_name,
-                "list" => boundary_structure.first[:list],
-                "federation" => kwargs[:federation],
-              }.compact
+              @boundary_map[impl_type_name] << Boundary.new(
+                location: location,
+                type_name: impl_type_name,
+                key: key_selections[0].name,
+                field: field_candidate.name,
+                arg: argument_name,
+                list: boundary_structure.first.list?,
+                federation: kwargs[:federation],
+              )
             end
           end
         end

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

@@ -10,20 +10,24 @@ module GraphQL
 
       def fetch(ops)
         origin_sets_by_operation = ops.each_with_object({}) do |op, memo|
-          origin_set = op["path"].reduce([@executor.data]) do |set, path_segment|
+          origin_set = op.path.reduce([@executor.data]) do |set, path_segment|
             set.flat_map { |obj| obj && obj[path_segment] }.tap(&:compact!)
           end
 
-          if op["if_type"]
+          if op.if_type
             # operations planned around unused fragment conditions should not trigger requests
-            origin_set.select! { _1["_STITCH_typename"] == op["if_type"] }
+            origin_set.select! { _1[SelectionHint.typename_node.alias] == op.if_type }
           end
 
           memo[op] = origin_set if origin_set.any?
         end
 
         if origin_sets_by_operation.any?
-          query_document, variable_names = build_document(origin_sets_by_operation, @executor.request.operation_name)
+          query_document, variable_names = build_document(
+            origin_sets_by_operation,
+            @executor.request.operation_name,
+            @executor.request.operation_directives,
+          )
           variables = @executor.request.variables.slice(*variable_names)
           raw_result = @executor.supergraph.execute_at_location(@location, query_document, variables, @executor.request.context)
           @executor.query_count += 1
@@ -34,7 +38,7 @@ module GraphQL
           @executor.errors.concat(extract_errors!(origin_sets_by_operation, errors)) if errors&.any?
         end
 
-        ops.map { origin_sets_by_operation[_1] ? _1["order"] : nil }
+        ops.map { origin_sets_by_operation[_1] ? _1.step : nil }
       end
 
       # Builds batched boundary queries
@@ -44,24 +48,24 @@ module GraphQL
       #   _1_1_result: item(key:"y") { boundarySelections... }
       #   _1_2_result: item(key:"z") { boundarySelections... }
       # }"
-      def build_document(origin_sets_by_operation, operation_name = nil)
+      def build_document(origin_sets_by_operation, operation_name = nil, operation_directives = nil)
         variable_defs = {}
         query_fields = origin_sets_by_operation.map.with_index do |(op, origin_set), batch_index|
-          variable_defs.merge!(op["variables"])
-          boundary = op["boundary"]
+          variable_defs.merge!(op.variables)
+          boundary = op.boundary
 
-          if boundary["list"]
+          if boundary.list
             input = origin_set.each_with_index.reduce(String.new) do |memo, (origin_obj, index)|
               memo << "," if index > 0
-              memo << build_key(boundary["key"], origin_obj, federation: boundary["federation"])
+              memo << build_key(boundary.key, origin_obj, federation: boundary.federation)
               memo
             end
 
-            "_#{batch_index}_result: #{boundary["field"]}(#{boundary["arg"]}:[#{input}]) #{op["selections"]}"
+            "_#{batch_index}_result: #{boundary.field}(#{boundary.arg}:[#{input}]) #{op.selections}"
           else
             origin_set.map.with_index do |origin_obj, index|
-              input = build_key(boundary["key"], origin_obj, federation: boundary["federation"])
-              "_#{batch_index}_#{index}_result: #{boundary["field"]}(#{boundary["arg"]}:#{input}) #{op["selections"]}"
+              input = build_key(boundary.key, origin_obj, federation: boundary.federation)
+              "_#{batch_index}_#{index}_result: #{boundary.field}(#{boundary.arg}:#{input}) #{op.selections}"
             end
           end
         end
@@ -71,7 +75,7 @@ module GraphQL
         if operation_name
           doc << " #{operation_name}"
           origin_sets_by_operation.each_key do |op|
-            doc << "_#{op["order"]}"
+            doc << "_#{op.step}"
           end
         end
 
@@ -80,15 +84,19 @@ module GraphQL
           doc << "(#{variable_str})"
         end
 
+        if operation_directives
+          doc << " #{operation_directives} "
+        end
+
         doc << "{ #{query_fields.join(" ")} }"
 
         return doc, variable_defs.keys
       end
 
       def build_key(key, origin_obj, federation: false)
-        key_value = JSON.generate(origin_obj["_STITCH_#{key}"])
+        key_value = JSON.generate(origin_obj[SelectionHint.key(key)])
         if federation
-          "{ __typename: \"#{origin_obj["_STITCH_typename"]}\", #{key}: #{key_value} }"
+          "{ __typename: \"#{origin_obj[SelectionHint.typename_node.alias]}\", #{key}: #{key_value} }"
         else
           key_value
         end

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

@@ -11,9 +11,13 @@ module GraphQL
       def fetch(ops)
         op = ops.first # There should only ever be one per location at a time
 
-        query_document = build_document(op, @executor.request.operation_name)
-        query_variables = @executor.request.variables.slice(*op["variables"].keys)
-        result = @executor.supergraph.execute_at_location(op["location"], query_document, query_variables, @executor.request.context)
+        query_document = build_document(
+          op,
+          @executor.request.operation_name,
+          @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.context)
         @executor.query_count += 1
 
         @executor.data.merge!(result["data"]) if result["data"]
@@ -22,25 +26,29 @@ module GraphQL
           @executor.errors.concat(result["errors"])
         end
 
-        ops.map { op["order"] }
+        ops.map(&:step)
       end
 
       # Builds root source documents
       # "query MyOperation_1($var:VarType) { rootSelections ... }"
-      def build_document(op, operation_name = nil)
+      def build_document(op, operation_name = nil, operation_directives = nil)
         doc = String.new
-        doc << op["operation_type"]
+        doc << op.operation_type
 
         if operation_name
-          doc << " #{operation_name}_#{op["order"]}"
+          doc << " #{operation_name}_#{op.step}"
         end
 
-        if op["variables"].any?
-          variable_defs = op["variables"].map { |k, v| "$#{k}:#{v}" }.join(",")
+        if op.variables.any?
+          variable_defs = op.variables.map { |k, v| "$#{k}:#{v}" }.join(",")
           doc << "(#{variable_defs})"
         end
 
-        doc << op["selections"]
+        if operation_directives
+          doc << " #{operation_directives} "
+        end
+
+        doc << op.selections
         doc
       end
     end

data/lib/graphql/stitching/executor.rb

@@ -5,13 +5,13 @@ require "json"
 module GraphQL
   module Stitching
     class Executor
-      attr_reader :supergraph, :request, :data, :errors
+      attr_reader :supergraph, :request, :plan, :data, :errors
       attr_accessor :query_count
 
       def initialize(supergraph:, request:, plan:, nonblocking: false)
         @supergraph = supergraph
         @request = request
-        @queue = plan["ops"]
+        @plan = plan
         @data = {}
         @errors = []
         @query_count = 0
@@ -39,22 +39,20 @@ module GraphQL
 
       private
 
-      def exec!(next_ordinals = [0])
-        if @exec_cycles > @queue.length
+      def exec!(next_steps = [0])
+        if @exec_cycles > @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 = @queue
-            .select { next_ordinals.include?(_1["after"]) }
-            .group_by { [_1["location"], _1["boundary"].nil?] }
+          tasks = @plan
+            .ops
+            .select { next_steps.include?(_1.after) }
+            .group_by { [_1.location, _1.boundary.nil?] }
             .map do |(location, root_source), ops|
-              if root_source
-                @dataloader.with(RootSource, self, location).request_all(ops)
-              else
-                @dataloader.with(BoundarySource, self, location).request_all(ops)
-              end
+              source_type = root_source ? RootSource : BoundarySource
+              @dataloader.with(source_type, self, location).request_all(ops)
             end
 
           tasks.each(&method(:exec_task))
@@ -65,8 +63,8 @@ module GraphQL
       end
 
       def exec_task(task)
-        next_ordinals = task.load.tap(&:compact!)
-        exec!(next_ordinals) if next_ordinals.any?
+        next_steps = task.load.tap(&:compact!)
+        exec!(next_steps) if next_steps.any?
       end
     end
   end

data/lib/graphql/stitching/plan.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    # Immutable structures representing a query plan.
+    # May serialize to/from JSON.
+    class Plan
+      Op = Struct.new(
+        :step,
+        :after,
+        :location,
+        :operation_type,
+        :selections,
+        :variables,
+        :path,
+        :if_type,
+        :boundary,
+        keyword_init: true
+      ) do
+        def as_json
+          {
+            step: step,
+            after: after,
+            location: location,
+            operation_type: operation_type,
+            selections: selections,
+            variables: variables,
+            path: path,
+            if_type: if_type,
+            boundary: boundary&.as_json
+          }.tap(&:compact!)
+        end
+      end
+
+      class << self
+        def from_json(json)
+          ops = json["ops"]
+          ops = ops.map do |op|
+            boundary = op["boundary"]
+            Op.new(
+              step: op["step"],
+              after: op["after"],
+              location: op["location"],
+              operation_type: op["operation_type"],
+              selections: op["selections"],
+              variables: op["variables"],
+              path: op["path"],
+              if_type: op["if_type"],
+              boundary: boundary ? GraphQL::Stitching::Boundary.new(**boundary) : nil,
+            )
+          end
+          new(ops: ops)
+        end
+      end
+
+      attr_reader :ops
+
+      def initialize(ops: [])
+        @ops = ops
+      end
+
+      def as_json
+        { ops: @ops.map(&:as_json) }
+      end
+    end
+  end
+end