grape 2.4.0 → 4.0.1

data/lib/grape/dsl/helpers.rb

@@ -3,80 +3,95 @@
 module Grape
   module DSL
     module Helpers
-      extend ActiveSupport::Concern
-      include Grape::DSL::Configuration
-
-      module ClassMethods
-        # Add helper methods that will be accessible from any
-        # endpoint within this namespace (and child namespaces).
-        #
-        # When called without a block, all known helpers within this scope
-        # are included.
-        #
-        # @param [Array] new_modules optional array of modules to include
-        # @param [Block] block optional block of methods to include
-        #
-        # @example Define some helpers.
-        #
-        #     class ExampleAPI < Grape::API
-        #       helpers do
-        #         def current_user
-        #           User.find_by_id(params[:token])
-        #         end
-        #       end
-        #     end
-        #
-        # @example Include many modules
-        #
-        #     class ExampleAPI < Grape::API
-        #       helpers Authentication, Mailer, OtherModule
-        #     end
-        #
-        def helpers(*new_modules, &block)
-          include_new_modules(new_modules)
-          include_block(block)
-          include_all_in_scope if !block && new_modules.empty?
-        end
+      # Add helper methods that will be accessible from any
+      # endpoint within this namespace (and child namespaces).
+      #
+      # When called without a block, all known helpers within this scope
+      # are included.
+      #
+      # @param [Array] new_modules optional array of modules to include
+      # @param [Block] block optional block of methods to include
+      #
+      # @example Define some helpers.
+      #
+      #     class ExampleAPI < Grape::API
+      #       helpers do
+      #         def current_user
+      #           User.find_by_id(params[:token])
+      #         end
+      #       end
+      #     end
+      #
+      # @example Include many modules
+      #
+      #     class ExampleAPI < Grape::API
+      #       helpers Authentication, Mailer, OtherModule
+      #     end
+      #
+      def helpers(*new_modules, &block)
+        include_new_modules(new_modules)
+        include_block(block)
+        include_all_in_scope if !block && new_modules.empty?
+      end
 
-        protected
+      private
 
-        def include_new_modules(modules)
-          return if modules.empty?
+      def include_new_modules(modules)
+        return if modules.empty?
 
-          modules.each { |mod| make_inclusion(mod) }
-        end
+        modules.each { |mod| make_inclusion(mod) }
+      end
 
-        def include_block(block)
-          return unless block
+      def include_block(block)
+        return unless block
 
-          Module.new.tap do |mod|
-            make_inclusion(mod) { mod.class_eval(&block) }
-          end
-        end
+        mod = Module.new
+        make_inclusion(mod) { mod.class_eval(&block) }
+      end
 
-        def make_inclusion(mod, &block)
-          define_boolean_in_mod(mod)
-          inject_api_helpers_to_mod(mod, &block)
-          namespace_stackable(:helpers, mod)
-        end
+      def make_inclusion(mod, &)
+        define_boolean_in_mod(mod)
+        inject_api_helpers_to_mod(mod, &)
+        inheritable_setting.add_helper(mod)
+      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
-        end
+      def include_all_in_scope
+        mod = Module.new
+        inheritable_setting.helpers.each { |mod_to_include| mod.include mod_to_include }
+        change!
+        mod
+      end
 
-        def define_boolean_in_mod(mod)
-          return if defined? mod::Boolean
+      def define_boolean_in_mod(mod)
+        return if defined? mod::Boolean
 
-          mod.const_set(:Boolean, Grape::API::Boolean)
-        end
+        mod.const_set(:Boolean, Grape::API::Boolean)
+      end
+
+      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
 
-        def inject_api_helpers_to_mod(mod, &block)
-          mod.extend(BaseHelper) unless mod.is_a?(BaseHelper)
-          yield if block
-          mod.api_changed(self)
+      # 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
 
@@ -100,7 +115,7 @@ module Grape
         def process_named_params
           return if @named_params.blank?
 
-          api.namespace_stackable(:named_params, @named_params)
+          api.inheritable_setting.add_named_params(@named_params)
         end
       end
     end

data/lib/grape/dsl/inside_route.rb

@@ -3,152 +3,11 @@
 module Grape
   module DSL
     module InsideRoute
-      extend ActiveSupport::Concern
-      include Grape::DSL::Settings
-      include Grape::DSL::Headers
+      include Declared
+      include Entity
 
-      # Denotes a situation where a DSL method has been invoked in a
-      # filter which it should not yet be available in
-      class MethodNotYetAvailable < StandardError; end
-
-      # @param type [Symbol] The type of filter for which evaluation has been
-      #   completed
-      # @return [Module] A module containing method overrides suitable for the
-      #   position in the filter evaluation sequence denoted by +type+.  This
-      #   defaults to an empty module if no overrides are defined for the given
-      #   filter +type+.
-      def self.post_filter_methods(type)
-        @post_filter_modules ||= { before: PostBeforeFilter }
-        @post_filter_modules[type]
-      end
-
-      # Methods which should not be available in filters until the before filter
-      # has completed
-      module PostBeforeFilter
-        def declared(passed_params, options = {}, declared_params = nil, params_nested_path = [])
-          options.reverse_merge!(include_missing: true, include_parent_namespaces: true, evaluate_given: false)
-          declared_params ||= optioned_declared_params(options[:include_parent_namespaces])
-
-          res = if passed_params.is_a?(Array)
-                  declared_array(passed_params, options, declared_params, params_nested_path)
-                else
-                  declared_hash(passed_params, options, declared_params, params_nested_path)
-                end
-
-          if (key_maps = namespace_stackable(:contract_key_map))
-            key_maps.each { |key_map| key_map.write(passed_params, res) }
-          end
-
-          res
-        end
-
-        private
-
-        def declared_array(passed_params, options, declared_params, params_nested_path)
-          passed_params.map do |passed_param|
-            declared(passed_param || {}, options, declared_params, params_nested_path)
-          end
-        end
-
-        def declared_hash(passed_params, options, declared_params, params_nested_path)
-          declared_params.each_with_object(passed_params.class.new) do |declared_param_attr, memo|
-            next if options[:evaluate_given] && !declared_param_attr.scope.attr_meets_dependency?(passed_params)
-
-            declared_hash_attr(passed_params, options, declared_param_attr.key, params_nested_path, memo)
-          end
-        end
-
-        def declared_hash_attr(passed_params, options, declared_param, params_nested_path, memo)
-          renamed_params = route_setting(:renamed_params) || {}
-          if declared_param.is_a?(Hash)
-            declared_param.each_pair do |declared_parent_param, declared_children_params|
-              params_nested_path_dup = params_nested_path.dup
-              params_nested_path_dup << declared_parent_param.to_s
-              next unless options[:include_missing] || passed_params.key?(declared_parent_param)
-
-              rename_path = params_nested_path + [declared_parent_param.to_s]
-              renamed_param_name = renamed_params[rename_path]
-
-              memo_key = optioned_param_key(renamed_param_name || declared_parent_param, options)
-              passed_children_params = passed_params[declared_parent_param] || passed_params.class.new
-
-              memo[memo_key] = handle_passed_param(params_nested_path_dup, passed_children_params.any?) do
-                declared(passed_children_params, options, declared_children_params, params_nested_path_dup)
-              end
-            end
-          else
-            # If it is not a Hash then it does not have children.
-            # Find its value or set it to nil.
-            return unless options[:include_missing] || passed_params.try(:key?, declared_param)
-
-            rename_path = params_nested_path + [declared_param.to_s]
-            renamed_param_name = renamed_params[rename_path]
-
-            memo_key = optioned_param_key(renamed_param_name || declared_param, options)
-            passed_param = passed_params[declared_param]
-
-            params_nested_path_dup = params_nested_path.dup
-            params_nested_path_dup << declared_param.to_s
-            memo[memo_key] = passed_param || handle_passed_param(params_nested_path_dup) do
-              passed_param
-            end
-          end
-        end
-
-        def handle_passed_param(params_nested_path, has_passed_children = false, &_block)
-          return yield if has_passed_children
-
-          key = params_nested_path[0]
-          key += "[#{params_nested_path[1..].join('][')}]" if params_nested_path.size > 1
-
-          route_options_params = options[:route_options][:params] || {}
-          type = route_options_params.dig(key, :type)
-          has_children = route_options_params.keys.any? { |k| k != key && k.start_with?("#{key}[") }
-
-          if type == 'Hash' && !has_children
-            {}
-          elsif type == 'Array' || (type&.start_with?('[') && type.exclude?(','))
-            []
-          elsif type == 'Set' || type&.start_with?('#<Set')
-            Set.new
-          else
-            yield
-          end
-        end
-
-        def optioned_param_key(declared_param, options)
-          options[:stringify] ? declared_param.to_s : declared_param.to_sym
-        end
-
-        def optioned_declared_params(include_parent_namespaces)
-          declared_params = if include_parent_namespaces
-                              # Declared params including parent namespaces
-                              route_setting(:declared_params)
-                            else
-                              # Declared params at current namespace
-                              namespace_stackable(:declared_params).last || []
-                            end
-
-          raise ArgumentError, 'Tried to filter for declared parameters but none exist.' unless declared_params
-
-          declared_params
-        end
-      end
-
-      # A filtering method that will return a hash
-      # consisting only of keys that have been declared by a
-      # `params` statement against the current/target endpoint or parent
-      # namespaces.
-      #
-      # @see +PostBeforeFilter#declared+
-      #
-      # @param params [Hash] The initial hash to filter. Usually this will just be `params`
-      # @param options [Hash] Can pass `:include_missing`, `:stringify` and `:include_parent_namespaces`
-      # options. `:include_parent_namespaces` defaults to true, hence must be set to false if
-      # you want only to return params declared against the current/target endpoint.
-      def declared(*)
-        raise MethodNotYetAvailable, '#declared is not available prior to parameter validation.'
-      end
+      # Backward compatibility: alias exception class to previous location
+      MethodNotYetAvailable = Declared::MethodNotYetAvailable
 
       # The API version as specified in the URL.
       def version
@@ -156,7 +15,7 @@ module Grape
       end
 
       def configuration
-        options[:for].configuration.evaluate
+        config.api.configuration.evaluate
       end
 
       # End the request and display an error to the
@@ -168,32 +27,11 @@ module Grape
       # @param backtrace [Array<String>] The backtrace of the exception that caused the error.
       # @param original_exception [Exception] The original exception that caused the error.
       def error!(message, status = nil, additional_headers = nil, backtrace = nil, original_exception = nil)
-        status = self.status(status || namespace_inheritable(:default_error_status))
+        resolved_status = self.status(status || inheritable_setting.default_error_status)
         headers = additional_headers.present? ? header.merge(additional_headers) : header
-        throw :error,
-              message: message,
-              status: status,
-              headers: headers,
-              backtrace: backtrace,
-              original_exception: original_exception
-      end
-
-      # Creates a Rack response based on the provided message, status, and headers.
-      # The content type in the headers is set to the default content type unless provided.
-      # The message is HTML-escaped if the content type is 'text/html'.
-      #
-      # @param message [String] The content of the response.
-      # @param status [Integer] The HTTP status code.
-      # @params headers [Hash] (optional) Headers for the response
-      #                      (default: {Rack::CONTENT_TYPE => content_type}).
-      #
-      # Returns:
-      # A Rack::Response object containing the specified message, status, and headers.
-      #
-      def rack_response(message, status = 200, headers = { Rack::CONTENT_TYPE => content_type })
-        Grape.deprecator.warn('The rack_response method has been deprecated, use error! instead.')
-        message = Rack::Utils.escape_html(message) if headers[Rack::CONTENT_TYPE] == 'text/html'
-        Rack::Response.new(Array.wrap(message), Rack::Utils.status_code(status), headers)
+        throw :error, Grape::Exceptions::ErrorResponse.new(
+          message:, status: resolved_status, headers:, backtrace:, original_exception:
+        )
       end
 
       # Redirect to a new url.
@@ -215,6 +53,12 @@ module Grape
         end
         header 'Location', url
         content_type 'text/plain'
+        # Render the message Grape generated as the plain text it is. Setting
+        # only the header left it to the API's own formatter, which on a JSON
+        # API returned the sentence wrapped in quotes under a text/plain content
+        # type. A caller-supplied body keeps the API's format: it may be
+        # structured, and the txt formatter would render a Hash through `to_s`.
+        api_format :txt unless body
         body body_message
       end
 
@@ -222,39 +66,21 @@ 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 instance_variable_defined?(:@status) && @status
-
-          if request.post?
-            201
-          elsif request.delete?
-            if instance_variable_defined?(:@body) && @body.present?
-              200
-            else
-              204
-            end
-          else
-            200
-          end
         else
-          raise ArgumentError, 'Status code must be Integer or Symbol.'
+          raise ArgumentError, 'status code must be Integer or Symbol'
         end
       end
 
       # 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
@@ -274,7 +100,7 @@ module Grape
           @body = ''
           status 204
         else
-          instance_variable_defined?(:@body) ? @body : nil
+          @body
         end
       end
 
@@ -288,7 +114,6 @@ module Grape
       #
       #   DELETE /12 # => 204 No Content, ""
       def return_no_content
-        status 204
         body false
       end
 
@@ -301,14 +126,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.
@@ -332,61 +155,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 = args.count > 1 ? args.extract_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.
@@ -401,43 +173,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)
-
-        if entity_class.nil?
-          # 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
-
-          object_class.ancestors.each do |potential|
-            entity_class ||= (namespace_stackable_with_hash(:representations) || {})[potential]
-          end
-
-          entity_class ||= object_class.const_get(:Entity) if object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
-        end
-
-        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: 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
@@ -449,6 +184,31 @@ 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.
+      # Reads the request method once instead of asking through +post?+ and
+      # +delete?+, each of which reads it again. Every response that did not set
+      # a status of its own comes through here, so it is read straight off the
+      # env: +Grape::Request+ wraps the very same Hash and answers
+      # +request_method+ with the same lookup, two method calls further down.
+      def default_status
+        request_method = env[Rack::REQUEST_METHOD]
+        return 201 if request_method == Rack::POST
+        return 204 if request_method == Rack::DELETE && @body.blank?
+
+        200
+      end
     end
   end
 end

data/lib/grape/dsl/logger.rb

@@ -3,19 +3,14 @@
 module Grape
   module DSL
     module Logger
-      include Grape::DSL::Settings
-
-      attr_writer :logger
-
       # Set or retrive the configured logger. If none was configured, this
       # method will create a new one, logging to stdout.
       # @param logger [Object] the new logger to use
       def logger(logger = nil)
-        if logger
-          global_setting(:logger, logger)
-        else
-          global_setting(:logger) || global_setting(:logger, ::Logger.new($stdout))
-        end
+        global_settings = inheritable_setting.global
+        return global_settings[:logger] = logger if logger
+
+        global_settings[:logger] || global_settings[:logger] = ::Logger.new($stdout)
       end
     end
   end