graphql-stitching 1.2.3 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99acc247a0e5e227236b0261b3f975e7277f642a9d76daaf4f6a985bfc4825ea
-  data.tar.gz: ef5f01132498ca4ba1be6f8593f189645ddf8fb6b6d8ab71f9b7d0e55d6ec682
+  metadata.gz: 5c1c6ae95fd6ec036a7678356c8bc48191d8cf5cfd9e4b2936e79fdb72b52f48
+  data.tar.gz: 7f8002d013e26f69df5a7023e147f98b86a46cc3027d2753b6d704bfe75a835b
 SHA512:
-  metadata.gz: d1bd0db4c7f6d363231330222006f2bbc552a669227a38aeb7861dde843b59bc3e61b0f301f97d4a5c6b55193d01424cd9f240c0ff7a7ee483e49150686ac3da
-  data.tar.gz: 348aa663608fd8b0e5544ccf7ec500d4295a63bb9bd19a91031f927165da2a206024ce6cb17111c3ebda2c172e08072be8d01716c11f0a05c3ea8a9a4b99466e
+  metadata.gz: 734fe2a73f5412f30ccc6d89a20e62c1da376422de65a816a9680f02330cb2df93c39803cc182c5eed1c310624509beccb0a69162c1dad407ccaf6ada69178dd
+  data.tar.gz: c293a3de403d0888d15047e2de120a8187e4fee598229572f37905dd4e4b3429017ee958ae8ab2a2c16561d25761128b9a6ffb954cbf49b5a310c92aa77f7ffe

data/README.md

@@ -10,12 +10,13 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 - Shared objects, fields, enums, and inputs across locations.
 - Combining local and remote schemas.
 - File uploads via [multipart form spec](https://github.com/jaydenseric/graphql-multipart-request-spec).
+- Tested with all minor versions of `graphql-ruby`.
 
 **NOT Supported:**
 - Computed fields (ie: federation-style `@requires`).
 - Subscriptions, defer/stream.
 
-This Ruby implementation is a sibling to [GraphQL Tools](https://the-guild.dev/graphql/stitching) (JS) and [Bramble](https://movio.github.io/bramble/) (Go), and its capabilities fall somewhere in between them. GraphQL stitching is similar in concept to [Apollo Federation](https://www.apollographql.com/docs/federation/), though more generic. The opportunity here is for a Ruby application to stitch its local schemas together or onto remote sources without requiring an additional proxy service running in another language. If your goal is to build a purely high-throughput API gateway, consider not using Ruby.
+This Ruby implementation is a sibling to [GraphQL Tools](https://the-guild.dev/graphql/stitching) (JS) and [Bramble](https://movio.github.io/bramble/) (Go), and its capabilities fall somewhere in between them. GraphQL stitching is similar in concept to [Apollo Federation](https://www.apollographql.com/docs/federation/), though more generic. The opportunity here is for a Ruby application to stitch its local schemas together or onto remote sources without requiring an additional proxy service running in another language. If your goal is to build a purely high-performance API gateway, consider not using Ruby.
 
 ## Getting started
 
@@ -179,7 +180,7 @@ See [error handling](./docs/mechanics.md#stitched-errors) tips for list queries.
 
 #### Abstract queries
 
-It's okay for stitching queries to be implemented through abstract types. An abstract query will provide access to all of its possible types. For interfaces, the key selection should match a field within the interface. For unions, all possible types must implement the key selection individually.
+It's okay for stitching queries to be implemented through abstract types. An abstract query will provide access to all of its possible types by default, each of which must implement the key.
 
 ```graphql
 interface Node {
@@ -194,13 +195,33 @@ type Query {
 }
 ```
 
+To customize which types an abstract query provides and their respective keys, you may extend the `@stitch` directive with a `typeName` constraint. This can be repeated to select multiple types.
+
+```graphql
+directive @stitch(key: String!, typeName: String) repeatable on FIELD_DEFINITION
+
+type Product { sku: ID! }
+type Order { id: ID! }
+type Customer { id: ID! } # << not stitched
+union Entity = Product | Order | Customer
+
+type Query {
+  entity(key: ID!): Entity
+    @stitch(key: "sku", typeName: "Product")
+    @stitch(key: "id", typeName: "Order")
+}
+```
+
 #### Multiple query arguments
 
-Stitching infers which argument to use for queries with a single argument. For queries that accept multiple arguments, the key must provide an argument mapping specified as `"<arg>:<key>"`. Note the `"id:id"` key:
+Stitching infers which argument to use for queries with a single argument, or when the key name matches its intended argument. For queries that accept multiple arguments with unmatched names, the key may provide an argument mapping specified as `"<arg>:<key>"`.
 
 ```graphql
+type Product {
+  id: ID!
+}
 type Query {
-  product(id: ID, upc: ID): Product @stitch(key: "id:id")
+  product(by_id: ID, by_sku: ID): Product @stitch(key: "by_id:id")
 }
 ```
 
@@ -210,8 +231,8 @@ A type may exist in multiple locations across the graph using different keys, fo
 
 ```graphql
 type Product { id:ID! }          # storefronts location
-type Product { id:ID! upc:ID! }  # products location
-type Product { upc:ID! }         # catelog location
+type Product { id:ID! sku:ID! }  # products location
+type Product { sku:ID! }         # catelog location
 ```
 
 In the above graph, the `storefronts` and `catelog` locations have different keys that join through an intermediary. This pattern is perfectly valid and resolvable as long as the intermediary provides stitching queries for each possible key:
@@ -219,11 +240,11 @@ In the above graph, the `storefronts` and `catelog` locations have different key
 ```graphql
 type Product {
   id: ID!
-  upc: ID!
+  sku: ID!
 }
 type Query {
   productById(id: ID!): Product @stitch(key: "id")
-  productByUpc(upc: ID!): Product @stitch(key: "upc")
+  productByUpc(sku: ID!): Product @stitch(key: "sku")
 }
 ```
 
@@ -232,10 +253,10 @@ The `@stitch` directive is also repeatable, allowing a single query to associate
 ```graphql
 type Product {
   id: ID!
-  upc: ID!
+  sku: ID!
 }
 type Query {
-  product(id: ID, upc: ID): Product @stitch(key: "id:id") @stitch(key: "upc:upc")
+  product(id: ID, sku: ID): Product @stitch(key: "id") @stitch(key: "sku")
 }
 ```
 
@@ -269,11 +290,11 @@ A clean SDL string may also have stitching directives applied via static configu
 sdl_string = <<~GRAPHQL
   type Product {
     id: ID!
-    upc: ID!
+    sku: ID!
   }
   type Query {
     productById(id: ID!): Product
-    productByUpc(upc: ID!): Product
+    productByUpc(sku: ID!): Product
   }
 GRAPHQL
 
@@ -283,7 +304,7 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
     executable: ->() { ... },
     stitch: [
       { field_name: "productById", key: "id" },
-      { field_name: "productByUpc", key: "upc" },
+      { field_name: "productByUpc", key: "sku" },
     ]
   },
   # ...

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Composer
+    class BoundaryConfig
+      ENTITY_TYPENAME = "_Entity"
+      ENTITIES_QUERY = "_entities"
+
+      class << self
+        def extract_directive_assignments(schema, location, assignments)
+          return EMPTY_OBJECT unless assignments && assignments.any?
+
+          assignments.each_with_object({}) do |kwargs, memo|
+            type = kwargs[:parent_type_name] ? schema.get_type(kwargs[:parent_type_name]) : schema.query
+            raise ComposerError, "Invalid stitch directive type `#{kwargs[:parent_type_name]}`" unless type
+
+            field = type.get_field(kwargs[:field_name])
+            raise ComposerError, "Invalid stitch directive field `#{kwargs[:field_name]}`" unless field
+
+            field_path = "#{location}.#{field.name}"
+            memo[field_path] ||= []
+            memo[field_path] << from_kwargs(kwargs)
+          end
+        end
+
+        def extract_federation_entities(schema, location)
+          return EMPTY_OBJECT unless federation_entities_schema?(schema)
+
+          schema.possible_types(schema.get_type(ENTITY_TYPENAME)).each_with_object({}) do |entity_type, memo|
+            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"
+              memo[field_path] ||= []
+              memo[field_path] << new(
+                key: key,
+                type_name: entity_type.graphql_name,
+                federation: true,
+              )
+            end
+          end
+        end
+
+        def from_kwargs(kwargs)
+          new(
+            key: kwargs[:key],
+            type_name: kwargs[:type_name] || kwargs[:typeName],
+            federation: kwargs[:federation] || false,
+          )
+        end
+
+        private
+
+        def federation_entities_schema?(schema)
+          entity_type = schema.get_type(ENTITY_TYPENAME)
+          entities_query = schema.query.get_field(ENTITIES_QUERY)
+          entity_type && entity_type.kind.union? && entities_query && entities_query.type.unwrap == entity_type
+        end
+      end
+
+      attr_reader :key, :type_name, :federation
+
+      def initialize(key:, type_name:, federation: false)
+        @key = key
+        @type_name = type_name
+        @federation = federation
+      end
+    end
+  end
+end

data/lib/graphql/stitching/composer.rb

@@ -3,6 +3,7 @@
 require_relative "./composer/base_validator"
 require_relative "./composer/validate_interfaces"
 require_relative "./composer/validate_boundaries"
+require_relative "./composer/boundary_config"
 
 module GraphQL
   module Stitching
@@ -61,7 +62,7 @@ module GraphQL
         @default_value_merger = default_value_merger || BASIC_VALUE_MERGER
         @directive_kwarg_merger = directive_kwarg_merger || BASIC_VALUE_MERGER
         @root_field_location_selector = root_field_location_selector || BASIC_ROOT_FIELD_LOCATION_SELECTOR
-        @stitch_directives = {}
+        @boundary_configs = {}
 
         @field_map = nil
         @boundary_map = nil
@@ -187,37 +188,8 @@ module GraphQL
             raise ComposerError, "The schema for `#{location}` location must be a GraphQL::Schema class."
           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
-
-            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
-
-          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
+          @boundary_configs.merge!(BoundaryConfig.extract_directive_assignments(schema, location, input[:stitch]))
+          @boundary_configs.merge!(BoundaryConfig.extract_federation_entities(schema, location))
 
           schemas[location.to_s] = schema
           executables[location.to_s] = input[:executable] || schema
@@ -557,19 +529,17 @@ module GraphQL
       def extract_boundaries(type_name, types_by_location)
         types_by_location.each do |location, type_candidate|
           type_candidate.fields.each do |field_name, field_candidate|
-            boundary_type_name = field_candidate.type.unwrap.graphql_name
+            boundary_type = field_candidate.type.unwrap
             boundary_structure = Util.flatten_type_structure(field_candidate.type)
-            boundary_kwargs = @stitch_directives["#{location}.#{field_name}"] || []
+            boundary_configs = @boundary_configs.fetch("#{location}.#{field_name}",  [])
 
             field_candidate.directives.each do |directive|
               next unless directive.graphql_name == GraphQL::Stitching.stitch_directive
-              boundary_kwargs << directive.arguments.keyword_arguments
+              boundary_configs << BoundaryConfig.from_kwargs(directive.arguments.keyword_arguments)
             end
 
-            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
+            boundary_configs.each do |config|
+              key_selections = GraphQL.parse("{ #{config.key} }").definitions[0].selections
 
               if key_selections.length != 1
                 raise ComposerError, "Boundary key at #{type_name}.#{field_name} must specify exactly one key."
@@ -578,6 +548,8 @@ module GraphQL
               argument_name = key_selections[0].alias
               argument_name ||= if field_candidate.arguments.size == 1
                 field_candidate.arguments.keys.first
+              elsif field_candidate.arguments[config.key]
+                config.key
               end
 
               argument = field_candidate.arguments[argument_name]
@@ -591,15 +563,26 @@ module GraphQL
                 raise ComposerError, "Mismatched input/output for #{type_name}.#{field_name}.#{argument_name} boundary. Arguments must map directly to results."
               end
 
-              @boundary_map[impl_type_name] ||= []
-              @boundary_map[impl_type_name] << Boundary.new(
+              boundary_type_name = if config.type_name
+                if !boundary_type.kind.abstract?
+                  raise ComposerError, "Resolver config may only specify a type name for abstract resolvers."
+                elsif !boundary_type.possible_types.find { _1.graphql_name == config.type_name }
+                  raise ComposerError, "Type `#{config.type_name}` is not a possible return type for query `#{field_name}`."
+                end
+                config.type_name
+              else
+                boundary_type.graphql_name
+              end
+
+              @boundary_map[boundary_type_name] ||= []
+              @boundary_map[boundary_type_name] << Boundary.new(
                 location: location,
-                type_name: impl_type_name,
+                type_name: boundary_type_name,
                 key: key_selections[0].name,
                 field: field_candidate.name,
                 arg: argument_name,
                 list: boundary_structure.first.list?,
-                federation: kwargs[:federation] || false,
+                federation: config.federation,
               )
             end
           end

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

@@ -5,6 +5,7 @@ module GraphQL::Stitching
     class ResolverDirective < GraphQL::Schema::Directive
       graphql_name "resolver"
       locations OBJECT, INTERFACE, UNION
+      argument :type_name, String, required: false
       argument :location, String, required: true
       argument :key, String, required: true
       argument :field, String, required: true

data/lib/graphql/stitching/supergraph.rb

@@ -31,7 +31,7 @@ module GraphQL
               kwargs = directive.arguments.keyword_arguments
               boundary_map[type_name] ||= []
               boundary_map[type_name] << Boundary.new(
-                type_name: type_name,
+                type_name: kwargs.fetch(:type_name, type_name),
                 location: kwargs[:location],
                 key: kwargs[:key],
                 field: kwargs[:field],
@@ -134,6 +134,7 @@ module GraphQL
               end
 
               type.directive(ResolverDirective, **{
+                type_name: (boundary.type_name if boundary.type_name != type_name),
                 location: boundary.location,
                 key: boundary.key,
                 field: boundary.field,

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.2.3"
+    VERSION = "1.2.4"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.2.4
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-06 00:00:00.000000000 Z
+date: 2024-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -114,6 +114,7 @@ files:
 - lib/graphql/stitching/client.rb
 - lib/graphql/stitching/composer.rb
 - lib/graphql/stitching/composer/base_validator.rb
+- lib/graphql/stitching/composer/boundary_config.rb
 - lib/graphql/stitching/composer/validate_boundaries.rb
 - lib/graphql/stitching/composer/validate_interfaces.rb
 - lib/graphql/stitching/executor.rb