grape 1.8.0 → 4.0.1

data/lib/grape/dsl/middleware.rb

@@ -3,51 +3,33 @@
 module Grape
   module DSL
     module Middleware
-      extend ActiveSupport::Concern
-
-      include Grape::DSL::Configuration
-
-      module ClassMethods
-        # Apply a custom middleware to the API. Applies
-        # to the current namespace and any children, but
-        # not parents.
-        #
-        # @param middleware_class [Class] The class of the middleware you'd like
-        #   to inject.
-        def use(middleware_class, *args, &block)
-          arr = [:use, middleware_class, *args]
-          arr << block if block
-
-          namespace_stackable(:middleware, arr)
-        end
-
-        def insert(*args, &block)
-          arr = [:insert, *args]
-          arr << block if block
-
-          namespace_stackable(:middleware, arr)
-        end
-
-        def insert_before(*args, &block)
-          arr = [:insert_before, *args]
-          arr << block if block
-
-          namespace_stackable(:middleware, arr)
-        end
+      # Apply a custom middleware to the API. Applies
+      # to the current namespace and any children, but
+      # not parents.
+      #
+      # @param middleware_class [Class] The class of the middleware you'd like
+      #   to inject.
+      def use(middleware_class, *args, &block)
+        arr = [:use, middleware_class, *args]
+        arr << block if block
+
+        inheritable_setting.add_middleware(arr)
+      end
 
-        def insert_after(*args, &block)
-          arr = [:insert_after, *args]
+      %i[insert insert_before insert_after].each do |method_name|
+        define_method method_name do |*args, &block|
+          arr = [method_name, *args]
           arr << block if block
 
-          namespace_stackable(:middleware, arr)
+          inheritable_setting.add_middleware(arr)
         end
+      end
 
-        # Retrieve an array of the middleware classes
-        # and arguments that are currently applied to the
-        # application.
-        def middleware
-          namespace_stackable(:middleware) || []
-        end
+      # Retrieve an array of the middleware classes
+      # and arguments that are currently applied to the
+      # application.
+      def middleware
+        inheritable_setting.middleware
       end
     end
   end

data/lib/grape/dsl/parameters.rb

@@ -6,8 +6,6 @@ module Grape
     # and describe the parameters accepted by an endpoint, or all endpoints
     # within a namespace.
     module Parameters
-      extend ActiveSupport::Concern
-
       # Set the module used to build the request.params.
       #
       # @param build_with the ParamBuilder module to use when building request.params
@@ -23,15 +21,15 @@ module Grape
       #     class API < Grape::API
       #       desc "Get collection"
       #       params do
-      #         build_with Grape::Extensions::Hashie::Mash::ParamBuilder
+      #         build_with :hashie_mash
       #         requires :user_id, type: Integer
       #       end
       #       get do
       #         params['user_id']
       #       end
       #     end
-      def build_with(build_with = nil)
-        @api.namespace_inheritable(:build_params_with, build_with)
+      def build_with(build_with)
+        @api.inheritable_setting.build_params_with = build_with
       end
 
       # Include reusable params rules among current.
@@ -55,9 +53,10 @@ module Grape
       #         Collection.page(params[:page]).per(params[:per_page])
       #       end
       #     end
-      def use(*names)
-        named_params = @api.namespace_stackable_with_hash(:named_params) || {}
-        options = names.extract_options!
+      def use(*names, **options)
+        return redispatch_legacy_options(:use, names, options) if legacy_options?(names)
+
+        named_params = @api.inheritable_setting.named_params || {}
         names.each do |name|
           params_block = named_params.fetch(name) do
             raise "Params :#{name} not found!"
@@ -77,8 +76,8 @@ module Grape
       #
       # @param attrs list of parameters names, or, if :using is
       #   passed as an option, which keys to include (:all or :none) from
-      #   the :using hash. The last key can be a hash, which specifies
-      #   options for the parameters
+      #   the :using hash. Passing the options as a trailing positional Hash
+      #   is deprecated; pass them as keyword arguments instead.
       # @option attrs :type [Class] the type to coerce this parameter to before
       #   passing it to the endpoint. See {Grape::Validations::Types} for a list of
       #   types that are supported automatically. Custom classes may be used
