graphql-stitching 1.0.0 → 1.0.1

data/lib/graphql/stitching/planner.rb

@@ -4,28 +4,25 @@ module GraphQL
   module Stitching
     class Planner
       SUPERGRAPH_LOCATIONS = [Supergraph::LOCATION].freeze
-      TYPENAME_NODE = GraphQL::Language::Nodes::Field.new(alias: "_STITCH_typename", name: "__typename")
-      ROOT_ORDER = 0
+      QUERY_OP = "query"
+      MUTATION_OP = "mutation"
+      ROOT_INDEX = 0
 
       def initialize(supergraph:, request:)
         @supergraph = supergraph
         @request = request
-        @planning_order = ROOT_ORDER
-        @operations_by_entrypoint = {}
+        @planning_index = ROOT_INDEX
+        @steps_by_entrypoint = {}
       end
 
       def perform
         build_root_entrypoints
         expand_abstract_boundaries
-        self
+        Plan.new(ops: steps.map(&:to_plan_op))
       end
 
-      def operations
-        @operations_by_entrypoint.values.sort_by!(&:order)
-      end
-
-      def to_h
-        { "ops" => operations.map!(&:to_h) }
+      def steps
+        @steps_by_entrypoint.values.sort_by!(&:index)
       end
 
       private
@@ -48,7 +45,7 @@ module GraphQL
       # B.3) Collect all variable definitions used within the filtered selection.
       # These specify which request variables to pass along with the selection.
       #
-      # B.4) Add a `__typename` selection to concrete types and abstracts that implement
+      # B.4) Add a `__typename` selection to abstracts and concrete types that implement
       # fragments. This provides resolved type information used during execution.
       #
       # C) Delegate adjoining selections to new entrypoint locations.
@@ -57,7 +54,7 @@ module GraphQL
       # C.3) Distribute remaining fields among locations weighted by greatest availability.
       #
       # D) Create paths routing to new entrypoint locations via boundary queries.
-      # D.1) Types joining through multiple keys route using a-star search.
+      # D.1) Types joining through multiple keys route using A* search.
       # D.2) Types joining through a single key route via quick location match.
       # (D.2 is an optional optimization of D.1)
       #
@@ -68,38 +65,38 @@ module GraphQL
       # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
       # **
 
