graphql-stitching 0.3.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3cb133db35cdb705f296a2fe67909bfe2f07baefc873cf502ba48dbd53e8c6a
-  data.tar.gz: c81040a57f364a1a8a045bf079428cfae3c8a5886d2f7d0aaae45844c055b92e
+  metadata.gz: 9ff6bbdb8e949da02a0ed58f6db5ab56a6e622d9befc436042dcaaed6556a0f0
+  data.tar.gz: ecb682677bb576a3742e1a0ebf8eabe4d17e2dfbc214120aed4cbef09db881df
 SHA512:
-  metadata.gz: dc2a8d99942c2a5e1558ded0fbb467dd96d4bdb30c5a2ff9aa2348161ae28073cf36b2b56e51b0d92b757f68a87366ab1750e716bf0939d1645bf1ddee2049f5
-  data.tar.gz: 599760134f3f59f6ec5285e0d0976e1e9c07ba4103a74341bb35d1dacb89d0026383da2f4c2ca47d33ce3971510d9dddcc61d90a5248342406a4787f650d6126
+  metadata.gz: 506a02bced23940043c43bfb59b4a3cba9cf98c7177f0f0abe58b16b0543498cb7acdeecac4d44d22d867d3dd12f3be756236b36ac534e22eb3ed2f347f16984
+  data.tar.gz: b409cbe17f3d4792bb8aa4ae0553d8d15dcb5a5316999248a66644fabae67133036804f9a34d805b3bed58e11e40158ca36444365f80773e945c2b586588fd39

data/README.md

@@ -9,6 +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.
 
 **NOT Supported:**
 - Computed fields (ie: federation-style `@requires`).
@@ -32,7 +33,7 @@ require "graphql/stitching"
 
 ## Usage
 
-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):
+The quickest way to start is to use the provided [`Client`](./docs/client.md) component that wraps a stitched graph in an executable workflow with [caching hooks](./docs/client.md#cache-hooks):
 
 ```ruby
 movies_schema = <<~GRAPHQL
@@ -45,21 +46,21 @@ showtimes_schema = <<~GRAPHQL
   type Query { showtime(id: ID!): Showtime }
 GRAPHQL
 
-gateway = GraphQL::Stitching::Gateway.new(locations: {
+client = GraphQL::Stitching::Client.new(locations: {
   movies: {
     schema: GraphQL::Schema.from_definition(movies_schema),
-    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3000"),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3000"),
   },
   showtimes: {
     schema: GraphQL::Schema.from_definition(showtimes_schema),
-    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001"),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
   },
   my_local: {
     schema: MyLocal::GraphQL::Schema,
   },
 })
 
-result = gateway.execute(
+result = client.execute(
   query: "query FetchFromAll($movieId:ID!, $showtimeId:ID!){
     movie(id:$movieId) { name }
     showtime(id:$showtimeId): { time }
@@ -72,7 +73,7 @@ result = gateway.execute(
 
 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` constructor is an easy quick start, the library also has several discrete components that can be assembled into custom workflows:
+While the `Client` 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.
@@ -86,7 +87,11 @@ While the `Gateway` constructor is an easy quick start, the library also has sev
 
 ![Merging types](./docs/images/merging.png)
 
-To facilitate this merging of types, stitching must know how to cross-reference and fetch each variant of a type from its source location. This is done using the `@stitch` directive:
+To facilitate this merging of types, stitching must know how to cross-reference and fetch each variant of a type from its source location. This can be done using [arbitrary queries](#merged-types-via-arbitrary-queries) or [federation entities](#merged-types-via-federation-entities).
+
+### Merged types via arbitrary queries
+
+Types can merge through arbitrary queries using the `@stitch` directive:
 
 ```graphql
 directive @stitch(key: String!) repeatable on FIELD_DEFINITION
@@ -121,14 +126,14 @@ shipping_schema = <<~GRAPHQL
   }
 GRAPHQL
 
-supergraph = GraphQL::Stitching::Composer.new.perform({
+client = GraphQL::Stitching::Client.new(locations: {
   products: {
     schema: GraphQL::Schema.from_definition(products_schema),
-    executable:  GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001"),
+    executable:  GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
   },
   shipping: {
     schema: GraphQL::Schema.from_definition(shipping_schema),
-    executable:  GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3002"),
+    executable:  GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
   },
 })
 ```
@@ -294,6 +299,66 @@ The library is configured to use a `@stitch` directive by default. You may custo
 GraphQL::Stitching.stitch_directive = "merge"
 ```
 
+### Merged types via Federation entities
+
+The [Apollo Federation specification](https://www.apollographql.com/docs/federation/subgraph-spec/) defines a standard interface for accessing merged type variants across locations. Stitching can utilize a _subset_ of this interface to facilitate basic type merging. The following spec is supported:
+
+- `@key(fields: "id")` (repeatable) specifies a key field for an object type. The key `fields` argument may only contain one field selection.
+- `_Entity` is a union type that must contain all types that implement a `@key`.
+- `_Any` is a scalar that recieves raw JSON objects; each object representation contains a `__typename` and the type's key field.
+- `_entities(representations: [_Any!]!): [_Entity]!` is a root query for local entity types.
+
+The composer will automatcially detect and stitch schemas with an `_entities` query, for example:
+
+```ruby
+accounts_schema = <<~GRAPHQL
+  directive @key(fields: String!) repeatable on OBJECT
+
+  type User @key(fields: "id") {
+    id: ID!
+    name: String!
+    address: String!
+  }
+
+  union _Entity = User
+  scalar _Any
+
+  type Query {
+    user(id: ID!): User
+    _entities(representations: [_Any!]!): [_Entity]!
+  }
+GRAPHQL
+
+comments_schema = <<~GRAPHQL
+  directive @key(fields: String!) repeatable on OBJECT
+
+  type User @key(fields: "id") {
+    id: ID!
+    comments: [String!]!
+  }
+
+  union _Entity = User
+  scalar _Any
+
+  type Query {
+    _entities(representations: [_Any!]!): [_Entity]!
+  }
+GRAPHQL
+
+client = GraphQL::Stitching::Client.new(locations: {
+  accounts: {
+    schema: GraphQL::Schema.from_definition(accounts_schema),
+    executable: ...,
+  },
+  comments: {
+    schema: GraphQL::Schema.from_definition(comments_schema),
+    executable: ...,
+  },
+})
+```
+
+It's perfectly fine to mix and match schemas that implement an `_entities` query with schemas that implement `@stitch` directives; the protocols achieve the same result. Note that stitching is much simpler than Apollo Federation by design, and that Federation's advanced routing features (such as the `@requires` and `@external` directives) will not work with stitching.
+
 ## Executables
 
 An executable resource performs location-specific GraphQL requests. Executables may be `GraphQL::Schema` classes, or any object that responds to `.call(location, source, variables, context)` and returns a raw GraphQL response:
@@ -320,7 +385,7 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
   },
   second: {
     schema: SecondSchema,
-    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001", headers: { ... }),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001", headers: { ... }),
   },
   third: {
     schema: ThirdSchema,
@@ -333,7 +398,7 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
 })
 ```
 
-The `GraphQL::Stitching::RemoteClient` 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)).
+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)).
 
 ## Concurrency
 

data/docs/README.md

@@ -6,7 +6,7 @@ This module provides a collection of components that may be composed into a stit
 
 Major components include:
 
-- [Gateway](./gateway.md) - an out-of-the-box stitching configuration.
+- [Client](./client.md) - an out-of-the-box setup for performing stitched requests.
 - [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.

data/docs/client.md

@@ -0,0 +1,103 @@
+## GraphQL::Stitching::Client
+
+The `Client` is an out-of-the-box convenience with all stitching components assembled into a default workflow. A client is designed to work for most common needs, though you're welcome to assemble the component parts into your own configuration (see the [client source](../lib/graphql/stitching/client.rb) for an example). A client is constructed with the same [location settings](./composer.md#performing-composition) used to perform supergraph composition:
+
+```ruby
+movies_schema = "type Query { ..."
+showtimes_schema = "type Query { ..."
+
+client = GraphQL::Stitching::Client.new(locations: {
+  products: {
+    schema: GraphQL::Schema.from_definition(movies_schema),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3000"),
+    stitch: [{ field_name: "products", key: "id" }],
+  },
+  showtimes: {
+    schema: GraphQL::Schema.from_definition(showtimes_schema),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
+  },
+  my_local: {
+    schema: MyLocal::GraphQL::Schema,
+  },
+})
+```
+
+Alternatively, you may pass a prebuilt `Supergraph` instance to the `Client` constructor. This is useful when [exporting and rehydrating](./supergraph.md#export-and-caching) supergraph instances, which bypasses the need for runtime composition:
+
+```ruby
+exported_schema = "type Query { ..."
+exported_mapping = JSON.parse("{ ... }")
+supergraph = GraphQL::Stitching::Supergraph.from_export(
+  schema: exported_schema,
+  delegation_map: exported_mapping,
+  executables: { ... },
+)
+
+client = GraphQL::Stitching::Client.new(supergraph: supergraph)
+```
+
+### Execution
+
+A client provides an `execute` method with a subset of arguments provided by [`GraphQL::Schema.execute`](https://graphql-ruby.org/queries/executing_queries). Executing requests on a stitching client becomes mostly a drop-in replacement to executing on a `GraphQL::Schema` instance:
+
+```ruby
+result = client.execute(
+  query: "query MyProduct($id: ID!) { product(id: $id) { name } }",
+  variables: { "id" => "1" },
+  operation_name: "MyProduct",
+)
+```
+
+Arguments for the `execute` method include:
+
+* `query`: a query (or mutation) as a string or parsed AST.
+* `variables`: a hash of variables for the request.
+* `operation_name`: the name of the operation to execute (when multiple are provided).
+* `validate`: true if static validation should run on the supergraph schema before execution.
+* `context`: an object passed through to executable calls and client hooks.
+
+### Cache hooks
+
+The client provides cache hooks to enable caching query plans across requests. Without caching, every request made to the client will be planned individually. With caching, a query may be planned once, cached, and then executed from cache for subsequent requests. Cache keys are a normalized digest of each query string.
+
+```ruby
+client.on_cache_read do |key, _context|
+  $redis.get(key) # << 3P code
+end
+
+client.on_cache_write do |key, payload, _context|
+  $redis.set(key, payload) # << 3P code
+end
+```
+
+Note that inlined input data works against caching, so you should _avoid_ this:
+
+```graphql
+query {
+  product(id: "1") { name }
+}
+```
+
+Instead, always leverage variables in queries so that the document body remains consistent across requests:
+
+```graphql
+query($id: ID!) {
+  product(id: $id) { name }
+}
+
+# variables: { "id" => "1" }
+```
+
+### Error hooks
+
+The client also provides an error hook. Any program errors rescued during execution will be passed to the `on_error` handler, which can report on the error as needed and return a formatted error message for the client to add to the [GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) result.
+
+```ruby
+client.on_error do |err, context|
+  # log the error
+  Bugsnag.notify(err)
+
+  # return a formatted message for the public response
+  "Whoops, please contact support abount request '#{context[:request_id]}'"
+end
+```

data/docs/composer.md

@@ -68,12 +68,12 @@ products_sdl = "type Query { ..."
 supergraph = GraphQL::Stitching::Composer.new.perform({
   storefronts: {
     schema: GraphQL::Schema.from_definition(storefronts_sdl),
-    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001"),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
     stitch: [{ field_name: "storefront", key: "id" }],
   },
   products: {
     schema: GraphQL::Schema.from_definition(products_sdl),
-    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3002"),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
   },
   my_local: {
     schema: MyLocalSchema,

data/docs/supergraph.md

@@ -28,7 +28,7 @@ supergraph = GraphQL::Stitching::Supergraph.from_export(
   schema: supergraph_sdl,
   delegation_map: delegation_map,
   executables: {
-    my_remote: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3000"),
+    my_remote: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3000"),
     my_local: MyLocalSchema,
   }
 )

data/example/gateway.rb

@@ -13,17 +13,17 @@ class StitchedApp
     @graphiql = file.read
     file.close
 
-    @gateway = GraphQL::Stitching::Gateway.new(locations: {
+    @client = GraphQL::Stitching::Client.new(locations: {
       products: {
         schema: Schemas::Example::Products,
       },
       storefronts: {
         schema: Schemas::Example::Storefronts,
-        executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001/graphql"),
+        executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001/graphql"),
       },
       manufacturers: {
         schema: Schemas::Example::Manufacturers,
-        executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3002/graphql"),
+        executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002/graphql"),
       }
     })
   end
@@ -34,7 +34,7 @@ class StitchedApp
     when /graphql/
       params = JSON.parse(req.body.read)
 
-      result = @gateway.execute(
+      result = @client.execute(
         query: params["query"],
         variables: params["variables"],
         operation_name: params["operationName"],

data/lib/graphql/stitching/{gateway.rb → client.rb}

@@ -4,16 +4,16 @@ require "json"
 
 module GraphQL
   module Stitching
-    class Gateway
-      class GatewayError < StitchingError; end
+    class Client
+      class ClientError < StitchingError; end
 
       attr_reader :supergraph
 
       def initialize(locations: nil, supergraph: nil, composer: nil)
         @supergraph = if locations && supergraph
-          raise GatewayError, "Cannot provide both locations and a supergraph."
+          raise ClientError, "Cannot provide both locations and a supergraph."
         elsif supergraph && !supergraph.is_a?(GraphQL::Stitching::Supergraph)
-          raise GatewayError, "Provided supergraph must be a GraphQL::Stitching::Supergraph instance."
+          raise ClientError, "Provided supergraph must be a GraphQL::Stitching::Supergraph instance."
         elsif supergraph
           supergraph
         else
@@ -57,17 +57,17 @@ module GraphQL
       end
 
       def on_cache_read(&block)
-        raise GatewayError, "A cache read block is required." unless block_given?
+        raise ClientError, "A cache read block is required." unless block_given?
         @on_cache_read = block
       end
 
       def on_cache_write(&block)
-        raise GatewayError, "A cache write block is required." unless block_given?
+        raise ClientError, "A cache write block is required." unless block_given?
         @on_cache_write = block
       end
 
       def on_error(&block)
-        raise GatewayError, "An error handler block is required." unless block_given?
+        raise ClientError, "An error handler block is required." unless block_given?
         @on_error = block
       end
 

data/lib/graphql/stitching/composer.rb

@@ -30,6 +30,7 @@ module GraphQL
         @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
+        @stitch_directives = {}
       end
 
       def perform(locations_input)
@@ -91,7 +92,7 @@ module GraphQL
           when "ENUM"
             build_enum_type(type_name, types_by_location, enum_usage)
           when "OBJECT"
-            extract_boundaries(type_name, types_by_location)
+            extract_boundaries(type_name, types_by_location) if type_name == @query_name
             build_object_type(type_name, types_by_location)
           when "INTERFACE"
             build_interface_type(type_name, types_by_location)
@@ -145,22 +146,35 @@ module GraphQL
             raise ComposerError, "The schema for `#{location}` location must be a GraphQL::Schema class."
           end
 
-          if input[:stitch]
-            stitch_directive = Class.new(GraphQL::Schema::Directive) do
-              graphql_name(GraphQL::Stitching.stitch_directive)
-              locations :FIELD_DEFINITION
-              argument :key, String
-              repeatable true
-            end
+          input.fetch(:stitch, GraphQL::Stitching::EMPTY_ARRAY).each do |dir|
+            type = dir[:parent_type_name] ? schema.types[dir[:parent_type_name]] : schema.query
+            raise ComposerError, "Invalid stitch directive type `#{dir[:parent_type_name]}`" unless type
 
-            input[:stitch].each do |dir|
-              type = dir[:type_name] ? schema.types[dir[:type_name]] : schema.query
-              raise ComposerError, "Invalid stitch directive type `#{dir[:type_name]}`" unless type
+            field = type.fields[dir[:field_name]]
+            raise ComposerError, "Invalid stitch directive field `#{dir[:field_name]}`" unless field
 
-              field = type.fields[dir[:field_name]]
-              raise ComposerError, "Invalid stitch directive field `#{dir[:field_name]}`" unless field
+            field_path = "#{location}.#{field.name}"
+            @stitch_directives[field_path] ||= []
+            @stitch_directives[field_path] << dir.slice(:key, :type_name)
+          end
 
-              field.directive(stitch_directive, **dir.slice(:key))
+          federation_entity_type = schema.types["_Entity"]
+          if federation_entity_type && federation_entity_type.kind.union? && schema.query.fields["_entities"]&.type&.unwrap == federation_entity_type
+            schema.possible_types(federation_entity_type).each do |entity_type|
+              entity_type.directives.each do |directive|
+                next unless directive.graphql_name == "key"
+
+                key = directive.arguments.keyword_arguments.fetch(:fields).strip
+                raise ComposerError, "Composite federation keys are not supported." unless /^\w+$/.match?(key)
+
+                field_path = "#{location}._entities"
+                @stitch_directives[field_path] ||= []
+                @stitch_directives[field_path] << {
+                  key: key,
+                  type_name: entity_type.graphql_name,
+                  federation: true,
+                }
+              end
             end
           end
 
@@ -462,11 +476,16 @@ module GraphQL
           type_candidate.fields.each do |field_name, field_candidate|
             boundary_type_name = field_candidate.type.unwrap.graphql_name
             boundary_structure = Util.flatten_type_structure(field_candidate.type)
+            boundary_kwargs = @stitch_directives["#{location}.#{field_name}"] || []
 
             field_candidate.directives.each do |directive|
               next unless directive.graphql_name == GraphQL::Stitching.stitch_directive
+              boundary_kwargs << directive.arguments.keyword_arguments
+            end
 
-              key = directive.arguments.keyword_arguments.fetch(:key)
+            boundary_kwargs.each do |kwargs|
+              key = kwargs.fetch(:key)
+              impl_type_name = kwargs.fetch(:type_name, boundary_type_name)
               key_selections = GraphQL.parse("{ #{key} }").definitions[0].selections
 
               if key_selections.length != 1
@@ -489,15 +508,16 @@ module GraphQL
                 raise ComposerError, "Mismatched input/output for #{type_name}.#{field_name}.#{argument_name} boundary. Arguments must map directly to results."
               end
 
-              @boundary_map[boundary_type_name] ||= []
-              @boundary_map[boundary_type_name] << {
+              @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],
-                "type_name" => boundary_type_name,
-              }
+                "federation" => kwargs[:federation],
+              }.compact
             end
           end
         end

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class Executor::BoundarySource < GraphQL::Dataloader::Source
+      def initialize(executor, location)
+        @executor = executor
+        @location = location
+      end
+
+      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|
+            set.flat_map { |obj| obj && obj[path_segment] }.tap(&:compact!)
+          end
+
+          if op["if_type"]
+            # operations planned around unused fragment conditions should not trigger requests
+            origin_set.select! { _1["_STITCH_typename"] == 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)
+          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
+
+          merge_results!(origin_sets_by_operation, raw_result.dig("data"))
+
+          errors = raw_result.dig("errors")
+          @executor.errors.concat(extract_errors!(origin_sets_by_operation, errors)) if errors&.any?
+        end
+
+        ops.map { origin_sets_by_operation[_1] ? _1["order"] : nil }
+      end
+
+      # Builds batched boundary queries
+      # "query MyOperation_2_3($var:VarType) {
+      #   _0_result: list(keys:["a","b","c"]) { boundarySelections... }
+      #   _1_0_result: item(key:"x") { boundarySelections... }
+      #   _1_1_result: item(key:"y") { boundarySelections... }
+      #   _1_2_result: item(key:"z") { boundarySelections... }
+      # }"
+      def build_document(origin_sets_by_operation, operation_name = 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"]
+
+          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
+            end
+
+            "_#{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"]}"
+            end
+          end
+        end
+
+        doc = String.new("query") # << boundary fulfillment always uses query
+
+        if operation_name
+          doc << " #{operation_name}"
+          origin_sets_by_operation.each_key do |op|
+            doc << "_#{op["order"]}"
+          end
+        end
+
+        if variable_defs.any?
+          variable_str = variable_defs.map { |k, v| "$#{k}:#{v}" }.join(",")
+          doc << "(#{variable_str})"
+        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}"])
+        if federation
+          "{ __typename: \"#{origin_obj["_STITCH_typename"]}\", #{key}: #{key_value} }"
+        else
+          key_value
+        end
+      end
+
+      def merge_results!(origin_sets_by_operation, raw_result)
+        return unless raw_result
+
+        origin_sets_by_operation.each_with_index do |(op, origin_set), batch_index|
+          results = if op.dig("boundary", "list")
+            raw_result["_#{batch_index}_result"]
+          else
+            origin_set.map.with_index { |_, index| raw_result["_#{batch_index}_#{index}_result"] }
+          end
+
+          next unless results&.any?
+
+          origin_set.each_with_index do |origin_obj, index|
+            origin_obj.merge!(results[index]) if results[index]
+          end
+        end
+      end
+
+      # https://spec.graphql.org/June2018/#sec-Errors
+      def extract_errors!(origin_sets_by_operation, errors)
+        ops = origin_sets_by_operation.keys
+        origin_sets = origin_sets_by_operation.values
+        pathed_errors_by_op_index_and_object_id = {}
+
+        errors_result = errors.each_with_object([]) do |err, memo|
+          err.delete("locations")
+          path = err["path"]
+
+          if path && path.length > 0
+            result_alias = /^_(\d+)(?:_(\d+))?_result$/.match(path.first.to_s)
+
+            if result_alias
+              path = err["path"] = path[1..-1]
+
+              origin_obj = if result_alias[2]
+                origin_sets.dig(result_alias[1].to_i, result_alias[2].to_i)
+              elsif path[0].is_a?(Integer) || /\d+/.match?(path[0].to_s)
+                origin_sets.dig(result_alias[1].to_i, path.shift.to_i)
+              end
+
+              if origin_obj
+                by_op_index = pathed_errors_by_op_index_and_object_id[result_alias[1].to_i] ||= {}
+                by_object_id = by_op_index[origin_obj.object_id] ||= []
+                by_object_id << err
+                next
+              end
+            end
+          end
+
+          memo << err
+        end
+
+        if pathed_errors_by_op_index_and_object_id.any?
+          pathed_errors_by_op_index_and_object_id.each do |op_index, pathed_errors_by_object_id|
+            repath_errors!(pathed_errors_by_object_id, ops.dig(op_index, "path"))
+            errors_result.concat(pathed_errors_by_object_id.values)
+          end
+        end
+        errors_result.flatten!
+      end
+
+      private
+
+      # traverse forward through origin data, expanding arrays to follow all paths
+      # any errors found for an origin object_id have their path prefixed by the object path
+      def repath_errors!(pathed_errors_by_object_id, forward_path, current_path=[], root=@executor.data)
+        current_path.push(forward_path.shift)
+        scope = root[current_path.last]
+
+        if forward_path.any? && scope.is_a?(Array)
+          scope.each_with_index do |element, index|
+            inner_elements = element.is_a?(Array) ? element.flatten : [element]
+            inner_elements.each do |inner_element|
+              current_path << index
+              repath_errors!(pathed_errors_by_object_id, forward_path, current_path, inner_element)
+              current_path.pop
+            end
+          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|
+            inner_elements = element.is_a?(Array) ? element.flatten : [element]
+            inner_elements.each do |inner_element|
+              errors = pathed_errors_by_object_id[inner_element.object_id]
+              errors.each { _1["path"] = [*current_path, index, *_1["path"]] } if errors
+            end
+          end
+
+        else
+          errors = pathed_errors_by_object_id[scope.object_id]
+          errors.each { _1["path"] = [*current_path, *_1["path"]] } if errors
+        end
+
+        forward_path.unshift(current_path.pop)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class Executor::RootSource < GraphQL::Dataloader::Source
+      def initialize(executor, location)
+        @executor = executor
+        @location = location
+      end
+
+      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)
+        @executor.query_count += 1
+
+        @executor.data.merge!(result["data"]) if result["data"]
+        if result["errors"]&.any?
+          result["errors"].each { _1.delete("locations") }
+          @executor.errors.concat(result["errors"])
+        end
+
+        ops.map { op["order"] }
+      end
+
+      # Builds root source documents
+      # "query MyOperation_1($var:VarType) { rootSelections ... }"
+      def build_document(op, operation_name = nil)
+        doc = String.new
+        doc << op["operation_type"]
+
+        if operation_name
+          doc << " #{operation_name}_#{op["order"]}"
+        end
+
+        if op["variables"].any?
+          variable_defs = op["variables"].map { |k, v| "$#{k}:#{v}" }.join(",")
+          doc << "(#{variable_defs})"
+        end
+
+        doc << op["selections"]
+        doc
+      end
+    end
+  end
+end

data/lib/graphql/stitching/executor.rb

@@ -5,232 +5,6 @@ require "json"
 module GraphQL
   module Stitching
     class Executor
-
-      class RootSource < GraphQL::Dataloader::Source
-        def initialize(executor, location)
-          @executor = executor
-          @location = location
-        end
-
-        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)
-          @executor.query_count += 1
-
-          @executor.data.merge!(result["data"]) if result["data"]
-          if result["errors"]&.any?
-            result["errors"].each { _1.delete("locations") }
-            @executor.errors.concat(result["errors"])
-          end
-
-          ops.map { op["order"] }
-        end
-
-        # Builds root source documents
-        # "query MyOperation_1($var:VarType) { rootSelections ... }"
-        def build_document(op, operation_name = nil)
-          doc = String.new
-          doc << op["operation_type"]
-
-          if operation_name
-            doc << " #{operation_name}_#{op["order"]}"
-          end
-
-          if op["variables"].any?
-            variable_defs = op["variables"].map { |k, v| "$#{k}:#{v}" }.join(",")
-            doc << "(#{variable_defs})"
-          end
-
-          doc << op["selections"]
-          doc
-        end
-      end
-
-      class BoundarySource < GraphQL::Dataloader::Source
-        def initialize(executor, location)
-          @executor = executor
-          @location = location
-        end
-
-        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|
-              set.flat_map { |obj| obj && obj[path_segment] }.tap(&:compact!)
-            end
-
-            if op["if_type"]
-              # operations planned around unused fragment conditions should not trigger requests
-              origin_set.select! { _1["_STITCH_typename"] == 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)
-            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
-
-            merge_results!(origin_sets_by_operation, raw_result.dig("data"))
-
-            errors = raw_result.dig("errors")
-            @executor.errors.concat(extract_errors!(origin_sets_by_operation, errors)) if errors&.any?
-          end
-
-          ops.map { origin_sets_by_operation[_1] ? _1["order"] : nil }
-        end
-
-        # Builds batched boundary queries
-        # "query MyOperation_2_3($var:VarType) {
-        #   _0_result: list(keys:["a","b","c"]) { boundarySelections... }
-        #   _1_0_result: item(key:"x") { boundarySelections... }
-        #   _1_1_result: item(key:"y") { boundarySelections... }
-        #   _1_2_result: item(key:"z") { boundarySelections... }
-        # }"
-        def build_document(origin_sets_by_operation, operation_name = 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"]
-            key_selection = "_STITCH_#{boundary["key"]}"
-
-            if boundary["list"]
-              input = JSON.generate(origin_set.map { _1[key_selection] })
-              "_#{batch_index}_result: #{boundary["field"]}(#{boundary["arg"]}:#{input}) #{op["selections"]}"
-            else
-              origin_set.map.with_index do |origin_obj, index|
-                input = JSON.generate(origin_obj[key_selection])
-                "_#{batch_index}_#{index}_result: #{boundary["field"]}(#{boundary["arg"]}:#{input}) #{op["selections"]}"
-              end
-            end
-          end
-
-          doc = String.new
-          doc << "query" # << boundary fulfillment always uses query
-
-          if operation_name
-            doc << " #{operation_name}"
-            origin_sets_by_operation.each_key do |op|
-              doc << "_#{op["order"]}"
-            end
-          end
-
-          if variable_defs.any?
-            variable_str = variable_defs.map { |k, v| "$#{k}:#{v}" }.join(",")
-            doc << "(#{variable_str})"
-          end
-
-          doc << "{ #{query_fields.join(" ")} }"
-
-          return doc, variable_defs.keys
-        end
-
-        def merge_results!(origin_sets_by_operation, raw_result)
-          return unless raw_result
-
-          origin_sets_by_operation.each_with_index do |(op, origin_set), batch_index|
-            results = if op.dig("boundary", "list")
-              raw_result["_#{batch_index}_result"]
-            else
-              origin_set.map.with_index { |_, index| raw_result["_#{batch_index}_#{index}_result"] }
-            end
-
-            next unless results&.any?
-
-            origin_set.each_with_index do |origin_obj, index|
-              origin_obj.merge!(results[index]) if results[index]
-            end
-          end
-        end
-
-        # https://spec.graphql.org/June2018/#sec-Errors
-        def extract_errors!(origin_sets_by_operation, errors)
-          ops = origin_sets_by_operation.keys
-          origin_sets = origin_sets_by_operation.values
-          pathed_errors_by_op_index_and_object_id = {}
-
-          errors_result = errors.each_with_object([]) do |err, memo|
-            err.delete("locations")
-            path = err["path"]
-
-            if path && path.length > 0
-              result_alias = /^_(\d+)(?:_(\d+))?_result$/.match(path.first.to_s)
-
-              if result_alias
-                path = err["path"] = path[1..-1]
-
-                origin_obj = if result_alias[2]
-                  origin_sets.dig(result_alias[1].to_i, result_alias[2].to_i)
-                elsif path[0].is_a?(Integer) || /\d+/.match?(path[0].to_s)
-                  origin_sets.dig(result_alias[1].to_i, path.shift.to_i)
-                end
-
-                if origin_obj
-                  by_op_index = pathed_errors_by_op_index_and_object_id[result_alias[1].to_i] ||= {}
-                  by_object_id = by_op_index[origin_obj.object_id] ||= []
-                  by_object_id << err
-                  next
-                end
-              end
-            end
-
-            memo << err
-          end
-
-          if pathed_errors_by_op_index_and_object_id.any?
-            pathed_errors_by_op_index_and_object_id.each do |op_index, pathed_errors_by_object_id|
-              repath_errors!(pathed_errors_by_object_id, ops.dig(op_index, "path"))
-              errors_result.concat(pathed_errors_by_object_id.values)
-            end
-          end
-          errors_result.flatten!
-        end
-
-        private
-
-        # traverse forward through origin data, expanding arrays to follow all paths
-        # any errors found for an origin object_id have their path prefixed by the object path
-        def repath_errors!(pathed_errors_by_object_id, forward_path, current_path=[], root=@executor.data)
-          current_path.push(forward_path.shift)
-          scope = root[current_path.last]
-
-          if forward_path.any? && scope.is_a?(Array)
-            scope.each_with_index do |element, index|
-              inner_elements = element.is_a?(Array) ? element.flatten : [element]
-              inner_elements.each do |inner_element|
-                current_path << index
-                repath_errors!(pathed_errors_by_object_id, forward_path, current_path, inner_element)
-                current_path.pop
-              end
-            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|
-              inner_elements = element.is_a?(Array) ? element.flatten : [element]
-              inner_elements.each do |inner_element|
-                errors = pathed_errors_by_object_id[inner_element.object_id]
-                errors.each { _1["path"] = [*current_path, index, *_1["path"]] } if errors
-              end
-            end
-
-          else
-            errors = pathed_errors_by_object_id[scope.object_id]
-            errors.each { _1["path"] = [*current_path, *_1["path"]] } if errors
-          end
-
-          forward_path.unshift(current_path.pop)
-        end
-      end
-
       attr_reader :supergraph, :request, :data, :errors
       attr_accessor :query_count
 
@@ -297,3 +71,6 @@ module GraphQL
     end
   end
 end
+
+require_relative "./executor/boundary_source"
+require_relative "./executor/root_source"

data/lib/graphql/stitching/{remote_client.rb → http_executable.rb}

@@ -6,7 +6,7 @@ require "json"
 
 module GraphQL
   module Stitching
-    class RemoteClient
+    class HttpExecutable
       def initialize(url:, headers:{})
         @url = url
         @headers = { "Content-Type" => "application/json" }.merge!(headers)

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "0.3.6"
+    VERSION = "1.0.0"
   end
 end

data/lib/graphql/stitching.rb

@@ -5,6 +5,7 @@ require "graphql"
 module GraphQL
   module Stitching
     EMPTY_OBJECT = {}.freeze
+    EMPTY_ARRAY = [].freeze
 
     class StitchingError < StandardError; end
 
@@ -23,13 +24,13 @@ module GraphQL
   end
 end
 
-require_relative "stitching/gateway"
 require_relative "stitching/supergraph"
+require_relative "stitching/client"
 require_relative "stitching/composer"
 require_relative "stitching/executor"
+require_relative "stitching/http_executable"
 require_relative "stitching/planner_operation"
 require_relative "stitching/planner"
-require_relative "stitching/remote_client"
 require_relative "stitching/request"
 require_relative "stitching/shaper"
 require_relative "stitching/util"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 1.0.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-11 00:00:00.000000000 Z
+date: 2023-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -80,9 +80,9 @@ files:
 - README.md
 - Rakefile
 - docs/README.md
+- docs/client.md
 - docs/composer.md
 - docs/executor.md
-- docs/gateway.md
 - docs/images/library.png
 - docs/images/merging.png
 - docs/images/stitching.png
@@ -97,15 +97,17 @@ files:
 - gemfiles/graphql_1.13.9.gemfile
 - graphql-stitching.gemspec
 - lib/graphql/stitching.rb
+- lib/graphql/stitching/client.rb
 - lib/graphql/stitching/composer.rb
 - lib/graphql/stitching/composer/base_validator.rb
 - lib/graphql/stitching/composer/validate_boundaries.rb
 - lib/graphql/stitching/composer/validate_interfaces.rb
 - lib/graphql/stitching/executor.rb
-- lib/graphql/stitching/gateway.rb
+- lib/graphql/stitching/executor/boundary_source.rb
+- lib/graphql/stitching/executor/root_source.rb
+- lib/graphql/stitching/http_executable.rb
 - lib/graphql/stitching/planner.rb
 - lib/graphql/stitching/planner_operation.rb
-- lib/graphql/stitching/remote_client.rb
 - lib/graphql/stitching/request.rb
 - lib/graphql/stitching/shaper.rb
 - lib/graphql/stitching/supergraph.rb

data/docs/gateway.md

@@ -1,103 +0,0 @@
-## GraphQL::Stitching::Gateway
-
-The `Gateway` is an out-of-the-box convenience with all stitching components assembled into a default workflow. A gateway is designed to work for most common needs, though you're welcome to assemble the component parts into your own configuration. A Gateway is constructed with the same [location settings](./composer.md#performing-composition) used to perform supergraph composition:
-
-```ruby
-movies_schema = "type Query { ..."
-showtimes_schema = "type Query { ..."
-
-gateway = GraphQL::Stitching::Gateway.new(locations: {
-  products: {
-    schema: GraphQL::Schema.from_definition(movies_schema),
-    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3000"),
-    stitch: [{ field_name: "products", key: "id" }],
-  },
-  showtimes: {
-    schema: GraphQL::Schema.from_definition(showtimes_schema),
-    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001"),
-  },
-  my_local: {
-    schema: MyLocal::GraphQL::Schema,
-  },
-})
-```
-
-Alternatively, you may pass a prebuilt `Supergraph` instance to the Gateway constructor. This is useful when [exporting and rehydrating](./supergraph.md#export-and-caching) supergraph instances, which bypasses the need for runtime composition:
-
-```ruby
-exported_schema = "type Query { ..."
-exported_mapping = JSON.parse("{ ... }")
-supergraph = GraphQL::Stitching::Supergraph.from_export(
-  schema: exported_schema,
-  delegation_map: exported_mapping,
-  executables: { ... },
-)
-
-gateway = GraphQL::Stitching::Gateway.new(supergraph: supergraph)
-```
-
-### Execution
-
-A gateway provides an `execute` method with a subset of arguments provided by [`GraphQL::Schema.execute`](https://graphql-ruby.org/queries/executing_queries). Executing requests on a stitched gateway becomes mostly a drop-in replacement to executing on a `GraphQL::Schema` instance:
-
-```ruby
-result = gateway.execute(
-  query: "query MyProduct($id: ID!) { product(id: $id) { name } }",
-  variables: { "id" => "1" },
-  operation_name: "MyProduct",
-)
-```
-
-Arguments for the `execute` method include:
-
-* `query`: a query (or mutation) as a string or parsed AST.
-* `variables`: a hash of variables for the request.
-* `operation_name`: the name of the operation to execute (when multiple are provided).
-* `validate`: true if static validation should run on the supergraph schema before execution.
-* `context`: an object passed through to executable calls and gateway hooks.
-
-### Cache hooks
-
-The gateway provides cache hooks to enable caching query plans across requests. Without caching, every request made the the gateway will be planned individually. With caching, a query may be planned once, cached, and then executed from cache for subsequent requests. Cache keys are a normalized digest of each query string.
-
-```ruby
-gateway.on_cache_read do |key, _context|
-  $redis.get(key) # << 3P code
-end
-
-gateway.on_cache_write do |key, payload, _context|
-  $redis.set(key, payload) # << 3P code
-end
-```
-
-Note that inlined input data works against caching, so you should _avoid_ this:
-
-```graphql
-query {
-  product(id: "1") { name }
-}
-```
-
-Instead, always leverage variables in queries so that the document body remains consistent across requests:
-
-```graphql
-query($id: ID!) {
-  product(id: $id) { name }
-}
-
-# variables: { "id" => "1" }
-```
-
-### Error hooks
-
-The gateway also provides an error hook. Any program errors rescued during execution will be passed to the `on_error` handler, which can report on the error as needed and return a formatted error message for the gateway to add to the [GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) result.
-
-```ruby
-gateway.on_error do |err, context|
-  # log the error
-  Bugsnag.notify(err)
-
-  # return a formatted message for the public response
-  "Whoops, please contact support abount request '#{context[:request_id]}'"
-end
-```