graphql 2.3.18 → 2.3.20

data/lib/graphql/schema.rb

@@ -317,6 +317,9 @@ module GraphQL
         GraphQL::StaticValidation::Validator.new(schema: self)
       end
 
+      # Add `plugin` to this schema
+      # @param plugin [#use] A Schema plugin
+      # @return void
       def use(plugin, **kwargs)
         if kwargs.any?
           plugin.use(self, **kwargs)
@@ -334,8 +337,9 @@ module GraphQL
       # @return [Hash<String => Class>] A dictionary of type classes by their GraphQL name
       # @see get_type Which is more efficient for finding _one type_ by name, because it doesn't merge hashes.
       def types(context = GraphQL::Query::NullContext.instance)
-        if use_schema_visibility?
-          return Visibility::Subset.from_context(context, self).all_types_h
+        if use_visibility_profile?
+          types = Visibility::Profile.from_context(context, self)
+          return types.all_types_h
         end
         all_types = non_introspection_types.merge(introspection_system.types)
         visible_types = {}
@@ -362,17 +366,19 @@ module GraphQL
       end
 
       # @param type_name [String]
+      # @param context [GraphQL::Query::Context] Used for filtering definitions at query-time
+      # @param use_visibility_profile Private, for migration to {Schema::Visibility}
       # @return [Module, nil] A type, or nil if there's no type called `type_name`
-      def get_type(type_name, context = GraphQL::Query::NullContext.instance)
-        if use_schema_visibility?
-          return Visibility::Subset.from_context(context, self).type(type_name)
+      def get_type(type_name, context = GraphQL::Query::NullContext.instance, use_visibility_profile = use_visibility_profile?)
+        if use_visibility_profile
+          return Visibility::Profile.from_context(context, self).type(type_name)
         end
         local_entry = own_types[type_name]
         type_defn = case local_entry
         when nil
           nil
         when Array
-          if context.respond_to?(:types) && context.types.is_a?(GraphQL::Schema::Visibility::Subset)
+          if context.respond_to?(:types) && context.types.is_a?(GraphQL::Schema::Visibility::Profile)
             local_entry
           else
             visible_t = nil
@@ -398,7 +404,7 @@ module GraphQL
 
         type_defn ||
           introspection_system.types[type_name] || # todo context-specific introspection?
-          (superclass.respond_to?(:get_type) ? superclass.get_type(type_name, context) : nil)
+          (superclass.respond_to?(:get_type) ? superclass.get_type(type_name, context, use_visibility_profile) : nil)
       end
 
       # @return [Boolean] Does this schema have _any_ definition for a type named `type_name`, regardless of visibility?
@@ -425,12 +431,20 @@ module GraphQL
         end
       end
 
+      # Get or set the root `query { ... }` object for this schema.
+      #
+      # @example Using `Types::Query` as the entry-point
+      #   query { Types::Query }
+      #
+      # @param new_query_object [Class<GraphQL::Schema::Object>] The root type to use for queries
+      # @param lazy_load_block If a block is given, then it will be called when GraphQL-Ruby needs the root query type.
+      # @return [Class<GraphQL::Schema::Object>, nil] The configured query root type, if there is one.
       def query(new_query_object = nil, &lazy_load_block)
         if new_query_object || block_given?
           if @query_object
             dup_defn = new_query_object || yield
             raise GraphQL::Error, "Second definition of `query(...)` (#{dup_defn.inspect}) is invalid, already configured with #{@query_object.inspect}"
-          elsif use_schema_visibility?
+          elsif use_visibility_profile?
             @query_object = block_given? ? lazy_load_block : new_query_object
           else
             @query_object = new_query_object || lazy_load_block.call
@@ -444,12 +458,20 @@ module GraphQL
         end
       end
 
+      # Get or set the root `mutation { ... }` object for this schema.
+      #
+      # @example Using `Types::Mutation` as the entry-point
+      #   mutation { Types::Mutation }
+      #
+      # @param new_mutation_object [Class<GraphQL::Schema::Object>] The root type to use for mutations
+      # @param lazy_load_block If a block is given, then it will be called when GraphQL-Ruby needs the root mutation type.
+      # @return [Class<GraphQL::Schema::Object>, nil] The configured mutation root type, if there is one.
       def mutation(new_mutation_object = nil, &lazy_load_block)
         if new_mutation_object || block_given?
           if @mutation_object
             dup_defn = new_mutation_object || yield
             raise GraphQL::Error, "Second definition of `mutation(...)` (#{dup_defn.inspect}) is invalid, already configured with #{@mutation_object.inspect}"
-          elsif use_schema_visibility?
+          elsif use_visibility_profile?
             @mutation_object = block_given? ? lazy_load_block : new_mutation_object
           else
             @mutation_object = new_mutation_object || lazy_load_block.call
@@ -463,12 +485,20 @@ module GraphQL
         end
       end
 
+      # Get or set the root `subscription { ... }` object for this schema.
+      #
+      # @example Using `Types::Subscription` as the entry-point
+      #   subscription { Types::Subscription }
+      #
+      # @param new_subscription_object [Class<GraphQL::Schema::Object>] The root type to use for subscriptions
+      # @param lazy_load_block If a block is given, then it will be called when GraphQL-Ruby needs the root subscription type.
+      # @return [Class<GraphQL::Schema::Object>, nil] The configured subscription root type, if there is one.
       def subscription(new_subscription_object = nil, &lazy_load_block)
         if new_subscription_object || block_given?
           if @subscription_object
             dup_defn = new_subscription_object || yield
             raise GraphQL::Error, "Second definition of `subscription(...)` (#{dup_defn.inspect}) is invalid, already configured with #{@subscription_object.inspect}"
-          elsif use_schema_visibility?
+          elsif use_visibility_profile?
             @subscription_object = block_given? ? lazy_load_block : new_subscription_object
             add_subscription_extension_if_necessary
           else
@@ -486,8 +516,7 @@ module GraphQL
         end
       end
 
-      # @see [GraphQL::Schema::Warden] Restricted access to root types
-      # @return [GraphQL::ObjectType, nil]
+      # @api private
       def root_type_for_operation(operation)
         case operation
         when "query"
@@ -501,14 +530,16 @@ module GraphQL
         end
       end
 
+      # @return [Array<Class>] The root types (query, mutation, subscription) defined for this schema
       def root_types
-        if use_schema_visibility?
+        if use_visibility_profile?
           [query, mutation, subscription].compact
         else
           @root_types
         end
       end
 
+      # @api private
       def warden_class
         if defined?(@warden_class)
           @warden_class
@@ -519,39 +550,46 @@ module GraphQL
         end
       end
 
+      # @api private
       attr_writer :warden_class
 
-      def subset_class
-        if defined?(@subset_class)
-          @subset_class
-        elsif superclass.respond_to?(:subset_class)
-          superclass.subset_class
+      # @api private
+      def visibility_profile_class
+        if defined?(@visibility_profile_class)
+          @visibility_profile_class
+        elsif superclass.respond_to?(:visibility_profile_class)
+          superclass.visibility_profile_class
         else
-          GraphQL::Schema::Visibility::Subset
+          GraphQL::Schema::Visibility::Profile
         end
       end
 
-      attr_writer :subset_class, :use_schema_visibility, :visibility
-
-      def use_schema_visibility?
-        if defined?(@use_schema_visibility)
-          @use_schema_visibility
-        elsif superclass.respond_to?(:use_schema_visibility?)
-          superclass.use_schema_visibility?
+      # @api private
+      attr_writer :visibility_profile_class, :use_visibility_profile
+      # @api private
+      attr_accessor :visibility
+      # @api private
+      def use_visibility_profile?
+        if defined?(@use_visibility_profile)
+          @use_visibility_profile
+        elsif superclass.respond_to?(:use_visibility_profile?)
+          superclass.use_visibility_profile?
         else
           false
         end
       end
 
       # @param type [Module] The type definition whose possible types you want to see
+      # @param context [GraphQL::Query::Context] used for filtering visible possible types at runtime
+      # @param use_visibility_profile Private, for migration to {Schema::Visibility}
       # @return [Hash<String, Module>] All possible types, if no `type` is given.
       # @return [Array<Module>] Possible types for `type`, if it's given.
-      def possible_types(type = nil, context = GraphQL::Query::NullContext.instance)
-        if use_schema_visibility?
+      def possible_types(type = nil, context = GraphQL::Query::NullContext.instance, use_visibility_profile = use_visibility_profile?)
+        if use_visibility_profile
           if type
-            return Visibility::Subset.from_context(context, self).possible_types(type)
+            return Visibility::Profile.from_context(context, self).possible_types(type)
           else
-            raise "Schema.possible_types is not implemented for `use_schema_visibility?`"
+            raise "Schema.possible_types is not implemented for `use_visibility_profile?`"
           end
         end
         if type
@@ -571,7 +609,7 @@ module GraphQL
               introspection_system.possible_types[type] ||
               (
                 superclass.respond_to?(:possible_types) ?
-                  superclass.possible_types(type, context) :
+                  superclass.possible_types(type, context, use_visibility_profile) :
                   EMPTY_ARRAY
               )
           end
@@ -774,6 +812,7 @@ module GraphQL
         res[:errors]
       end
 
+      # @param new_query_class [Class<GraphQL::Query>] A subclass to use when executing queries
       def query_class(new_query_class = NOT_CONFIGURED)
         if NOT_CONFIGURED.equal?(new_query_class)
           @query_class || (superclass.respond_to?(:query_class) ? superclass.query_class : GraphQL::Query)
@@ -927,7 +966,7 @@ module GraphQL
               To add other types to your schema, you might want `extra_types`: https://graphql-ruby.org/schema/definition.html#extra-types
             ERR
           end
-          add_type_and_traverse(new_orphan_types, root: false) unless use_schema_visibility?
+          add_type_and_traverse(new_orphan_types, root: false) unless use_visibility_profile?
           own_orphan_types.concat(new_orphan_types.flatten)
         end
 
@@ -959,6 +998,8 @@ module GraphQL
         end
       end
 
+
+      # @param new_default_logger [#log] Something to use for logging messages
       def default_logger(new_default_logger = NOT_CONFIGURED)
         if NOT_CONFIGURED.equal?(new_default_logger)
           if defined?(@default_logger)
@@ -979,6 +1020,7 @@ module GraphQL
         end
       end
 
+      # @param new_context_class [Class<GraphQL::Query::Context>] A subclass to use when executing queries
       def context_class(new_context_class = nil)
         if new_context_class
           @context_class = new_context_class
@@ -987,6 +1029,20 @@ module GraphQL
         end
       end
 
+      # Register a handler for errors raised during execution. The handlers can return a new value or raise a new error.
+      #
+      # @example Handling "not found" with a client-facing error
+      #   rescue_from(ActiveRecord::NotFound) { raise GraphQL::ExecutionError, "An object could not be found" }
+      #
+      # @param err_classes [Array<StandardError>] Classes which should be rescued by `handler_block`
+      # @param handler_block The code to run when one of those errors is raised during execution
+      # @yieldparam error [StandardError] An instance of one of the configured `err_classes`
+      # @yieldparam object [Object] The current application object in the query when the error was raised
+      # @yieldparam arguments [GraphQL::Query::Arguments] The current field arguments when the error was raised
+      # @yieldparam context [GraphQL::Query::Context] The context for the currently-running operation
+      # @yieldreturn [Object] Some object to use in the place where this error was raised
+      # @raise [GraphQL::ExecutionError] In the handler, raise to add a client-facing error to the response
+      # @raise [StandardError] In the handler, raise to crash the query with a developer-facing error
       def rescue_from(*err_classes, &handler_block)
         err_classes.each do |err_class|
           Execution::Errors.register_rescue_from(err_class, error_handlers[:subclass_handlers], handler_block)
@@ -1053,8 +1109,24 @@ module GraphQL
         end
       end
 
-      def resolve_type(type, obj, ctx)
-        raise GraphQL::RequiredImplementationMissingError, "#{self.name}.resolve_type(type, obj, ctx) must be implemented to use Union types, Interface types, or `loads:` (tried to resolve: #{type.name})"
+      # GraphQL-Ruby calls this method during execution when it needs the application to determine the type to use for an object.
+      #
+      # Usually, this object was returned from a field whose return type is an {GraphQL::Schema::Interface} or a {GraphQL::Schema::Union}.
+      # But this method is called in other cases, too -- for example, when {GraphQL::Schema::Argument.loads} cases an object to be directly loaded from the database.
+      #
+      # @example Returning a GraphQL type based on the object's class name
+      #   class MySchema < GraphQL::Schema
+      #     def resolve_type(_abs_type, object, _context)
+      #       graphql_type_name = "Types::#{object.class.name}Type"
+      #       graphql_type_name.constantize # If this raises a NameError, then come implement special cases in this method
+      #     end
+      #   end
+      # @param abstract_type [Class, Module, nil] The Interface or Union type which is being resolved, if there is one
+      # @param application_object [Object] The object returned from a field whose type must be determined
+      # @param context [GraphQL::Query::Context] The query context for the currently-executing query
+      # @return [Class<GraphQL::Schema::Object] The Object type definition to use for `obj`
+      def resolve_type(abstract_type, application_object, context)
+        raise GraphQL::RequiredImplementationMissingError, "#{self.name}.resolve_type(abstract_type, application_object, context) must be implemented to use Union types, Interface types, or `loads:` (tried to resolve: #{abstract_type.name})"
       end
       # rubocop:enable Lint/DuplicateMethods
 
@@ -1069,15 +1141,45 @@ module GraphQL
           child_class.own_trace_modes[name] = child_class.build_trace_mode(name)
         end
         child_class.singleton_class.prepend(ResolveTypeWithType)
-        super
-      end
 
-      def object_from_id(node_id, ctx)
-        raise GraphQL::RequiredImplementationMissingError, "#{self.name}.object_from_id(node_id, ctx) must be implemented to load by ID (tried to load from id `#{node_id}`)"
+        if use_visibility_profile?
+          vis = self.visibility
+          child_class.visibility = vis.dup_for(child_class)
+        end
+        super
       end
 
-      def id_from_object(object, type, ctx)
-        raise GraphQL::RequiredImplementationMissingError, "#{self.name}.id_from_object(object, type, ctx) must be implemented to create global ids (tried to create an id for `#{object.inspect}`)"
+      # Fetch an object based on an incoming ID and the current context. This method should return an object
+      # from your application, or return `nil` if there is no object or the object shouldn't be available to this operation.
+      #
+      # @example Fetching an object with Rails's GlobalID
+      #   def self.object_from_id(object_id, _context)
+      #     GlobalID.find(global_id)
+      #     # TODO: use `context[:current_user]` to determine if this object is authorized.
+      #   end
+      # @param object_id [String] The ID to fetch an object for. This may be client-provided (as in `node(id: ...)` or `loads:`) or previously stored by the schema (eg, by the `ObjectCache`)
+      # @param context [GraphQL::Query::Context] The context for the currently-executing operation
+      # @return [Object, nil] The application which `object_id` references, or `nil` if there is no object or the current operation shouldn't have access to the object
+      # @see id_from_object which produces these IDs
+      def object_from_id(object_id, context)
+        raise GraphQL::RequiredImplementationMissingError, "#{self.name}.object_from_id(object_id, context) must be implemented to load by ID (tried to load from id `#{node_id}`)"
+      end
+
+      # Return a stable ID string for `object` so that it can be refetched later, using {.object_from_id}.
+      #
+      # {GlobalID}(https://github.com/rails/globalid) and {SQIDs}(https://sqids.org/ruby) can both be used to create IDs.
+      #
+      # @example Using Rails's GlobalID to generate IDs
+      #   def self.id_from_object(application_object, graphql_type, context)
+      #     application_object.to_gid_param
+      #   end
+      #
+      # @param application_object [Object] Some object encountered by GraphQL-Ruby while running a query
+      # @param graphql_type [Class, Module] The type that GraphQL-Ruby is using for `application_object` during this query
+      # @param context [GraphQL::Query::Context] The context for the operation that is currently running
+      # @return [String] A stable identifier which can be passed to {.object_from_id} later to re-fetch `application_object`
+      def id_from_object(application_object, graphql_type, context)
+        raise GraphQL::RequiredImplementationMissingError, "#{self.name}.id_from_object(application_object, graphql_type, context) must be implemented to create global ids (tried to create an id for `#{application_object.inspect}`)"
       end
 
       def visible?(member, ctx)
@@ -1132,6 +1234,16 @@ module GraphQL
         unauthorized_object(unauthorized_error)
       end
 
+      # Called at runtime when GraphQL-Ruby encounters a mismatch between the application behavior
+      # and the GraphQL type system.
+      #
+      # The default implementation of this method is to follow the GraphQL specification,
+      # but you can override this to report errors to your bug tracker or customize error handling.
+      # @param type_error [GraphQL::Error] several specific error classes are passed here, see the default implementation for details
+      # @param context [GraphQL::Query::Context] the context for the currently-running operation
+      # @return [void]
+      # @raise [GraphQL::ExecutionError] to return this error to the client
+      # @raise [GraphQL::Error] to crash the query and raise a developer-facing error
       def type_error(type_error, ctx)
         case type_error
         when GraphQL::InvalidNullError
@@ -1186,7 +1298,7 @@ module GraphQL
       # @param new_directive [Class]
       # @return void
       def directive(new_directive)
-        if use_schema_visibility?
+        if use_visibility_profile?
           own_directives[new_directive.graphql_name] = new_directive
         else
           add_type_and_traverse(new_directive, root: false)
@@ -1227,6 +1339,7 @@ module GraphQL
       # @param mode [Symbol] Trace module will only be used for this trade mode
       # @param options [Hash] Keywords that will be passed to the tracing class during `#initialize`
       # @return [void]
+      # @see GraphQL::Tracing::Trace for available tracing methods
       def trace_with(trace_mod, mode: :default, **options)
         if mode.is_a?(Array)
           mode.each { |m| trace_with(trace_mod, mode: m, **options) }
@@ -1304,6 +1417,8 @@ module GraphQL
         trace_class_for_mode.new(**trace_options)
       end
 
+      # @param new_analyzer [Class<GraphQL::Analysis::Analyzer>] An analyzer to run on queries to this schema
+      # @see GraphQL::Analysis the analysis system
       def query_analyzer(new_analyzer)
         own_query_analyzers << new_analyzer
       end
@@ -1312,6 +1427,8 @@ module GraphQL
         find_inherited_value(:query_analyzers, EMPTY_ARRAY) + own_query_analyzers
       end
 
+      # @param new_analyzer [Class<GraphQL::Analysis::Analyzer>] An analyzer to run on multiplexes to this schema
+      # @see GraphQL::Analysis the analysis system
       def multiplex_analyzer(new_analyzer)
         own_multiplex_analyzers << new_analyzer
       end
@@ -1395,6 +1512,11 @@ module GraphQL
         end
       end
 
+      # Called when execution encounters a `SystemStackError`. By default, it adds a client-facing error to the response.
+      # You could modify this method to report this error to your bug tracker.
+      # @param query [GraphQL::Query]
+      # @param err [SystemStackError]
+      # @return [void]
       def query_stack_error(query, err)
         query.context.errors.push(GraphQL::ExecutionError.new("This query is too large to execute."))
       end

data/lib/graphql/static_validation/rules/fields_will_merge.rb

@@ -212,6 +212,7 @@ module GraphQL
 
       def find_conflict(response_key, field1, field2, mutually_exclusive: false)
         return if @conflict_count >= context.max_errors
+        return if field1.definition.nil? || field2.definition.nil?
 
         node1 = field1.node
         node2 = field2.node

data/lib/graphql/testing/helpers.rb

@@ -92,7 +92,7 @@ module GraphQL
           end
           graphql_result
         else
-          unfiltered_type = Schema::Visibility::Subset.pass_thru(schema: schema, context: context).type(type_name)
+          unfiltered_type = Schema::Visibility::Profile.pass_thru(schema: schema, context: context).type(type_name)
           if unfiltered_type
             raise TypeNotVisibleError.new(type_name: type_name)
           else

data/lib/graphql/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module GraphQL
-  VERSION = "2.3.18"
+  VERSION = "2.3.20"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql
 version: !ruby/object:Gem::Version
-  version: 2.3.18
+  version: 2.3.20
 platform: ruby
 authors:
 - Robert Mosolgo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-07 00:00:00.000000000 Z
+date: 2024-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -503,7 +503,7 @@ files:
 - lib/graphql/schema/validator/required_validator.rb
 - lib/graphql/schema/visibility.rb
 - lib/graphql/schema/visibility/migration.rb
-- lib/graphql/schema/visibility/subset.rb
+- lib/graphql/schema/visibility/profile.rb
 - lib/graphql/schema/warden.rb
 - lib/graphql/schema/wrapper.rb
 - lib/graphql/static_validation.rb