@@ -125,76 +124,34 @@ module Grape
       #         requires :name, type: String
       #       end
       #     end
-      def requires(*attrs, &block)
-        orig_attrs = attrs.clone
+      def requires(*attrs, using: nil, except: nil, as: nil, **opts, &)
+        return redispatch_legacy_options(:requires, attrs, { using:, except:, as: }.compact.merge(opts), &) if legacy_options?(attrs)
 
-        opts = attrs.extract_options!.clone
-        opts[:presence] = { value: true, message: opts[:message] }
-        opts = @group.merge(opts) if instance_variable_defined?(:@group) && @group
-
-        if opts[:using]
-          require_required_and_optional_fields(attrs.first, opts)
-        else
-          validate_attributes(attrs, opts, &block)
-          block ? new_scope(orig_attrs, &block) : push_declared_params(attrs, **opts.slice(:as))
-        end
+        declare(attrs, opts, required: true, using:, except:, as:, &)
       end
 
       # Allow, but don't require, one or more parameters for the current
       #   endpoint.
       # @param (see #requires)
       # @option (see #requires)
-      def optional(*attrs, &block)
-        orig_attrs = attrs.clone
-
-        opts = attrs.extract_options!.clone
-        type = opts[:type]
-        opts = @group.merge(opts) if instance_variable_defined?(:@group) && @group
+      def optional(*attrs, using: nil, except: nil, as: nil, **opts, &)
+        return redispatch_legacy_options(:optional, attrs, { using:, except:, as: }.compact.merge(opts), &) if legacy_options?(attrs)
 
-        # check type for optional parameter group
-        if attrs && block
-          raise Grape::Exceptions::MissingGroupType if type.nil?
-          raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
-        end
-
-        if opts[:using]
-          require_optional_fields(attrs.first, opts)
-        else
-          validate_attributes(attrs, opts, &block)
-
-          block ? new_scope(orig_attrs, true, &block) : push_declared_params(attrs, **opts.slice(:as))
-        end
+        declare(attrs, opts, required: false, using:, except:, as:, &)
       end
 
       # Define common settings for one or more parameters
       # @param (see #requires)
       # @option (see #requires)
-      def with(*attrs, &block)
-        new_group_scope(attrs.clone, &block)
-      end
-
-      # Disallow the given parameters to be present in the same request.
-      # @param attrs [*Symbol] parameters to validate
-      def mutually_exclusive(*attrs)
-        validates(attrs, mutual_exclusion: { value: true, message: extract_message_option(attrs) })
+      def with(**opts, &)
+        new_group_attrs = @group&.deep_merge(opts) || opts
+        new_group_scope(new_group_attrs, &)
       end
 
-      # Require exactly one of the given parameters to be present.
-      # @param (see #mutually_exclusive)
-      def exactly_one_of(*attrs)
-        validates(attrs, exactly_one_of: { value: true, message: extract_message_option(attrs) })
-      end
-
-      # Require at least one of the given parameters to be present.
-      # @param (see #mutually_exclusive)
-      def at_least_one_of(*attrs)
-        validates(attrs, at_least_one_of: { value: true, message: extract_message_option(attrs) })
-      end
-
-      # Require that either all given params are present, or none are.
-      # @param (see #mutually_exclusive)
-      def all_or_none_of(*attrs)
-        validates(attrs, all_or_none_of: { value: true, message: extract_message_option(attrs) })
+      %i[mutually_exclusive exactly_one_of at_least_one_of all_or_none_of].each do |validator|
+        define_method validator do |*attrs, message: nil|
+          validates(attrs, { validator => { value: true, message: } })
+        end
       end
 
       # Define a block of validations which should be applied if and only if
@@ -204,62 +161,99 @@ module Grape
       # @raise Grape::Exceptions::UnknownParameter if `attr` has not been
       #   defined in this scope yet
       # @yield a parameter definition DSL
-      def given(*attrs, &block)
+      def given(*attrs, &)
         attrs.each do |attr|
           proxy_attr = first_hash_key_or_param(attr)
           raise Grape::Exceptions::UnknownParameter.new(proxy_attr) unless declared_param?(proxy_attr)
         end
-        new_lateral_scope(dependent_on: attrs, &block)
+        new_lateral_scope(dependent_on: attrs, &)
       end
 
       # Test for whether a certain parameter has been defined in this params
       # block yet.
       # @return [Boolean] whether the parameter has been defined
       def declared_param?(param)
-        if lateral?
-          # Elements of @declared_params of lateral scope are pushed in @parent. So check them in @parent.
-          @parent.declared_param?(param)
-        else
-          # @declared_params also includes hashes of options and such, but those
-          # won't be flattened out.
-          @declared_params.flatten.any? do |declared_param_attr|
-            first_hash_key_or_param(declared_param_attr.key) == param
-          end
+        # Elements of @declared_params of lateral scope are pushed in @parent. So check them in @parent.
+        return @parent.declared_param?(param) if lateral?
+
+        # @declared_params also includes hashes of options and such, but those
+        # won't be flattened out.
+        @declared_params.flatten.any? do |declared_param_attr|
+          first_hash_key_or_param(declared_param_attr.key) == param
         end
       end
 
       alias group requires
 
-      class EmptyOptionalValue; end
-
-      def map_params(params, element, is_array = false)
-        if params.is_a?(Array)
-          params.map do |el|
-            map_params(el, element, true)
-          end
-        elsif params.is_a?(Hash)
-          params[element] || (@optional && is_array ? EmptyOptionalValue : {})
-        elsif params == EmptyOptionalValue
-          EmptyOptionalValue
-        else
-          {}
-        end
-      end
+      EmptyOptionalValue = Object.new.freeze
 
       # @param params [Hash] initial hash of parameters
       # @return hash of parameters relevant for the current scope
       # @api private
       def params(params)
-        params = @parent.params(params) if instance_variable_defined?(:@parent) && @parent
-        params = map_params(params, @element) if instance_variable_defined?(:@element) && @element
-        params
+        scoped = @parent ? (@parent.qualifying_params.presence || @parent.params(params)) : params
+        @element ? map_params(scoped, @element) : scoped
       end
 
       private
 
+      # @deprecated A trailing positional options Hash is deprecated; pass keyword
+      #   arguments instead. Before Ruby 3 keyword separation this Hash was pulled
+      #   off the argument list by `extract_options!`; now it lands in the splat and
+      #   would silently be treated as a parameter name.
+      # +requires+ and +optional+ differ only in whether what they declare is
+      # required, so the declaration itself lives here.
+      #
+      # The two +using:+ helpers stay separate. They are not one computation
+      # with a flag flipped: +requires+ treats +except+ as "these go in the
+      # other bucket", while +optional+ has no other bucket — +:all+ ignores
+      # +except+ and +:none+ uses it to drop fields entirely.
+      def declare(attrs, opts, required:, using:, except:, as:, &block)
+        merged_opts = @group&.deep_merge(opts) || opts
+        declared_as = as || merged_opts[:as]
+
+        if using
+          return require_required_and_optional_fields(attrs.first, using:, except:) if required
+
+          return require_optional_fields(attrs.first, using:, except:)
+        end
+
+        validates(attrs, merged_opts, required:)
+        return push_declared_params(attrs, as: declared_as) unless block
+
+        new_scope(attrs.first, type: merged_opts[:type], as: declared_as, optional: !required, &block)
+      end
+
+      def legacy_options?(args)
+        args.size > 1 && args.last.is_a?(Hash)
+      end
+
+      # Re-invokes +method_name+ with the trailing Hash splatted as keyword
+      # arguments, so Ruby routes its keys to the same place they would have
+      # reached had the caller omitted the braces.
+      def redispatch_legacy_options(method_name, args, opts, &)
+        Grape.deprecator.warn("Passing a positional options Hash to `#{method_name}` is deprecated. Pass keyword arguments instead.")
+        __send__(method_name, *args[0..-2], **args.last.merge(opts), &)
+      end
+
       def first_hash_key_or_param(parameter)
         parameter.is_a?(Hash) ? parameter.keys.first : parameter
       end
+
+      def map_params(params, element, is_array: false)
+        case params
+        when Array
+          params.map do |el|
+            map_params(el, element, is_array: true)
+          end
+        when Hash
+          params[element] || (@optional && is_array ? EmptyOptionalValue : {})
+        when EmptyOptionalValue
+          EmptyOptionalValue
+        else
+          {}
+        end
+      end
     end
   end
 end

data/lib/grape/dsl/request_response.rb

@@ -3,171 +3,167 @@
 module Grape
   module DSL
     module RequestResponse
-      extend ActiveSupport::Concern
+      # Specify the default format for the API's serializers.
+      # May be `:json` or `:txt` (default).
+      def default_format(new_format = nil)
+        return inheritable_setting.default_format if new_format.nil?
 
-      include Grape::DSL::Configuration
+        inheritable_setting.default_format = new_format.to_sym
+      end
 
-      module ClassMethods
-        # Specify the default format for the API's serializers.
-        # May be `:json` or `:txt` (default).
-        def default_format(new_format = nil)
-          namespace_inheritable(:default_format, new_format.nil? ? nil : new_format.to_sym)
-        end
+      # Specify the format for the API's serializers.
+      # May be `:json`, `:xml`, `:txt`, etc.
+      def format(new_format = nil)
+        return inheritable_setting.format if new_format.nil?
 
-        # Specify the format for the API's serializers.
-        # May be `:json`, `:xml`, `:txt`, etc.
-        def format(new_format = nil)
-          if new_format
-            namespace_inheritable(:format, new_format.to_sym)
-            # define the default error formatters
-            namespace_inheritable(:default_error_formatter, Grape::ErrorFormatter.formatter_for(new_format, **{}))
-            # define a single mime type
-            mime_type = content_types[new_format.to_sym]
-            raise Grape::Exceptions::MissingMimeType.new(new_format) unless mime_type
-
-            namespace_stackable(:content_types, new_format.to_sym => mime_type)
-          else
-            namespace_inheritable(:format)
-          end
-        end
+        symbolic_new_format = new_format.to_sym
+        inheritable_setting.format = symbolic_new_format
+        inheritable_setting.default_error_formatter = Grape::ErrorFormatter.formatter_for(symbolic_new_format)
 
-        # Specify a custom formatter for a content-type.
-        def formatter(content_type, new_formatter)
-          namespace_stackable(:formatters, content_type.to_sym => new_formatter)
-        end
+        content_type = content_types[symbolic_new_format]
+        raise Grape::Exceptions::MissingMimeType.new(new_format) unless content_type
 
-        # Specify a custom parser for a content-type.
-        def parser(content_type, new_parser)
-          namespace_stackable(:parsers, content_type.to_sym => new_parser)
-        end
+        inheritable_setting.add_content_type(symbolic_new_format, content_type)
+      end
 
-        # Specify a default error formatter.
-        def default_error_formatter(new_formatter_name = nil)
-          if new_formatter_name
-            new_formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name, **{})
-            namespace_inheritable(:default_error_formatter, new_formatter)
-          else
-            namespace_inheritable(:default_error_formatter)
-          end
-        end
+      # Specify a custom formatter for a content-type.
+      def formatter(content_type, new_formatter)
+        inheritable_setting.add_formatter(content_type.to_sym, new_formatter)
+      end
 
-        def error_formatter(format, options)
-          formatter = if options.is_a?(Hash) && options.key?(:with)
-                        options[:with]
-                      else
-                        options
-                      end
+      # Specify a custom parser for a content-type.
+      def parser(content_type, new_parser)
+        inheritable_setting.add_parser(content_type.to_sym, new_parser)
+      end
 
-          namespace_stackable(:error_formatters, format.to_sym => formatter)
-        end
+      # Specify a default error formatter, by the name it is registered under.
+      # A name nothing is registered for used to be stored as
+      # +ErrorFormatter::Txt+ — the fallback the lookup applied — so a typo
+      # read back as a working setting and silently rendered errors as text.
+      def default_error_formatter(new_formatter_name = nil)
+        return inheritable_setting.default_error_formatter if new_formatter_name.nil?
 
-        # Specify additional content-types, e.g.:
-        #   content_type :xls, 'application/vnd.ms-excel'
-        def content_type(key, val)
-          namespace_stackable(:content_types, key.to_sym => val)
-        end
+        formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name)
+        raise Grape::Exceptions::UnknownErrorFormatter.new(new_formatter_name) if formatter.nil?
 
-        # All available content types.
-        def content_types
-          c_types = namespace_stackable_with_hash(:content_types)
-          Grape::ContentTypes.content_types_for c_types
-        end
+        inheritable_setting.default_error_formatter = formatter
+      end
 
-        # Specify the default status code for errors.
-        def default_error_status(new_status = nil)
-          namespace_inheritable(:default_error_status, new_status)
-        end
+      # Specify a custom error formatter for a format, passed positionally or
+      # as +with:+. A nil formatter used to be registered as-is, which is the
+      # one thing the registration cannot mean: the format then resolves as if
+      # the call had never been made. Reject it here, where the mistake is.
+      def error_formatter(format, options = nil, with: nil)
+        formatter = with || options
+        raise ArgumentError, "error_formatter `#{format.inspect}` requires a formatter, given positionally or as `with:`" if formatter.nil?
 
-        # Allows you to rescue certain exceptions that occur to return
-        # a grape error rather than raising all the way to the
-        # server level.
-        #
-        # @example Rescue from custom exceptions
-        #     class ExampleAPI < Grape::API
-        #       class CustomError < StandardError; end
-        #
-        #       rescue_from CustomError
-        #     end
-        #
-        # @overload rescue_from(*exception_classes, **options)
-        #   @param [Array] exception_classes A list of classes that you want to rescue, or
-        #     the symbol :all to rescue from all exceptions.
-        #   @param [Block] block Execution block to handle the given exception.
-        #   @param [Hash] options Options for the rescue usage.
-        #   @option options [Boolean] :backtrace Include a backtrace in the rescue response.
-        #   @option options [Boolean] :rescue_subclasses Also rescue subclasses of exception classes
-        #   @param [Proc] handler Execution proc to handle the given exception as an
-        #     alternative to passing a block.
-        def rescue_from(*args, &block)
-          if args.last.is_a?(Proc)
-            handler = args.pop
-          elsif block
-            handler = block
-          end
-
-          options = args.extract_options!
-          raise ArgumentError, 'both :with option and block cannot be passed' if block && options.key?(:with)
-
-          handler ||= extract_with(options)
-
-          if args.include?(:all)
-            namespace_inheritable(:rescue_all, true)
-            namespace_inheritable(:all_rescue_handler, handler)
-          elsif args.include?(:grape_exceptions)
-            namespace_inheritable(:rescue_all, true)
-            namespace_inheritable(:rescue_grape_exceptions, true)
-            namespace_inheritable(:grape_exceptions_rescue_handler, handler)
-          else
-            handler_type =
-              case options[:rescue_subclasses]
-              when nil, true
-                :rescue_handlers
-              else
-                :base_only_rescue_handlers
-              end
-
-            namespace_reverse_stackable(handler_type, args.to_h { |arg| [arg, handler] })
-          end
-
-          namespace_stackable(:rescue_options, options)
-        end
+        inheritable_setting.add_error_formatter(format.to_sym, formatter)
+      end
+
+      # Specify additional content-types, e.g.:
+      #   content_type :xls, 'application/vnd.ms-excel'
+      def content_type(key, val)
+        inheritable_setting.add_content_type(key.to_sym, val)
+      end
+
+      # All available content types.
+      def content_types
+        Grape::ContentTypes.content_types_for(inheritable_setting.content_types)
+      end
+
+      # Specify the default status code for errors.
+      def default_error_status(new_status = nil)
+        return inheritable_setting.default_error_status if new_status.nil?
 
-        # Allows you to specify a default representation entity for a
-        # class. This allows you to map your models to their respective
-        # entities once and then simply call `present` with the model.
-        #
-        # @example
-        #   class ExampleAPI < Grape::API
-        #     represent User, with: Entity::User
-        #
-        #     get '/me' do
-        #       present current_user # with: Entity::User is assumed
-        #     end
-        #   end
-        #
-        # Note that Grape will automatically go up the class ancestry to
-        # try to find a representing entity, so if you, for example, define
-        # an entity to represent `Object` then all presented objects will
-        # bubble up and utilize the entity provided on that `represent` call.
-        #
-        # @param model_class [Class] The model class that will be represented.
-        # @option options [Class] :with The entity class that will represent the model.
-        def represent(model_class, options)
-          raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with].is_a?(Class)
-
-          namespace_stackable(:representations, model_class => options[:with])
+        inheritable_setting.default_error_status = new_status
+      end
+
+      # Allows you to rescue certain exceptions that occur to return
+      # a grape error rather than raising all the way to the
+      # server level.
+      #
+      # @example Rescue from custom exceptions
+      #     class ExampleAPI < Grape::API
+      #       class CustomError < StandardError; end
+      #
+      #       rescue_from CustomError
+      #     end
+      #
+      META_RESCUE_SELECTORS = %i[all grape_exceptions internal_grape_exceptions].freeze
+      private_constant :META_RESCUE_SELECTORS
+
+      # @overload rescue_from(*exception_classes, **options)
+      #   @param [Array] exception_classes A list of classes that you want to rescue, or
+      #     one of the meta selectors +:all+, +:grape_exceptions+,
+      #     +:internal_grape_exceptions+. Meta selectors must be used alone;
+      #     mixing with exception classes raises +ArgumentError+.
+      #   @param [Block] block Execution block to handle the given exception.
+      #   @param [Proc] with Execution proc to handle the given exception as an alternative
+      #     to passing a block.
+      #   @param [Boolean] rescue_subclasses Also rescue subclasses of exception classes;
+      #     defaults to +true+.
+      #   @param [Boolean] backtrace Include the rescued exception's backtrace in the
+      #     rescue response body.
+      #   @param [Boolean] original_exception Include +inspect+ of the rescued exception
+      #     in the rescue response body.
+      def rescue_from(*args, with: nil, rescue_subclasses: true, backtrace: false, original_exception: false, &block)
+        handler = extract_handler(args, with:, block:)
+        meta_selector = (args & META_RESCUE_SELECTORS).first
+        raise ArgumentError, "rescue_from `#{meta_selector.inspect}` does not accept additional arguments" if meta_selector && args.size > 1
+
+        case meta_selector
+        when :all
+          inheritable_setting.add_all_rescue_handler(handler)
+        when :grape_exceptions
+          inheritable_setting.add_grape_exceptions_rescue_handler(handler)
+        when :internal_grape_exceptions
+          inheritable_setting.add_internal_grape_exceptions_rescue_handler(handler)
+        else
+          inheritable_setting.add_rescue_handlers(args.to_h { |klass| [klass, handler] }, subclasses: rescue_subclasses)
         end
 
-        private
+        inheritable_setting.add_rescue_options(RescueOptions.new(backtrace:, original_exception:))
+      end
+
+      # Allows you to specify a default representation entity for a
+      # class. This allows you to map your models to their respective
+      # entities once and then simply call `present` with the model.
+      #
+      # @example
+      #   class ExampleAPI < Grape::API
+      #     represent User, with: Entity::User
+      #
+      #     get '/me' do
+      #       present current_user # with: Entity::User is assumed
+      #     end
+      #   end
+      #
+      # Note that Grape will automatically go up the class ancestry to
+      # try to find a representing entity, so if you, for example, define
+      # an entity to represent `Object` then all presented objects will
+      # bubble up and utilize the entity provided on that `represent` call.
+      #
+      # @param model_class [Class] The model class that will be represented.
+      # @option options [Class] :with The entity class that will represent the model.
+      def represent(model_class, with:)
+        raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless with.is_a?(Class)
+
+        inheritable_setting.add_representation(model_class, with)
+      end
+
+      private
 
-        def extract_with(options)
-          return unless options.key?(:with)
+      def extract_handler(args, with:, block:)
+        raise ArgumentError, 'both :with option and block cannot be passed' if block && with
 
-          with_option = options.delete(:with)
-          return with_option if with_option.instance_of?(Proc)
-          return with_option.to_sym if with_option.instance_of?(Symbol) || with_option.instance_of?(String)
+        return args.pop if args.last.is_a?(Proc)
+        return block if block
+        return unless with
 
-          raise ArgumentError, "with: #{with_option.class}, expected Symbol, String or Proc"
+        case with
+        when Proc, Symbol then with
+        when String then with.to_sym
+        else raise ArgumentError, "with: `#{with.class}`, expected Symbol, String or Proc"
         end
       end
     end