graphql-stitching 0.2.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a05f9ff15f40a886a20136cdaf5323cf37a59e7d98de27cc19cf7e600feb48e2
-  data.tar.gz: 7727f7394bb99abcb3c3a448f1ebf8b3bd5f9b7a2fd74e9bc741285f401a23cc
+  metadata.gz: 10489fd6a8670d5a23a7afa132d7941a242848783f3697a4d3ddd519b208a4d8
+  data.tar.gz: 7a2e8dda124bdc6e96da43e1a4ed64bbb4baeaf0065f6d8411edaeba2c52e064
 SHA512:
-  metadata.gz: f8993da51f8bd18ec1e590727a24bcba8690831e006a1a3fc861cfaa83b9794b94f90fb0e458919d7997d67606ae8ece4acfdd8a3a0d6fe669e7971b01232cf3
-  data.tar.gz: 1032ed3279a98d1bc52db321a49a0a47d78dfb00cf9a8c922d1e77217ac837f8695c146908767ec398620f42a816f92eefc339d1fde970fe543904a6a30976f5
+  metadata.gz: 4c9243880e3b41fcede7fddb5947a962f1d4c43882ba07cc0ab63d1ba154527ef4cc8e5cc130bb2524b40fcbe093ecfd2f3b8fb0bafc9a2a7324050c30d2af00
+  data.tar.gz: a2b37c3ab8b98065a0910a458e177b71576c5d8f52c6f6eba0e31d25ae7797f1517a168aeef2f39c7295d27e4f981373b7a90066dc7ab8651670ecbd41fc70d5

data/.github/workflows/ci.yml

@@ -16,6 +16,8 @@ jobs:
             ruby: 3.2
           - gemfile: Gemfile
             ruby: 3.1
+          - gemfile: gemfiles/graphql_1.13.gemfile
+            ruby: 3.1
           - gemfile: Gemfile
             ruby: 2.7
 

data/README.md

@@ -70,12 +70,12 @@ result = gateway.execute(
 )
 ```
 
-Schemas provided to the `Gateway` constructor may be class-based schemas with local resolvers (locally-executable schemas), or schemas built from SDL strings (schema definition language parsed using `GraphQL::Schema.from_definition`) and mapped to remote locations. See [composer docs](./docs/composer.md) for more information on how schemas get merged.
+Schemas provided to the `Gateway` constructor may be class-based schemas with local resolvers (locally-executable schemas), or schemas built from SDL strings (schema definition language parsed using `GraphQL::Schema.from_definition`) and mapped to remote locations. See [composer docs](./docs/composer.md#merge-patterns) for more information on how schemas get merged.
 
 While the [`Gateway`](./docs/gateway.md) constructor is an easy quick start, the library also has several discrete components that can be assembled into custom workflows:
 
-- [Composer](./docs/composer.md) - merges and validates many schemas into one graph.
-- [Supergraph](./docs/supergraph.md) - manages the combined schema and location routing maps. Can be exported, cached, and rehydrated.
+- [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.
@@ -121,17 +121,16 @@ shipping_schema = <<~GRAPHQL
   }
 GRAPHQL
 
-supergraph = GraphQL::Stitching::Composer.new(schemas: {
-  "products" => GraphQL::Schema.from_definition(products_schema),
-  "shipping" => GraphQL::Schema.from_definition(shipping_schema),
+supergraph = GraphQL::Stitching::Composer.new.perform({
+  products: {
+    schema: GraphQL::Schema.from_definition(products_schema),
+    executable:  GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001"),
+  },
+  shipping: {
+    schema: GraphQL::Schema.from_definition(shipping_schema),
+    executable:  GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3002"),
+  },
 })
-
-supergraph.assign_executable("products",
-  GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001")
-)
-supergraph.assign_executable("shipping",
-  GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3002")
-)
 ```
 
 Focusing on the `@stitch` directive usage:
@@ -255,7 +254,7 @@ The `@stitch` directive can be exported from a class-based schema to an SDL stri
 
 #### SDL-based schemas
 
