graphql-stitching 1.0.6 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbeabcd8c2327504cc5ccc613942d163bddddb2087e7eb90c966861777d67b9d
-  data.tar.gz: cf03589e91ef96fb8dc9b74ca2703c20095e586bab45f91a89b3579376edbdac
+  metadata.gz: 66c85693da3a07eb7b3ab81fe76b69ce095aaffa8b9cab68a1f34b86e20963ba
+  data.tar.gz: f1e8bbbe3ffdaf23189f219cad6fe604203527e12911a0609fb1711375effe58
 SHA512:
-  metadata.gz: 78b5d6bbf4abccb99795c6225e1a61807ed74f94ad9ce5bdde0be534133e101c7d51f677d3c89aebaad7ebe2b125ff11a192a3d1a29cdacb3d3b51049801212f
-  data.tar.gz: ade024c4ace1474d9c7a7cd80fb8820fc71e456e566d89fe656d07bf4b64e60db83561546a908b5d2fcbec9d88ac740a7080946e981a74f7bd904b3da0aeebfb
+  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, _request|
-  $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, _request|
-  $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 when possible:
+Note that inlined input data works against caching, so you should _avoid_ these input literals when possible:
 
 ```graphql
 query {
@@ -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, request)
+          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, request)
+          @on_cache_write.call(request, JSON.generate(plan.as_json))
         end
 
         plan

data/lib/graphql/stitching/composer.rb

@@ -541,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/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/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.6"
+    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.6
+  version: 1.1.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-29 00:00:00.000000000 Z
+date: 2023-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql