graphql-stitching 1.4.2 → 1.5.0

data/lib/graphql/stitching/planner.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "planner/step"
+
 module GraphQL
   module Stitching
+    # Planner partitions request selections by best-fit graph locations,
+    # and provides a query plan with sequential execution steps.
     class Planner
       SUPERGRAPH_LOCATIONS = [Supergraph::SUPERGRAPH_LOCATION].freeze
-      TYPENAME = "__typename"
-      QUERY_OP = "query"
-      MUTATION_OP = "mutation"
       ROOT_INDEX = 0
 
       def initialize(request)
@@ -85,7 +86,7 @@ module GraphQL
         end
 
         if step.nil?
-          @steps_by_entrypoint[entrypoint] = PlannerStep.new(
+          @steps_by_entrypoint[entrypoint] = Step.new(
             index: next_index,
             after: parent_index,
             location: location,
@@ -124,6 +125,7 @@ module GraphQL
               parent_index: ROOT_INDEX,
               parent_type: parent_type,
               selections: selections,
+              operation_type: QUERY_OP,
             )
           end
 
@@ -152,6 +154,22 @@ module GraphQL
             ).index
           end
 
+        when SUBSCRIPTION_OP
+          parent_type = @supergraph.schema.subscription
+
+          each_field_in_scope(parent_type, @request.operation.selections) do |node|
+            raise StitchingError, "Too many root fields for subscription." unless @steps_by_entrypoint.empty?
+
+            locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name] || SUPERGRAPH_LOCATIONS
+            add_step(
+              location: locations.first,
+              parent_index: ROOT_INDEX,
+              parent_type: parent_type,
+              selections: [node],
+              operation_type: SUBSCRIPTION_OP,
+            )
+          end
+
         else
           raise StitchingError, "Invalid operation type."
         end
@@ -261,7 +279,7 @@ module GraphQL
 
         # B.4) Add a `__typename` export to abstracts and types that implement
         # fragments so that resolved type information is available during execution.
-        if requires_typename
+        if requires_typename && !locale_selections.include?(Resolver::TYPENAME_EXPORT_NODE)
           locale_selections << Resolver::TYPENAME_EXPORT_NODE
         end
 
@@ -277,6 +295,10 @@ module GraphQL
             route.reduce(locale_selections) do |parent_selections, resolver|
               # E.1) Add the key of each resolver query into the prior location's selection set.
               parent_selections.push(*resolver.key.export_nodes) if resolver.key
+              parent_selections.uniq! do |node|
+                export_node = node.is_a?(GraphQL::Language::Nodes::Field) && Resolver.export_key?(node.alias)
+                export_node ? node.alias : node.object_id
+              end
 
               # E.2) Add a planner step for each new entrypoint location.
               add_step(
@@ -289,8 +311,6 @@ module GraphQL
               ).selections
             end
           end
-
-          locale_selections.uniq! { _1.alias || _1.name }
         end
 
         locale_selections