-A clean SDL string may also have stitching directives applied via static configuration using the `GraphQL::Stitching` module to build the SDL into a schema:
+A clean SDL string may also have stitching directives applied via static configuration by passing a `stitch` array in [location settings](./docs/composer.md#performing-composition):
 
 ```ruby
 sdl_string = <<~GRAPHQL
@@ -269,13 +268,15 @@ sdl_string = <<~GRAPHQL
   }
 GRAPHQL
 
-decorated_schema = GraphQL::Stitching.schema_from_definition(sdl_string, stitch_directives: [
-  { type_name: "Query", field_name: "productById", key: "id" },
-  { type_name: "Query", field_name: "productByUpc", key: "upc" },
-])
-
-supergraph = GraphQL::Stitching::Composer.new(schemas: {
-  "products" => decorated_schema,
+supergraph = GraphQL::Stitching::Composer.new.perform({
+  products:  {
+    schema: GraphQL::Schema.from_definition(sdl_string),
+    executable: ->() { ... },
+    stitch: [
+      { field_name: "productById", key: "id" },
+      { field_name: "productByUpc", key: "upc" },
+    ]
+  },
   # ...
 })
 ```
@@ -290,26 +291,41 @@ GraphQL::Stitching.stitch_directive = "merge"
 
 ## Executables
 
-An executable resource performs location-specific GraphQL requests. Executables may be `GraphQL::Schema` classes, or objects that respond to `.call` with the following arguments...
+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:
 
 ```ruby
 class MyExecutable
-  def call(location, query_string, variables, context)
+  def call(location, source, variables, context)
     # process a GraphQL request...
+    return {
+      "data" => { ... },
+      "errors" => [ ... ],
+    }
   end
 end
 ```
 
-By default, a [Supergraph](./docs/supergraph.md) will use the individual `GraphQL::Schema` classes that composed it as executable resources for each location. You may assign new executables using `assign_executable`:
+A [Supergraph](./docs/supergraph.md) is composed with executable resources provided for each location. Any location that omits the `executable` option will use the provided `schema` as its default executable:
 
 ```ruby
-supergraph = GraphQL::Stitching::Composer.new(...)
-
-supergraph.assign_executable("location1", MyExecutable.new)
-supergraph.assign_executable("location2", ->(loc, query, vars, ctx) { ... })
-supergraph.assign_executable("location3") do |loc, query vars, ctx|
-  # ...
-end
+supergraph = GraphQL::Stitching::Composer.new.perform({
+  first: {
+    schema: FirstSchema,
+    # executable:^^^^^^ delegates to FirstSchema,
+  },
+  second: {
+    schema: SecondSchema,
+    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001", headers: { ... }),
+  },
+  third: {
+    schema: ThirdSchema,
+    executable: MyExecutable.new,
+  },
+  fourth: {
+    schema: FourthSchema,
+    executable: ->(loc, query, vars, ctx) { ... },
+  },
+})
 ```
 
 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)).

data/docs/composer.md

@@ -1,47 +1,92 @@
 ## GraphQL::Stitching::Composer
 
-The `Composer` receives many individual `GraphQL:Schema` instances for various graph locations and _composes_ them into a combined [`Supergraph`](./supergraph.md) that is validated for integrity. The resulting supergraph provides a combined GraphQL schema and delegation maps used to route incoming requests:
+A `Composer` receives many individual `GraphQL:Schema` instances for various graph locations and _composes_ them into a combined [`Supergraph`](./supergraph.md) that is validated for integrity.
+
+### Configuring composition
+
+A `Composer` may be constructed with optional settings that tune how it builds a schema:
+
+```ruby
+composer = GraphQL::Stitching::Composer.new(
+  query_name: "Query",
+  mutation_name: "Mutation",
+  description_merger: ->(values_by_location, info) { values_by_location.values.join("\n") },
+  deprecation_merger: ->(values_by_location, info) { values_by_location.values.first },
+  directive_kwarg_merger: ->(values_by_location, info) { values_by_location.values.last },
+)
+```
+
+Constructor arguments:
+
+- **`query_name:`** _optional_, the name of the root query type in the composed schema; `Query` by default. The root query types from all location schemas will be merged into this type, regardless of their local names.
+
+- **`mutation_name:`** _optional_, the name of the root mutation type in the composed schema; `Mutation` by default. The root mutation types from all location schemas will be merged into this type, regardless of their local names.
+
+- **`description_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging element description strings from across locations.
+
+- **`deprecation_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging element deprecation strings from across locations.
+
+- **`directive_kwarg_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging directive keyword arguments from across locations.
+
+#### Value merger functions
+
+Static data values such as element descriptions and directive arguments must also merge across locations. By default, the first non-null value encountered for a given element attribute is used. A value merger function may customize this process by selecting a different value or computing a new one:
+
+```ruby
+supergraph = GraphQL::Stitching::Composer.new(
+  description_merger: ->(values_by_location, info) { values_by_location.values.compact.join("\n") },
+)
+```
+
+A merger function receives `values_by_location` and `info` arguments; these provide possible values keyed by location and info about where in the schema these values were encountered:
+
+```ruby
+values_by_location = {
+  "storefronts" => "A fabulous data type.",
+  "products" => "An excellent data type.",
+}
+
+info = {
+  type_name: "Product",
+  # field_name: ...,
+  # argument_name: ...,
+  # directive_name: ...,
+}
+```
+
+### Performing composition
+
+Construct a `Composer` and call its `perform` method with location settings to compose a supergraph:
 
 ```ruby
-storefronts_sdl = <<~GRAPHQL
-  type Storefront {
-    id:ID!
-    name: String!
-    products: [Product]
-  }
-
-  type Product {
-    id:ID!
-  }
-
-  type Query {
-    storefront(id: ID!): Storefront
-  }
-GRAPHQL
-
-products_sdl = <<~GRAPHQL
-  directive @stitch(key: String!) repeatable on FIELD_DEFINITION
-
-  type Product {
-    id:ID!
-    name: String
-    price: Int
-  }
-
-  type Query {
-    product(id: ID!): Product @stitch(key: "id")
-  }
-GRAPHQL
-
-supergraph = GraphQL::Stitching::Composer.new(schemas: {
-  "storefronts" => GraphQL::Schema.from_definition(storefronts_sdl),
-  "products" => GraphQL::Schema.from_definition(products_sdl),
-}).perform
+storefronts_sdl = "type Query { ..."
+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"),
+    stitch: [{ field_name: "storefront", key: "id" }],
+  },
+  products: {
+    schema: GraphQL::Schema.from_definition(products_sdl),
+    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3002"),
+  },
+  my_local: {
+    schema: MyLocalSchema,
+  },
+})
 
 combined_schema = supergraph.schema
 ```
 
-The individual schemas provided to the composer are assigned a location name based on their input key. These source schemas may be built from SDL (Schema Definition Language) strings using `GraphQL::Schema.from_definition`, or may be structured Ruby classes that inherit from `GraphQL::Schema`. The source schemas are used exclusively for type reference and do NOT need any real data resolvers. Likewise, the resulting combined schema is only used for type reference and resolving introspections.
+Location settings have top-level keys that specify arbitrary location names, each of which provide:
+
+- **`schema:`** _required_, provides a `GraphQL::Schema` class for the location. This may be a class-based schema that inherits from `GraphQL::Schema`, or built from SDL (Schema Definition Language) string using `GraphQL::Schema.from_definition` and mapped to a remote location. The provided schema is only used for type reference and does not require any real data resolvers (unless it is also used as the location's executable, see below).
+
+- **`executable:`** _optional_, provides an executable resource to be called when delegating a request to this location. Executables are `GraphQL::Schema` classes or any object with a `.call(location, source, variables, context)` method that returns a GraphQL response. Omitting the executable option will use the location's provided `schema` as the executable resource.
+
+- **`stitch:`** _optional_, an array of configs used to dynamically apply `@stitch` directives to select root fields prior to composing. This is useful when you can't easily render stitching directives into a location's source schema.
 
 ### Merge patterns
 
@@ -71,40 +116,3 @@ The strategy used to merge source schemas into the combined schema is based on e
   - Stitching directives (both definitions and assignments) are omitted.
 
 Note that the structure of a composed schema may change based on new schema additions and/or element usage (ie: changing input object arguments in one service may cause the intersection of arguments to change). Therefore, it's highly recommended that you use a [schema comparator](https://github.com/xuorig/graphql-schema_comparator) to flag regressions across composed schema versions.
-
-### Value merger functions
-
-The composer has no way of intelligently merging static data values that are embedded into a schema. These include:
-
-- Element descriptions
-- Element deprecations
-- Directive keyword argument values
-
-By default, the first non-null value encountered across locations is used to fill these data slots. You may customize this aggregation process by providing value merger functions:
-
-
-```ruby
-supergraph = GraphQL::Stitching::Composer.new(
-  schemas: { ... },
-  description_merger: ->(values_by_location, info) { values_by_location.values.last },
-  deprecation_merger: ->(values_by_location, info) { values_by_location.values.last },
-  directive_kwarg_merger: ->(values_by_location, info) { values_by_location.values.last },
-).perform
-```
-
-Each merger accepts a `values_by_location` and an `info` argument; these provide the values found across locations and info about where in schema they were encountered:
-
-```ruby
-values_by_location = {
-  "storefronts" => "A fabulous data type.",
-  "products" => "An excellent data type.",
-}
-
-info = {
-  type_name: "Product",
-  # field_name: ...,
-  # argument_name: ...,
-}
-```
-
-The function should then select a value (or compute a new one) and return that for use in the combined schema.

data/docs/executor.md

@@ -43,6 +43,22 @@ raw_result = GraphQL::Stitching::Executor.new(
 ).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",
+      "_STITCH_upc" => "1",
+      "_STITCH_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):

data/docs/gateway.md

@@ -1,10 +1,6 @@
 ## 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.
-
-### Building
-
-The Gateway constructor accepts configuration to build a [`Supergraph`](./supergraph.md) for you. Location names are root keys, and each location config provides a `schema` and an optional [executable](../README.md#executables).
+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 { ..."
@@ -14,6 +10,7 @@ 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),
@@ -25,23 +22,23 @@ gateway = GraphQL::Stitching::Gateway.new(locations: {
 })
 ```
 
-Locations provided with only a `schema` will assign the schema as the location executable (these are locally-executable schemas, and must have locally-implemented resolvers). Locations that provide an `executable` will perform requests using the executable.
-
-#### From exported supergraph
-
-It's possible to [export and rehydrate](./supergraph.md#export-and-caching) `Supergraph` instances, allowing a supergraph to be cached as static artifacts and then rehydrated quickly at runtime without going through composition. To setup a gateway with a prebuilt supergraph, you may pass it as a `supergraph` argument:
+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 = "..."
+exported_schema = "type Query { ..."
 exported_mapping = JSON.parse("{ ... }")
-supergraph = GraphQL::Stitching::Supergraph.from_export(exported_schema, exported_mapping)
+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 to a stitched gateway becomes mostly a drop-in replacement to executing a `GraphQL::Schema` instance:
+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(
@@ -57,7 +54,7 @@ Arguments for the `execute` method include:
 * `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 that gets passed through to gateway caching and error hooks.
+* `context`: an object passed through to executable calls and gateway hooks.
 
 ### Cache hooks
 

data/docs/supergraph.md

@@ -1,32 +1,6 @@
 ## GraphQL::Stitching::Supergraph
 
-A `Supergraph` is the singuar representation of a stitched graph. `Supergraph` is generated by a [`Composer`](./composer.md), and contains the combined schema and delegation map for location routing.
-
-```ruby
-storefronts_sdl = "type Query { storefront(id: ID!): Storefront } ..."
-products_sdl = "type Query { product(id: ID!): Product } ..."
-
-supergraph = GraphQL::Stitching::Composer.new(schemas: {
-  "storefronts" => GraphQL::Schema.from_definition(storefronts_sdl),
-  "products" => GraphQL::Schema.from_definition(products_sdl),
-}).perform
-
-combined_schema = supergraph.schema
-```
-
-### Assigning executables
-
-A Supergraph also manages executable resources assigned for each location (ie: the objects that perform GraphQL requests for each location). An executable is a `GraphQL::Schema` class or any object that implements a `.call(location, query_string, variables)` method and returns a raw GraphQL response. Executables are assigned to a supergraph using `assign_executable`:
-
-```ruby
-supergraph = GraphQL::Stitching::Composer.new(...)
-
-supergraph.assign_executable("location1", MyExecutable.new)
-supergraph.assign_executable("location2", ->(loc, query, vars) { ... })
-supergraph.assign_executable("location3") do |loc, query vars|
-  # ...
-end
-```
+A `Supergraph` is the singuar representation of a stitched graph. `Supergraph` is composed from many locations, and provides a combined GraphQL schema and delegation maps used to route incoming requests.
 
 ### Export and caching
 
@@ -44,22 +18,18 @@ File.write("supergraph/schema.graphql", supergraph_sdl)
 File.write("supergraph/delegation_map.json", JSON.generate(delegation_map))
 ```
 
-To restore a cached Supergraph, collect the cached SDL and delegation mapping then recreate the Supergraph using `from_export`:
+To restore a Supergraph, call `from_export` proving the cached SDL string, the parsed JSON delegation mapping, and a hash of executables keyed by their location names:
 
 ```ruby
 supergraph_sdl = $redis.get("cached_supergraph_sdl")
 delegation_map = JSON.parse($redis.get("cached_delegation_map"))
 
-supergraph = GraphQL::Stitching::Supergraph.from_export(supergraph_sdl, delegation_map)
-```
-
-Note that a supergraph built from cache will not have _any_ executables assigned to it, so you'll need to manually reassign executables for each location:
-
-```ruby
-remote_client = GraphQL::Stitching::RemoteClient.new(
-  url: "http:localhost:3000",
-  headers: { "Authorization" => "Bearer 12345" }
+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_local: MyLocalSchema,
+  }
 )
-supergraph.assign_executable("my_remote", remote_client)
-supergraph.assign_executable("my_local", MyLocal::Schema)
 ```

data/gemfiles/graphql_1.13.9.gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+gem 'graphql', '1.13.9'

data/lib/graphql/stitching/composer.rb

@@ -16,28 +16,25 @@ module GraphQL
       ].freeze
 
       def initialize(
-        schemas:,
         query_name: "Query",
         mutation_name: "Mutation",
         description_merger: nil,
         deprecation_merger: nil,
         directive_kwarg_merger: nil
       )
