graphql-stitching 1.0.5 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d90338dfde5c26515a55afdee7f5bd936a4563b2b8f83e1ffc1a4420c56a5cf
-  data.tar.gz: d728c5dfabb5e0250c38a6718ac7b535cfa7a183872dc60fa95a9b91b777a64a
+  metadata.gz: 66c85693da3a07eb7b3ab81fe76b69ce095aaffa8b9cab68a1f34b86e20963ba
+  data.tar.gz: f1e8bbbe3ffdaf23189f219cad6fe604203527e12911a0609fb1711375effe58
 SHA512:
-  metadata.gz: cc5ff912f354e08b9f204028d5e6eed85a81bf283bd5dc13bb7ee9b69b83d0bb39ba83f9fbaac66be1363e86ce3f6bd1b3f7cc4466ef83998a751e3dbccf9013
-  data.tar.gz: 055e1c09f88e8f893a3ebb0aa3d7558156ec5c4a33b704cca69499efee4fd02e3a70e6efedeca1332f92392c7093ea8024ba9aefb159ce77b4f11510cd8d7a1c
+  metadata.gz: a86ac6f20dda8dc5ae68d548d85d9c4482856c56e86a07cee9ff5689ba95cf73f19dadd80d6f711a55a0b9e25796522b1b1feb4c7d70f7fa499a0f38beb0d24a
+  data.tar.gz: 61b2d6f21dc8001fab5e6d8c27d3cc04582fc506daa17f45354475cb9ef6812a355ec5819257d9d582d7f4a312b85b10b539322e3fa14b73a255376a75687658

data/docs/client.md

