coming together.

Author: gmac

docs/composing_a_supergraph.md

@@ -42,11 +42,7 @@ client = GraphQL::Stitching::Client.new(
     mutation_name: "Mutation",
     subscription_name: "Subscription",
     visibility_profiles: nil, # ["public", "private", ...]
-    description_merger: ->(values_by_location, info) { values_by_location.values.join("\n") },
-    deprecation_merger: ->(values_by_location, info) { values_by_location.values.first },
-    default_value_merger: ->(values_by_location, info) { values_by_location.values.first },
-    directive_kwarg_merger: ->(values_by_location, info) { values_by_location.values.last },
-    root_entrypoints: {},
+    root_entrypoints: { "Query.ping" => "pings" },
   },
   locations: {
     # ...
@@ -62,47 +58,49 @@ client = GraphQL::Stitching::Client.new(
 
 - **`visibility_profiles:`**, an array of [visibility profiles](./visibility.md) that the supergraph responds to.
 
-- **`description_merger:`**, a [value merger function](#value-merger-functions) for merging element description strings from across locations.
-
-- **`deprecation_merger:`**, a [value merger function](#value-merger-functions) for merging element deprecation strings from across locations.
-
-- **`default_value_merger:`**, a [value merger function](#value-merger-functions) for merging argument default values from across locations.
-
-- **`directive_kwarg_merger:`**, a [value merger function](#value-merger-functions) for merging directive keyword arguments from across locations.
-
 - **`root_entrypoints:`**, a hash of root field names mapped to their entrypoint locations, see [overlapping root fields](#overlapping-root-fields) below.
 
-#### Value merger functions
+### Value mergers
 
-Static data values such as element descriptions and directive arguments must also merge across locations. By default, the first non-null value encountered for a given element attribute is used. A value merger function may customize this process by selecting a different value or computing a new one:
+Static data values such as element descriptions and directive arguments must also merge across locations. By default, the first non-null value encountered for a given element property is used. Value merger methods can be customized by defining them on your own `Client` class:
 
 ```ruby
-join_values_merger = ->(values_by_location, info) { values_by_location.values.compact.join("\n") }
-
-client = GraphQL::Stitching::Client.new(
-  composer_options: {
-    description_merger: join_values_merger,
-    deprecation_merger: join_values_merger,
-    default_value_merger: join_values_merger,
-    directive_kwarg_merger: join_values_merger,
-  },
-)
+class MyClient < GraphQL::Stitching::Client
+  def merge_descriptions(values_by_location, info)
+    # return a merged element description string from across locations...
+    values_by_location.each_value.join("\n")
+  end
+
+  def merge_deprecations(values_by_location, info)
+    # return a merged element deprecation string from across locations...
+  end
+
+  def merge_default_values(values_by_location, info)
+    # return a merged argument default value from across locations...
+  end
+
+  def merge_kwargs(values_by_location, info)
+    # return a merged directive keyword argument from across locations...
+  end
+end
+
+client = MyClient.new(locations: ...)
 ```
 
-A merger function receives `values_by_location` and `info` arguments; these provide possible values keyed by location and info about where in the schema these values were encountered:
+All merge functions receive `values_by_location` and `info` arguments; these provide possible values keyed by location and info about where in the schema these values were encountered. For example:
 
 ```ruby
 values_by_location = {
-  "users" => "A fabulous data type.",
-  "products" => "An excellent data type.",
+  "users" => "A fabulous data type description.",
+  "products" => "An excellent data type description.",
 }
 
-info = {
+info = GraphQL::Stitching::Formatter::Info.new(
   type_name: "Product",
   # field_name: ...,
   # argument_name: ...,
   # directive_name: ...,
-}
+)
 ```
 
 ### Cached supergraphs

lib/graphql/stitching/client.rb

@@ -7,6 +7,8 @@ module Stitching
     # Client is an out-of-the-box helper that assembles all 
     # stitching components into a workflow that executes requests.
     class Client
+      include Formatter
+
       class << self
         def from_definition(schema, executables:)
           new(supergraph: Supergraph.from_definition(schema, executables: executables))
@@ -30,6 +32,7 @@ def initialize(locations: nil, supergraph: nil, composer_options: {})
         elsif supergraph
           supergraph
         else
+          composer_options = { formatter: self }.merge!(composer_options)
           composer = Composer.new(**composer_options)
           composer.perform(locations)
         end
@@ -58,29 +61,45 @@ def execute(raw_query = nil, query: nil, variables: nil, operation_name: nil, co
       rescue GraphQL::ParseError, GraphQL::ExecutionError => e
         error_result(request, [e])
       rescue StandardError => e
-        custom_message = @on_error.call(request, e) if @on_error
-        error_result(request, [{ "message" => custom_message || "An unexpected error occured." }])
+        error_result(request, [handle_error(request, e)])
       end
 
       def on_cache_read(&block)
+        Warning.warn("Using `on_cache_read` is deprecated and will be removed. Use `read_cached_plan` instead.")
         raise ArgumentError, "A cache read block is required." unless block_given?
         @on_cache_read = block
       end
 
       def on_cache_write(&block)
+        Warning.warn("Using `on_cache_write` is deprecated and will be removed. Use `write_cached_plan` instead.")
         raise ArgumentError, "A cache write block is required." unless block_given?
         @on_cache_write = block
       end
 
       def on_error(&block)
+        Warning.warn("Using `on_error` is deprecated and will be removed. Use `handle_error` instead.")
         raise ArgumentError, "An error handler block is required." unless block_given?
         @on_error = block
       end
 
+      def read_cached_plan(request)
+        @on_cache_read.call(request) if @on_cache_read
+      end
+
+      def write_cached_plan(request, plan)
+        @on_cache_write.call(request, JSON.generate(plan.as_json)) if @on_cache_write
+      end
+
+      def handle_error(request, error)
+        message = @on_error.call(request, error) if @on_error
+        message ||= "An unexpected error occured."
+        { "message" => message }
+      end
+
       private
 
       def load_plan(request)
-        if @on_cache_read && plan_json = @on_cache_read.call(request)
+        if (plan_json = read_cached_plan(request))
           plan = Plan.from_json(JSON.parse(plan_json))
 
           # only use plans referencing current resolver versions
@@ -89,20 +108,13 @@ def load_plan(request)
           end
         end
 
-        plan = request.plan
-
-        if @on_cache_write
-          @on_cache_write.call(request, JSON.generate(plan.as_json))
+        request.plan.tap do |plan|
+          write_cached_plan(request, plan)
         end
-
-        plan
       end
 
       def error_result(request, errors)
-        public_errors = errors.map! do |e|
-          e.is_a?(Hash) ? e : e.to_h
-        end
-
+        public_errors = errors.map! { |e| e.is_a?(Hash) ? e : e.to_h }
         GraphQL::Query::Result.new(query: request, values: { "errors" => public_errors })
       end
     end

lib/graphql/stitching/composer.rb

@@ -11,6 +11,8 @@ module Stitching
     # representing various graph locations and merges them into one 
     # combined Supergraph that is validated for integrity.
     class Composer
+      include Formatter
+
       # @api private
       NO_DEFAULT_VALUE = begin
         t = Class.new(GraphQL::Schema::Object) do
@@ -20,19 +22,6 @@ class Composer
         t.get_field("f").get_argument("a").default_value
       end
 
-      # @api private
-      BASIC_VALUE_MERGER = ->(values_by_location, _info) { values_by_location.each_value.find { !_1.nil? } }
-      
-      # @api private
-      VISIBILITY_PROFILES_MERGER = begin
-        f = Class.new(Formatter) do
-          def merge_kwargs(values_by_location, _info)
-            values_by_location.each_value.reduce(:&)
-          end
-        end
-        f.new
-      end
-
       # @api private
       COMPOSITION_VALIDATORS = [
         ValidateInterfaces,
@@ -59,18 +48,14 @@ def initialize(
         mutation_name: "Mutation",
         subscription_name: "Subscription",
         visibility_profiles: [],
-        deprecation_merger: nil,
-        root_field_location_selector: nil,
         root_entrypoints: nil,
         formatter: nil
       )
         @query_name = query_name
         @mutation_name = mutation_name
         @subscription_name = subscription_name
-        @deprecation_merger = deprecation_merger || BASIC_VALUE_MERGER
-        @root_field_location_selector = root_field_location_selector
         @root_entrypoints = root_entrypoints || {}
-        @formatter = formatter || Formatter.new
+        @formatter = formatter || self
 
         @field_map = {}
         @resolver_map = {}
@@ -232,7 +217,7 @@ def build_directive(directive_name, directives_by_location)
 
         Class.new(GraphQL::Schema::Directive) do
           graphql_name(directive_name)
-          description(builder.merge_descriptions(directive_name, directives_by_location))
+          description(builder.merge_member_descriptions(directive_name, directives_by_location))
           repeatable(directives_by_location.values.any?(&:repeatable?))
           locations(*directives_by_location.values.flat_map(&:locations).tap(&:uniq!))
           builder.build_merged_arguments(directive_name, directives_by_location, self, directive_name: directive_name)
@@ -249,7 +234,7 @@ def build_scalar_type(type_name, types_by_location)
 
         Class.new(GraphQL::Stitching::Supergraph::ScalarType) do
           graphql_name(type_name)
-          description(builder.merge_descriptions(type_name, types_by_location))
+          description(builder.merge_member_descriptions(type_name, types_by_location))
           builder.build_merged_directives(type_name, types_by_location, self)
         end
       end
@@ -276,14 +261,14 @@ def build_enum_type(type_name, types_by_location, enum_usage)
 
         Class.new(GraphQL::Stitching::Supergraph::EnumType) do
           graphql_name(type_name)
-          description(builder.merge_descriptions(type_name, types_by_location))
+          description(builder.merge_member_descriptions(type_name, types_by_location))
           builder.build_merged_directives(type_name, types_by_location, self)
 
           enum_values_by_name_location.each do |value_name, enum_values_by_location|
             enum_value = value(value_name,
               value: value_name,
-              description: builder.merge_descriptions(type_name, enum_values_by_location, enum_value: value_name),
-              deprecation_reason: builder.merge_deprecations(type_name, enum_values_by_location, enum_value: value_name),
+              description: builder.merge_member_descriptions(type_name, enum_values_by_location, enum_value: value_name),
+              deprecation_reason: builder.merge_member_deprecations(type_name, enum_values_by_location, enum_value: value_name),
             )
 
             builder.build_merged_directives(type_name, enum_values_by_location, enum_value, enum_value: value_name)
@@ -298,7 +283,7 @@ def build_object_type(type_name, types_by_location)
 
         Class.new(GraphQL::Stitching::Supergraph::ObjectType) do
           graphql_name(type_name)
-          description(builder.merge_descriptions(type_name, types_by_location))
+          description(builder.merge_member_descriptions(type_name, types_by_location))
 
           interface_names = types_by_location.values.flat_map { _1.interfaces.map(&:graphql_name) }
           interface_names.tap(&:uniq!).each do |interface_name|
@@ -318,7 +303,7 @@ def build_interface_type(type_name, types_by_location)
         Module.new do
           include GraphQL::Stitching::Supergraph::InterfaceType
           graphql_name(type_name)
-          description(builder.merge_descriptions(type_name, types_by_location))
+          description(builder.merge_member_descriptions(type_name, types_by_location))
 
           interface_names = types_by_location.values.flat_map { _1.interfaces.map(&:graphql_name) }
           interface_names.tap(&:uniq!).each do |interface_name|
@@ -337,7 +322,7 @@ def build_union_type(type_name, types_by_location)
 
         Class.new(GraphQL::Stitching::Supergraph::UnionType) do
           graphql_name(type_name)
-          description(builder.merge_descriptions(type_name, types_by_location))
+          description(builder.merge_member_descriptions(type_name, types_by_location))
 
           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) })
@@ -352,7 +337,7 @@ def build_input_object_type(type_name, types_by_location)
 
         Class.new(GraphQL::Stitching::Supergraph::InputObjectType) do
           graphql_name(type_name)
-          description(builder.merge_descriptions(type_name, types_by_location))
+          description(builder.merge_member_descriptions(type_name, types_by_location))
           builder.build_merged_arguments(type_name, types_by_location, self)
           builder.build_merged_directives(type_name, types_by_location, self)
         end
@@ -385,8 +370,8 @@ def build_merged_fields(type_name, types_by_location, owner)
           type = merge_value_types(type_name, value_types, field_name: field_name)
           schema_field = owner.field(
             field_name,
-            description: merge_descriptions(type_name, fields_by_location, field_name: field_name),
-            deprecation_reason: merge_deprecations(type_name, fields_by_location, field_name: field_name),
+            description: merge_member_descriptions(type_name, fields_by_location, field_name: field_name),
+            deprecation_reason: merge_member_deprecations(type_name, fields_by_location, field_name: field_name),
             type: Util.unwrap_non_null(type),
             null: !type.non_null?,
             connection: false,
@@ -438,8 +423,8 @@ def build_merged_arguments(type_name, members_by_location, owner, field_name: ni
           type = merge_value_types(type_name, value_types, argument_name: argument_name, field_name: field_name)
           schema_argument = owner.argument(
             argument_name,
-            description: merge_descriptions(type_name, arguments_by_location, argument_name: argument_name, field_name: field_name),
-            deprecation_reason: merge_deprecations(type_name, arguments_by_location, argument_name: argument_name, field_name: field_name),
+            description: merge_member_descriptions(type_name, arguments_by_location, argument_name: argument_name, field_name: field_name),
+            deprecation_reason: merge_member_deprecations(type_name, arguments_by_location, argument_name: argument_name, field_name: field_name),
             type: Util.unwrap_non_null(type),
             required: type.non_null?,
             camelize: false,
@@ -484,7 +469,7 @@ def build_merged_directives(type_name, members_by_location, owner, field_name: n
 
             if (profiles = kwarg_values_by_name_location["profiles"])
               @visibility_profiles.merge(profiles.each_value.reduce(&:|))
-              kwarg_formatter = VISIBILITY_PROFILES_MERGER
+              kwarg_formatter = self
             end
           end
 
@@ -538,7 +523,7 @@ def merge_value_types(type_name, subgraph_types, field_name: nil, argument_name:
 
       # @!scope class
       # @!visibility private
-      def merge_descriptions(type_name, members_by_location, field_name: nil, argument_name: nil, enum_value: nil)
+      def merge_member_descriptions(type_name, members_by_location, field_name: nil, argument_name: nil, enum_value: nil)
         strings_by_location = members_by_location.each_with_object({}) { |(l, m), memo| memo[l] = m.description }
         @formatter.merge_descriptions(strings_by_location, Formatter::Info.new(
           type_name: type_name,
@@ -550,14 +535,14 @@ def merge_descriptions(type_name, members_by_location, field_name: nil, argument
 
       # @!scope class
       # @!visibility private
-      def merge_deprecations(type_name, members_by_location, field_name: nil, argument_name: nil, enum_value: nil)
+      def merge_member_deprecations(type_name, members_by_location, field_name: nil, argument_name: nil, enum_value: nil)
         strings_by_location = members_by_location.each_with_object({}) { |(l, m), memo| memo[l] = m.deprecation_reason }
-        @deprecation_merger.call(strings_by_location, {
+        @formatter.merge_deprecations(strings_by_location, Formatter::Info.new(
           type_name: type_name,
           field_name: field_name,
           argument_name: argument_name,
           enum_value: enum_value,
-        }.tap(&:compact!))
+        ))
       end
 
       # @!scope class
@@ -632,15 +617,7 @@ def select_root_field_locations(schema)
             next unless root_field_locations.length > 1
 
             root_field_path = "#{root_type.graphql_name}.#{root_field_name}"
-            target_location = if @root_field_location_selector && @root_entrypoints.empty?
-              Warning.warn("Composer option `root_field_location_selector` is deprecated and will be removed.")
-              @root_field_location_selector.call(root_field_locations, {
-                type_name: root_type.graphql_name,
-                field_name: root_field_name,
-              })
-            else
-              @root_entrypoints[root_field_path] || root_field_locations.last
-            end
+            target_location = @root_entrypoints[root_field_path] || root_field_locations.last
 
             unless root_field_locations.include?(target_location)
               raise CompositionError, "Invalid `root_entrypoints` configuration: `#{root_field_path}` has no `#{target_location}` location."

lib/graphql/stitching/formatter.rb

@@ -5,7 +5,7 @@
 
 module GraphQL
   module Stitching
-    class Formatter
+    module Formatter
       class Info
         attr_reader :type_name, :field_name, :argument_name, :enum_value, :directive_name, :kwarg_name
 
@@ -43,7 +43,11 @@ def merge_default_values(values_by_location, info)
       end
 
       def merge_kwargs(values_by_location, info)
-        merge_values(values_by_location, info)
+        if info.directive_name == GraphQL::Stitching.visibility_directive
+          values_by_location.each_value.reduce(:&)
+        else
+          merge_values(values_by_location, info)
+        end
       end
     end
   end