-        @schemas = schemas
         @query_name = query_name
         @mutation_name = mutation_name
-        @field_map = {}
-        @boundary_map = {}
-        @mapped_type_names = {}
-
         @description_merger = description_merger || DEFAULT_VALUE_MERGER
         @deprecation_merger = deprecation_merger || DEFAULT_VALUE_MERGER
         @directive_kwarg_merger = directive_kwarg_merger || DEFAULT_VALUE_MERGER
       end
 
-      def perform
+      def perform(locations_input)
+        reset!
+        schemas, executables = prepare_locations_input(locations_input)
+
         # "directive_name" => "location" => candidate_directive
-        @subschema_directives_by_name_and_location = @schemas.each_with_object({}) do |(location, schema), memo|
+        @subschema_directives_by_name_and_location = schemas.each_with_object({}) do |(location, schema), memo|
           (schema.directives.keys - schema.default_directives.keys - GraphQL::Stitching.stitching_directive_names).each do |directive_name|
             memo[directive_name] ||= {}
             memo[directive_name][location] = schema.directives[directive_name]
@@ -52,7 +49,7 @@ module GraphQL
         @schema_directives.merge!(GraphQL::Schema.default_directives)
 
         # "Typename" => "location" => candidate_type
-        @subschema_types_by_name_and_location = @schemas.each_with_object({}) do |(location, schema), memo|
+        @subschema_types_by_name_and_location = schemas.each_with_object({}) do |(location, schema), memo|
           raise ComposerError, "Location keys must be strings" unless location.is_a?(String)
           raise ComposerError, "The subscription operation is not supported." if schema.subscription
 
@@ -74,7 +71,7 @@ module GraphQL
           end
         end
 
-        enum_usage = build_enum_usage_map(@schemas.values)
+        enum_usage = build_enum_usage_map(schemas.values)
 
         # "Typename" => merged_type
         schema_types = @subschema_types_by_name_and_location.each_with_object({}) do |(type_name, types_by_location), memo|
@@ -119,7 +116,7 @@ module GraphQL
           schema: schema,
           fields: @field_map,
           boundaries: @boundary_map,
-          executables: @schemas,
+          executables: executables,
         )
 
         VALIDATORS.each do |validator|
@@ -130,6 +127,45 @@ module GraphQL
         supergraph
       end
 
