graphql 0.16.0 → 2.0.15

data/lib/graphql/schema/relay_classic_mutation.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+require "graphql/types/string"
+
+module GraphQL
+  class Schema
+    # Mutations that extend this base class get some conventions added for free:
+    #
+    # - An argument called `clientMutationId` is _always_ added, but it's not passed
+    #   to the resolve method. The value is re-inserted to the response. (It's for
+    #   client libraries to manage optimistic updates.)
+    # - The returned object type always has a field called `clientMutationId` to support that.
+    # - The mutation accepts one argument called `input`, `argument`s defined in the mutation
+    #   class are added to that input object, which is generated by the mutation.
+    #
+    # These conventions were first specified by Relay Classic, but they come in handy:
+    #
+    # - `clientMutationId` supports optimistic updates and cache rollbacks on the client
+    # - using a single `input:` argument makes it easy to post whole JSON objects to the mutation
+    #   using one GraphQL variable (`$input`) instead of making a separate variable for each argument.
+    #
+    # @see {GraphQL::Schema::Mutation} for an example, it's basically the same.
+    #
+    class RelayClassicMutation < GraphQL::Schema::Mutation
+      # The payload should always include this field
+      field(:client_mutation_id, String, "A unique identifier for the client performing the mutation.")
+      # Relay classic default:
+      null(true)
+
+      # Override {GraphQL::Schema::Resolver#resolve_with_support} to
+      # delete `client_mutation_id` from the kwargs.
+      def resolve_with_support(**inputs)
+        input = inputs[:input].to_kwargs
+
+        new_extras = field ? field.extras : []
+        all_extras = self.class.extras + new_extras
+
+        # Transfer these from the top-level hash to the
+        # shortcutted `input:` object
+        all_extras.each do |ext|
+          # It's possible that the `extra` was not passed along by this point,
+          # don't re-add it if it wasn't given here.
+          if inputs.key?(ext)
+            input[ext] = inputs[ext]
+          end
+        end
+
+        if input
+          # This is handled by Relay::Mutation::Resolve, a bit hacky, but here we are.
+          input_kwargs = input.to_h
+          client_mutation_id = input_kwargs.delete(:client_mutation_id)
+        else
+          # Relay Classic Mutations with no `argument`s
+          # don't require `input:`
+          input_kwargs = {}
+        end
+
+        return_value = if input_kwargs.any?
+          super(**input_kwargs)
+        else
+          super()
+        end
+
+        context.schema.after_lazy(return_value) do |return_hash|
+          # It might be an error
+          if return_hash.is_a?(Hash)
+            return_hash[:client_mutation_id] = client_mutation_id
+          end
+          return_hash
+        end
+      end
+
+      class << self
+        def dummy
+          @dummy ||= begin
+            d = Class.new(GraphQL::Schema::Resolver)
+            d.argument_class(self.argument_class)
+            # TODO make this lazier?
+            d.argument(:input, input_type, description: "Parameters for #{self.graphql_name}")
+            d
+          end
+        end
+
+        def field_arguments(context = GraphQL::Query::NullContext)
+          dummy.arguments(context)
+        end
+
+        def get_field_argument(name, context = GraphQL::Query::NullContext)
+          dummy.get_argument(name, context)
+        end
+
+        def own_field_arguments
+          dummy.own_arguments
+        end
+
+        def all_field_argument_definitions
+          dummy.all_argument_definitions
+        end
+
+        # Also apply this argument to the input type:
+        def argument(*args, own_argument: false, **kwargs, &block)
+          it = input_type # make sure any inherited arguments are already added to it
+          arg = super(*args, **kwargs, &block)
+
+          # This definition might be overriding something inherited;
+          # if it is, remove the inherited definition so it's not confused at runtime as having multiple definitions
+          prev_args = it.own_arguments[arg.graphql_name]
+          case prev_args
+          when GraphQL::Schema::Argument
+            if prev_args.owner != self
+              it.own_arguments.delete(arg.graphql_name)
+            end
+          when Array
+            prev_args.reject! { |a| a.owner != self }
+            if prev_args.empty?
+              it.own_arguments.delete(arg.graphql_name)
+            end
+          end
+
+          it.add_argument(arg)
+          arg
+        end
+
+        # The base class for generated input object types
+        # @param new_class [Class] The base class to use for generating input object definitions
+        # @return [Class] The base class for this mutation's generated input object (default is {GraphQL::Schema::InputObject})
+        def input_object_class(new_class = nil)
+          if new_class
+            @input_object_class = new_class
+          end
+          @input_object_class || (superclass.respond_to?(:input_object_class) ? superclass.input_object_class : GraphQL::Schema::InputObject)
+        end
+
+        # @param new_input_type [Class, nil] If provided, it configures this mutation to accept `new_input_type` instead of generating an input type
+        # @return [Class] The generated {Schema::InputObject} class for this mutation's `input`
+        def input_type(new_input_type = nil)
+          if new_input_type
+            @input_type = new_input_type
+          end
+          @input_type ||= generate_input_type
+        end
+
+        private
+
+        # Generate the input type for the `input:` argument
+        # To customize how input objects are generated, override this method
+        # @return [Class] a subclass of {.input_object_class}
+        def generate_input_type
+          mutation_args = all_argument_definitions
+          mutation_class = self
+          Class.new(input_object_class) do
+            class << self
+              def default_graphql_name
+                "#{self.mutation.graphql_name}Input"
+              end
+
+              def description(new_desc = nil)
+                super || "Autogenerated input type of #{self.mutation.graphql_name}"
+              end
+            end
+            mutation(mutation_class)
+            # these might be inherited:
+            mutation_args.each do |arg|
+              add_argument(arg)
+            end
+            argument :client_mutation_id, String, "A unique identifier for the client performing the mutation.", required: false
+          end
+        end
+      end
+
+      private
+
+      def authorize_arguments(args, values)
+        # remove the `input` wrapper to match values
+        input_args = args["input"].type.unwrap.arguments(context)
+        super(input_args, values)
+      end
+    end
+  end
+end

data/lib/graphql/schema/resolver/has_payload_type.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    class Resolver
+      # Adds `field(...)` helper to resolvers so that they can
+      # generate payload types.
+      #
+      # Or, an already-defined one can be attached with `payload_type(...)`.
+      module HasPayloadType
+        # Call this method to get the derived return type of the mutation,
+        # or use it as a configuration method to assign a return type
+        # instead of generating one.
+        # @param new_payload_type [Class, nil] If a type definition class is provided, it will be used as the return type of the mutation field
+        # @return [Class] The object type which this mutation returns.
+        def payload_type(new_payload_type = nil)
+          if new_payload_type
+            @payload_type = new_payload_type
+          end
+          @payload_type ||= generate_payload_type
+        end
+
+        def type(new_type = nil, null: nil)
+          if new_type
+            payload_type(new_type)
+            if !null.nil?
+              self.null(null)
+            end
+          else
+            super()
+          end
+        end
+
+        alias :type_expr :payload_type
+
+        def field_class(new_class = nil)
+          if new_class
+            @field_class = new_class
+          elsif defined?(@field_class) && @field_class
+            @field_class
+          else
+            find_inherited_value(:field_class, GraphQL::Schema::Field)
+          end
+        end
+
+        # An object class to use for deriving return types
+        # @param new_class [Class, nil] Defaults to {GraphQL::Schema::Object}
+        # @return [Class]
+        def object_class(new_class = nil)
+          if new_class
+            if defined?(@payload_type)
+              raise "Can't configure `object_class(...)` after the payload type has already been initialized. Move this configuration higher up the class definition."
+            end
+            @object_class = new_class
+          else
+            @object_class || find_inherited_value(:object_class, GraphQL::Schema::Object)
+          end
+        end
+
+        NO_INTERFACES = [].freeze
+
+        def field(*args, **kwargs, &block)
+          pt = payload_type # make sure it's initialized with any inherited fields
+          field_defn = super
+
+          # Remove any inherited fields to avoid false conflicts at runtime
+          prev_fields = pt.own_fields[field_defn.graphql_name]
+          case prev_fields
+          when GraphQL::Schema::Field
+            if prev_fields.owner != self
+              pt.own_fields.delete(field_defn.graphql_name)
+            end
+          when Array
+            prev_fields.reject! { |f| f.owner != self }
+            if prev_fields.empty?
+              pt.own_fields.delete(field_defn.graphql_name)
+            end
+          end
+
+          pt.add_field(field_defn, method_conflict_warning: false)
+          field_defn
+        end
+
+        private
+
+        # Build a subclass of {.object_class} based on `self`.
+        # This value will be cached as `{.payload_type}`.
+        # Override this hook to customize return type generation.
+        def generate_payload_type
+          resolver_name = graphql_name
+          resolver_fields = all_field_definitions
+          Class.new(object_class) do
+            graphql_name("#{resolver_name}Payload")
+            description("Autogenerated return type of #{resolver_name}.")
+            resolver_fields.each do |f|
+              # Reattach the already-defined field here
+              # (The field's `.owner` will still point to the mutation, not the object type, I think)
+              # Don't re-warn about a method conflict. Since this type is generated, it should be fixed in the resolver instead.
+              add_field(f, method_conflict_warning: false)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/schema/resolver.rb

@@ -0,0 +1,402 @@
+# frozen_string_literal: true
+require "graphql/schema/resolver/has_payload_type"
+
+module GraphQL
+  class Schema
+    # A class-based container for field configuration and resolution logic. It supports:
+    #
+    # - Arguments, via `.argument(...)` helper, which will be applied to the field.
+    # - Return type, via `.type(..., null: ...)`, which will be applied to the field.
+    # - Description, via `.description(...)`, which will be applied to the field
+    # - Resolution, via `#resolve(**args)` method, which will be called to resolve the field.
+    # - `#object` and `#context` accessors for use during `#resolve`.
+    #
+    # Resolvers can be attached with the `resolver:` option in a `field(...)` call.
+    #
+    # A resolver's configuration may be overridden with other keywords in the `field(...)` call.
+    #
+    # @see {GraphQL::Schema::Mutation} for a concrete subclass of `Resolver`.
+    # @see {GraphQL::Function} `Resolver` is a replacement for `GraphQL::Function`
+    class Resolver
+      include Schema::Member::GraphQLTypeNames
+      # Really we only need description from here, but:
+      extend Schema::Member::BaseDSLMethods
+      extend GraphQL::Schema::Member::HasArguments
+      extend GraphQL::Schema::Member::HasValidators
+      include Schema::Member::HasPath
+      extend Schema::Member::HasPath
+
+      # @param object [Object] The application object that this field is being resolved on
+      # @param context [GraphQL::Query::Context]
+      # @param field [GraphQL::Schema::Field]
+      def initialize(object:, context:, field:)
+        @object = object
+        @context = context
+        @field = field
+        # Since this hash is constantly rebuilt, cache it for this call
+        @arguments_by_keyword = {}
+        self.class.arguments(context).each do |name, arg|
+          @arguments_by_keyword[arg.keyword] = arg
+        end
+        @prepared_arguments = nil
+      end
+
+      # @return [Object] The application object this field is being resolved on
+      attr_reader :object
+
+      # @return [GraphQL::Query::Context]
+      attr_reader :context
+
+      # @return [GraphQL::Dataloader]
+      def dataloader
+        context.dataloader
+      end
+
+      # @return [GraphQL::Schema::Field]
+      attr_reader :field
+
+      def arguments
+        @prepared_arguments || raise("Arguments have not been prepared yet, still waiting for #load_arguments to resolve. (Call `.arguments` later in the code.)")
+      end
+
+      # This method is _actually_ called by the runtime,
+      # it does some preparation and then eventually calls
+      # the user-defined `#resolve` method.
+      # @api private
+      def resolve_with_support(**args)
+        # First call the ready? hook which may raise
+        ready_val = if args.any?
+          ready?(**args)
+        else
+          ready?
+        end
+        context.schema.after_lazy(ready_val) do |is_ready, ready_early_return|
+          if ready_early_return
+            if is_ready != false
+              raise "Unexpected result from #ready? (expected `true`, `false` or `[false, {...}]`): [#{is_ready.inspect}, #{ready_early_return.inspect}]"
+            else
+              ready_early_return
+            end
+          elsif is_ready
+            # Then call each prepare hook, which may return a different value
+            # for that argument, or may return a lazy object
+            load_arguments_val = load_arguments(args)
+            context.schema.after_lazy(load_arguments_val) do |loaded_args|
+              @prepared_arguments = loaded_args
+              Schema::Validator.validate!(self.class.validators, object, context, loaded_args, as: @field)
+              # Then call `authorized?`, which may raise or may return a lazy object
+              authorized_val = if loaded_args.any?
+                authorized?(**loaded_args)
+              else
+                authorized?
+              end
+              context.schema.after_lazy(authorized_val) do |(authorized_result, early_return)|
+                # If the `authorized?` returned two values, `false, early_return`,
+                # then use the early return value instead of continuing
+                if early_return
+                  if authorized_result == false
+                    early_return
+                  else
+                    raise "Unexpected result from #authorized? (expected `true`, `false` or `[false, {...}]`): [#{authorized_result.inspect}, #{early_return.inspect}]"
+                  end
+                elsif authorized_result
+                  # Finally, all the hooks have passed, so resolve it
+                  if loaded_args.any?
+                    public_send(self.class.resolve_method, **loaded_args)
+                  else
+                    public_send(self.class.resolve_method)
+                  end
+                else
+                  raise GraphQL::UnauthorizedFieldError.new(context: context, object: object, type: field.owner, field: field)
+                end
+              end
+            end
+          end
+        end
+      end
+
+      # Do the work. Everything happens here.
+      # @return [Object] An object corresponding to the return type
+      def resolve(**args)
+        raise GraphQL::RequiredImplementationMissingError, "#{self.class.name}#resolve should execute the field's logic"
+      end
+
+      # Called before arguments are prepared.
+      # Implement this hook to make checks before doing any work.
+      #
+      # If it returns a lazy object (like a promise), it will be synced by GraphQL
+      # (but the resulting value won't be used).
+      #
+      # @param args [Hash] The input arguments, if there are any
+      # @raise [GraphQL::ExecutionError] To add an error to the response
+      # @raise [GraphQL::UnauthorizedError] To signal an authorization failure
+      # @return [Boolean, early_return_data] If `false`, execution will stop (and `early_return_data` will be returned instead, if present.)
+      def ready?(**args)
+        true
+      end
+
+      # Called after arguments are loaded, but before resolving.
+      #
+      # Override it to check everything before calling the mutation.
+      # @param inputs [Hash] The input arguments
+      # @raise [GraphQL::ExecutionError] To add an error to the response
+      # @raise [GraphQL::UnauthorizedError] To signal an authorization failure
+      # @return [Boolean, early_return_data] If `false`, execution will stop (and `early_return_data` will be returned instead, if present.)
+      def authorized?(**inputs)
+        arg_owner = @field # || self.class
+        args = arg_owner.arguments(context)
+        authorize_arguments(args, inputs)
+      end
+
+      # Called when an object loaded by `loads:` fails the `.authorized?` check for its resolved GraphQL object type.
+      #
+      # By default, the error is re-raised and passed along to {{Schema.unauthorized_object}}.
+      #
+      # Any value returned here will be used _instead of_ of the loaded object.
+      # @param err [GraphQL::UnauthorizedError]
+      def unauthorized_object(err)
+        raise err
+      end
+
+      private
+
+      def authorize_arguments(args, inputs)
+        args.each_value do |argument|
+          arg_keyword = argument.keyword
+          if inputs.key?(arg_keyword) && !(arg_value = inputs[arg_keyword]).nil? && (arg_value != argument.default_value)
+            arg_auth, err = argument.authorized?(self, arg_value, context)
+            if !arg_auth
+              return arg_auth, err
+            else
+              true
+            end
+          else
+            true
+          end
+        end
+      end
+
+      def load_arguments(args)
+        prepared_args = {}
+        prepare_lazies = []
+
+        args.each do |key, value|
+          arg_defn = @arguments_by_keyword[key]
+          if arg_defn
+            prepped_value = prepared_args[key] = arg_defn.load_and_authorize_value(self, value, context)
+            if context.schema.lazy?(prepped_value)
+              prepare_lazies << context.schema.after_lazy(prepped_value) do |finished_prepped_value|
+                prepared_args[key] = finished_prepped_value
+              end
+            end
+          else
+            # these are `extras:`
+            prepared_args[key] = value
+          end
+        end
+
+        # Avoid returning a lazy if none are needed
+        if prepare_lazies.any?
+          GraphQL::Execution::Lazy.all(prepare_lazies).then { prepared_args }
+        else
+          prepared_args
+        end
+      end
+
+      def get_argument(name, context = GraphQL::Query::NullContext)
+        self.class.get_argument(name, context)
+      end
+
+      class << self
+        def field_arguments(context = GraphQL::Query::NullContext)
+          arguments(context)
+        end
+
+        def get_field_argument(name, context = GraphQL::Query::NullContext)
+          get_argument(name, context)
+        end
+
+        def all_field_argument_definitions
+          all_argument_definitions
+        end
+
+        # Default `:resolve` set below.
+        # @return [Symbol] The method to call on instances of this object to resolve the field
+        def resolve_method(new_method = nil)
+          if new_method
+            @resolve_method = new_method
+          end
+          @resolve_method || (superclass.respond_to?(:resolve_method) ? superclass.resolve_method : :resolve)
+        end
+
+        # Additional info injected into {#resolve}
+        # @see {GraphQL::Schema::Field#extras}
+        def extras(new_extras = nil)
+          if new_extras
+            @own_extras = new_extras
+          end
+          own_extras = @own_extras || []
+          own_extras + (superclass.respond_to?(:extras) ? superclass.extras : [])
+        end
+
+        # If `true` (default), then the return type for this resolver will be nullable.
+        # If `false`, then the return type is non-null.
+        #
+        # @see #type which sets the return type of this field and accepts a `null:` option
+        # @param allow_null [Boolean] Whether or not the response can be null
+        def null(allow_null = nil)
+          if !allow_null.nil?
+            @null = allow_null
+          end
+
+          @null.nil? ? (superclass.respond_to?(:null) ? superclass.null : true) : @null
+        end
+
+        def resolver_method(new_method_name = nil)
+          if new_method_name
+            @resolver_method = new_method_name
+          else
+            @resolver_method || :resolve_with_support
+          end
+        end
+
+        # Call this method to get the return type of the field,
+        # or use it as a configuration method to assign a return type
+        # instead of generating one.
+        # TODO unify with {#null}
+        # @param new_type [Class, Array<Class>, nil] If a type definition class is provided, it will be used as the return type of the field
+        # @param null [true, false] Whether or not the field may return `nil`
+        # @return [Class] The type which this field returns.
+        def type(new_type = nil, null: nil)
+          if new_type
+            if null.nil?
+              raise ArgumentError, "required argument `null:` is missing"
+            end
+            @type_expr = new_type
+            @null = null
+          else
+            if type_expr
+              GraphQL::Schema::Member::BuildType.parse_type(type_expr, null: self.null)
+            elsif superclass.respond_to?(:type)
+              superclass.type
+            else
+              nil
+            end
+          end
+        end
+
+        # Specifies the complexity of the field. Defaults to `1`
+        # @return [Integer, Proc]
+        def complexity(new_complexity = nil)
+          if new_complexity
+            @complexity = new_complexity
+          end
+          @complexity || (superclass.respond_to?(:complexity) ? superclass.complexity : 1)
+        end
+
+        def broadcastable(new_broadcastable)
+          @broadcastable = new_broadcastable
+        end
+
+        # @return [Boolean, nil]
+        def broadcastable?
+          if defined?(@broadcastable)
+            @broadcastable
+          else
+            (superclass.respond_to?(:broadcastable?) ? superclass.broadcastable? : nil)
+          end
+        end
+
+        # Get or set the `max_page_size:` which will be configured for fields using this resolver
+        # (`nil` means "unlimited max page size".)
+        # @param max_page_size [Integer, nil] Set a new value
+        # @return [Integer, nil] The `max_page_size` assigned to fields that use this resolver
+        def max_page_size(new_max_page_size = :not_given)
+          if new_max_page_size != :not_given
+            @max_page_size = new_max_page_size
+          elsif defined?(@max_page_size)
+            @max_page_size
+          elsif superclass.respond_to?(:max_page_size)
+            superclass.max_page_size
+          else
+            nil
+          end
+        end
+
+        # @return [Boolean] `true` if this resolver or a superclass has an assigned `max_page_size`
+        def has_max_page_size?
+          (!!defined?(@max_page_size)) || (superclass.respond_to?(:has_max_page_size?) && superclass.has_max_page_size?)
+        end
+
+        # Get or set the `default_page_size:` which will be configured for fields using this resolver
+        # (`nil` means "unlimited default page size".)
+        # @param default_page_size [Integer, nil] Set a new value
+        # @return [Integer, nil] The `default_page_size` assigned to fields that use this resolver
+        def default_page_size(new_default_page_size = :not_given)
+          if new_default_page_size != :not_given
+            @default_page_size = new_default_page_size
+          elsif defined?(@default_page_size)
+            @default_page_size
+          elsif superclass.respond_to?(:default_page_size)
+            superclass.default_page_size
+          else
+            nil
+          end
+        end
+
+        # @return [Boolean] `true` if this resolver or a superclass has an assigned `default_page_size`
+        def has_default_page_size?
+          (!!defined?(@default_page_size)) || (superclass.respond_to?(:has_default_page_size?) && superclass.has_default_page_size?)
+        end
+
+        # A non-normalized type configuration, without `null` applied
+        def type_expr
+          @type_expr || (superclass.respond_to?(:type_expr) ? superclass.type_expr : nil)
+        end
+
+        # Add an argument to this field's signature, but
+        # also add some preparation hook methods which will be used for this argument
+        # @see {GraphQL::Schema::Argument#initialize} for the signature
+        def argument(*args, **kwargs, &block)
+          # Use `from_resolver: true` to short-circuit the InputObject's own `loads:` implementation
+          # so that we can support `#load_{x}` methods below.
+          super(*args, from_resolver: true, **kwargs)
+        end
+
+        # Registers new extension
+        # @param extension [Class] Extension class
+        # @param options [Hash] Optional extension options
+        def extension(extension, **options)
+          @own_extensions ||= []
+          @own_extensions << {extension => options}
+        end
+
+        # @api private
+        def extensions
+          own_exts = @own_extensions
+          # Jump through some hoops to avoid creating arrays when we don't actually need them
+          if superclass.respond_to?(:extensions)
+            s_exts = superclass.extensions
+            if own_exts
+              if s_exts.any?
+                own_exts + s_exts
+              else
+                own_exts
+              end
+            else
+              s_exts
+            end
+          else
+            own_exts || EMPTY_ARRAY
+          end
+        end
+
+        private
+
+        def own_extensions
+          @own_extensions
+        end
+      end
+    end
+  end
+end