data/lib/graphql/stitching/{skip_include.rb → request/skip_include.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module GraphQL
-  module Stitching
+module GraphQL::Stitching
+  class Request
     # 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.

data/lib/graphql/stitching/request.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "request/skip_include"
+
 module GraphQL
   module Stitching
+    # Request combines a supergraph, GraphQL document, variables, 
+    # variable/fragment definitions, and the selected operation.
+    # It provides the lifecycle of validating, preparing,
+    # planning, and executing upon these inputs.
     class Request
-      SUPPORTED_OPERATIONS = ["query", "mutation"].freeze
       SKIP_INCLUDE_DIRECTIVE = /@(?:skip|include)/
 
       # @return [Supergraph] supergraph instance that resolves the request.
@@ -83,7 +88,6 @@ module GraphQL
         @operation ||= begin
           operation_defs = @document.definitions.select do |d|
             next unless d.is_a?(GraphQL::Language::Nodes::OperationDefinition)
-            next unless SUPPORTED_OPERATIONS.include?(d.operation_type)
             @operation_name ? d.name == @operation_name : true
           end
 
@@ -97,6 +101,21 @@ module GraphQL
         end
       end
 
+      # @return [Boolean] true if operation type is a query
+      def query?
+        operation.operation_type == QUERY_OP
+      end
+
+      # @return [Boolean] true if operation type is a mutation
+      def mutation?
+        operation.operation_type == MUTATION_OP
+      end
+
+      # @return [Boolean] true if operation type is a subscription
+      def subscription?
+        operation.operation_type == SUBSCRIPTION_OP
+      end
+
       # @return [String] A string of directives applied to the root operation. These are passed through in all subgraph requests.
       def operation_directives
         @operation_directives ||= if operation.directives.any?
@@ -162,7 +181,7 @@ module GraphQL
           raise StitchingError, "Plan must be a `GraphQL::Stitching::Plan`." unless new_plan.is_a?(Plan)
           @plan = new_plan
         else
-          @plan ||= GraphQL::Stitching::Planner.new(self).perform
+          @plan ||= Planner.new(self).perform
         end
       end
 
@@ -170,7 +189,26 @@ module GraphQL
       # @param raw [Boolean] specifies the result should be unshaped without pruning or null bubbling. Useful for debugging.
       # @return [Hash] the rendered GraphQL response with "data" and "errors" sections.
       def execute(raw: false)
-        GraphQL::Stitching::Executor.new(self).perform(raw: raw)
+        add_subscription_update_handler if subscription?
+        Executor.new(self).perform(raw: raw)
+      end
+
+      private
+
+      # Adds a handler into context for enriching subscription updates with stitched data
+      def add_subscription_update_handler
+        request = self
+        @context[:stitch_subscription_update] = -> (result) {
+          stitched_result = Executor.new(
+            request,
+            data: result.to_h["data"] || {},
+            errors: result.to_h["errors"] || [],
+            after: request.plan.ops.first.step,
+          ).perform
+
+          result.to_h.merge!(stitched_result.to_h)
+          result
+        }
       end
     end
   end

data/lib/graphql/stitching/resolver/arguments.rb

@@ -130,8 +130,8 @@ module GraphQL::Stitching
 
       def verify_key(arg, key)
         key_field = value.reduce(Resolver::KeyField.new("", inner: key)) do |field, ns|
-          if ns == Resolver::TYPE_NAME
-            Resolver::KeyField.new(Resolver::TYPE_NAME)
+          if ns == TYPENAME
+            Resolver::KeyField.new(TYPENAME)
           elsif field
             field.inner.find { _1.name == ns }
           end

data/lib/graphql/stitching/resolver/keys.rb

@@ -3,7 +3,6 @@
 module GraphQL::Stitching
   class Resolver
     EXPORT_PREFIX = "_export_"
-    TYPE_NAME = "__typename"
 
     class FieldNode
       # GraphQL Ruby changed the argument assigning Field.alias from
@@ -59,8 +58,8 @@ module GraphQL::Stitching
 
     EMPTY_FIELD_SET = KeyFieldSet.new(GraphQL::Stitching::EMPTY_ARRAY)
     TYPENAME_EXPORT_NODE = FieldNode.build(
-      field_alias: "#{EXPORT_PREFIX}#{TYPE_NAME}",
-      field_name: TYPE_NAME,
+      field_alias: "#{EXPORT_PREFIX}#{TYPENAME}",
+      field_name: TYPENAME,
     )
 
     class Key < KeyFieldSet

data/lib/graphql/stitching/resolver.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "./resolver/arguments"
-require_relative "./resolver/keys"
+require_relative "resolver/arguments"
+require_relative "resolver/keys"
 
 module GraphQL
   module Stitching
-    # Defines a root resolver query that provides direct access to an entity type.
+    # Defines a type resolver query that provides direct access to an entity type.
     class Resolver
       extend ArgumentsParser
       extend KeysParser
@@ -47,7 +47,7 @@ module GraphQL
       end
 
       def version
-        @version ||= Digest::SHA2.hexdigest(as_json.to_json)
+        @version ||= Digest::SHA2.hexdigest("#{Stitching::VERSION}/#{as_json.to_json}")
       end
 
       def ==(other)

data/lib/graphql/stitching/supergraph.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "./supergraph/to_definition"
+require_relative "supergraph/to_definition"
 
 module GraphQL
   module Stitching
+    # Supergraph is the singuar representation of a stitched graph. 
+    # It provides the combined GraphQL schema and delegation maps 
+    # used to route selections across subgraph locations.
     class Supergraph
       SUPERGRAPH_LOCATION = "__super"
 
@@ -100,7 +103,7 @@ module GraphQL
           executable.execute(
             query: source,
             variables: variables,
-            context: request.context.frozen? ? request.context.dup : request.context,
+            context: request.context.to_h,
             validate: false,
           )
         elsif executable.respond_to?(:call)

data/lib/graphql/stitching/util.rb

@@ -2,6 +2,7 @@
 
 module GraphQL
   module Stitching
+    # General utilities to aid with stitching.
     class Util
       TypeStructure = Struct.new(:list, :null, :name, keyword_init: true) do
         alias_method :list?, :list

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.4.2"
+    VERSION = "1.5.0"
   end
 end

data/lib/graphql/stitching.rb

@@ -4,7 +4,22 @@ require "graphql"
 
 module GraphQL
   module Stitching
+    # scope name of query operations.
+    QUERY_OP = "query"
+    
+    # scope name of mutation operations.
+    MUTATION_OP = "mutation"
+    
+    # scope name of subscription operations.
+    SUBSCRIPTION_OP = "subscription"
+    
+    # introspection typename field.
+    TYPENAME = "__typename"
+
+    # @api private
     EMPTY_OBJECT = {}.freeze
+
+    # @api private
     EMPTY_ARRAY = [].freeze
 
     class StitchingError < StandardError; end
@@ -18,6 +33,8 @@ module GraphQL
 
       attr_writer :stitch_directive
 
+      # Names of stitching directives to omit from the composed supergraph.
+      # @returns [Array<String>] list of stitching directive names.
       def stitching_directive_names
         [stitch_directive]
       end
@@ -26,16 +43,13 @@ module GraphQL
 end
 
 require_relative "stitching/supergraph"
-require_relative "stitching/resolver"
 require_relative "stitching/client"
 require_relative "stitching/composer"
 require_relative "stitching/executor"
 require_relative "stitching/http_executable"
 require_relative "stitching/plan"
-require_relative "stitching/planner_step"
 require_relative "stitching/planner"
 require_relative "stitching/request"
-require_relative "stitching/shaper"
-require_relative "stitching/skip_include"
+require_relative "stitching/resolver"
 require_relative "stitching/util"
 require_relative "stitching/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.5.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-03 00:00:00.000000000 Z
+date: 2024-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -90,6 +90,7 @@ files:
 - docs/mechanics.md
 - docs/request.md
 - docs/resolver.md
+- docs/subscriptions.md
 - docs/supergraph.md
 - examples/file_uploads/Gemfile
 - examples/file_uploads/Procfile
@@ -105,6 +106,51 @@ files:
 - examples/merged_types/graphiql.html
 - examples/merged_types/remote1.rb
 - examples/merged_types/remote2.rb
+- examples/subscriptions/.gitattributes
+- examples/subscriptions/.gitignore
+- examples/subscriptions/Gemfile
+- examples/subscriptions/README.md
+- examples/subscriptions/Rakefile
+- examples/subscriptions/app/channels/graphql_channel.rb
+- examples/subscriptions/app/controllers/graphql_controller.rb
+- examples/subscriptions/app/graphql/entities_schema.rb
+- examples/subscriptions/app/graphql/stitched_schema.rb
+- examples/subscriptions/app/graphql/subscriptions_schema.rb
+- examples/subscriptions/app/models/repository.rb
+- examples/subscriptions/app/views/graphql/client.html.erb
+- examples/subscriptions/bin/bundle
+- examples/subscriptions/bin/docker-entrypoint
+- examples/subscriptions/bin/importmap
+- examples/subscriptions/bin/rails
+- examples/subscriptions/bin/rake
+- examples/subscriptions/bin/setup
+- examples/subscriptions/config.ru
+- examples/subscriptions/config/application.rb
+- examples/subscriptions/config/boot.rb
+- examples/subscriptions/config/cable.yml
+- examples/subscriptions/config/credentials.yml.enc
+- examples/subscriptions/config/database.yml
+- examples/subscriptions/config/environment.rb
+- examples/subscriptions/config/environments/development.rb
+- examples/subscriptions/config/environments/production.rb
+- examples/subscriptions/config/environments/test.rb
+- examples/subscriptions/config/initializers/content_security_policy.rb
+- examples/subscriptions/config/initializers/filter_parameter_logging.rb
+- examples/subscriptions/config/initializers/inflections.rb
+- examples/subscriptions/config/initializers/permissions_policy.rb
+- examples/subscriptions/config/locales/en.yml
+- examples/subscriptions/config/master.key
+- examples/subscriptions/config/puma.rb
+- examples/subscriptions/config/routes.rb
+- examples/subscriptions/config/storage.yml
+- examples/subscriptions/db/seeds.rb
+- examples/subscriptions/public/404.html
+- examples/subscriptions/public/422.html
+- examples/subscriptions/public/500.html
+- examples/subscriptions/public/apple-touch-icon-precomposed.png
+- examples/subscriptions/public/apple-touch-icon.png
+- examples/subscriptions/public/favicon.ico
+- examples/subscriptions/public/robots.txt
 - gemfiles/graphql_1.13.9.gemfile
 - gemfiles/graphql_2.0.0.gemfile
 - gemfiles/graphql_2.1.0.gemfile
@@ -120,16 +166,16 @@ files:
 - lib/graphql/stitching/executor.rb
 - lib/graphql/stitching/executor/resolver_source.rb
 - lib/graphql/stitching/executor/root_source.rb
+- lib/graphql/stitching/executor/shaper.rb
 - lib/graphql/stitching/http_executable.rb
 - lib/graphql/stitching/plan.rb
 - lib/graphql/stitching/planner.rb
-- lib/graphql/stitching/planner_step.rb
+- lib/graphql/stitching/planner/step.rb
 - lib/graphql/stitching/request.rb
+- lib/graphql/stitching/request/skip_include.rb
 - lib/graphql/stitching/resolver.rb
 - lib/graphql/stitching/resolver/arguments.rb
 - lib/graphql/stitching/resolver/keys.rb
-- lib/graphql/stitching/shaper.rb
-- lib/graphql/stitching/skip_include.rb
 - lib/graphql/stitching/supergraph.rb
 - lib/graphql/stitching/supergraph/key_directive.rb
 - lib/graphql/stitching/supergraph/resolver_directive.rb