+      def prepare_locations_input(locations_input)
+        schemas = {}
+        executables = {}
+
+        locations_input.each do |location, input|
+          schema = input[:schema]
+
+          if schema.nil?
+            raise ComposerError, "A schema is required for `#{location}` location."
+          elsif !(schema.is_a?(Class) && schema <= GraphQL::Schema)
+            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[: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.directive(stitch_directive, **dir.slice(:key))
+            end
+          end
+
+          schemas[location.to_s] = schema
+          executables[location.to_s] = input[:executable] || schema
+        end
+
+        return schemas, executables
+      end
+
       def build_directive(directive_name, directives_by_location)
         builder = self
 
@@ -515,6 +551,16 @@ module GraphQL
           memo[enum_name] << :write
         end
       end
+
+      private
+
+      def reset!
+        @field_map = {}
+        @boundary_map = {}
+        @mapped_type_names = {}
+        @subschema_directives_by_name_and_location = nil
+        @schema_directives = nil
+      end
     end
   end
 end

data/lib/graphql/stitching/gateway.rb

@@ -9,17 +9,16 @@ module GraphQL
 
       attr_reader :supergraph
 
-      def initialize(locations: nil, supergraph: nil)
+      def initialize(locations: nil, supergraph: nil, composer: nil)
         @supergraph = if locations && supergraph
           raise GatewayError, "Cannot provide both locations and a supergraph."
-        elsif supergraph && !supergraph.is_a?(Supergraph)
+        elsif supergraph && !supergraph.is_a?(GraphQL::Stitching::Supergraph)
           raise GatewayError, "Provided supergraph must be a GraphQL::Stitching::Supergraph instance."
         elsif supergraph
           supergraph
-        elsif locations
-          build_supergraph_from_locations_config(locations)
         else
-          raise GatewayError, "No locations or supergraph provided."
+          composer ||= GraphQL::Stitching::Composer.new
+          composer.perform(locations)
         end
       end
 
@@ -74,28 +73,6 @@ module GraphQL
 
       private
 
-      def build_supergraph_from_locations_config(locations)
-        schemas = locations.each_with_object({}) do |(location, config), memo|
-          schema = config[:schema]
-          if schema.nil?
-            raise GatewayError, "A schema is required for `#{location}` location."
-          elsif !(schema.is_a?(Class) && schema <= GraphQL::Schema)
-            raise GatewayError, "The schema for `#{location}` location must be a GraphQL::Schema class."
-          else
-            memo[location.to_s] = schema
-          end
-        end
-
-        supergraph = GraphQL::Stitching::Composer.new(schemas: schemas).perform
-
-        locations.each do |location, config|
-          executable = config[:executable]
-          supergraph.assign_executable(location.to_s, executable) if executable
-        end
-
-        supergraph
-      end
-
       def fetch_plan(request)
         if @on_cache_read
           cached_plan = @on_cache_read.call(request.digest, request.context)

data/lib/graphql/stitching/planner.rb

@@ -53,18 +53,16 @@ module GraphQL
 
         when "mutation"
           parent_type = @supergraph.schema.mutation
-          location_groups = []
 
-          @request.operation.selections.reduce(nil) do |last_location, node|
+          location_groups = @request.operation.selections.each_with_object([]) do |node, memo|
             # root fields currently just delegate to the last location that defined them; this should probably be smarter
             next_location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].last
 
-            if next_location != last_location
-              location_groups << { location: next_location, selections: [] }
+            if memo.none? || memo.last[:location] != next_location
+              memo << { location: next_location, selections: [] }
             end
 
-            location_groups.last[:selections] << node
-            next_location
+            memo.last[:selections] << node
           end
 
           location_groups.reduce(0) do |after_key, group|
@@ -144,7 +142,7 @@ module GraphQL
         implements_fragments = false
 
         if parent_type.kind.interface?
-          expand_interface_selections(current_location, parent_type, input_selections)
+          input_selections = expand_interface_selections(current_location, parent_type, input_selections)
         end
 
         input_selections.each do |node|
@@ -254,7 +252,7 @@ module GraphQL
 
             # hill climbing selects highest scoring locations to use
             preferred_location = possible_locations.reduce(possible_locations.first) do |best_location, possible_location|
-              score = selections_by_location[location] ? remote_selections.length : 0
+              score = selections_by_location[possible_location] ? remote_selections.length : 0
               score += location_weights.fetch(possible_location, 0)
 
               if score > preferred_location_score
