graphql-stitching 1.2.4 → 1.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c1c6ae95fd6ec036a7678356c8bc48191d8cf5cfd9e4b2936e79fdb72b52f48
-  data.tar.gz: 7f8002d013e26f69df5a7023e147f98b86a46cc3027d2753b6d704bfe75a835b
+  metadata.gz: 754e7a61df541f685ef50ec79039df9742e4a2589a30eadf93125d6e4ef47aed
+  data.tar.gz: e2ceb89be07b42dbffeaa75416055fa62ffafa001088fd47b2b4f156aee6123a
 SHA512:
-  metadata.gz: 734fe2a73f5412f30ccc6d89a20e62c1da376422de65a816a9680f02330cb2df93c39803cc182c5eed1c310624509beccb0a69162c1dad407ccaf6ada69178dd
-  data.tar.gz: c293a3de403d0888d15047e2de120a8187e4fee598229572f37905dd4e4b3429017ee958ae8ab2a2c16561d25761128b9a6ffb954cbf49b5a310c92aa77f7ffe
+  metadata.gz: 561ecdc36e78b31e4f4fd2f85d4ff5e0f1ab23d44570de7d8ffe63c2e46b5856214eb07c25b98eafbd64857602ebd839e187175e9e3ec347caedf4651a00d332
+  data.tar.gz: dd7a98e1c97f7bd5a6ca2585c34b6538e94b6dfaaa83edf9b3f1bc287a79d04f62a29ebe2a6b6fae4d06e8af9f08bb20203a89f1b062f24dc622a66973f87abc

data/README.md

@@ -16,7 +16,7 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 - 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-performance 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-throughput federated reverse proxy, consider not using Ruby.
 
 ## Getting started
 