-      # adds an entrypoint for fetching and inserting data into the aggregate result.
-      def add_entrypoint(
+      # adds a planning step for fetching and inserting data into the aggregate result.
+      def add_step(
         location:,
-        parent_order:,
+        parent_index:,
         parent_type:,
         selections:,
         variables: {},
         path: [],
-        operation_type: "query",
+        operation_type: QUERY_OP,
         boundary: nil
       )
         # coalesce repeat parameters into a single entrypoint
-        boundary_key = boundary ? boundary["key"] : "_"
-        entrypoint = String.new("#{parent_order}/#{location}/#{parent_type.graphql_name}/#{boundary_key}")
+        boundary_key = boundary ? boundary.key : "_"
+        entrypoint = String.new("#{parent_index}/#{location}/#{parent_type.graphql_name}/#{boundary_key}")
         path.each { entrypoint << "/#{_1}" }
 
-        op = @operations_by_entrypoint[entrypoint]
-        next_order = op ? parent_order : @planning_order += 1
+        step = @steps_by_entrypoint[entrypoint]
+        next_index = step ? parent_index : @planning_index += 1
 
         if selections.any?
-          selections = extract_locale_selections(location, parent_type, next_order, selections, path, variables)
+          selections = extract_locale_selections(location, parent_type, next_index, selections, path, variables)
         end
 
-        if op.nil?
+        if step.nil?
           # concrete types that are not root Query/Mutation report themselves as a type condition
           # executor must check the __typename of loaded objects to see if they match subsequent operations
           # this prevents the executor from taking action on unused fragment selections
           conditional = !parent_type.kind.abstract? && parent_type != @supergraph.schema.root_type_for_operation(operation_type)
 
-          @operations_by_entrypoint[entrypoint] = PlannerOperation.new(
-            order: next_order,
-            after: parent_order,
+          @steps_by_entrypoint[entrypoint] = PlannerStep.new(
+            index: next_index,
+            after: parent_index,
             location: location,
             parent_type: parent_type,
             operation_type: operation_type,
@@ -110,57 +107,59 @@ module GraphQL
             boundary: boundary,
           )
         else
-          op.selections.concat(selections)
-          op
+          step.selections.concat(selections)
+          step
         end
       end
 
+      ScopePartition = Struct.new(:location, :selections, keyword_init: true)
+
       # A) Group all root selections by their preferred entrypoint locations.
       def build_root_entrypoints
         case @request.operation.operation_type
-        when "query"
+        when QUERY_OP
           # A.1) Group query fields by location for parallel execution.
           parent_type = @supergraph.schema.query
 
           selections_by_location = {}
-          each_selection_in_type(parent_type, @request.operation.selections) do |node|
+          each_field_in_scope(parent_type, @request.operation.selections) do |node|
             locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name] || SUPERGRAPH_LOCATIONS
             selections_by_location[locations.first] ||= []
             selections_by_location[locations.first] << node
           end
 
           selections_by_location.each do |location, selections|
-            add_entrypoint(
+            add_step(
               location: location,
-              parent_order: ROOT_ORDER,
+              parent_index: ROOT_INDEX,
               parent_type: parent_type,
               selections: selections,
             )
           end
 
-        when "mutation"
+        when MUTATION_OP
           # A.2) Partition mutation fields by consecutive location for serial execution.
           parent_type = @supergraph.schema.mutation
 
           partitions = []
-          each_selection_in_type(parent_type, @request.operation.selections) do |node|
+          each_field_in_scope(parent_type, @request.operation.selections) do |node|
             next_location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].first
 
-            if partitions.none? || partitions.last[:location] != next_location
-              partitions << { location: next_location, selections: [] }
+            if partitions.none? || partitions.last.location != next_location
+              partitions << ScopePartition.new(location: next_location, selections: [])
             end
 
-            partitions.last[:selections] << node
+            partitions.last.selections << node
           end
 
-          partitions.reduce(ROOT_ORDER) do |parent_order, partition|
-            add_entrypoint(
-              location: partition[:location],
-              parent_order: parent_order,
+          partitions.reduce(ROOT_INDEX) do |parent_index, partition|
+            add_step(
+              location: partition.location,
+              parent_index: parent_index,
               parent_type: parent_type,
-              selections: partition[:selections],
-              operation_type: "mutation",
-            ).order
+              selections: partition.selections,
+              operation_type: MUTATION_OP,
+            ).index
           end
 
         else
@@ -168,7 +167,7 @@ module GraphQL
         end
       end
 
-      def each_selection_in_type(parent_type, input_selections, &block)
+      def each_field_in_scope(parent_type, input_selections, &block)
         input_selections.each do |node|
           case node
           when GraphQL::Language::Nodes::Field
@@ -176,12 +175,12 @@ module GraphQL
 
           when GraphQL::Language::Nodes::InlineFragment
             next unless node.type.nil? || parent_type.graphql_name == node.type.name
-            each_selection_in_type(parent_type, node.selections, &block)
+            each_field_in_scope(parent_type, node.selections, &block)
 
           when GraphQL::Language::Nodes::FragmentSpread
             fragment = @request.fragment_definitions[node.name]
             next unless parent_type.graphql_name == fragment.type.name
-            each_selection_in_type(parent_type, fragment.selections, &block)
+            each_field_in_scope(parent_type, fragment.selections, &block)
 
           else
             raise "Unexpected node of type #{node.class.name} in selection set."
@@ -193,7 +192,7 @@ module GraphQL
       def extract_locale_selections(
         current_location,
         parent_type,
-        parent_order,
+        parent_index,
         input_selections,
         path,
         locale_variables,
@@ -230,7 +229,7 @@ module GraphQL
               locale_selections << node
             else
               path.push(node.alias || node.name)
-              selection_set = extract_locale_selections(current_location, field_type, parent_order, node.selections, path, locale_variables)
+              selection_set = extract_locale_selections(current_location, field_type, parent_index, node.selections, path, locale_variables)
               path.pop
 
               locale_selections << node.merge(selections: selection_set)
@@ -242,7 +241,7 @@ module GraphQL
 
             is_same_scope = fragment_type == parent_type
             selection_set = is_same_scope ? locale_selections : []
-            extract_locale_selections(current_location, fragment_type, parent_order, node.selections, path, locale_variables, selection_set)
+            extract_locale_selections(current_location, fragment_type, parent_index, node.selections, path, locale_variables, selection_set)
 
             unless is_same_scope
               locale_selections << node.merge(selections: selection_set)
@@ -256,7 +255,7 @@ module GraphQL
             fragment_type = @supergraph.memoized_schema_types[fragment.type.name]
             is_same_scope = fragment_type == parent_type
             selection_set = is_same_scope ? locale_selections : []
-            extract_locale_selections(current_location, fragment_type, parent_order, fragment.selections, path, locale_variables, selection_set)
+            extract_locale_selections(current_location, fragment_type, parent_index, fragment.selections, path, locale_variables, selection_set)
 
             unless is_same_scope
               locale_selections << GraphQL::Language::Nodes::InlineFragment.new(type: fragment.type, selections: selection_set)
@@ -268,10 +267,10 @@ module GraphQL
           end
         end
 
-        # B.4) Add a `__typename` selection to concrete types and abstracts that implement
+        # B.4) Add a `__typename` selection to abstracts and concrete types that implement
         # fragments so that resolved type information is available during execution.
         if requires_typename
-          locale_selections << TYPENAME_NODE
+          locale_selections << SelectionHint.typename_node
         end
 
         if remote_selections
@@ -285,28 +284,24 @@ module GraphQL
           routes.each_value do |route|
             route.reduce(locale_selections) do |parent_selections, boundary|
               # E.1) Add the key of each boundary query into the prior location's selection set.
-              foreign_key = "_STITCH_#{boundary["key"]}"
+              foreign_key = SelectionHint.key(boundary.key)
               has_key = false
               has_typename = false
 
-              parent_selections.each do |selection|
-                next unless selection.is_a?(GraphQL::Language::Nodes::Field)
-                case selection.alias
-                when foreign_key
-                  has_key = true
-                when TYPENAME_NODE.alias
-                  has_typename = true
-                end
+              parent_selections.each do |node|
+                next unless node.is_a?(GraphQL::Language::Nodes::Field)
+                has_key ||= node.alias == foreign_key
+                has_typename ||= node.alias == SelectionHint.typename_node.alias
               end
 
-              parent_selections << GraphQL::Language::Nodes::Field.new(alias: foreign_key, name: boundary["key"]) unless has_key
-              parent_selections << TYPENAME_NODE unless has_typename
+              parent_selections << SelectionHint.key_node(boundary.key) unless has_key
+              parent_selections << SelectionHint.typename_node unless has_typename
 
               # E.2) Add a planner operation for each new entrypoint location.
-              location = boundary["location"]
-              add_entrypoint(
+              location = boundary.location
+              add_step(
                 location: location,
-                parent_order: parent_order,
+                parent_index: parent_index,
                 parent_type: parent_type,
                 selections: remote_selections_by_location[location] || [],
                 path: path.dup,
@@ -328,27 +323,13 @@ module GraphQL
 
         expanded_selections = nil
         input_selections = input_selections.filter_map do |node|
-          case node
-          when GraphQL::Language::Nodes::Field
-            if node.name != "__typename" && !local_interface_fields.include?(node.name)
-              expanded_selections ||= []
-              expanded_selections << node
-              next nil
-            end
-
-          when GraphQL::Language::Nodes::InlineFragment
-            fragment_type = node.type ? @supergraph.memoized_schema_types[node.type.name] : parent_type
-            selection_set = expand_interface_selections(current_location, fragment_type, node.selections)
-            node = node.merge(selections: selection_set)
-
-          when GraphQL::Language::Nodes::FragmentSpread
-            fragment = @request.fragment_definitions[node.name]
-            fragment_type = @supergraph.memoized_schema_types[fragment.type.name]
-            selection_set = expand_interface_selections(current_location, fragment_type, fragment.selections)
-            node = GraphQL::Language::Nodes::InlineFragment.new(type: fragment.type, selections: selection_set)
-
+          if node.is_a?(GraphQL::Language::Nodes::Field) && node.name != "__typename" && !local_interface_fields.include?(node.name)
+            expanded_selections ||= []
+            expanded_selections << node
+            nil
+          else
+            node
           end
-          node
         end
 
         if expanded_selections
@@ -446,10 +427,10 @@ module GraphQL
 
       # F) Wrap concrete selections targeting abstract boundaries in typed fragments.
       def expand_abstract_boundaries
-        @operations_by_entrypoint.each_value do |op|
+        @steps_by_entrypoint.each_value do |op|
           next unless op.boundary
 
-          boundary_type = @supergraph.memoized_schema_types[op.boundary["type_name"]]
+          boundary_type = @supergraph.memoized_schema_types[op.boundary.type_name]
           next unless boundary_type.kind.abstract?
           next if boundary_type == op.parent_type
 

data/lib/graphql/stitching/planner_step.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class PlannerStep
+      GRAPHQL_PRINTER = GraphQL::Language::Printer.new
+
+      attr_reader :index, :location, :parent_type, :if_type, :operation_type, :path
+      attr_accessor :after, :selections, :variables, :boundary
+
+      def initialize(
+        location:,
+        parent_type:,
+        index:,
+        after: nil,
+        operation_type: "query",
+        selections: [],
+        variables: {},
+        path: [],
+        if_type: nil,
+        boundary: nil
+      )
+        @location = location
+        @parent_type = parent_type
+        @index = index
+        @after = after
+        @operation_type = operation_type
+        @selections = selections
+        @variables = variables
+        @path = path
+        @if_type = if_type
+        @boundary = boundary
+      end
+
+      def to_plan_op
+        GraphQL::Stitching::Plan::Op.new(
+          step: @index,
+          after: @after,
+          location: @location,
+          operation_type: @operation_type,
+          selections: rendered_selections,
+          variables: rendered_variables,
+          path: @path,
+          if_type: @if_type,
+          boundary: @boundary,
+        )
+      end
+
+      private
+
+      def rendered_selections
+        op = GraphQL::Language::Nodes::OperationDefinition.new(operation_type: "", selections: @selections)
+        GRAPHQL_PRINTER.print(op).gsub!(/\s+/, " ").strip!
+      end
+
+      def rendered_variables
+        @variables.each_with_object({}) do |(variable_name, value_type), memo|
+          memo[variable_name] = GRAPHQL_PRINTER.print(value_type)
+        end
+      end
+    end
+  end
+end

data/lib/graphql/stitching/request.rb

@@ -5,54 +5,6 @@ module GraphQL
     class Request
       SUPPORTED_OPERATIONS = ["query", "mutation"].freeze
 
-      class ApplyRuntimeDirectives < GraphQL::Language::Visitor
-        def initialize(document, variables)
-          @changed = false
-          @variables = variables
-          super(document)
-        end
-
-        def changed?
-          @changed
-        end
-
-        def on_field(node, parent)
-          delete_node = false
-          filtered_directives = if node.directives.any?
-            node.directives.select do |directive|
-              if directive.name == "skip"
-                delete_node = assess_argument_value(directive.arguments.first)
-                false
-              elsif directive.name == "include"
-                delete_node = !assess_argument_value(directive.arguments.first)
-                false
-              else
-                true
-              end
-            end
-          end
-
-          if delete_node
-            @changed = true
-            super(DELETE_NODE, parent)
-          elsif filtered_directives && filtered_directives.length != node.directives.length
-            @changed = true
-            super(node.merge(directives: filtered_directives), parent)
-          else
-            super
-          end
-        end
-
-        private
-
-        def assess_argument_value(arg)
-          if arg.value.is_a?(GraphQL::Language::Nodes::VariableIdentifier)
-            return @variables[arg.value.name]
-          end
-          arg.value
-        end
-      end
-
       attr_reader :document, :variables, :operation_name, :context
 
       def initialize(document, operation_name: nil, variables: nil, context: nil)
@@ -114,10 +66,9 @@ module GraphQL
         end
 
         if @may_contain_runtime_directives
-          visitor = ApplyRuntimeDirectives.new(@document, @variables)
-          @document = visitor.visit
+          @document, modified = SkipInclude.render(@document, @variables)
 
-          if visitor.changed?
+          if modified
             @string = nil
             @digest = nil
             @operation = nil

data/lib/graphql/stitching/selection_hint.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class SelectionHint
+      HINT_PREFIX = "_STITCH_"
+
+      class << self
+        def key?(name)
+          return false unless name
+
+          name.start_with?(HINT_PREFIX)
+        end
+
+        def key(name)
+          "#{HINT_PREFIX}#{name}"
+        end
+
+        def key_node(field_name)
+          GraphQL::Language::Nodes::Field.new(alias: key(field_name), name: field_name)
+        end
+
+        def typename_node
+          @typename_node ||= key_node("__typename")
+        end
+      end
+    end
+  end
+end

data/lib/graphql/stitching/shaper.rb

@@ -19,8 +19,8 @@ module GraphQL
       def resolve_object_scope(raw_object, parent_type, selections, typename = nil)
         return nil if raw_object.nil?
 
-        typename ||= raw_object["_STITCH_typename"]
-        raw_object.reject! { |k, _v| k.start_with?("_STITCH_") }
+        typename ||= raw_object[SelectionHint.typename_node.alias]
+        raw_object.reject! { |key, _v| SelectionHint.key?(key) }
 
         selections.each do |node|
           case node

data/lib/graphql/stitching/skip_include.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class SkipInclude
+      class << self
+        # Faster implementation of an AST visitor for prerendering
+        # @skip and @include conditional directives into a document.
+        # This avoids unnecessary planning steps, and prepares result shaping.
+        def render(document, variables)
+          changed = false
+          definitions = document.definitions.map do |original_definition|
+            definition = render_node(original_definition, variables)
+            changed ||= definition.object_id != original_definition.object_id
+            definition
+          end
+
+          return document.merge(definitions: definitions), changed
+        end
+
+        private
+
+        def render_node(parent_node, variables)
+          changed = false
+          filtered_selections = parent_node.selections.filter_map do |original_node|
+            node = prune_node(original_node, variables)
+            if node.nil?
+              changed = true
+              next nil
+            end
+
+            node = render_node(node, variables) if node.selections.any?
+            changed ||= node.object_id != original_node.object_id
+            node
+          end
+
+          if filtered_selections.none?
+            filtered_selections << SelectionHint.typename_node
+          end
+
+          if changed
+            parent_node.merge(selections: filtered_selections)
+          else
+            parent_node
+          end
+        end
+
+        def prune_node(node, variables)
+          return node unless node.directives.any?
+
+          delete_node = false
+          filtered_directives = node.directives.reject do |directive|
+            if directive.name == "skip"
+              delete_node = assess_condition(directive.arguments.first, variables)
+              true
+            elsif directive.name == "include"
+              delete_node = !assess_condition(directive.arguments.first, variables)
+              true
+            end
+          end
+
+          if delete_node
+            nil
+          elsif filtered_directives.length != node.directives.length
+            node.merge(directives: filtered_directives)
+          else
+            node
+          end
+        end
+
+        def assess_condition(arg, variables)
+          if arg.value.is_a?(GraphQL::Language::Nodes::VariableIdentifier)
+            variables[arg.value.name] || variables[arg.value.name.to_sym]
+          else
+            arg.value
+          end
+        end
+      end
+    end
+  end
+end