graphql-stitching 1.2.5 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 754e7a61df541f685ef50ec79039df9742e4a2589a30eadf93125d6e4ef47aed
-  data.tar.gz: e2ceb89be07b42dbffeaa75416055fa62ffafa001088fd47b2b4f156aee6123a
+  metadata.gz: 448ca61527e02c6f232fa811e7e99ba1aa243bc58685f313ca5613a6724ea306
+  data.tar.gz: a0af76ea7eb429d60f5a7e4df4c39103539a01a69136c769f027cef52a108cab
 SHA512:
-  metadata.gz: 561ecdc36e78b31e4f4fd2f85d4ff5e0f1ab23d44570de7d8ffe63c2e46b5856214eb07c25b98eafbd64857602ebd839e187175e9e3ec347caedf4651a00d332
-  data.tar.gz: dd7a98e1c97f7bd5a6ca2585c34b6538e94b6dfaaa83edf9b3f1bc287a79d04f62a29ebe2a6b6fae4d06e8af9f08bb20203a89f1b062f24dc622a66973f87abc
+  metadata.gz: 8cea8a8674d67a421059e32778ffc3d1bbd699fa307efe2aead4571925ed77d8da7852431ef99c5809e0106ff16af212c26a6372c211b2d287d3a2c4cef5eb80
+  data.tar.gz: 972f74c60afef0c615d8dc6a3069bb7ddfbe88a84e22a8940d496037ab67f23491c639e8cc3e145b98697c921eb6c20577babec4be2a8e6a3221264e925cdc01

data/README.md

@@ -6,7 +6,7 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 
 **Supports:**
 - Merged object and abstract types.
-- Multiple keys per merged type.
+- Multiple and composite keys per merged type.
 - 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).