@@ -153,7 +153,7 @@ type Query {
 * The `@stitch` directive is applied to a root query where the merged type may be accessed. The merged type identity is inferred from the field return.
 * The `key: "id"` parameter indicates that an `{ id }` must be selected from prior locations so it may be submitted as an argument to this query. The query argument used to send the key is inferred when possible ([more on arguments](#multiple-query-arguments) later).
 
-Each location that provides a unique variant of a type must provide at least one stitching query for the type. The exception to this requirement are [foreign key types](./docs/mechanics.md##modeling-foreign-keys-for-stitching) that contain only a single key field:
+Each location that provides a unique variant of a type must provide at least one resolver query for the type. The exception to this requirement are [outbound-only types](./docs/mechanics.md#outbound-only-merged-types) and/or [foreign key types](./docs/mechanics.md##modeling-foreign-keys-for-stitching) that contain no exclusive data:
 
 ```graphql
 type Product {
@@ -161,11 +161,11 @@ type Product {
 }
 ```
 
-The above representation of a `Product` type provides no unique data beyond a key that is available in other locations. Thus, this representation will never require an inbound request to fetch it, and its stitching query may be omitted.
+The above representation of a `Product` type contains nothing but a key that is available in other locations. Therefore, this representation will never require an inbound request to fetch it, and its resolver query may be omitted.
 
 #### List queries
 
-It's okay ([even preferable](#batching) in most circumstances) to provide a list accessor as a stitching query. The only requirement is that both the field argument and return type must be lists, and the query results are expected to be a mapped set with `null` holding the position of missing results.
+It's okay ([even preferable](#batching) in most circumstances) to provide a list accessor as a resolver query. The only requirement is that both the field argument and return type must be lists, and the query results are expected to be a mapped set with `null` holding the position of missing results.
 
 ```graphql
 type Query {
@@ -180,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 by default, each of which must implement the key.
+It's okay for resolver 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 {
@@ -214,14 +214,14 @@ type Query {
 
 #### Multiple query arguments
 
-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>"`.
+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 should provide an argument alias specified as `"<arg>:<key>"`.
 
 ```graphql
 type Product {
   id: ID!
 }
 type Query {
-  product(by_id: ID, by_sku: ID): Product @stitch(key: "by_id:id")
+  product(byId: ID, bySku: ID): Product @stitch(key: "byId:id")
 }
 ```
 
@@ -235,7 +235,7 @@ 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:
+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 resolver queries for each possible key:
 
 ```graphql
 type Product {
@@ -244,7 +244,7 @@ type Product {
 }
 type Query {
   productById(id: ID!): Product @stitch(key: "id")
-  productByUpc(sku: ID!): Product @stitch(key: "sku")
+  productBySku(sku: ID!): Product @stitch(key: "sku")
 }
 ```
 
@@ -294,7 +294,7 @@ sdl_string = <<~GRAPHQL
   }
   type Query {
     productById(id: ID!): Product
-    productByUpc(sku: ID!): Product
+    productBySku(sku: ID!): Product
   }
 GRAPHQL
 
@@ -304,7 +304,7 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
     executable: ->() { ... },
     stitch: [
       { field_name: "productById", key: "id" },
-      { field_name: "productByUpc", key: "sku" },
+      { field_name: "productBySku", key: "sku" },
     ]
   },
   # ...

data/docs/mechanics.md

@@ -303,3 +303,45 @@ And produces this result:
 ```
 
 Location B is allowed to return `null` here because its one unique field, `rating`, is nullable (the `id` field can be provided by Location A). If `rating` were non-null, then null bubbling would invalidate the response data.
+
+### Outbound-only merged types
+
+Merged types do not always require a resolver query. For example:
+
+```graphql
+# -- Location A
+
+type Widget {
+  id: ID!
+  name: String
+}
+
+type Query {
+  widgetA(id: ID!): Widget @stitch(key: "id")
+}
+
+# -- Location B
+
+type Widget {
+  id: ID!
+  size: Float
+}
+
+type Query {
+  widgetB(id: ID!): Widget @stitch(key: "id")
+}
+
+# -- Location C
+
+type Widget {
+  id: ID!
+  name: String
+  size: Float
+}
+
+type Query {
+  featuredWidget: Widget
+}
+```
+
+In this graph, `Widget` is a merged type without a resolver query in location C. This works because all of its fields are resolvable in other locations; that means location C can provide outbound representations of this type without ever needing to resolve inbound requests for it. Outbound types do still require a key field (such as `id` above) that allow them to join with data in other resolver locations.

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

@@ -4,29 +4,29 @@ module GraphQL::Stitching
   class Composer
     class ValidateBoundaries < BaseValidator
 
-      def perform(ctx, composer)
-        ctx.schema.types.each do |type_name, type|
+      def perform(supergraph, composer)
+        supergraph.schema.types.each do |type_name, type|
           # objects and interfaces that are not the root operation types
           next unless type.kind.object? || type.kind.interface?
-          next if ctx.schema.query == type || ctx.schema.mutation == type
+          next if supergraph.schema.query == type || supergraph.schema.mutation == type
           next if type.graphql_name.start_with?("__")
 
           # multiple subschemas implement the type
           candidate_types_by_location = composer.candidate_types_by_name_and_location[type_name]
           next unless candidate_types_by_location.length > 1
 
-          boundaries = ctx.boundaries[type_name]
+          boundaries = supergraph.boundaries[type_name]
           if boundaries&.any?
-            validate_as_boundary(ctx, type, candidate_types_by_location, boundaries)
+            validate_as_boundary(supergraph, type, candidate_types_by_location, boundaries)
           elsif type.kind.object?
-            validate_as_shared(ctx, type, candidate_types_by_location)
+            validate_as_shared(supergraph, type, candidate_types_by_location)
           end
         end
       end
 
       private
 
-      def validate_as_boundary(ctx, type, candidate_types_by_location, boundaries)
+      def validate_as_boundary(supergraph, type, candidate_types_by_location, boundaries)
         # abstract boundaries are expanded with their concrete implementations, which each get validated. Ignore the abstract itself.
         return if type.kind.abstract?
 
@@ -41,25 +41,30 @@ module GraphQL::Stitching
           memo[boundary.location][boundary.key] = boundary
         end
 
-        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
+        boundary_keys = boundaries.map(&:key).to_set
+
+        # All non-key fields must be resolvable in at least one boundary location
+        supergraph.locations_by_type_and_field[type.graphql_name].each do |field_name, locations|
+          next if boundary_keys.include?(field_name)
 
-        # all locations have a boundary, or else are key-only
-        candidate_types_by_location.each do |location, subschema_type|
-          unless boundaries_by_location_and_key[location] || key_only_types_by_location[location]
-            raise Composer::ValidationError, "A boundary query is required for `#{type.graphql_name}` in #{location} because it provides unique fields."
+          if locations.none? { boundaries_by_location_and_key[_1] }
+            where = locations.length > 1 ? "one of #{locations.join(", ")} locations" : locations.first
+            raise Composer::ValidationError, "A boundary query is required for `#{type.graphql_name}` in #{where} to resolve field `#{field_name}`."
           end
         end
 
-        outbound_access_locations = key_only_types_by_location.keys
-        bidirectional_access_locations = candidate_types_by_location.keys - outbound_access_locations
+        # All locations of a boundary type must include at least one key field
+        supergraph.fields_by_type_and_location[type.graphql_name].each do |location, field_names|
+          if field_names.none? { boundary_keys.include?(_1) }
+            raise Composer::ValidationError, "A boundary key is required for `#{type.graphql_name}` in #{location} to join with other locations."
+          end
+        end
 
         # verify that all outbound locations can access all inbound locations
-        (outbound_access_locations + bidirectional_access_locations).each do |location|
-          remote_locations = bidirectional_access_locations.reject { _1 == location }
-          paths = ctx.route_type_to_locations(type.graphql_name, location, remote_locations)
+        resolver_locations = boundaries_by_location_and_key.keys
+        candidate_types_by_location.each_key do |location|
+          remote_locations = resolver_locations.reject { _1 == location }
+          paths = supergraph.route_type_to_locations(type.graphql_name, location, remote_locations)
           if paths.length != remote_locations.length || paths.any? { |_loc, path| path.nil? }
             raise Composer::ValidationError, "Cannot route `#{type.graphql_name}` boundaries in #{location} to all other locations. "\
               "All locations must provide a boundary accessor that uses a conjoining key."
@@ -67,7 +72,7 @@ module GraphQL::Stitching
         end
       end
 
-      def validate_as_shared(ctx, type, candidate_types_by_location)
+      def validate_as_shared(supergraph, type, candidate_types_by_location)
         expected_fields = begin
           type.fields.keys.sort
         rescue StandardError => e
@@ -79,8 +84,8 @@ module GraphQL::Stitching
           end
         end
 
-        candidate_types_by_location.each do |location, subschema_type|
-          if subschema_type.fields.keys.sort != expected_fields
+        candidate_types_by_location.each do |location, candidate_type|
+          if candidate_type.fields.keys.sort != expected_fields
             raise Composer::ValidationError, "Shared type `#{type.graphql_name}` must have consistent fields across locations, "\
               "or else define boundary queries so that its unique fields may be accessed remotely."
           end

data/lib/graphql/stitching/composer.rb

@@ -68,6 +68,7 @@ module GraphQL
         @boundary_map = nil
         @mapped_type_names = nil
         @candidate_directives_by_name_and_location = nil
+        @candidate_types_by_name_and_location = nil
         @schema_directives = nil
       end
 

data/lib/graphql/stitching/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.5
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-07 00:00:00.000000000 Z
+date: 2024-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql