grape 3.2.1 → 3.3.0

data/lib/grape/dsl/desc.rb

@@ -9,7 +9,8 @@ module Grape
       # @param description [String] descriptive string for this endpoint
       #   or namespace
       # @param options [Hash] other properties you can set to describe the
-      #   endpoint or namespace. Optional.
+      #   endpoint or namespace. Optional. Pass these as keyword arguments;
+      #   passing a positional options Hash is deprecated.
       # @option options :detail [String] additional detail about this endpoint
       # @option options :summary [String] summary for this endpoint
       # @option options :params [Hash] param types and info. normally, you set
@@ -49,7 +50,12 @@ module Grape
       #       # ...
       #     end
       #
-      def desc(description, options = {}, &config_block)
+      def desc(description, *legacy_options, **options, &config_block)
+        if legacy_options.any?
+          Grape.deprecator.warn('Passing a positional options Hash to `desc` is deprecated. Pass keyword arguments instead.')
+          options = legacy_options.first.merge(options)
+        end
+
         settings =
           if config_block
             endpoint_config = defined?(configuration) ? configuration : nil

data/lib/grape/dsl/entity.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Entity
+      # Allows you to make use of Grape Entities by setting
+      # the response body to the serializable hash of the
+      # entity provided in the `:with` option. This has the
+      # added benefit of automatically passing along environment
+      # and version information to the serialization, making it
+      # very easy to do conditional exposures. See Entity docs
+      # for more info.
+      #
+      # @param args [Array] either `(object)` or `(key, object)` where key is a Symbol
+      #   used to nest the representation under that key in the response body.
+      # @param root [Symbol, String, nil] wraps the representation under this root key.
+      # @param with [Class, nil] the entity class to use for representation.
+      #   If omitted, the entity class is inferred from the object via {#entity_class_for_obj}.
+      # @param options [Hash] additional options forwarded to the entity's `represent` call.
+      #
+      # @example
+      #
+      #   get '/users/:id' do
+      #     present User.find(params[:id]),
+      #       with: API::Entities::User,
+      #       admin: current_user.admin?
+      #   end
+      def present(*args, root: nil, with: nil, **options)
+        key, object = args.count == 2 && args.first.is_a?(Symbol) ? args : [nil, args.first]
+        entity_class = with || entity_class_for_obj(object)
+        representation = entity_class ? entity_representation_for(entity_class, object, options) : object
+        representation = { root => representation } if root
+
+        if key
+          representation = body&.merge(key => representation) || { key => representation }
+        elsif entity_class.present? && body
+          raise ArgumentError, "Representation of type #{representation.class} cannot be merged." unless representation.respond_to?(:merge)
+
+          representation = body.merge(representation)
+        end
+
+        body representation
+      end
+
+      # Attempt to locate the Entity class for a given object, if not given
+      # explicitly. This is done by looking for the presence of Klass::Entity,
+      # where Klass is the class of the `object` parameter, or one of its
+      # ancestors.
+      # @param object [Object] the object to locate the Entity class for
+      # @return [Class] the located Entity class, or nil if none is found
+      def entity_class_for_obj(object)
+        klass = object_class(object)
+
+        representations = inheritable_setting.namespace_stackable_with_hash(:representations)
+        if representations
+          potential = klass.ancestors.detect { |potential| representations.key?(potential) }
+          return representations[potential] if potential && representations[potential]
+        end
+
+        return unless klass.const_defined?(:Entity)
+
+        entity = klass.const_get(:Entity)
+        entity if entity.respond_to?(:represent)
+      end
+
+      private
+
+      # Resolves the class used to look up the Entity for +object+.
+      # @param object [Object] the object to represent.
+      # @return [Class] the object's collection element class, wrapped class, or its own class.
+      def object_class(object)
+        return object.klass if object.respond_to?(:klass)
+        return object.first.class if object.respond_to?(:first)
+
+        object.class
+      end
+
+      # @param entity_class [Class] the entity class to use for representation.
+      # @param object [Object] the object to represent.
+      # @param options [Hash] additional options forwarded to the entity's `represent` call.
+      # @return the representation of the given object as done through the given entity_class.
+      def entity_representation_for(entity_class, object, options)
+        embeds = env.key?(Grape::Env::API_VERSION) ? { env:, version: env[Grape::Env::API_VERSION] } : { env: }
+        entity_class.represent(object, **embeds, **options)
+      end
+    end
+  end
+end

data/lib/grape/dsl/helpers.rb

@@ -45,9 +45,8 @@ module Grape
       def include_block(block)
         return unless block
 
-        Module.new.tap do |mod|
-          make_inclusion(mod) { mod.class_eval(&block) }
-        end
+        mod = Module.new
+        make_inclusion(mod) { mod.class_eval(&block) }
       end
 
       def make_inclusion(mod, &)
@@ -57,10 +56,10 @@ module Grape
       end
 
       def include_all_in_scope
-        Module.new.tap do |mod|
-          namespace_stackable(:helpers).each { |mod_to_include| mod.include mod_to_include }
-          change!
-        end
+        mod = Module.new
+        namespace_stackable(:helpers).each { |mod_to_include| mod.include mod_to_include }
+        change!
+        mod
       end
 
       def define_boolean_in_mod(mod)
@@ -72,9 +71,30 @@ module Grape
       def inject_api_helpers_to_mod(mod, &block)
         mod.extend(BaseHelper) unless mod.is_a?(BaseHelper)
         yield if block
+        warn_on_endpoint_overrides(mod) if Grape.config.warn_on_helper_overrides
         mod.api_changed(self)
       end
 
+      # When +Grape.config.warn_on_helper_overrides+ is enabled, emit a
+      # warning to +$stderr+ for any helper method that masks an instance
+      # method on +Grape::Endpoint+. Helpers are mixed into the endpoint's
+      # singleton class and therefore take precedence over +Endpoint+
+      # instance methods — usually intentional, but a common source of
+      # surprise when the framework gains a method that already collides
+      # with an existing helper name.
+      def warn_on_endpoint_overrides(mod)
+        overridden = mod.instance_methods(false).select { |m| Grape::Endpoint.method_defined?(m) }
+        return if overridden.empty?
+
+        overridden.each do |name|
+          warn(
+            "Grape: helper method `#{name}` overrides Grape::Endpoint##{name}. " \
+            'The helper takes precedence. To use the framework implementation, remove the helper. ' \
+            'Silence this warning by setting Grape.config.warn_on_helper_overrides = false.'
+          )
+        end
+      end
+
       # This module extends user defined helpers
       # to provide some API-specific functionality.
       module BaseHelper

data/lib/grape/dsl/inside_route.rb

@@ -4,6 +4,7 @@ module Grape
   module DSL
     module InsideRoute
       include Declared
+      include Entity
 
       # Backward compatibility: alias exception class to previous location
       MethodNotYetAvailable = Declared::MethodNotYetAvailable
@@ -14,7 +15,7 @@ module Grape
       end
 
       def configuration
-        options[:for].configuration.evaluate
+        config.for.configuration.evaluate
       end
 
       # End the request and display an error to the
@@ -28,12 +29,9 @@ module Grape
       def error!(message, status = nil, additional_headers = nil, backtrace = nil, original_exception = nil)
         status = self.status(status || inheritable_setting.namespace_inheritable[:default_error_status])
         headers = additional_headers.present? ? header.merge(additional_headers) : header
-        throw :error,
-              message:,
-              status:,
-              headers:,
-              backtrace:,
-              original_exception:
+        throw :error, Grape::Exceptions::ErrorResponse.new(
+          message:, status:, headers:, backtrace:, original_exception:
+        )
       end
 
       # Redirect to a new url.
@@ -62,27 +60,11 @@ module Grape
       #
       # @param status [Integer] The HTTP Status Code to return for this request.
       def status(status = nil)
-        case status
-        when Symbol
-          raise ArgumentError, "Status code :#{status} is invalid." unless Rack::Utils::SYMBOL_TO_STATUS_CODE.key?(status)
+        return @status || default_status if status.nil?
 
+        case status
+        when Symbol, Integer
           @status = Rack::Utils.status_code(status)
-        when Integer
-          @status = status
-        when nil
-          return @status if @status
-
-          if request.post?
-            201
-          elsif request.delete?
-            if @body.present?
-              200
-            else
-              204
-            end
-          else
-            200
-          end
         else
           raise ArgumentError, 'Status code must be Integer or Symbol.'
         end
@@ -90,11 +72,9 @@ module Grape
 
       # Set response content-type
       def content_type(val = nil)
-        if val
-          header(Rack::CONTENT_TYPE, val)
-        else
-          header[Rack::CONTENT_TYPE]
-        end
+        return header(Rack::CONTENT_TYPE, val) if val
+
+        header[Rack::CONTENT_TYPE]
       end
 
       # Allows you to define the response body as something other than the
@@ -128,7 +108,6 @@ module Grape
       #
       #   DELETE /12 # => 204 No Content, ""
       def return_no_content
-        status 204
         body false
       end
 
@@ -141,14 +120,12 @@ module Grape
       #
       #   GET /file # => "contents of file"
       def sendfile(value = nil)
-        if value.is_a?(String)
-          file_body = Grape::ServeStream::FileBody.new(value)
-          @stream = Grape::ServeStream::StreamResponse.new(file_body)
-        elsif !value.is_a?(NilClass)
-          raise ArgumentError, 'Argument must be a file path'
-        else
-          stream
-        end
+        return stream if value.nil?
+
+        raise ArgumentError, 'Argument must be a file path' unless value.is_a?(String)
+
+        file_body = Grape::ServeStream::FileBody.new(value)
+        @stream = Grape::ServeStream::StreamResponse.new(file_body)
       end
 
       # Allows you to define the response as a streamable object.
@@ -172,60 +149,10 @@ module Grape
         header Rack::CONTENT_LENGTH, nil
         header 'Transfer-Encoding', nil
         header Rack::CACHE_CONTROL, 'no-cache' # Skips ETag generation (reading the response up front)
-        if value.is_a?(String)
-          file_body = Grape::ServeStream::FileBody.new(value)
-          @stream = Grape::ServeStream::StreamResponse.new(file_body)
-        elsif value.respond_to?(:each)
-          @stream = Grape::ServeStream::StreamResponse.new(value)
-        elsif !value.is_a?(NilClass)
-          raise ArgumentError, 'Stream object must respond to :each.'
-        else
-          @stream
-        end
-      end
-
-      # Allows you to make use of Grape Entities by setting
-      # the response body to the serializable hash of the
-      # entity provided in the `:with` option. This has the
-      # added benefit of automatically passing along environment
-      # and version information to the serialization, making it
-      # very easy to do conditional exposures. See Entity docs
-      # for more info.
-      #
-      # @example
-      #
-      #   get '/users/:id' do
-      #     present User.find(params[:id]),
-      #       with: API::Entities::User,
-      #       admin: current_user.admin?
-      #   end
-      def present(*args, **options)
-        key, object = if args.count == 2 && args.first.is_a?(Symbol)
-                        args
-                      else
-                        [nil, args.first]
-                      end
-        entity_class = entity_class_for_obj(object, options)
-
-        root = options.delete(:root)
-
-        representation = if entity_class
-                           entity_representation_for(entity_class, object, options)
-                         else
-                           object
-                         end
 
-        representation = { root => representation } if root
+        return @stream if value.nil?
 
-        if key
-          representation = (body || {}).merge(key => representation)
-        elsif entity_class.present? && body
-          raise ArgumentError, "Representation of type #{representation.class} cannot be merged." unless representation.respond_to?(:merge)
-
-          representation = body.merge(representation)
-        end
-
-        body representation
+        @stream = Grape::ServeStream::StreamResponse.new(stream_body(value))
       end
 
       # Returns route information for the current request.
@@ -240,43 +167,6 @@ module Grape
         env[Grape::Env::GRAPE_ROUTING_ARGS][:route_info]
       end
 
-      # Attempt to locate the Entity class for a given object, if not given
-      # explicitly. This is done by looking for the presence of Klass::Entity,
-      # where Klass is the class of the `object` parameter, or one of its
-      # ancestors.
-      # @param object [Object] the object to locate the Entity class for
-      # @param options [Hash]
-      # @option options :with [Class] the explicit entity class to use
-      # @return [Class] the located Entity class, or nil if none is found
-      def entity_class_for_obj(object, options)
-        entity_class = options.delete(:with)
-        return entity_class if entity_class
-
-        # entity class not explicitly defined, auto-detect from relation#klass or first object in the collection
-        object_class = if object.respond_to?(:klass)
-                         object.klass
-                       else
-                         object.respond_to?(:first) ? object.first.class : object.class
-                       end
-
-        representations = inheritable_setting.namespace_stackable_with_hash(:representations)
-        if representations
-          potential = object_class.ancestors.detect { |potential| representations.key?(potential) }
-          entity_class = representations[potential] if potential
-        end
-
-        entity_class = object_class.const_get(:Entity) if !entity_class && object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
-        entity_class
-      end
-
-      # @return the representation of the given object as done through
-      #   the given entity_class.
-      def entity_representation_for(entity_class, object, options)
-        embeds = { env: }
-        embeds[:version] = env[Grape::Env::API_VERSION] if env.key?(Grape::Env::API_VERSION)
-        entity_class.represent(object, **embeds, **options)
-      end
-
       def http_version
         env.fetch('HTTP_VERSION') { env[Rack::SERVER_PROTOCOL] }
       end
@@ -288,6 +178,25 @@ module Grape
       def context
         self
       end
