graphql-stitching 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d33ec469a7f4598bd9f198b25102bcb3453d034b124fb18bcfd8ec595b78a6ce
-  data.tar.gz: a6ef6c8e218045a508c22ade74fb83504d762c0a6cadb5ed3cd4f58a89bddcea
+  metadata.gz: 448ca61527e02c6f232fa811e7e99ba1aa243bc58685f313ca5613a6724ea306
+  data.tar.gz: a0af76ea7eb429d60f5a7e4df4c39103539a01a69136c769f027cef52a108cab
 SHA512:
-  metadata.gz: dc753d25c70045d1f2f995a0bbc8329ab426e1c5426943fa88e03fa71128fe8c1da928a8c905c997396c4d248e26e4400a02e2b2bc56d9e26b4916b5c63a8a7b
-  data.tar.gz: fdea7099a1cb486df512bdb93e7d90cceef42e7ff875e4c72c8e4b1fb46836d9e15cf5ae6124ca81132ec2a0707aca08a0d2a80d35fc40b18cf036c12576ff43
+  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:

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/resolver_config.rb

@@ -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,
-                representations: 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],
-            representations: kwargs[:representations] || 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, :representations
+      attr_reader :key, :type_name, :arguments
 
-      def initialize(key:, type_name:, representations: false)
+      def initialize(key:, type_name:, arguments: nil)
         @key = key
         @type_name = type_name
-        @representations = representations
+        @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

@@ -12,81 +12,82 @@ module GraphQL::Stitching
           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
+          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, candidate_types_by_location, resolvers)
+            validate_as_resolver(supergraph, type, subgraph_types_by_location, resolvers)
           elsif type.kind.object?
-            validate_as_shared(supergraph, type, candidate_types_by_location)
+            validate_as_shared(supergraph, type, subgraph_types_by_location)
           end
         end
       end
 
       private
 
-      def validate_as_resolver(supergraph, type, candidate_types_by_location, resolvers)
+      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)
-            raise Composer::ValidationError, "Multiple resolver queries for `#{type.graphql_name}.#{resolver.key}` "\
+          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] = resolver
+          memo[resolver.location][resolver.key.to_definition] = resolver
         end
 
-        resolver_keys = resolvers.map(&:key).to_set
+        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_keys.include?(field_name)
+          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 Composer::ValidationError, "A resolver query is required for `#{type.graphql_name}` in #{where} to resolve field `#{field_name}`."
+            raise ValidationError, "A resolver query is required for `#{type.graphql_name}` in #{where} to resolve field `#{field_name}`."
           end
         end
 
-        # All locations of a resolver 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? { resolver_keys.include?(_1) }
-            raise Composer::ValidationError, "A resolver key is required for `#{type.graphql_name}` in #{location} to join with other locations."
+        # 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
-        candidate_types_by_location.each_key do |location|
+        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 Composer::ValidationError, "Cannot route `#{type.graphql_name}` resolvers in #{location} to all other locations. "\
+            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, candidate_types_by_location)
+      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 Composer::ComposerError, "Merged interface inheritance requires GraphQL >= v2.0.3"
+            raise CompositionError, "Merged interface inheritance requires GraphQL >= v2.0.3"
           else
             raise e
           end
         end
 
-        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, "\
+        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