@@ -328,8 +326,8 @@ module GraphQL
         local_interface_fields = @supergraph.fields_by_type_and_location[parent_type.graphql_name][current_location]
 
         expanded_selections = nil
-        input_selections.reject! do |node|
-          if node.is_a?(GraphQL::Language::Nodes::Field) && !local_interface_fields.include?(node.name)
+        input_selections = input_selections.reject do |node|
+          if node.is_a?(GraphQL::Language::Nodes::Field) && node.name != "__typename" && !local_interface_fields.include?(node.name)
             expanded_selections ||= []
             expanded_selections << node
             true
@@ -344,6 +342,8 @@ module GraphQL
             input_selections << GraphQL::Language::Nodes::InlineFragment.new(type: type_name, selections: expanded_selections)
           end
         end
+
+        input_selections
       end
 
       # expand concrete type selections into typed fragments when sending to abstract boundaries

data/lib/graphql/stitching/shaper.rb

@@ -42,15 +42,16 @@ module GraphQL
             return nil if raw_object[field_name].nil? && node_type.non_null?
 
           when GraphQL::Language::Nodes::InlineFragment
-            next unless typename == node.type.name
             fragment_type = @schema.types[node.type.name]
+            next unless fragment_matches_typename?(fragment_type, typename)
+
             result = resolve_object_scope(raw_object, fragment_type, node.selections, typename)
             return nil if result.nil?
 
           when GraphQL::Language::Nodes::FragmentSpread
             fragment = @request.fragment_definitions[node.name]
             fragment_type = @schema.types[fragment.type.name]
-            next unless typename == fragment_type.graphql_name
+            next unless fragment_matches_typename?(fragment_type, typename)
 
             result = resolve_object_scope(raw_object, fragment_type, fragment.selections, typename)
             return nil if result.nil?
@@ -91,6 +92,11 @@ module GraphQL
 
         resolved_list
       end
+
+      def fragment_matches_typename?(fragment_type, typename)
+        return true if fragment_type.graphql_name == typename
+        fragment_type.kind.interface? && @schema.possible_types(fragment_type).any? { _1.graphql_name == typename }
+      end
     end
   end
 end

data/lib/graphql/stitching/supergraph.rb

@@ -15,11 +15,39 @@ module GraphQL
         "__DirectiveLocation",
       ].freeze
 
+      def self.validate_executable!(location, executable)
+        return true if executable.is_a?(Class) && executable <= GraphQL::Schema
+        return true if executable && executable.respond_to?(:call)
+        raise StitchingError, "Invalid executable provided for location `#{location}`."
+      end
+
+      def self.from_export(schema:, delegation_map:, executables:)
+        schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
+
+        executables = delegation_map["locations"].each_with_object({}) do |location, memo|
+          executable = executables[location] || executables[location.to_sym]
+          if validate_executable!(location, executable)
+            memo[location] = executable
+          end
+        end
+
+        new(
+          schema: schema,
+          fields: delegation_map["fields"],
+          boundaries: delegation_map["boundaries"],
+          executables: executables,
+        )
+      end
+
       attr_reader :schema, :boundaries, :locations_by_type_and_field, :executables
 
-      def initialize(schema:, fields:, boundaries:, executables: {})
+      def initialize(schema:, fields:, boundaries:, executables:)
         @schema = schema
         @boundaries = boundaries
+        @possible_keys_by_type = {}
+        @possible_keys_by_type_and_location = {}
+
+        # add introspection types into the fields mapping
         @locations_by_type_and_field = INTROSPECTION_TYPES.each_with_object(fields) do |type_name, memo|
           introspection_type = schema.get_type(type_name)
           next unless introspection_type.kind.fields?
@@ -27,57 +55,46 @@ module GraphQL
           memo[type_name] = introspection_type.fields.keys.each_with_object({}) do |field_name, m|
             m[field_name] = [LOCATION]
           end
-        end
+        end.freeze
 
-        @possible_keys_by_type = {}
-        @possible_keys_by_type_and_location = {}
-        @executables = { LOCATION => @schema }.merge!(executables)
+        # validate and normalize executable references
+        @executables = executables.each_with_object({ LOCATION => @schema }) do |(location, executable), memo|
+          if self.class.validate_executable!(location, executable)
+            memo[location.to_s] = executable
+          end
+        end.freeze
       end
 
       def fields
         @locations_by_type_and_field.reject { |k, _v| INTROSPECTION_TYPES.include?(k) }
       end
 
+      def locations
+        @executables.keys.reject { _1 == LOCATION }
+      end
+
       def export
         return GraphQL::Schema::Printer.print_schema(@schema), {
+          "locations" => locations,
           "fields" => fields,
           "boundaries" => @boundaries,
         }
       end
 
-      def self.from_export(schema, delegation_map, executables: {})
-        schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
-        new(
-          schema: schema,
-          fields: delegation_map["fields"],
-          boundaries: delegation_map["boundaries"],
-          executables: executables,
-        )
-      end
-
-      def assign_executable(location, executable = nil, &block)
-        executable ||= block
-        unless executable.is_a?(Class) && executable <= GraphQL::Schema
-          raise StitchingError, "A client or block handler must be provided." unless executable
-          raise StitchingError, "A client must be callable" unless executable.respond_to?(:call)
-        end
-        @executables[location] = executable
-      end
-
-      def execute_at_location(location, query, variables, context)
+      def execute_at_location(location, source, variables, context)
         executable = executables[location]
 
         if executable.nil?
           raise StitchingError, "No executable assigned for #{location} location."
         elsif executable.is_a?(Class) && executable <= GraphQL::Schema
           executable.execute(
-            query: query,
+            query: source,
             variables: variables,
             context: context.frozen? ? context.dup : context,
             validate: false,
           )
         elsif executable.respond_to?(:call)
-          executable.call(location, query, variables, context)
+          executable.call(location, source, variables, context)
         else
           raise StitchingError, "Missing valid executable for #{location} location."
         end

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "0.2.3"
+    VERSION = "0.3.1"
   end
 end

data/lib/graphql/stitching.rb

@@ -19,56 +19,6 @@ module GraphQL
       def stitching_directive_names
         [stitch_directive]
       end
-
-      def schema_from_definition(sdl, stitch_directives:)
-        ast = GraphQL.parse(sdl)
-
-        if stitch_directives&.any?
-          directive_definition = ast.definitions.find do |d|
-            d.is_a?(GraphQL::Language::Nodes::DirectiveDefinition) && d.name == stitch_directive
-          end
-
-          if !directive_definition
-            directive_sdl = "directive @#{stitch_directive}(key: String!) repeatable on FIELD_DEFINITION"
-            directive_definition = GraphQL.parse(directive_sdl).definitions.first
-            ast.send(:merge!, { definitions: [directive_definition, *ast.definitions] })
-          end
-        end
-
-        stitch_directives.each do |config|
-          config[:type_name] ||= "Query"
-
-          type_node = ast.definitions.find do |d|
-            d.is_a?(GraphQL::Language::Nodes::ObjectTypeDefinition) && d.name == config[:type_name]
-          end
-
-          raise StitchingError, "invalid type name `#{config[:type_name]}`." unless type_node
-
-          field_node = type_node.fields.find do |f|
-            f.name == config[:field_name]
-          end
-
-          raise StitchingError, "invalid field name `#{config[:field_name]}`." unless field_node
-
-          field_node.send(:merge!, {
-            directives: [
-              *field_node.directives,
-              GraphQL::Language::Nodes::Directive.new(
-                arguments: [GraphQL::Language::Nodes::Argument.new(name: "key", value: config[:key])],
-                name: stitch_directive,
-              )
-            ]
-          })
-        end
-
-        if GraphQL::Schema::BuildFromDefinition.method(:from_document).parameters.first.last == :document
-          # GraphQL v1.13.x
-          GraphQL::Schema::BuildFromDefinition.from_document(ast, default_resolve: nil)
-        else
-          # GraphQL v2
-          GraphQL::Schema::BuildFromDefinition.from_document(GraphQL::Schema, ast, default_resolve: nil)
-        end
-      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.1
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-22 00:00:00.000000000 Z
+date: 2023-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -93,6 +93,7 @@ files:
 - example/graphiql.html
 - example/remote1.rb
 - example/remote2.rb
+- gemfiles/graphql_1.13.9.gemfile
 - graphql-stitching.gemspec
 - lib/graphql/stitching.rb
 - lib/graphql/stitching/composer.rb