+
+      private
+
+      # Wraps a stream +value+ into a body that responds to +:each+.
+      def stream_body(value)
+        return Grape::ServeStream::FileBody.new(value) if value.is_a?(String)
+
+        raise ArgumentError, 'Stream object must respond to :each.' unless value.respond_to?(:each)
+
+        value
+      end
+
+      # The default HTTP status when none has been set explicitly.
+      def default_status
+        return 201 if request.post?
+        return 204 if request.delete? && @body.blank?
+
+        200
+      end
     end
   end
 end

data/lib/grape/dsl/logger.rb

@@ -8,11 +8,9 @@ module Grape
       # @param logger [Object] the new logger to use
       def logger(logger = nil)
         global_settings = inheritable_setting.global
-        if logger
-          global_settings[:logger] = logger
-        else
-          global_settings[:logger] || global_settings[:logger] = ::Logger.new($stdout)
-        end
+        return global_settings[:logger] = logger if logger
+
+        global_settings[:logger] || global_settings[:logger] = ::Logger.new($stdout)
       end
     end
   end

data/lib/grape/dsl/parameters.rb

@@ -122,23 +122,21 @@ module Grape
       #         requires :name, type: String
       #       end
       #     end
-      def requires(*attrs, **opts, &block)
+      def requires(*attrs, using: nil, except: nil, **opts, &block)
         opts[:presence] = { value: true, message: opts[:message] }
         opts = @group.deep_merge(opts) if @group
 
-        if opts[:using]
-          require_required_and_optional_fields(attrs.first, using: opts[:using], except: opts[:except])
-        else
-          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
+        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, **opts, &block)
+      def optional(*attrs, using: nil, except: nil, **opts, &block)
         type = opts[:type]
         opts = @group.deep_merge(opts) if @group
 
@@ -148,13 +146,10 @@ module Grape
           raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
         end
 
-        if opts[:using]
-          require_optional_fields(attrs.first, using: opts[:using], except: opts[:except])
-        else
-          validate_attributes(attrs, **opts, &block)
+        return require_optional_fields(attrs.first, using:, except:) if using
 
-          block ? new_scope(attrs.first, type: opts[:type], as: opts[:as], optional: true, &block) : push_declared_params(attrs, as: opts[: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
@@ -190,35 +185,19 @@ module Grape
       # 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 # rubocop:disable Lint/EmptyClass
-
-      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
@@ -234,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

@@ -44,13 +44,8 @@ module Grape
         inheritable_setting.namespace_inheritable[:default_error_formatter] = new_formatter
       end
 
-      def error_formatter(format, options)
-        formatter = if options.is_a?(Hash) && options.key?(:with)
-                      options[:with]
-                    else
-                      options
-                    end
-
+      def error_formatter(format, options = nil, with: nil)
+        formatter = with || options
         inheritable_setting.namespace_stackable[:error_formatters] = { format.to_sym => formatter }
       end
 
@@ -84,46 +79,52 @@ module Grape
       #       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
-      #     the symbol :all to rescue from all exceptions.
+      #     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 [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, **options, &block)
-        if args.last.is_a?(Proc)
-          handler = args.pop
-        elsif block
-          handler = block
+      #   @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
 
-        raise ArgumentError, 'both :with option and block cannot be passed' if block && options.key?(:with)
-
-        handler ||= extract_with(options)
-
-        if args.include?(:all)
-          inheritable_setting.namespace_inheritable[:rescue_all] = true
-          inheritable_setting.namespace_inheritable[:all_rescue_handler] = handler
-        elsif args.include?(:grape_exceptions)
-          inheritable_setting.namespace_inheritable[:rescue_all] = true
-          inheritable_setting.namespace_inheritable[:rescue_grape_exceptions] = true
-          inheritable_setting.namespace_inheritable[:grape_exceptions_rescue_handler] = handler
+        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 =
-            case options[:rescue_subclasses]
-            when nil, true
-              :rescue_handlers
-            else
-              :base_only_rescue_handlers
-            end
-
-          inheritable_setting.namespace_reverse_stackable[handler_type] = args.to_h { |arg| [arg, handler] }
+          handler_type = rescue_subclasses ? :rescue_handlers : :base_only_rescue_handlers
+          inheritable_setting.namespace_reverse_stackable[handler_type] = args.to_h { |klass| [klass, handler] }
         end
 
-        inheritable_setting.namespace_stackable[:rescue_options] = options
+        inheritable_setting.namespace_stackable[:rescue_options] = RescueOptions.new(backtrace:, original_exception:)
       end
 
       # Allows you to specify a default representation entity for a
@@ -146,22 +147,26 @@ module Grape
       #
       # @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)
+      def represent(model_class, with:)
+        raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless with.is_a?(Class)
 
-        inheritable_setting.namespace_stackable[:representations] = { model_class => options[:with] }
+        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
   end