grape 1.8.0 → 3.3.5

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.namespace_stackable[: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.namespace_stackable[: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.namespace_stackable[: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.namespace_inheritable[:build_params_with] = build_with
       end
 
       # Include reusable params rules among current.
@@ -55,9 +53,8 @@ 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)
+        named_params = @api.inheritable_setting.namespace_stackable_with_hash(:named_params) || {}
         names.each do |name|
           params_block = named_params.fetch(name) do
             raise "Params :#{name} not found!"
@@ -125,31 +122,23 @@ module Grape
       #         requires :name, type: String
       #       end
       #     end
-      def requires(*attrs, &block)
-        orig_attrs = attrs.clone
-
-        opts = attrs.extract_options!.clone
+      def requires(*attrs, using: nil, except: nil, **opts, &block)
         opts[:presence] = { value: true, message: opts[:message] }
-        opts = @group.merge(opts) if instance_variable_defined?(:@group) && @group
+        opts = @group.deep_merge(opts) if @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
+        return require_required_and_optional_fields(attrs.first, using:, except:) if using
+
+        validate_attributes(attrs, **opts, &block)
+        block ? new_scope(attrs.first, type: opts[:type], as: opts[:as], &block) : push_declared_params(attrs, as: opts[: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
+      def optional(*attrs, using: nil, except: nil, **opts, &block)
         type = opts[:type]
-        opts = @group.merge(opts) if instance_variable_defined?(:@group) && @group
+        opts = @group.deep_merge(opts) if @group
 
         # check type for optional parameter group
         if attrs && block
@@ -157,44 +146,24 @@ module Grape
           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)
+        return require_optional_fields(attrs.first, using:, except:) if using
 
-          block ? new_scope(orig_attrs, true, &block) : push_declared_params(attrs, **opts.slice(:as))
-        end
+        validate_attributes(attrs, **opts, &block)
+        block ? new_scope(attrs.first, type: opts[:type], as: opts[:as], optional: true, &block) : push_declared_params(attrs, as: opts[: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) })
-      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) })
+      def with(**opts, &)
+        new_group_attrs = @group&.deep_merge(opts) || opts
+        new_group_scope(new_group_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,54 +173,38 @@ 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 = @parent.qualifying_params.presence || @parent.params(params) if @parent
+        params = map_params(params, @element) if @element
         params
       end
 
@@ -260,6 +213,21 @@ module Grape
       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,169 @@
 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.namespace_inheritable[:default_format] if new_format.nil?
 
-      include Grape::DSL::Configuration
+        inheritable_setting.namespace_inheritable[: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.namespace_inheritable[: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.namespace_inheritable[:format] = symbolic_new_format
+        inheritable_setting.namespace_inheritable[: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.namespace_stackable[:content_types] = { 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.namespace_stackable[:formatters] = { 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.namespace_stackable[:parsers] = { content_type.to_sym => new_parser }
+      end
 
-          namespace_stackable(:error_formatters, format.to_sym => formatter)
-        end
+      # Specify a default error formatter.
+      def default_error_formatter(new_formatter_name = nil)
+        return inheritable_setting.namespace_inheritable[: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
+        new_formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name)
+        inheritable_setting.namespace_inheritable[:default_error_formatter] = new_formatter
+      end
 
-        # All available content types.
-        def content_types
-          c_types = namespace_stackable_with_hash(:content_types)
-          Grape::ContentTypes.content_types_for c_types
-        end
+      def error_formatter(format, options = nil, with: nil)
+        formatter = with || options
+        inheritable_setting.namespace_stackable[:error_formatters] = { format.to_sym => 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 additional content-types, e.g.:
+      #   content_type :xls, 'application/vnd.ms-excel'
+      def content_type(key, val)
+        inheritable_setting.namespace_stackable[:content_types] = { key.to_sym => val }
+      end
+
+      # All available content types.
+      def content_types
+        c_types = inheritable_setting.namespace_stackable_with_hash(:content_types)
+        Grape::ContentTypes.content_types_for c_types
+      end
+
+      # Specify the default status code for errors.
+      def default_error_status(new_status = nil)
+        return inheritable_setting.namespace_inheritable[:default_error_status] if new_status.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)
+        inheritable_setting.namespace_inheritable[: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
+
+        namespace_inheritable = nil
+        arg = nil
+
+        if args.one?
+          arg = args.first
+          namespace_inheritable = inheritable_setting.namespace_inheritable
         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, options)
-          raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with].is_a?(Class)
-
-          namespace_stackable(:representations, model_class => options[:with])
+        case arg
+        when :all
+          namespace_inheritable[:rescue_all] = true
+          namespace_inheritable[:all_rescue_handler] = handler
+        when :grape_exceptions
+          namespace_inheritable[:rescue_all] = true
+          namespace_inheritable[:rescue_grape_exceptions] = true
+          namespace_inheritable[:grape_exceptions_rescue_handler] = handler
+        when :internal_grape_exceptions
+          namespace_inheritable[:internal_grape_exceptions_rescue_handler] = handler
+        else
+          handler_type = rescue_subclasses ? :rescue_handlers : :base_only_rescue_handlers
+          inheritable_setting.namespace_reverse_stackable[handler_type] = args.to_h { |klass| [klass, handler] }
         end
 
-        private
+        inheritable_setting.namespace_stackable[: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.namespace_stackable[:representations] = { 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

data/lib/grape/dsl/rescue_options.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    # Immutable value object holding the response-shaping booleans accepted
+    # by +Grape::DSL::RequestResponse#rescue_from+. Stored on the
+    # inheritable settings as +namespace_stackable[:rescue_options]+ and
+    # delegated to by +Grape::Middleware::Error+ (which forwards
+    # +backtrace+/+original_exception+ to the formatter as
+    # +include_backtrace+/+include_original_exception+).
+    #
+    # Defaults are duplicated on +#initialize+ here and on +#rescue_from+'s
+    # signature on purpose: keeping them on both sides means each entry point
+    # is self-documenting without needing to import a shared constant — the
+    # DSL signature shows what a user sees in the IDE, and the Data object
+    # has working defaults when constructed directly (middleware
+    # `DEFAULT_OPTIONS`, spec fixtures, etc.). The two must stay in lockstep.
+    RescueOptions = Data.define(:backtrace, :original_exception) do
+      def initialize(backtrace: false, original_exception: false)
+        super
+      end
+    end
+  end
+end