grape 1.1.0 → 1.7.1

data/lib/grape/config.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Grape
+  module Config
+    class Configuration
+      ATTRIBUTES = %i[
+        param_builder
+      ].freeze
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize
+        reset
+      end
+
+      def reset
+        self.param_builder = Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder
+      end
+    end
+
+    def self.extended(base)
+      def base.configure
+        block_given? ? yield(config) : config
+      end
+
+      def base.config
+        @configuration ||= Grape::Config::Configuration.new
+      end
+    end
+  end
+end
+
+Grape.extend Grape::Config
+Grape.config.reset

data/lib/grape/content_types.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'grape/util/registrable'
+
+module Grape
+  module ContentTypes
+    extend Util::Registrable
+
+    # Content types are listed in order of preference.
+    CONTENT_TYPES = {
+      xml: 'application/xml',
+      serializable_hash: 'application/json',
+      json: 'application/json',
+      binary: 'application/octet-stream',
+      txt: 'text/plain'
+    }.freeze
+
+    class << self
+      def content_types_for_settings(settings)
+        return if settings.blank?
+
+        settings.each_with_object({}) { |value, result| result.merge!(value) }
+      end
+
+      def content_types_for(from_settings)
+        if from_settings.present?
+          from_settings
+        else
+          Grape::ContentTypes::CONTENT_TYPES.merge(default_elements)
+        end
+      end
+    end
+  end
+end

data/lib/grape/cookies.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Cookies
     def initialize
@@ -31,9 +33,11 @@ module Grape
       @cookies.each(&block)
     end
 
+    # rubocop:disable Layout/SpaceBeforeBrackets
     def delete(name, **opts)
       options = opts.merge(value: 'deleted', expires: Time.at(0))
       self.[]=(name, options)
     end
+    # rubocop:enable Layout/SpaceBeforeBrackets
   end
 end

data/lib/grape/dry_types.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'dry-types'
+
+module Grape
+  module DryTypes
+    # Call +Dry.Types()+ to add all registered types to +DryTypes+ which is
+    # a container in this case. Check documentation for more information
+    # https://dry-rb.org/gems/dry-types/1.2/getting-started/
+    include Dry.Types()
+  end
+end

data/lib/grape/dsl/api.rb

@@ -1,4 +1,4 @@
-require 'active_support/concern'
+# frozen_string_literal: true
 
 module Grape
   module DSL

data/lib/grape/dsl/callbacks.rb

@@ -1,4 +1,4 @@
-require 'active_support/concern'
+# frozen_string_literal: true
 
 module Grape
   module DSL
@@ -43,6 +43,26 @@ module Grape
         def after(&block)
           namespace_stackable(:afters, block)
         end
+
+        # Allows you to specify a something that will always be executed after a call
+        # API call. Unlike the `after` block, this code will run even on
+        # unsuccesful requests.
+        # @example
+        #   class ExampleAPI < Grape::API
+        #     before do
+        #       ApiLogger.start
+        #     end
+        #     finally do
+        #       ApiLogger.close
+        #     end
+        #   end
+        #
+        # This will make sure that the ApiLogger is opened and closed around every
+        # request
+        # @param  ensured_block [Proc] The block to be executed after every api_call
+        def finally(&block)
+          namespace_stackable(:finallies, block)
+        end
       end
     end
   end

data/lib/grape/dsl/configuration.rb

@@ -1,4 +1,4 @@
-require 'active_support/concern'
+# frozen_string_literal: true
 
 module Grape
   module DSL

data/lib/grape/dsl/desc.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   module DSL
     module Desc
@@ -9,6 +11,7 @@ module Grape
       # @param options [Hash] other properties you can set to describe the
       #   endpoint or namespace. Optional.
       # @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
       #   these via the `params` dsl method.
       # @option options :entity [Grape::Entity] the entity returned upon a
@@ -16,7 +19,16 @@ module Grape
       # @option options :http_codes [Array[Array]] possible HTTP codes this
       #   endpoint may return, with their meanings, in a 2d array
       # @option options :named [String] a specific name to help find this route
+      # @option options :body_name [String] override the autogenerated body name param
       # @option options :headers [Hash] HTTP headers this method can accept
+      # @option options :hidden [Boolean] hide the endpoint or not
+      # @option options :deprecated [Boolean] deprecate the endpoint or not
+      # @option options :is_array [Boolean] response entity is array or not
+      # @option options :nickname [String] nickname of the endpoint
+      # @option options :produces [Array[String]] a list of MIME types the endpoint produce
+      # @option options :consumes [Array[String]] a list of MIME types the endpoint consume
+      # @option options :security [Array[Hash]] a list of security schemes
+      # @option options :tags [Array[String]] a list of tags
       # @yield a block yielding an instance context with methods mapping to
       #   each of the above, except that :entity is also aliased as #success
       #   and :http_codes is aliased as #failure.
@@ -38,17 +50,25 @@ module Grape
       #     end
       #
       def desc(description, options = {}, &config_block)
-        if block_given?
-          config_class = desc_container
+        if config_block
+          endpoint_configuration = if defined?(configuration)
+                                     # When the instance is mounted - the configuration is executed on mount time
+                                     if configuration.respond_to?(:evaluate)
+                                       configuration.evaluate
+                                     # Within `given` or `mounted blocks` the configuration is already evaluated
+                                     elsif configuration.is_a?(Hash)
+                                       configuration
+                                     end
+                                   end
+          endpoint_configuration ||= {}
+          config_class = desc_container(endpoint_configuration)
 
           config_class.configure do
             description description
           end
 
           config_class.configure(&config_block)
-          unless options.empty?
-            warn '[DEPRECATION] Passing a options hash and a block to `desc` is deprecated. Move all hash options to block.'
-          end
+          warn '[DEPRECATION] Passing a options hash and a block to `desc` is deprecated. Move all hash options to block.' unless options.empty?
           options = config_class.settings
         else
           options = options.merge(description: description)
@@ -58,34 +78,32 @@ module Grape
         route_setting :description, options
       end
 
-      def description_field(field, value = nil)
-        if value
-          description = route_setting(:description)
-          description ||= route_setting(:description, {})
-          description[field] = value
-        else
-          description = route_setting(:description)
-          description[field] if description
-        end
-      end
-
-      def unset_description_field(field)
-        description = route_setting(:description)
-        description.delete(field) if description
-      end
-
       # Returns an object which configures itself via an instance-context DSL.
-      def desc_container
+      def desc_container(endpoint_configuration)
         Module.new do
           include Grape::Util::StrictHashConfiguration.module(
+            :summary,
             :description,
             :detail,
             :params,
             :entity,
             :http_codes,
             :named,
-            :headers
+            :body_name,
+            :headers,
+            :hidden,
+            :deprecated,
+            :is_array,
+            :nickname,
+            :produces,
+            :consumes,
+            :security,
+            :tags,
+            :default
           )
+          config_context.define_singleton_method(:configuration) do
+            endpoint_configuration
+          end
 
           def config_context.success(*args)
             entity(*args)

data/lib/grape/dsl/headers.rb

@@ -1,8 +1,13 @@
+# frozen_string_literal: true
+
 module Grape
   module DSL
     module Headers
-      # Set an individual header or retrieve
-      # all headers that have been set.
+      # This method has four responsibilities:
+      # 1. Set a specifc header value by key
+      # 2. Retrieve a specifc header value by key
+      # 3. Retrieve all headers that have been set
+      # 4. Delete a specifc header key-value pair
       def header(key = nil, val = nil)
         if key
           val ? header[key.to_s] = val : header.delete(key.to_s)

data/lib/grape/dsl/helpers.rb

@@ -1,4 +1,4 @@
-require 'active_support/concern'
+# frozen_string_literal: true
 
 module Grape
   module DSL
@@ -34,8 +34,8 @@ module Grape
         #
         def helpers(*new_modules, &block)
           include_new_modules(new_modules) if new_modules.any?
-          include_block(block) if block_given?
-          include_all_in_scope if !block_given? && new_modules.empty?
+          include_block(block) if block
+          include_all_in_scope if !block && new_modules.empty?
         end
 
         protected
@@ -65,12 +65,13 @@ module Grape
 
         def define_boolean_in_mod(mod)
           return if defined? mod::Boolean
-          mod.const_set('Boolean', Virtus::Attribute::Boolean)
+
+          mod.const_set(:Boolean, Grape::API::Boolean)
         end
 
-        def inject_api_helpers_to_mod(mod, &_block)
+        def inject_api_helpers_to_mod(mod, &block)
           mod.extend(BaseHelper) unless mod.is_a?(BaseHelper)
-          yield if block_given?
+          yield if block
           mod.api_changed(self)
         end
       end
@@ -79,6 +80,7 @@ module Grape
       # to provide some API-specific functionality.
       module BaseHelper
         attr_accessor :api
+
         def params(name, &block)
           @named_params ||= {}
           @named_params[name] = block
@@ -92,7 +94,8 @@ module Grape
         protected
 
         def process_named_params
-          return unless @named_params && @named_params.any?
+          return unless instance_variable_defined?(:@named_params) && @named_params && @named_params.any?
+
           api.namespace_stackable(:named_params, @named_params)
         end
       end

data/lib/grape/dsl/inside_route.rb

@@ -1,4 +1,5 @@
-require 'active_support/concern'
+# frozen_string_literal: true
+
 require 'grape/dsl/headers'
 
 module Grape
@@ -26,85 +27,106 @@ module Grape
       # Methods which should not be available in filters until the before filter
       # has completed
       module PostBeforeFilter
-        def declared(passed_params, options = {}, declared_params = nil)
-          options = options.reverse_merge(include_missing: true, include_parent_namespaces: true)
-          declared_params ||= optioned_declared_params(options)
+        def declared(passed_params, options = {}, declared_params = nil, params_nested_path = [])
+          options = options.reverse_merge(include_missing: true, include_parent_namespaces: true, evaluate_given: false)
+          declared_params ||= optioned_declared_params(**options)
 
           if passed_params.is_a?(Array)
-            declared_array(passed_params, options, declared_params)
+            declared_array(passed_params, options, declared_params, params_nested_path)
           else
-            declared_hash(passed_params, options, declared_params)
+            declared_hash(passed_params, options, declared_params, params_nested_path)
           end
         end
 
         private
 
-        def declared_array(passed_params, options, declared_params)
+        def declared_array(passed_params, options, declared_params, params_nested_path)
           passed_params.map do |passed_param|
-            declared(passed_param || {}, options, declared_params)
+            declared(passed_param || {}, options, declared_params, params_nested_path)
           end
         end
 
-        def declared_hash(passed_params, options, declared_params)
-          declared_params.each_with_object(passed_params.class.new) do |declared_param, memo|
-            if declared_param.is_a?(Hash)
-              declared_param.each_pair do |declared_parent_param, declared_children_params|
-                next unless options[:include_missing] || passed_params.key?(declared_parent_param)
+        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)
 
-                passed_children_params = passed_params[declared_parent_param] || passed_params.class.new
-                memo_key = optioned_param_key(declared_parent_param, options)
+            declared_hash_attr(passed_params, options, declared_param_attr.key, params_nested_path, memo)
+          end
+        end
 
-                memo[memo_key] = handle_passed_param(declared_parent_param, passed_children_params) do
-                  declared(passed_children_params, options, declared_children_params)
-                end
-              end
-            else
-              # If it is not a Hash then it does not have children.
-              # Find its value or set it to nil.
-              has_alias = route_setting(:aliased_params) && route_setting(:aliased_params).find { |current| current[declared_param] }
-              param_alias = has_alias[declared_param] if has_alias
+        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)
 
-              next unless options[:include_missing] || passed_params.key?(declared_param) || (param_alias && passed_params.key?(param_alias))
+              rename_path = params_nested_path + [declared_parent_param.to_s]
+              renamed_param_name = renamed_params[rename_path]
 
-              if param_alias
-                memo[optioned_param_key(param_alias, options)] = passed_params[param_alias]
-              else
-                memo[optioned_param_key(declared_param, options)] = passed_params[declared_param]
+              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.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(declared_param, passed_children_params, &_block)
-          should_be_empty_array?(declared_param, passed_children_params) ? [] : yield
-        end
+        def handle_passed_param(params_nested_path, has_passed_children = false, &_block)
+          return yield if has_passed_children
 
-        def should_be_empty_array?(declared_param, passed_children_params)
-          declared_param_is_array?(declared_param) && passed_children_params.empty?
-        end
+          key = params_nested_path[0]
+          key += "[#{params_nested_path[1..].join('][')}]" if params_nested_path.size > 1
 
-        def declared_param_is_array?(declared_param)
-          route_options_params[declared_param.to_s] && route_options_params[declared_param.to_s][:type] == 'Array'
-        end
+          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) }
 
-        def route_options_params
-          options[:route_options][:params] || {}
+          if type == 'Hash' && !has_children
+            {}
+          elsif type == 'Array' || (type&.start_with?('[') && !type&.include?(','))
+            []
+          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(options)
+        def optioned_declared_params(**options)
           declared_params = if options[:include_parent_namespaces]
                               # Declared params including parent namespaces
-                              route_setting(:saved_declared_params).flatten | Array(route_setting(:declared_params))
+                              route_setting(:declared_params)
                             else
                               # Declared params at current namespace
-                              route_setting(:saved_declared_params).last & Array(route_setting(:declared_params))
+                              namespace_stackable(:declared_params).last || []
                             end
 
           raise ArgumentError, 'Tried to filter for declared parameters but none exist.' unless declared_params
+
           declared_params
         end
       end
@@ -129,13 +151,19 @@ module Grape
         env[Grape::Env::API_VERSION]
       end
 
+      def configuration
+        options[:for].configuration.evaluate
+      end
+
       # End the request and display an error to the
       # end user with the specified message.
       #
       # @param message [String] The message to display.
       # @param status [Integer] the HTTP Status Code. Defaults to default_error_status, 500 if not set.
-      def error!(message, status = nil, headers = nil)
+      # @param additional_headers [Hash] Addtional headers for the response.
+      def error!(message, status = nil, additional_headers = nil)
         self.status(status || namespace_inheritable(:default_error_status))
+        headers = additional_headers.present? ? header.merge(additional_headers) : header
         throw :error, message: message, status: self.status, headers: headers
       end
 
@@ -168,17 +196,19 @@ module Grape
       def status(status = nil)
         case status
         when Symbol
-          raise ArgumentError, "Status code :#{status} is invalid." unless Rack::Utils::SYMBOL_TO_STATUS_CODE.keys.include?(status)
+          raise ArgumentError, "Status code :#{status} is invalid." unless Rack::Utils::SYMBOL_TO_STATUS_CODE.key?(status)
+
           @status = Rack::Utils.status_code(status)
         when Integer
           @status = status
         when nil
-          return @status if @status
+          return @status if instance_variable_defined?(:@status) && @status
+
           case request.request_method.to_s.upcase
           when Grape::Http::Headers::POST
             201
           when Grape::Http::Headers::DELETE
-            if @body.present?
+            if instance_variable_defined?(:@body) && @body.present?
               200
             else
               204
@@ -229,7 +259,7 @@ module Grape
           @body = ''
           status 204
         else
-          @body
+          instance_variable_defined?(:@body) ? @body : nil
         end
       end
 
@@ -247,23 +277,36 @@ module Grape
         body false
       end
 
-      # Allows you to define the response as a file-like object.
+      # Deprecated method to send files to the client. Use `sendfile` or `stream`
+      def file(value = nil)
+        if value.is_a?(String)
+          warn '[DEPRECATION] Use sendfile or stream to send files.'
+          sendfile(value)
+        elsif !value.is_a?(NilClass)
+          warn '[DEPRECATION] Use stream to use a Stream object.'
+          stream(value)
+        else
+          warn '[DEPRECATION] Use sendfile or stream to send files.'
+          sendfile
+        end
+      end
+
+      # Allows you to send a file to the client via sendfile.
       #
       # @example
       #   get '/file' do
-      #     file FileStreamer.new(...)
+      #     sendfile FileStreamer.new(...)
       #   end
       #
       #   GET /file # => "contents of file"
-      def file(value = nil)
+      def sendfile(value = nil)
         if value.is_a?(String)
-          file_body = Grape::ServeFile::FileBody.new(value)
-          @file = Grape::ServeFile::FileResponse.new(file_body)
+          file_body = Grape::ServeStream::FileBody.new(value)
+          @stream = Grape::ServeStream::StreamResponse.new(file_body)
         elsif !value.is_a?(NilClass)
-          warn '[DEPRECATION] Argument as FileStreamer-like object is deprecated. Use path to file instead.'
-          @file = Grape::ServeFile::FileResponse.new(value)
+          raise ArgumentError, 'Argument must be a file path'
         else
-          @file
+          stream
         end
       end
 
@@ -283,10 +326,21 @@ module Grape
       # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/chunked.rb
       # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/etag.rb
       def stream(value = nil)
+        return if value.nil? && @stream.nil?
+
         header 'Content-Length', nil
         header 'Transfer-Encoding', nil
         header 'Cache-Control', 'no-cache' # Skips ETag generation (reading the response up front)
-        file(value)
+        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
@@ -322,11 +376,13 @@ module Grape
                          end
 
         representation = { root => representation } if root
+
         if key
-          representation = (@body || {}).merge(key => representation)
-        elsif entity_class.present? && @body
+          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)
+
+          representation = body.merge(representation)
         end
 
         body representation
@@ -356,7 +412,7 @@ module Grape
         entity_class = options.delete(:with)
 
         if entity_class.nil?
-          # entity class not explicitely defined, auto-detect from relation#klass or first object in the collection
+          # 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
@@ -378,7 +434,7 @@ module Grape
       def entity_representation_for(entity_class, object, options)
         embeds = { env: env }
         embeds[:version] = env[Grape::Env::API_VERSION] if env[Grape::Env::API_VERSION]
-        entity_class.represent(object, embeds.merge(options))
+        entity_class.represent(object, **embeds.merge(options))
       end
     end
   end

data/lib/grape/dsl/logger.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   module DSL
     module Logger