@@ -25,11 +25,9 @@ client = GraphQL::Stitching::Client.new(locations: {
 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,
+supergraph_sdl = File.read("precomposed_schema.graphql")
+supergraph = GraphQL::Stitching::Supergraph.from_definition(
+  supergraph_sdl,
   executables: { ... },
 )
 
@@ -61,16 +59,16 @@ Arguments for the `execute` method include:
 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
+client.on_cache_read do |request|
+  $redis.get(request.digest) # << 3P code
 end
 
-client.on_cache_write do |key, payload, _context|
-  $redis.set(key, payload) # << 3P code
+client.on_cache_write do |request, payload|
+  $redis.set(request.digest, payload) # << 3P code
 end
 ```
 
-Note that inlined input data works against caching, so you should _avoid_ this:
+Note that inlined input data works against caching, so you should _avoid_ these input literals when possible:
 
 ```graphql
 query {
@@ -78,7 +76,7 @@ query {
 }
 ```
 
-Instead, always leverage variables in queries so that the document body remains consistent across requests:
+Instead, leverage query variables so that the document body remains consistent across requests:
 
 ```graphql
 query($id: ID!) {
@@ -93,11 +91,11 @@ query($id: ID!) {
 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|
+client.on_error do |request, err|
   # log the error
   Bugsnag.notify(err)
 
   # return a formatted message for the public response
-  "Whoops, please contact support abount request '#{context[:request_id]}'"
+  "Whoops, please contact support abount request '#{request.context[:request_id]}'"
 end
 ```

data/docs/request.md

@@ -3,18 +3,22 @@
 A `Request` contains a parsed GraphQL document and variables, and handles the logistics of extracting the appropriate operation, variable definitions, and fragments. A `Request` should be built once per server request and passed through to other stitching components that utilize request information.
 
 ```ruby
-document = "query FetchMovie($id: ID!) { movie(id:$id) { id genre } }"
-request = GraphQL::Stitching::Request.new(document, variables: { "id" => "1" }, operation_name: "FetchMovie")
-
-request.document # parsed AST via GraphQL.parse
-request.variables # user-submitted variables
-request.string # normalized printed document string
-request.digest # SHA digest of the normalized document string
-
-request.variable_definitions # a mapping of variable names to their type definitions
-request.fragment_definitions # a mapping of fragment names to their fragment definitions
+source = "query FetchMovie($id: ID!) { movie(id:$id) { id genre } }"
+request = GraphQL::Stitching::Request.new(source, variables: { "id" => "1" }, operation_name: "FetchMovie")
 ```
 
+A `Request` provides the following information:
+
+- `req.document`: parsed AST of the GraphQL source
+- `req.variables`: a hash of user-submitted variables
+- `req.string`: the original GraphQL source string, or printed document
+- `req.digest`: a SHA2 of the request string
+- `req.normalized_string`: printed document string with consistent whitespace
+- `req.normalized_digest`: a SHA2 of the normalized string
+- `req.operation`: the operation definition selected for the request
+- `req.variable_definitions`: a mapping of variable names to their type definitions
+- `req.fragment_definitions`: a mapping of fragment names to their fragment definitions
+
 ### Preparing requests
 
 A request should be prepared for stitching using the `prepare!` method _after_ validations have been run:

data/docs/supergraph.md

@@ -4,29 +4,25 @@ A `Supergraph` is the singuar representation of a stitched graph. `Supergraph` i
 
 ### Export and caching
 
-A Supergraph is designed to be composed, cached, and restored. Calling the `export` method will return an SDL (Schema Definition Language) print of the combined graph schema and a delegation mapping hash. These can be persisted in any raw format that suits your stack:
+A Supergraph is designed to be composed, cached, and restored. Calling `to_definition` will return an SDL (Schema Definition Language) print of the combined graph schema with delegation mapping directives. This pre-composed schema can be persisted in any raw format that suits your stack:
 
 ```ruby
-supergraph_sdl, delegation_map = supergraph.export
+supergraph_sdl = supergraph.to_definition
 
-# stash these resources in Redis...
+# stash this composed schema in a cache...
 $redis.set("cached_supergraph_sdl", supergraph_sdl)
-$redis.set("cached_delegation_map", JSON.generate(delegation_map))
 
-# or, write the resources as files and commit them to your repo...
+# or, write the composed schema as a file into your repo...
 File.write("supergraph/schema.graphql", supergraph_sdl)
-File.write("supergraph/delegation_map.json", JSON.generate(delegation_map))
 ```
 
-To restore a Supergraph, call `from_export` proving the cached SDL string, the parsed JSON delegation mapping, and a hash of executables keyed by their location names:
+To restore a Supergraph, call `from_definition` providing the cached SDL string and a hash of executables keyed by their location names:
 
 ```ruby
 supergraph_sdl = $redis.get("cached_supergraph_sdl")
-delegation_map = JSON.parse($redis.get("cached_delegation_map"))
 
-supergraph = GraphQL::Stitching::Supergraph.from_export(
-  schema: supergraph_sdl,
-  delegation_map: delegation_map,
+supergraph = GraphQL::Stitching::Supergraph.from_definition(
+  supergraph_sdl,
   executables: {
     my_remote: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3000"),
     my_local: MyLocalSchema,

data/lib/graphql/stitching/client.rb

@@ -52,7 +52,7 @@ module GraphQL
       rescue GraphQL::ParseError, GraphQL::ExecutionError => e
         error_result([e])
       rescue StandardError => e
-        custom_message = @on_error.call(e, request.context) if @on_error
+        custom_message = @on_error.call(request, e) if @on_error
         error_result([{ "message" => custom_message || "An unexpected error occured." }])
       end
 
@@ -75,14 +75,14 @@ module GraphQL
 
       def fetch_plan(request)
         if @on_cache_read
-          cached_plan = @on_cache_read.call(request.digest, request.context)
+          cached_plan = @on_cache_read.call(request)
           return GraphQL::Stitching::Plan.from_json(JSON.parse(cached_plan)) if cached_plan
         end
 
         plan = yield
 
         if @on_cache_write
-          @on_cache_write.call(request.digest, JSON.generate(plan.as_json), request.context)
+          @on_cache_write.call(request, JSON.generate(plan.as_json))
         end
 
         plan

data/lib/graphql/stitching/composer.rb

@@ -53,7 +53,7 @@ module GraphQL
           end
         end
 
-        # "Typename" => merged_directive
+        # "directive_name" => merged_directive
         @schema_directives = @candidate_directives_by_name_and_location.each_with_object({}) do |(directive_name, directives_by_location), memo|
           memo[directive_name] = build_directive(directive_name, directives_by_location)
         end
@@ -88,19 +88,20 @@ module GraphQL
 
         # "Typename" => merged_type
         schema_types = @candidate_types_by_name_and_location.each_with_object({}) do |(type_name, types_by_location), memo|
-          kinds = types_by_location.values.map { _1.kind.name }.uniq
+          kinds = types_by_location.values.map { _1.kind.name }.tap(&:uniq!)
 
           if kinds.length > 1
             raise ComposerError, "Cannot merge different kinds for `#{type_name}`. Found: #{kinds.join(", ")}."
           end
 
+          extract_boundaries(type_name, types_by_location) if type_name == @query_name
+
           memo[type_name] = case kinds.first
           when "SCALAR"
             build_scalar_type(type_name, types_by_location)
           when "ENUM"
             build_enum_type(type_name, types_by_location, enum_usage)
           when "OBJECT"
-            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)
@@ -200,7 +201,7 @@ module GraphQL
           graphql_name(directive_name)
           description(builder.merge_descriptions(directive_name, directives_by_location))
           repeatable(directives_by_location.values.any?(&:repeatable?))
-          locations(*directives_by_location.values.flat_map(&:locations).uniq)
+          locations(*directives_by_location.values.flat_map(&:locations).tap(&:uniq!))
           builder.build_merged_arguments(directive_name, directives_by_location, self, directive_name: directive_name)
         end
       end
@@ -262,7 +263,7 @@ module GraphQL
           description(builder.merge_descriptions(type_name, types_by_location))
 
           interface_names = types_by_location.values.flat_map { _1.interfaces.map(&:graphql_name) }
-          interface_names.uniq.each do |interface_name|
+          interface_names.tap(&:uniq!).each do |interface_name|
             implements(builder.build_type_binding(interface_name))
           end
 
@@ -280,7 +281,7 @@ module GraphQL
           description(builder.merge_descriptions(type_name, types_by_location))
 
           interface_names = types_by_location.values.flat_map { _1.interfaces.map(&:graphql_name) }
-          interface_names.uniq.each do |interface_name|
+          interface_names.tap(&:uniq!).each do |interface_name|
             implements(builder.build_type_binding(interface_name))
           end
 
@@ -296,7 +297,7 @@ module GraphQL
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
 
-          possible_names = types_by_location.values.flat_map { _1.possible_types.map(&:graphql_name) }.uniq
+          possible_names = types_by_location.values.flat_map { _1.possible_types.map(&:graphql_name) }.tap(&:uniq!)
           possible_types(*possible_names.map { builder.build_type_binding(_1) })
           builder.build_merged_directives(type_name, types_by_location, self)
         end
@@ -540,7 +541,7 @@ module GraphQL
                 field: field_candidate.name,
                 arg: argument_name,
                 list: boundary_structure.first.list?,
-                federation: kwargs[:federation],
+                federation: kwargs[:federation] || false,
               )
             end
           end

data/lib/graphql/stitching/executor/boundary_source.rb

@@ -160,7 +160,8 @@ module GraphQL
             errors_result.concat(pathed_errors_by_object_id.values)
           end
         end
-        errors_result.flatten!
+
+        errors_result.tap(&:flatten!)
       end
 
       private

data/lib/graphql/stitching/planner.rb

@@ -3,7 +3,7 @@
 module GraphQL
   module Stitching
     class Planner
-      SUPERGRAPH_LOCATIONS = [Supergraph::LOCATION].freeze
+      SUPERGRAPH_LOCATIONS = [Supergraph::SUPERGRAPH_LOCATION].freeze
       TYPENAME = "__typename"
       QUERY_OP = "query"
       MUTATION_OP = "mutation"

data/lib/graphql/stitching/request.rb

@@ -4,14 +4,13 @@ module GraphQL
   module Stitching
     class Request
       SUPPORTED_OPERATIONS = ["query", "mutation"].freeze
+      SKIP_INCLUDE_DIRECTIVE = /@(?:skip|include)/
 
       attr_reader :document, :variables, :operation_name, :context
 
       def initialize(document, operation_name: nil, variables: nil, context: nil)
-        @may_contain_runtime_directives = true
-
         @document = if document.is_a?(String)
-          @may_contain_runtime_directives = document.include?("@")
+          @string = document
           GraphQL.parse(document)
         else
           document
@@ -23,13 +22,21 @@ module GraphQL
       end
 
       def string
-        @string ||= @document.to_query_string
+        @string || normalized_string
+      end
+
+      def normalized_string
+        @normalized_string ||= @document.to_query_string
       end
 
       def digest
         @digest ||= Digest::SHA2.hexdigest(string)
       end
 
+      def normalized_digest
+        @normalized_digest ||= Digest::SHA2.hexdigest(normalized_string)
+      end
+
       def operation
         @operation ||= begin
           operation_defs = @document.definitions.select do |d|
@@ -69,18 +76,15 @@ module GraphQL
 
       def prepare!
         operation.variables.each do |v|
-          @variables[v.name] = v.default_value if @variables[v.name].nil?
+          @variables[v.name] = v.default_value if @variables[v.name].nil? && !v.default_value.nil?
         end
 
-        if @may_contain_runtime_directives
-          @document, modified = SkipInclude.render(@document, @variables)
-
-          if modified
-            @string = nil
-            @digest = nil
-            @operation = nil
-            @variable_definitions = nil
-            @fragment_definitions = nil
+        if @string.nil? || @string.match?(SKIP_INCLUDE_DIRECTIVE)
+          SkipInclude.render(@document, @variables) do |modified_ast|
+            @document = modified_ast
+            @string = @normalized_string = nil
+            @digest = @normalized_digest = nil
+            @operation = @operation_directives = @variable_definitions = nil
           end
         end
 

data/lib/graphql/stitching/skip_include.rb

@@ -15,7 +15,11 @@ module GraphQL
             definition
           end
 
-          return document.merge(definitions: definitions), changed
+          return document unless changed
+
+          document = document.merge(definitions: definitions)
+          yield(document) if block_given?
+          document
         end
 
         private

data/lib/graphql/stitching/supergraph.rb

@@ -3,34 +3,89 @@
 module GraphQL
   module Stitching
     class Supergraph
-      LOCATION = "__super"
+      SUPERGRAPH_LOCATION = "__super"
+
+      class ResolverDirective < GraphQL::Schema::Directive
+        graphql_name "resolver"
+        locations OBJECT, INTERFACE, UNION
+        argument :location, String, required: true
+        argument :key, String, required: true
+        argument :field, String, required: true
+        argument :arg, String, required: true
+        argument :list, Boolean, required: false
+        argument :federation, Boolean, required: false
+        repeatable true
+      end
 
-      def self.validate_executable!(location, executable)
-        return true if executable.is_a?(Class) && executable <= GraphQL::Schema
-        return true if executable && executable.respond_to?(:call)
-        raise StitchingError, "Invalid executable provided for location `#{location}`."
+      class SourceDirective < GraphQL::Schema::Directive
+        graphql_name "source"
+        locations FIELD_DEFINITION
+        argument :location, String, required: true
+        repeatable true
       end
 
-      def self.from_export(schema:, delegation_map:, executables:)
-        schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
+      class << self
+        def validate_executable!(location, executable)
+          return true if executable.is_a?(Class) && executable <= GraphQL::Schema
+          return true if executable && executable.respond_to?(:call)
+          raise StitchingError, "Invalid executable provided for location `#{location}`."
+        end
+
+        def from_definition(schema, executables:)
+          schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
+          field_map = {}
+          boundary_map = {}
+          possible_locations = {}
+          introspection_types = schema.introspection_system.types.keys
+
+          schema.types.each do |type_name, type|
+            next if introspection_types.include?(type_name)
+
+            type.directives.each do |directive|
+              next unless directive.graphql_name == ResolverDirective.graphql_name
+
+              kwargs = directive.arguments.keyword_arguments
+              boundary_map[type_name] ||= []
+              boundary_map[type_name] << Boundary.new(
+                type_name: type_name,
+                location: kwargs[:location],
+                key: kwargs[:key],
+                field: kwargs[:field],
+                arg: kwargs[:arg],
+                list: kwargs[:list] || false,
+                federation: kwargs[:federation] || false,
+              )
+            end
+
+            next unless type.kind.fields?
 
-        executables = delegation_map["locations"].each_with_object({}) do |location, memo|
-          executable = executables[location] || executables[location.to_sym]
-          if validate_executable!(location, executable)
-            memo[location] = executable
+            type.fields.each do |field_name, field|
+              field.directives.each do |d|
+                next unless d.graphql_name == SourceDirective.graphql_name
+
+                location = d.arguments.keyword_arguments[:location]
+                field_map[type_name] ||= {}
+                field_map[type_name][field_name] ||= []
+                field_map[type_name][field_name] << location
+                possible_locations[location] = true
+              end
+            end
           end
-        end
 
-        boundaries = delegation_map["boundaries"].map do |k, b|
-          [k, b.map { Boundary.new(**_1) }]
-        end
+          executables = possible_locations.keys.each_with_object({}) do |location, memo|
+            executable = executables[location] || executables[location.to_sym]
+            if validate_executable!(location, executable)
+              memo[location] = executable
+            end
+          end
 
-        new(
-          schema: schema,
-          fields: delegation_map["fields"],
-          boundaries: boundaries.to_h,
-          executables: executables,
-        )
+          new(
+            schema: schema,
+            fields: field_map,
+            boundaries: boundary_map,
+            executables: executables,
+          )
+        end
       end
 
       attr_reader :schema, :boundaries, :locations_by_type_and_field, :executables
@@ -48,32 +103,77 @@ module GraphQL
           next unless type.kind.fields?
 
           memo[type_name] = type.fields.keys.each_with_object({}) do |field_name, m|
-            m[field_name] = [LOCATION]
+            m[field_name] = [SUPERGRAPH_LOCATION]
           end
         end.freeze
 
         # validate and normalize executable references
-        @executables = executables.each_with_object({ LOCATION => @schema }) do |(location, executable), memo|
+        @executables = executables.each_with_object({ SUPERGRAPH_LOCATION => @schema }) do |(location, executable), memo|
           if self.class.validate_executable!(location, executable)
             memo[location.to_s] = executable
           end
         end.freeze
       end
 
+      def to_definition
+        if @schema.directives[ResolverDirective.graphql_name].nil?
+          @schema.directive(ResolverDirective)
+        end
+        if @schema.directives[SourceDirective.graphql_name].nil?
+          @schema.directive(SourceDirective)
+        end
+
+        @schema.types.each do |type_name, type|
+          if boundaries_for_type = @boundaries.dig(type_name)
+            boundaries_for_type.each do |boundary|
+              existing = type.directives.find do |d|
+                kwargs = d.arguments.keyword_arguments
+                d.graphql_name == ResolverDirective.graphql_name &&
+                  kwargs[:location] == boundary.location &&
+                  kwargs[:key] == boundary.key &&
+                  kwargs[:field] == boundary.field &&
+                  kwargs[:arg] == boundary.arg &&
+                  kwargs.fetch(:list, false) == boundary.list &&
+                  kwargs.fetch(:federation, false) == boundary.federation
+              end
+
+              type.directive(ResolverDirective, **{
+                location: boundary.location,
+                key: boundary.key,
+                field: boundary.field,
+                arg: boundary.arg,
+                list: boundary.list || nil,
+                federation: boundary.federation || nil,
+              }.tap(&:compact!)) if existing.nil?
+            end
+          end
+
+          next unless type.kind.fields?
+
+          type.fields.each do |field_name, field|
+            locations_for_field = @locations_by_type_and_field.dig(type_name, field_name)
+            next if locations_for_field.nil?
+
+            locations_for_field.each do |location|
+              existing = field.directives.find do |d|
+                d.graphql_name == SourceDirective.graphql_name &&
+                  d.arguments.keyword_arguments[:location] == location
+              end
+
+              field.directive(SourceDirective, location: location) if existing.nil?
+            end
+          end
+        end
+
+        @schema.to_definition
+      end
+
       def fields
         @locations_by_type_and_field.reject { |k, _v| memoized_introspection_types[k] }
       end
 
       def locations
-        @executables.keys.reject { _1 == LOCATION }
-      end
-
-      def export
-        return GraphQL::Schema::Printer.print_schema(@schema), {
-          "locations" => locations,
-          "fields" => fields,
-          "boundaries" => @boundaries.map { |k, b| [k, b.map(&:as_json)] }.to_h,
-        }
+        @executables.keys.reject { _1 == SUPERGRAPH_LOCATION }
       end
 
       def memoized_introspection_types

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.0.5"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.1.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-19 00:00:00.000000000 Z
+date: 2023-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql