grape 0.12.0 → 0.14.0

data/lib/grape/util/env.rb

@@ -0,0 +1,22 @@
+module Grape
+  module Env
+    API_VERSION = 'api.version'.freeze
+    API_ENDPOINT = 'api.endpoint'.freeze
+    API_REQUEST_INPUT = 'api.request.input'.freeze
+    API_REQUEST_BODY = 'api.request.body'.freeze
+    API_TYPE = 'api.type'.freeze
+    API_SUBTYPE = 'api.subtype'.freeze
+    API_VENDOR = 'api.vendor'.freeze
+    API_FORMAT = 'api.format'.freeze
+
+    RACK_INPUT = 'rack.input'.freeze
+    RACK_REQUEST_QUERY_HASH = 'rack.request.query_hash'.freeze
+    RACK_REQUEST_FORM_HASH = 'rack.request.form_hash'.freeze
+    RACK_REQUEST_FORM_INPUT = 'rack.request.form_input'.freeze
+    RACK_ROUTING_ARGS = 'rack.routing_args'.freeze
+
+    GRAPE_REQUEST = 'grape.request'.freeze
+    GRAPE_REQUEST_HEADERS = 'grape.request.headers'.freeze
+    GRAPE_REQUEST_PARAMS = 'grape.request.params'.freeze
+  end
+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/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/util/strict_hash_configuration.rb

@@ -64,7 +64,8 @@ module Grape
           end
 
           define_method 'to_hash' do
-            merge_hash = setting_name.keys.each_with_object({}) { |k, hash| hash[k] = send("#{k}_context").to_hash }
+            merge_hash = {}
+            setting_name.each_key { |k| merge_hash[k] = send("#{k}_context").to_hash }
 
             @settings.to_hash.merge(
               merge_hash

data/lib/grape/validations/attributes_iterator.rb

@@ -3,15 +3,20 @@ module Grape
     class AttributesIterator
       include Enumerable
 
+      attr_reader :scope
+
       def initialize(validator, scope, params)
+        @scope = scope
         @attrs = validator.attrs
-        @params = scope.params(params)
-        @params = (@params.is_a?(Array) ? @params : [@params])
+        @params = Array.wrap(scope.params(params))
       end
 
       def each
         @params.each do |resource_params|
-          @attrs.each do |attr_name|
+          @attrs.each_with_index do |attr_name, index|
+            if resource_params.is_a?(Hash) && resource_params[attr_name].is_a?(Array)
+              scope.index = index
+            end
             yield resource_params, attr_name
           end
         end

data/lib/grape/validations/params_scope.rb

@@ -1,16 +1,30 @@
 module Grape
   module Validations
     class ParamsScope
-      attr_accessor :element, :parent
+      attr_accessor :element, :parent, :index
 
       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,63 @@ 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)}#{parent_index}[#{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
+
+      def parent_index
+        "[#{@parent.index}]" if @parent.present? && @parent.index.present?
       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,21 +129,46 @@ 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
         if attrs.first && !optional
           fail Grape::Exceptions::MissingGroupTypeError.new if type.nil?
-          fail Grape::Exceptions::UnsupportedGroupTypeError.new unless [Array, Hash].include?(type)
+          fail Grape::Exceptions::UnsupportedGroupTypeError.new unless [Array, Hash, JSON, Array[JSON]].include?(type)
         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)
@@ -106,10 +181,7 @@ module Grape
       def validates(attrs, validations)
         doc_attrs = { required: validations.keys.include?(:presence) }
 
-        # special case (type = coerce)
-        validations[:coerce] = validations.delete(:type) if validations.key?(:type)
-
-        coerce_type = validations[:coerce]
+        coerce_type = infer_coercion(validations)
 
         doc_attrs[:type] = coerce_type.to_s if coerce_type
 
@@ -141,19 +213,87 @@ module Grape
           validations.delete(:presence)
         end
 
-        # Before we run the rest of the validators, lets handle
+        # Before we run the rest of the validators, let's handle
         # whatever coercion so that we are working with correctly
         # type casted values
-        if validations.key? :coerce
-          validate('coerce', validations[:coerce], attrs, doc_attrs)
-          validations.delete(:coerce)
-        end
+        coerce_type validations, attrs, doc_attrs
 
         validations.each do |type, options|
           validate(type, options, attrs, doc_attrs)
         end
       end
 
