graphql-stitching 0.3.6 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3cb133db35cdb705f296a2fe67909bfe2f07baefc873cf502ba48dbd53e8c6a
-  data.tar.gz: c81040a57f364a1a8a045bf079428cfae3c8a5886d2f7d0aaae45844c055b92e
+  metadata.gz: 4ce8bb1075d536f01aa63487df3e1686bc0c2899b58ca14e95383caef38812e2
+  data.tar.gz: ae39e685bdb31cbf3962216cfce263b2970aa2aeac6be1901a7397cee6eb1656
 SHA512:
-  metadata.gz: dc2a8d99942c2a5e1558ded0fbb467dd96d4bdb30c5a2ff9aa2348161ae28073cf36b2b56e51b0d92b757f68a87366ab1750e716bf0939d1645bf1ddee2049f5
-  data.tar.gz: 599760134f3f59f6ec5285e0d0976e1e9c07ba4103a74341bb35d1dacb89d0026383da2f4c2ca47d33ce3971510d9dddcc61d90a5248342406a4787f650d6126
+  metadata.gz: e718527102969773accf28b2323cbde1d2c467339c44bb876144ae5387a7aaec64143b35b6dfff21401fb087c64ed8742f79cda78e743518ba045871c320f51f
+  data.tar.gz: 74bc97f475b61ea51dd8ce9e42a1ff2783d0c1717a38ff812e256962d64b97ef0ccc092de11e529a22e274d8ad5cf77af9fd7ed2fd680e20e0c058534942a5d6

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 arbitrary queries or 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/boundary.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    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/{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
@@ -41,7 +41,7 @@ module GraphQL
           GraphQL::Stitching::Planner.new(
             supergraph: @supergraph,
             request: request,
-          ).perform.to_h
+          ).perform
         end
 
         GraphQL::Stitching::Executor.new(
@@ -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
 
@@ -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

@@ -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
 
@@ -416,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
 
@@ -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] << {
-                "location" => location,
-                "key" => key_selections[0].name,
-                "field" => field_candidate.name,
-                "arg" => argument_name,
-                "list" => boundary_structure.first[:list],
-                "type_name" => boundary_type_name,
-              }
+              @boundary_map[impl_type_name] ||= []
+              @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