grape 0.12.0 → 0.13.0

data/lib/grape/middleware/formatter.rb

@@ -11,13 +11,6 @@ module Grape
         }
       end
 
-      def headers
-        env.dup.inject({}) do |h, (k, v)|
-          h[k.to_s.downcase[5..-1]] = v if k.to_s.downcase.start_with?('http_')
-          h
-        end
-      end
-
       def before
         negotiate_content_type
         read_body_input
@@ -25,26 +18,49 @@ module Grape
 
       def after
         status, headers, bodies = *@app_response
-        # allow content-type to be explicitly overwritten
-        api_format = mime_types[headers[Grape::Http::Headers::CONTENT_TYPE]] || env['api.format']
-        formatter = Grape::Formatter::Base.formatter_for api_format, options
-        begin
-          bodymap = if bodies.respond_to?(:collect)
-                      bodies.collect do |body|
-                        formatter.call body, env
-                      end
-                    else
-                      bodies
-                    end
-        rescue Grape::Exceptions::InvalidFormatter => e
-          throw :error, status: 500, message: e.message
+
+        if bodies.is_a?(Grape::Util::FileResponse)
+          headers = ensure_content_type(headers)
+
+          response =
+            Rack::Response.new([], status, headers) do |resp|
+              resp.body = bodies.file
+            end
+        else
+          # Allow content-type to be explicitly overwritten
+          api_format = mime_types[headers[Grape::Http::Headers::CONTENT_TYPE]] || env['api.format']
+          formatter = Grape::Formatter::Base.formatter_for(api_format, options)
+
+          begin
+            bodymap = bodies.collect do |body|
+              formatter.call(body, env)
+            end
+
+            headers = ensure_content_type(headers)
+
+            response = Rack::Response.new(bodymap, status, headers)
+          rescue Grape::Exceptions::InvalidFormatter => e
+            throw :error, status: 500, message: e.message
+          end
         end
-        headers[Grape::Http::Headers::CONTENT_TYPE] = content_type_for(env['api.format']) unless headers[Grape::Http::Headers::CONTENT_TYPE]
-        Rack::Response.new(bodymap, status, headers)
+
+        response
       end
 
       private
 
+      # Set the content type header for the API format if it is not already present.
+      #
+      # @param headers [Hash]
+      # @return [Hash]
+      def ensure_content_type(headers)
+        if headers[Grape::Http::Headers::CONTENT_TYPE]
+          headers
+        else
+          headers.merge(Grape::Http::Headers::CONTENT_TYPE => content_type_for(env['api.format']))
+        end
+      end
+
       def request
         @request ||= Rack::Request.new(env)
       end
@@ -133,7 +149,7 @@ module Grape
       end
 
       def mime_array
-        accept = headers[Grape::Http::Headers::ACCEPT]
+        accept = env[Grape::Http::Headers::HTTP_ACCEPT]
         return [] unless accept
 
         accept_into_mime_and_quality = %r{

data/lib/grape/namespace.rb

@@ -1,22 +1,33 @@
 module Grape
+  # A container for endpoints or other namespaces, which allows for both
+  # logical grouping of endpoints as well as sharing commonconfiguration.
+  # May also be referred to as group, segment, or resource.
   class Namespace
     attr_reader :space, :options
 
-    # options:
-    #   requirements: a hash
+    # @param space [String] the name of this namespace
+    # @param options [Hash] options hash
+    # @option options :requirements [Hash] param-regex pairs, all of which must
+    #   be met by a request's params for all endpoints in this namespace, or
+    #   validation will fail and return a 422.
     def initialize(space, options = {})
       @space = space.to_s
       @options = options
     end
 
+    # Retrieves the requirements from the options hash, if given.
+    # @return [Hash]
     def requirements
       options[:requirements] || {}
     end
 
+    # (see ::joined_space_path)
     def self.joined_space(settings)
       (settings || []).map(&:space).join('/')
     end
 
+    # Join the namespaces from a list of settings to create a path prefix.
+    # @param settings [Array] list of Grape::Util::InheritableSettings.
     def self.joined_space_path(settings)
       Rack::Mount::Utils.normalize_path(joined_space(settings))
     end

data/lib/grape/path.rb

@@ -1,4 +1,5 @@
 module Grape
+  # Represents a path to an endpoint.
   class Path
     def self.prepare(raw_path, namespace, settings)
       Path.new(raw_path, namespace, settings).path_with_suffix

data/lib/grape/route.rb

@@ -1,10 +1,12 @@
 module Grape
   # A compiled route for inspection.
   class Route
+    # @api private
     def initialize(options = {})
       @options = options || {}
     end
 
+    # @api private
     def method_missing(method_id, *arguments)
       match = /route_([_a-zA-Z]\w*)/.match(method_id.to_s)
       if match
@@ -14,12 +16,15 @@ module Grape
       end
     end
 
+    # Generate a short, human-readable representation of this route.
     def to_s
       "version=#{route_version}, method=#{route_method}, path=#{route_path}"
     end
 
     private
 
+    # This is defined so that certain Ruby methods which attempt to call #to_ary
+    # on objects, e.g. Array#join, will not hit #method_missing.
     def to_ary
       nil
     end

data/lib/grape/util/file_response.rb

@@ -0,0 +1,21 @@
+module Grape
+  module Util
+    # A simple class used to identify responses which represent files and do not
+    # need to be formatted or pre-read by Rack::Response
+    class FileResponse
+      attr_reader :file
+
+      # @param file [Object]
+      def initialize(file)
+        @file = file
+      end
+
+      # Equality provided mostly for tests.
+      #
+      # @return [Boolean]
+      def ==(other)
+        file == other.file
+      end
+    end
+  end
+end

data/lib/grape/util/inheritable_setting.rb

@@ -1,22 +1,31 @@
 module Grape
   module Util
+    # A branchable, inheritable settings object which can store both stackable
+    # and inheritable values (see InheritableValues and StackableValues).
     class InheritableSetting
       attr_accessor :route, :api_class, :namespace, :namespace_inheritable, :namespace_stackable
       attr_accessor :parent, :point_in_time_copies
 
+      # Retrieve global settings.
       def self.global
         @global ||= {}
       end
 
-      def self.reset_global! # only for testing
+      # Clear all global settings.
+      # @api private
+      # @note only for testing
+      def self.reset_global!
         @global = {}
       end
 
+      # Instantiate a new settings instance, with blank values. The fresh
+      # instance can then be set to inherit from an existing instance (see
+      # #inherit_from).
       def initialize
         self.route = {}
         self.api_class = {}
         self.namespace = InheritableValues.new # only inheritable from a parent when
-        # used with a mount, or should every API::Class be a seperate namespace by default?
+        # used with a mount, or should every API::Class be a separate namespace by default?
         self.namespace_inheritable = InheritableValues.new
         self.namespace_stackable = StackableValues.new
 
@@ -25,10 +34,15 @@ module Grape
         self.parent = nil
       end
 
+      # Return the class-level global properties.
       def global
         self.class.global
       end
 
+      # Set our inherited values to the given parent's current values. Also,
+      # update the inherited values on any settings instances which were forked
+      # from us.
+      # @param parent [InheritableSetting]
       def inherit_from(parent)
         return if parent.nil?
 
@@ -41,6 +55,10 @@ module Grape
         point_in_time_copies.map { |cloned_one| cloned_one.inherit_from parent }
       end
 
+      # Create a point-in-time copy of this settings instance, with clones of
+      # all our values. Note that, should this instance's parent be set or
+      # changed via #inherit_from, it will copy that inheritence to any copies
+      # which were made.
       def point_in_time_copy
         self.class.new.tap do |new_setting|
           point_in_time_copies << new_setting
@@ -56,10 +74,13 @@ module Grape
         end
       end
 
+      # Resets the instance store of per-route settings.
+      # @api private
       def route_end
         @route = {}
       end
 
+      # Return a serializable hash of our values.
       def to_hash
         {
           global: global.clone,

data/lib/grape/util/inheritable_values.rb

@@ -36,7 +36,7 @@ module Grape
       def initialize_copy(other)
         super
         self.inherited_values = other.inherited_values
-        self.new_values = other.new_values.deep_dup
+        self.new_values = other.new_values.dup
       end
 
       protected

data/lib/grape/util/parameter_types.rb

@@ -0,0 +1,58 @@
+module Grape
+  module ParameterTypes
+    # Types representing a single value, which are coerced through Virtus
+    # or special logic in Grape.
+    PRIMITIVES = [
+      # Numerical
+      Integer,
+      Float,
+      BigDecimal,
+      Numeric,
+
+      # Date/time
+      Date,
+      DateTime,
+      Time,
+
+      # Misc
+      Virtus::Attribute::Boolean,
+      String,
+      Symbol,
+      Rack::Multipart::UploadedFile
+    ]
+
+    # Types representing data structures.
+    STRUCTURES = [
+      Hash,
+      Array,
+      Set
+    ]
+
+    # @param type [Class] type to check
+    # @return [Boolean] whether or not the type is known by Grape as a valid
+    #   type for a single value
+    def self.primitive?(type)
+      PRIMITIVES.include?(type)
+    end
+
+    # @param type [Class] type to check
+    # @return [Boolean] whether or not the type is known by Grape as a valid
+    #   data structure type
+    # @note This method does not yet consider 'complex types', which inherit
+    #   Virtus.model.
+    def self.structure?(type)
+      STRUCTURES.include?(type)
+    end
+
+    # A valid custom type must implement a class-level `parse` method, taking
+    #   one String argument and returning the parsed value in its correct type.
+    # @param type [Class] type to check
+    # @return [Boolean] whether or not the type can be used as a custom type
+    def self.custom_type?(type)
+      !primitive?(type) &&
+        !structure?(type) &&
+        type.respond_to?(:parse) &&
+        type.method(:parse).arity == 1
+    end
+  end
+end

data/lib/grape/util/stackable_values.rb

@@ -13,7 +13,10 @@ module Grape
 
       def [](name)
         return @froozen_values[name] if @froozen_values.key? name
-        [@inherited_values[name], @new_values[name]].compact.flatten(1)
+        value = [@inherited_values[name], @new_values[name]]
+        value.compact!
+        value.flatten!(1)
+        value
       end
 
       def []=(name, value)
@@ -45,7 +48,7 @@ module Grape
       def initialize_copy(other)
         super
         self.inherited_values = other.inherited_values
-        self.new_values = other.new_values.deep_dup
+        self.new_values = other.new_values.dup
       end
     end
   end

data/lib/grape/validations/params_scope.rb

@@ -5,12 +5,26 @@ module Grape
 
       include Grape::DSL::Parameters
 
+      # Open up a new ParamsScope, allowing parameter definitions per
+      #   Grape::DSL::Params.
+      # @param opts [Hash] options for this scope
+      # @option opts :element [Symbol] the element that contains this scope; for
+      #   this to be relevant, @parent must be set
+      # @option opts :parent [ParamsScope] the scope containing this scope
+      # @option opts :api [API] the API endpoint to modify
+      # @option opts :optional [Boolean] whether or not this scope needs to have
+      #   any parameters set or not
+      # @option opts :type [Class] a type meant to govern this scope (deprecated)
+      # @option opts :dependent_on [Symbol] if present, this scope should only
+      #   validate if this param is present in the parent scope
+      # @yield the instance context, open for parameter definitions
       def initialize(opts, &block)
-        @element  = opts[:element]
-        @parent   = opts[:parent]
-        @api      = opts[:api]
-        @optional = opts[:optional] || false
-        @type     = opts[:type]
+        @element      = opts[:element]
+        @parent       = opts[:parent]
+        @api          = opts[:api]
+        @optional     = opts[:optional] || false
+        @type         = opts[:type]
+        @dependent_on = opts[:dependent_on]
         @declared_params = []
 
         instance_eval(&block) if block_given?
@@ -18,27 +32,59 @@ module Grape
         configure_declared_params
       end
 
+      # @return [Boolean] whether or not this entire scope needs to be
+      #   validated
       def should_validate?(parameters)
         return false if @optional && params(parameters).respond_to?(:all?) && params(parameters).all?(&:blank?)
+        return false if @dependent_on && params(parameters).try(:[], @dependent_on).blank?
         return true if parent.nil?
         parent.should_validate?(parameters)
       end
 
+      # @return [String] the proper attribute name, with nesting considered.
       def full_name(name)
-        return "#{@parent.full_name(@element)}[#{name}]" if @parent
-        name.to_s
+        case
+        when nested?
+          # Find our containing element's name, and append ours.
+          "#{@parent.full_name(@element)}[#{name}]"
+        when lateral?
+          # Find the name of the element as if it was at the
+          # same nesting level as our parent.
+          @parent.full_name(name)
+        else
+          # We must be the root scope, so no prefix needed.
+          name.to_s
+        end
       end
 
+      # @return [Boolean] whether or not this scope is the root-level scope
       def root?
         !@parent
       end
 
+      # A nested scope is contained in one of its parent's elements.
+      # @return [Boolean] whether or not this scope is nested
+      def nested?
+        @parent && @element
+      end
+
+      # A lateral scope is subordinate to its parent, but its keys are at the
+      # same level as its parent and thus is not contained within an element.
+      # @return [Boolean] whether or not this scope is lateral
+      def lateral?
+        @parent && !@element
+      end
+
+      # @return [Boolean] whether or not this scope needs to be present, or can
+      #   be blank
       def required?
         !@optional
       end
 
       protected
 
+      # Adds a parameter declaration to our list of validations.
+      # @param attrs [Array] (see Grape::DSL::Parameters#requires)
       def push_declared_params(attrs)
         @declared_params.concat attrs
       end
@@ -79,6 +125,13 @@ module Grape
         validates(attrs, validations)
       end
 
+      # Returns a new parameter scope, subordinate to the current one and nested
+      # under the parameter corresponding to `attrs.first`.
+      # @param attrs [Array] the attributes passed to the `requires` or
+      #   `optional` invocation that opened this scope.
+      # @param optional [Boolean] whether the parameter this are nested under
+      #   is optional or not (and hence, whether this block's params will be).
+      # @yield parameter scope
       def new_scope(attrs, optional = false, &block)
         # if required params are grouped and no type or unsupported type is provided, raise an error
         type = attrs[1] ? attrs[1][:type] : nil
@@ -88,12 +141,30 @@ module Grape
         end
 
         opts = attrs[1] || { type: Array }
-        ParamsScope.new(api: @api, element: attrs.first, parent: self, optional: optional, type: opts[:type], &block)
+        self.class.new(api: @api, element: attrs.first, parent: self, optional: optional, type: opts[:type], &block)
+      end
+
+      # Returns a new parameter scope, not nested under any current-level param
+      # but instead at the same level as the current scope.
+      # @param options [Hash] options to control how this new scope behaves
+      # @option options :dependent_on [Symbol] if given, specifies that this
+      #   scope should only validate if this parameter from the above scope is
+      #   present
+      # @yield parameter scope
+      def new_lateral_scope(options, &block)
+        self.class.new(
+          api:          @api,
+          element:      nil,
+          parent:       self,
+          options:      @optional,
+          type:         Hash,
+          dependent_on: options[:dependent_on],
+          &block)
       end
 
       # Pushes declared params to parent or settings
       def configure_declared_params
-        if @parent
+        if nested?
           @parent.push_declared_params [element => @declared_params]
         else
           @api.namespace_stackable(:declared_params, @declared_params)
@@ -183,6 +254,9 @@ module Grape
         return if values.is_a?(Proc)
         coerce_type = coerce_type.first if coerce_type.is_a?(Array)
         value_types = values.is_a?(Range) ? [values.begin, values.end] : values
+        if coerce_type == Virtus::Attribute::Boolean
+          value_types = value_types.map { |type| Virtus::Attribute.build(type) }
+        end
         if value_types.any? { |v| !v.is_a?(coerce_type) }
           fail Grape::Exceptions::IncompatibleOptionValues.new(:type, coerce_type, :values, values)
         end

data/lib/grape/validations/validators/coerce.rb

@@ -41,7 +41,9 @@ module Grape
       end
 
       def valid_type?(val)
-        if @option.is_a?(Array) || @option.is_a?(Set)
+        if val.instance_of?(InvalidValue)
+          false
+        elsif @option.is_a?(Array) || @option.is_a?(Set)
           _valid_array_type?(@option.first, val)
         else
           _valid_single_type?(@option, val)
@@ -54,7 +56,14 @@ module Grape
         return val || Set.new if type == Set
         return val || {}      if type == Hash
 
-        converter = Virtus::Attribute.build(type)
+        # To support custom types that Virtus can't easily coerce, pass in an
+        # explicit coercer. Custom types must implement a `parse` class method.
+        converter_options = {}
+        if ParameterTypes.custom_type?(type)
+          converter_options[:coercer] = type.method(:parse)
+        end
+
+        converter = Virtus::Attribute.build(type, converter_options)
         converter.coerce(val)
 
       # not the prettiest but some invalid coercion can currently trigger

data/lib/grape/validations.rb

@@ -1,4 +1,5 @@
 module Grape
+  # Registry to store and locate known Validators.
   module Validations
     class << self
       attr_accessor :validators
@@ -6,6 +7,10 @@ module Grape
 
     self.validators = {}
 
+    # Register a new validator, so it can be used to validate parameters.
+    # @param short_name [String] all lower-case, no spaces
+    # @param klass [Class] the validator class. Should inherit from
+    #   Validations::Base.
     def self.register_validator(short_name, klass)
       validators[short_name] = klass
     end

data/lib/grape/version.rb

@@ -1,3 +1,4 @@
 module Grape
-  VERSION = '0.12.0'
+  # The current version of Grape.
+  VERSION = '0.13.0'
 end

data/lib/grape.rb

@@ -9,19 +9,13 @@ require 'hashie'
 require 'set'
 require 'active_support/version'
 require 'active_support/core_ext/hash/indifferent_access'
-
-if ActiveSupport::VERSION::MAJOR >= 4
-  require 'active_support/core_ext/object/deep_dup'
-else
-  require_relative 'backports/active_support/deep_dup'
-end
-
 require 'active_support/ordered_hash'
 require 'active_support/core_ext/object/conversions'
 require 'active_support/core_ext/array/extract_options'
 require 'active_support/core_ext/hash/deep_merge'
+require 'active_support/core_ext/hash/except'
 require 'active_support/dependencies/autoload'
-require 'grape/util/content_types'
+require 'active_support/notifications'
 require 'multi_json'
 require 'multi_xml'
 require 'virtus'
@@ -66,6 +60,7 @@ module Grape
     autoload :InvalidVersionerOption
     autoload :UnknownValidator
     autoload :UnknownOptions
+    autoload :UnknownParameter
     autoload :InvalidWithOptionForRepresent
     autoload :IncompatibleOptionValues
     autoload :MissingGroupTypeError,          'grape/exceptions/missing_group_type'
@@ -129,6 +124,7 @@ module Grape
     autoload :StackableValues
     autoload :InheritableSetting
     autoload :StrictHashConfiguration
+    autoload :FileResponse
   end
 
   module DSL
@@ -159,6 +155,9 @@ module Grape
   end
 end
 
+require 'grape/util/content_types'
+require 'grape/util/parameter_types'
+
 require 'grape/validations/validators/base'
 require 'grape/validations/attributes_iterator'
 require 'grape/validations/validators/allow_blank'

data/spec/grape/api_spec.rb

@@ -795,6 +795,37 @@ describe Grape::API do
       expect(last_response.body).to eq(file)
     end
 
+    it 'returns the content of the file with file' do
+      file_content = 'This is some file content'
+      test_file = Tempfile.new('test')
+      test_file.write file_content
+      test_file.rewind
+
+      subject.get('/file') { file test_file }
+      get '/file'
+      expect(last_response.headers['Content-Length']).to eq('25')
+      expect(last_response.headers['Content-Type']).to eq('text/plain')
+      expect(last_response.body).to eq(file_content)
+    end
+
+    it 'streams the content of the file with stream' do
+      test_stream = Enumerator.new do |blk|
+        blk.yield 'This is some'
+        blk.yield ' file content'
+      end
+
+      subject.use Rack::Chunked
+      subject.get('/stream') { stream test_stream }
+      get '/stream', {}, 'HTTP_VERSION' => 'HTTP/1.1'
+
+      expect(last_response.headers['Content-Type']).to eq('text/plain')
+      expect(last_response.headers['Content-Length']).to eq(nil)
+      expect(last_response.headers['Cache-Control']).to eq('no-cache')
+      expect(last_response.headers['Transfer-Encoding']).to eq('chunked')
+
+      expect(last_response.body).to eq("c\r\nThis is some\r\nd\r\n file content\r\n0\r\n\r\n")
+    end
+
     it 'sets content type for error' do
       subject.get('/error') { error!('error in plain text', 500) }
       get '/error'
@@ -2123,6 +2154,38 @@ describe Grape::API do
         { description: 'Reverses a string.', params: { 's' => { desc: 'string to reverse', type: 'string' } } }
       ]
     end
+    it 'does not inherit param descriptions in consequent namespaces' do
+      subject.desc 'global description'
+      subject.params do
+        requires :param1
+        optional :param2
+      end
+      subject.namespace 'ns1' do
+        get do; end
+      end
+      subject.params do
+        optional :param2
+      end
+      subject.namespace 'ns2' do
+        get do; end
+      end
+      routes_doc = subject.routes.map { |route|
+        { description: route.route_description, params: route.route_params }
+      }
+      expect(routes_doc).to eq [
+        { description: 'global description',
+          params: {
+            'param1' => { required: true },
+            'param2' => { required: false }
+          }
+        },
+        { description: 'global description',
+          params: {
+            'param2' => { required: false }
+          }
+        }
+      ]
+    end
     it 'merges the parameters of the namespace with the parameters of the method' do
       subject.desc 'namespace'
       subject.params do