+      # Validate and comprehend the +:type+, +:types+, and +:coerce_with+
+      # options that have been supplied to the parameter declaration.
+      # The +:type+ and +:types+ options will be removed from the
+      # validations list, replaced appropriately with +:coerce+ and
+      # +:coerce_with+ options that will later be passed to
+      # {Validators::CoerceValidator}. The type that is returned may be
+      # used for documentation and further validation of parameter
+      # options.
+      #
+      # @param validations [Hash] list of validations supplied to the
+      #   parameter declaration
+      # @return [class-like] type to which the parameter will be coerced
+      # @raise [ArgumentError] if the given type options are invalid
+      def infer_coercion(validations)
+        if validations.key?(:type) && validations.key?(:types)
+          fail ArgumentError, ':type may not be supplied with :types'
+        end
+
+        validations[:coerce] = validations[:type] if validations.key?(:type)
+        validations[:coerce] = validations.delete(:types) if validations.key?(:types)
+
+        coerce_type = validations[:coerce]
+
+        # Special case - when the argument is a single type that is a
+        # variant-type collection.
+        if Types.multiple?(coerce_type) && validations.key?(:type)
+          validations[:coerce] = Types::VariantCollectionCoercer.new(
+            coerce_type,
+            validations.delete(:coerce_with)
+          )
+        end
+        validations.delete(:type)
+
+        coerce_type
+      end
+
+      # Enforce correct usage of :coerce_with parameter.
+      # We do not allow coercion without a type, nor with
+      # +JSON+ as a type since this defines its own coercion
+      # method.
+      def check_coerce_with(validations)
+        return unless validations.key?(:coerce_with)
+        # type must be supplied for coerce_with..
+        fail ArgumentError, 'must supply type for coerce_with' unless validations.key?(:coerce)
+
+        # but not special JSON types, which
+        # already imply coercion method
+        return unless [JSON, Array[JSON]].include? validations[:coerce]
+        fail ArgumentError, 'coerce_with disallowed for type: JSON'
+      end
+
+      # Add type coercion validation to this scope,
+      # if any has been specified.
+      # This validation has special handling since it is
+      # composited from more than one +requires+/+optional+
+      # parameter, and needs to be run before most other
+      # validations.
+      def coerce_type(validations, attrs, doc_attrs)
+        check_coerce_with(validations)
+
+        return unless validations.key?(:coerce)
+
+        coerce_options = {
+          type: validations[:coerce],
+          method: validations[:coerce_with]
+        }
+        validate('coerce', coerce_options, attrs, doc_attrs)
+        validations.delete(:coerce_with)
+        validations.delete(:coerce)
+      end
+
       def guess_coerce_type(coerce_type, values)
         return coerce_type if !values || values.is_a?(Proc)
         return values.first.class if coerce_type == Array && (values.is_a?(Range) || !values.empty?)
@@ -183,9 +323,11 @@ 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 value_types.any? { |v| !v.is_a?(coerce_type) }
-          fail Grape::Exceptions::IncompatibleOptionValues.new(:type, coerce_type, :values, values)
+        if coerce_type == Virtus::Attribute::Boolean
+          value_types = value_types.map { |type| Virtus::Attribute.build(type) }
         end
+        return unless value_types.any? { |v| !v.is_a?(coerce_type) }
+        fail Grape::Exceptions::IncompatibleOptionValues.new(:type, coerce_type, :values, values)
       end
     end
   end

data/lib/grape/validations/types/build_coercer.rb

@@ -0,0 +1,53 @@
+module Grape
+  module Validations
+    module Types
+      # Work out the +Virtus::Attribute+ object to
+      # use for coercing strings to the given +type+.
+      # Coercion +method+ will be inferred if none is
+      # supplied.
+      #
+      # If a +Virtus::Attribute+ object already built
+      # with +Virtus::Attribute.build+ is supplied as
+      # the +type+ it will be returned and +method+
+      # will be ignored.
+      #
+      # See {CustomTypeCoercer} for further details
+      # about coercion and type-checking inference.
+      #
+      # @param type [Class] the type to which input strings
+      #   should be coerced
+      # @param method [Class,#call] the coercion method to use
+      # @return [Virtus::Attribute] object to be used
+      #   for coercion and type validation
+      def self.build_coercer(type, method = nil)
+        # Accept pre-rolled virtus attributes without interference
+        return type if type.is_a? Virtus::Attribute
+
+        converter_options = {
+          nullify_blank: true
+        }
+        conversion_type = type
+
+        # Use a special coercer for multiply-typed parameters.
+        if Types.multiple?(type)
+          converter_options[:coercer] = Types::MultipleTypeCoercer.new(type, method)
+          conversion_type = Object
+
+        # Use a special coercer for custom types and coercion methods.
+        elsif method || Types.custom?(type)
+          converter_options[:coercer] = Types::CustomTypeCoercer.new(type, method)
+
+        # Grape swaps in its own Virtus::Attribute implementations
+        # for certain special types that merit first-class support
+        # (but not if a custom coercion method has been supplied).
+        elsif Types.special?(type)
+          conversion_type = Types::SPECIAL[type]
+        end
+
+        # Virtus will infer coercion and validation rules
+        # for many common ruby types.
+        Virtus::Attribute.build(conversion_type, converter_options)
+      end
+    end
+  end
+end