@@ -94,7 +94,7 @@ To facilitate this merging of types, stitching must know how to cross-reference
 Types merge through resolver queries identified by a `@stitch` directive:
 
 ```graphql
-directive @stitch(key: String!) repeatable on FIELD_DEFINITION
+directive @stitch(key: String!, arguments: String) repeatable on FIELD_DEFINITION
 ```
 
 This directive (or [static configuration](#sdl-based-schemas)) is applied to root queries where a merged type may be accessed in each location, and a `key` argument specifies a field needed from other locations to be used as a query argument.
@@ -151,7 +151,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).
+* 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](#argument-shapes) later).
 
 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:
 
@@ -198,7 +198,7 @@ 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
+directive @stitch(key: String!, arguments: String, typeName: String) repeatable on FIELD_DEFINITION
 
 type Product { sku: ID! }
 type Order { id: ID! }
@@ -212,19 +212,69 @@ type Query {
 }
 ```
 
-#### Multiple query arguments
+#### Argument shapes
 
-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>"`.
+Stitching infers which argument to use for queries with a single argument, or when the key name matches its intended argument. For custom mappings, the `arguments` option may specify a template of GraphQL arguments that insert key selections:
 
 ```graphql
 type Product {
   id: ID!
 }
 type Query {
-  product(byId: ID, bySku: ID): Product @stitch(key: "byId:id")
+  product(byId: ID, bySku: ID): Product
+    @stitch(key: "id", arguments: "byId: $.id")
 }
 ```
 
+Key insertions are prefixed by `$` and specify a dot-notation path to any selections made by the resolver `key`, or `__typename`. This syntax allows sending multiple arguments that intermix stitching keys with complex input shapes and other static values:
+
+```graphql
+type Product {
+  id: ID!
+}
+union Entity = Product
+input EntityKey {
+  id: ID!
+  type: String!
+}
+
+type Query {
+  entities(keys: [EntityKey!]!, source: String="database"): [Entity]!
+    @stitch(key: "id", arguments: "keys: { id: $.id, type: $.__typename }, source: 'cache'")
+}
+```
+
+See [resolver arguments](./docs/resolver.md#arguments) for full documentation on shaping input.
+
+#### Composite type keys
+
+Resolver keys may make composite selections for multiple key fields and/or nested scopes, for example:
+
+```graphql
+interface FieldOwner {
+  id: ID!
+  type: String!
+}
+type CustomField {
+  owner: FieldOwner!
+  key: String!
+  value: String
+}
+input CustomFieldLookup {
+  ownerId: ID!
+  ownerType: String!
+  key: String!
+}
+type Query {
+  customFields(lookups: [CustomFieldLookup!]!): [CustomField]! @stitch(
+    key: "owner { id type } key",
+    arguments: "lookups: { ownerId: $.owner.id, ownerType: $.owner.type, key: $.key }"
+  )
+}
+```
+
+Note that composite key selections may _not_ be distributed across locations. The complete selection criteria must be available in each location that provides the key.
+
 #### Multiple type keys
 
 A type may exist in multiple locations across the graph using different keys, for example:
@@ -265,7 +315,7 @@ type Query {
 The `@stitch` directive can be added to class-based schemas with a directive class:
 
 ```ruby
-class StitchField < GraphQL::Schema::Directive
+class StitchingResolver < GraphQL::Schema::Directive
   graphql_name "stitch"
   locations FIELD_DEFINITION
   repeatable true
@@ -274,7 +324,7 @@ end
 
 class Query < GraphQL::Schema::Object
   field :product, Product, null: false do
-    directive StitchField, key: "id"
+    directive StitchingResolver, key: "id"
     argument :id, ID, required: true
   end
 end
@@ -284,7 +334,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 by passing a `stitch` array in [location settings](./docs/composer.md#performing-composition):
+A clean schema 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
@@ -316,7 +366,7 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
 The library is configured to use a `@stitch` directive by default. You may customize this by setting a new name during initialization:
 
 ```ruby
-GraphQL::Stitching.stitch_directive = "merge"
+GraphQL::Stitching.stitch_directive = "resolver"
 ```
 
 ## Executables
@@ -365,17 +415,17 @@ The `GraphQL::Stitching::HttpExecutable` class is provided as a simple executabl
 The stitching executor automatically batches subgraph requests so that only one request is made per location per generation of data. This is done using batched queries that combine all data access for a given a location. For example:
 
 ```graphql
-query MyOperation_2 {
-  _0_result: widgets(ids:["a","b","c"]) { ... } # << 3 Widget
-  _1_0_result: sprocket(id:"x") { ... } # << 1 Sprocket
-  _1_1_result: sprocket(id:"y") { ... } # << 1 Sprocket
-  _1_2_result: sprocket(id:"z") { ... } # << 1 Sprocket
+query MyOperation_2($_0_key:[ID!]!, $_1_0_key:ID!, $_1_1_key:ID!, $_1_2_key:ID!) {
+  _0_result: widgets(ids: $_0_key) { ... } # << 3 Widget
+  _1_0_result: sprocket(id: $_1_0_key) { ... } # << 1 Sprocket
+  _1_1_result: sprocket(id: $_1_1_key) { ... } # << 1 Sprocket
+  _1_2_result: sprocket(id: $_1_2_key) { ... } # << 1 Sprocket
 }
 ```
 
 Tips:
 
-* List queries (like the `widgets` selection above) are more compact for accessing multiple records, and are therefore preferable as stitching accessors.
+* List queries (like the `widgets` selection above) are generally preferable as resolver queries because they keep the batched document consistent regardless of set size, and make for smaller documents that parse and validate faster.
 * Assure that root field resolvers across your subgraph implement batching to anticipate cases like the three `sprocket` selections above.
 
 Otherwise, there's no developer intervention necessary (or generally possible) to improve upon data access. Note that multiple generations of data may still force the executor to return to a previous location for more data.

data/docs/README.md

@@ -14,4 +14,5 @@ Major components include:
 
 Additional topics:
 
-- [Stitching mechanics](./mechanics.md) - learn more about building for stitching.
+- [Stitching mechanics](./mechanics.md) - more about building for stitching and how it operates.
+- [Federation entities](./federation_entities.md) - more about Apollo Federation compatibility.

data/docs/mechanics.md

@@ -314,6 +314,7 @@ Merged types do not always require a resolver query. For example:
 type Widget {
   id: ID!
   name: String
+  price: Float
 }
 
 type Query {
@@ -344,4 +345,4 @@ type Query {
 }
 ```
 
-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.
+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 shared key field (such as `id` above) that allow them to join with data in other resolver locations (such as `price` above).

data/docs/resolver.md

@@ -0,0 +1,101 @@
+## GraphQL::Stitching::Resolver
+
+A `Resolver` contains all information about a root query used by stitching to fetch location-specific variants of a merged type. Specifically, resolvers manage parsed keys and argument structures.
+
+### Arguments
+
+Resolvers configure arguments through a template string of [GraphQL argument literal syntax](https://spec.graphql.org/October2021/#sec-Language.Arguments). This allows sending multiple arguments that intermix stitching keys with complex object shapes and other static values.
+
+#### Key insertions
+
+Key values fetched from previous locations may be inserted into arguments. Key insertions are prefixed by `$` and specify a dot-notation path to any selections made by the resolver `key`, or `__typename`.
+
+```graphql
+type Query {
+  entity(id: ID!, type: String!): [Entity]!
+    @stitch(key: "owner { id }", arguments: "id: $.owner.id, type: $.__typename")
+}
+```
+
+Key insertions are _not_ quoted to differentiate them from other literal values.
+
+#### Lists
+
+List arguments may specify input just like non-list arguments, and [GraphQL list input coercion](https://spec.graphql.org/October2021/#sec-List.Input-Coercion) will assume the shape represents a list item:
+
+```graphql
+type Query {
+  product(ids: [ID!]!, source: DataSource!): [Product]!
+    @stitch(key: "id", arguments: "ids: $.id, source: CACHE")
+}
+```
+
+List resolvers (that return list types) may _only_ insert keys into repeatable list arguments, while non-list arguments may only contain static values. Nested list inputs are neither common nor practical, so are not supported.
+
+#### Built-in scalars
+
+Built-in scalars are written as normal literal values. For convenience, string literals may be enclosed in single quotes rather than escaped double-quotes:
+
+```graphql
+type Query {
+  product(id: ID!, source: String!): Product
+    @stitch(key: "id", arguments: "id: $.id, source: 'cache'")
+
+  variant(id: ID!, limit: Int!): Variant
+    @stitch(key: "id", arguments: "id: $.id, limit: 100")
+}
+```
+
+All scalar usage must be legal to the resolver field's arguments schema.
+
+#### Enums
+
+Enum literals may be provided anywhere in the input structure. They are _not_ quoted:
+
+```graphql
+enum DataSource {
+  CACHE
+}
+type Query {
+  product(id: ID!, source: DataSource!): [Product]!
+    @stitch(key: "id", arguments: "id: $.id, source: CACHE")
+}
+```
+
+All enum usage must be legal to the resolver field's arguments schema.
+
+#### Input Objects
+
+Input objects may be provided anywhere in the input, even as nested structures. The stitching resolver will build the specified object shape:
+
+```graphql
+input ComplexKey {
+  id: ID
+  nested: ComplexKey
+}
+type Query {
+  product(key: ComplexKey!): [Product]!
+    @stitch(key: "id", arguments: "key: { nested: { id: $.id } }")
+}
+```
+
+Input object shapes must conform to their respective schema definitions based on their placement within resolver arguments.
+
+#### Custom scalars
+
+Custom scalar keys allow any input shape to be submitted, from primitive scalars to complex object structures. These values will be sent and recieved as untyped JSON input:
+
+```graphql
+type Product {
+  id: ID!
+}
+union Entity = Product
+scalar Key
+
+type Query {
+  entities(representations: [Key!]!): [Entity]!
+    @stitch(key: "id", arguments: "representations: { id: $.id, __typename: $.__typename }")
+}
+```
+
+Custom scalar arguments have no structured schema definition to validate against. This makes them flexible but quite lax, for better or worse.

data/lib/graphql/stitching/client.rb

@@ -70,7 +70,11 @@ module GraphQL
       def load_plan(request)
         if @on_cache_read && plan_json = @on_cache_read.call(request)
           plan = GraphQL::Stitching::Plan.from_json(JSON.parse(plan_json))
-          return request.plan(plan)
+
+          # only use plans referencing current resolver versions
+          if plan.ops.all? { |op| !op.resolver || @supergraph.resolvers_by_version[op.resolver] }
+            return request.plan(plan)
+          end
         end
 
         plan = request.plan

data/lib/graphql/stitching/composer/{boundary_config.rb → resolver_config.rb}

@@ -2,7 +2,7 @@
 
 module GraphQL::Stitching
   class Composer
-    class BoundaryConfig
+    class ResolverConfig
       ENTITY_TYPENAME = "_Entity"
       ENTITIES_QUERY = "_entities"
 
@@ -12,10 +12,10 @@ module GraphQL::Stitching
 
           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
+            raise CompositionError, "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
+            raise CompositionError, "Invalid stitch directive field `#{kwargs[:field_name]}`" unless field
 
             field_path = "#{location}.#{field.name}"
             memo[field_path] ||= []
@@ -30,15 +30,15 @@ module GraphQL::Stitching
             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)
-
+              key = Resolver.parse_key(directive.arguments.keyword_arguments.fetch(:fields))
+              key_fields = key.map { "#{_1.name}: $.#{_1.name}" }
               field_path = "#{location}._entities"
+
               memo[field_path] ||= []
               memo[field_path] << new(
-                key: key,
+                key: key.to_definition,
                 type_name: entity_type.graphql_name,
-                federation: true,
+                arguments: "representations: { #{key_fields.join(", ")}, __typename: $.__typename }",
               )
             end
           end
@@ -48,7 +48,7 @@ module GraphQL::Stitching
           new(
             key: kwargs[:key],
             type_name: kwargs[:type_name] || kwargs[:typeName],
-            federation: kwargs[:federation] || false,
+            arguments: kwargs[:arguments],
           )
         end
 
@@ -57,16 +57,21 @@ module GraphQL::Stitching
         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
+          entity_type &&
+            entity_type.kind.union? &&
+            entities_query &&
+            entities_query.arguments["representations"] &&
+            entities_query.type.list? &&
+            entities_query.type.unwrap == entity_type
         end
       end
 
-      attr_reader :key, :type_name, :federation
+      attr_reader :key, :type_name, :arguments
 
-      def initialize(key:, type_name:, federation: false)
+      def initialize(key:, type_name:, arguments: nil)
         @key = key
         @type_name = type_name
-        @federation = federation
+        @arguments = arguments
       end
     end
   end

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

@@ -15,7 +15,7 @@ module GraphQL::Stitching
               # graphql-ruby will dynamically apply interface fields on a type implementation,
               # so check the delegation map to assure that all materialized fields have resolver locations.
               unless supergraph.locations_by_type_and_field[possible_type.graphql_name][field_name]&.any?
-                raise Composer::ValidationError, "Type #{possible_type.graphql_name} does not implement a `#{field_name}` field in any location, "\
+                raise ValidationError, "Type #{possible_type.graphql_name} does not implement a `#{field_name}` field in any location, "\
                   "which is required by interface #{interface_type.graphql_name}."
               end
 
@@ -24,7 +24,7 @@ module GraphQL::Stitching
               possible_type_structure = Util.flatten_type_structure(intersecting_field.type)
 
               if possible_type_structure.length != interface_type_structure.length
-                raise Composer::ValidationError, "Incompatible list structures between field #{possible_type.graphql_name}.#{field_name} of type "\
+                raise ValidationError, "Incompatible list structures 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
 
@@ -32,12 +32,12 @@ module GraphQL::Stitching
                 possible_struct = possible_type_structure[index]
 
                 if possible_struct.name != interface_struct.name
-                  raise Composer::ValidationError, "Incompatible named types between field #{possible_type.graphql_name}.#{field_name} of type "\
+                  raise 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.non_null?
-                  raise Composer::ValidationError, "Incompatible nullability between field #{possible_type.graphql_name}.#{field_name} of type "\
+                  raise 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
               end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Composer
+    class ValidateResolvers < BaseValidator
+
+      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 supergraph.schema.query == type || supergraph.schema.mutation == type
+          next if type.graphql_name.start_with?("__")
+
+          # multiple subschemas implement the type
+          subgraph_types_by_location = composer.subgraph_types_by_name_and_location[type_name]
+          next unless subgraph_types_by_location.length > 1
+
+          resolvers = supergraph.resolvers[type_name]
+          if resolvers&.any?
+            validate_as_resolver(supergraph, type, subgraph_types_by_location, resolvers)
+          elsif type.kind.object?
+            validate_as_shared(supergraph, type, subgraph_types_by_location)
+          end
+        end
+      end
+
+      private
+
+      def validate_as_resolver(supergraph, type, subgraph_types_by_location, resolvers)
+        # abstract resolvers are expanded with their concrete implementations, which each get validated. Ignore the abstract itself.
+        return if type.kind.abstract?
+
+        # only one resolver allowed per type/location/key
+        resolvers_by_location_and_key = resolvers.each_with_object({}) do |resolver, memo|
+          if memo.dig(resolver.location, resolver.key.to_definition)
+            raise ValidationError, "Multiple resolver queries for `#{type.graphql_name}.#{resolver.key}` "\
+              "found in #{resolver.location}. Limit one resolver query per type and key in each location. "\
+              "Abstract resolvers provide all possible types."
+          end
+          memo[resolver.location] ||= {}
+          memo[resolver.location][resolver.key.to_definition] = resolver
+        end
+
+        resolver_keys = resolvers.map(&:key)
+        resolver_key_strs = resolver_keys.map(&:to_definition).to_set
+
+        # All non-key fields must be resolvable in at least one resolver location
+        supergraph.locations_by_type_and_field[type.graphql_name].each do |field_name, locations|
+          next if resolver_key_strs.include?(field_name)
+
+          if locations.none? { resolvers_by_location_and_key[_1] }
+            where = locations.length > 1 ? "one of #{locations.join(", ")} locations" : locations.first
+            raise ValidationError, "A resolver query is required for `#{type.graphql_name}` in #{where} to resolve field `#{field_name}`."
+          end
+        end
+
+        # All locations of a merged type must include at least one resolver key
+        supergraph.fields_by_type_and_location[type.graphql_name].each_key do |location|
+          if resolver_keys.none? { _1.locations.include?(location) }
+            raise ValidationError, "A resolver 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
+        resolver_locations = resolvers_by_location_and_key.keys
+        subgraph_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 ValidationError, "Cannot route `#{type.graphql_name}` resolvers in #{location} to all other locations. "\
+              "All locations must provide a resolver query with a joining key."
+          end
+        end
+      end
+
+      def validate_as_shared(supergraph, type, subgraph_types_by_location)
+        expected_fields = begin
+          type.fields.keys.sort
+        rescue StandardError => e
+          # bug with inherited interfaces in older versions of GraphQL
+          if type.interfaces.any? { _1.is_a?(GraphQL::Schema::LateBoundType) }
+            raise CompositionError, "Merged interface inheritance requires GraphQL >= v2.0.3"
+          else
+            raise e
+          end
+        end
+
+        subgraph_types_by_location.each do |location, subgraph_type|
+          if subgraph_type.fields.keys.sort != expected_fields
+            raise ValidationError, "Shared type `#{type.graphql_name}` must have consistent fields across locations, "\
+              "or else define resolver queries so that its unique fields may be accessed remotely."
+          end
+        end
+      end
+    end
+  end
+end