grape 3.1.0 → 3.2.0

data/lib/grape/validations/params_scope.rb

@@ -3,8 +3,11 @@
 module Grape
   module Validations
     class ParamsScope
-      attr_accessor :element, :parent, :index
-      attr_reader :type, :params_meeting_dependency
+      attr_reader :parent, :type, :nearest_array_ancestor, :full_path
+
+      def qualifying_params
+        ParamScopeTracker.current&.qualifying_params(self)
+      end
 
       include Grape::DSL::Parameters
       include Grape::Validations::ParamsDocumentation
@@ -17,7 +20,7 @@ module Grape
       SPECIAL_JSON = [JSON, Array[JSON]].freeze
 
       class Attr
-        attr_accessor :key, :scope
+        attr_reader :key, :scope
 
         # Open up a new ParamsScope::Attr
         # @param key [Hash, Symbol] key of attr
@@ -47,36 +50,39 @@ module Grape
 
       # 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 :element_renamed [Symbol, nil] whenever this scope should
+      # @param api [API] the API endpoint to modify
+      # @param element [Symbol] the element that contains this scope; for
+      #   this to be relevant, parent must be set
+      # @param element_renamed [Symbol, nil] whenever this scope should
       #   be renamed and to what, given +nil+ no renaming is done
-      # @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
+      # @param parent [ParamsScope] the scope containing this scope
+      # @param 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 :type [Hash] group options for this scope
-      # @option opts :dependent_on [Symbol] if present, this scope should only
+      # @param type [Class] a type meant to govern this scope (deprecated)
+      # @param type [Hash] group options for this scope
+      # @param 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]
-        @element_renamed  = opts[:element_renamed]
-        @parent           = opts[:parent]
-        @api              = opts[:api]
-        @optional         = opts[:optional] || false
-        @type             = opts[:type]
-        @group            = opts[:group]
-        @dependent_on     = opts[:dependent_on]
-        @params_meeting_dependency = []
+      def initialize(api:, element: nil, element_renamed: nil, parent: nil, optional: false, type: nil, group: nil, dependent_on: nil, &block)
+        @element          = element
+        @element_renamed  = element_renamed
+        @parent           = parent
+        @api              = api
+        @optional         = optional
+        @type             = type
+        @group            = group
+        @dependent_on     = dependent_on
+        # Must be an ivar: push_declared_params is dispatched on self during
+        # instance_eval, so local variables from initialize are unreachable.
+        # configure_declared_params consumes it and clears @declared_params to nil.
         @declared_params = []
-        @index = nil
+        @full_path = build_full_path
 
         instance_eval(&block) if block
 
         configure_declared_params
+        @nearest_array_ancestor = find_nearest_array_ancestor
+        freeze
       end
 
       def configuration
@@ -90,9 +96,9 @@ module Grape
 
         return false if @optional && (scoped_params.blank? || all_element_blank?(scoped_params))
         return false unless meets_dependency?(scoped_params, parameters)
-        return true if parent.nil?
+        return true if @parent.nil?
 
-        parent.should_validate?(parameters)
+        @parent.should_validate?(parameters)
       end
 
       def meets_dependency?(params, request_params)
@@ -100,8 +106,9 @@ module Grape
         return false if @parent.present? && !@parent.meets_dependency?(@parent.params(request_params), request_params)
 
         if params.is_a?(Array)
-          @params_meeting_dependency = params.flatten.filter { |param| meets_dependency?(param, request_params) }
-          return @params_meeting_dependency.present?
+          filtered = params.flatten.filter { |param| meets_dependency?(param, request_params) }
+          ParamScopeTracker.current&.store_qualifying_params(self, filtered)
+          return filtered.present?
         end
 
         meets_hash_dependency?(params)
@@ -118,28 +125,27 @@ module Grape
         # params might be anything what looks like a hash, so it must implement a `key?` method
         return false unless params.respond_to?(:key?)
 
-        @dependent_on.each do |dependency|
+        @dependent_on.all? do |dependency|
           if dependency.is_a?(Hash)
-            dependency_key = dependency.keys[0]
-            proc = dependency.values[0]
-            return false unless proc.call(params[dependency_key])
-          elsif params[dependency].blank?
-            return false
+            key, callable = dependency.first
+            callable.call(params[key])
+          else
+            params[dependency].present?
           end
         end
-
-        true
       end
 
       # @return [String] the proper attribute name, with nesting considered.
       def full_name(name, index: nil)
+        tracker = ParamScopeTracker.current
         if nested?
           # Find our containing element's name, and append ours.
-          "#{@parent.full_name(@element)}#{brackets(index || @index)}#{brackets(name)}"
+          resolved_index = index || tracker&.index_for(self)
+          "#{@parent.full_name(@element)}#{brackets(resolved_index)}#{brackets(name)}"
         elsif lateral?
           # Find the name of the element as if it was at the same nesting level
           # as our parent. We need to forward our index upward to achieve this.
-          @parent.full_name(name, index: @index)
+          @parent.full_name(name, index: tracker&.index_for(self))
         else
           # We must be the root scope, so no prefix needed.
           name.to_s
@@ -174,28 +180,23 @@ module Grape
         !@optional
       end
 
-      def reset_index
-        @index = nil
-      end
-
       protected
 
       # Adds a parameter declaration to our list of validations.
       # @param attrs [Array] (see Grape::DSL::Parameters#requires)
-      def push_declared_params(attrs, opts = {})
+      def push_declared_params(attrs, **opts)
         opts[:declared_params_scope] = self unless opts.key?(:declared_params_scope)
-        return @parent.push_declared_params(attrs, opts) if lateral?
+        return @parent.push_declared_params(attrs, **opts) if lateral?
 
         push_renamed_param(full_path + [attrs.first], opts[:as]) if opts[:as]
         @declared_params.concat(attrs.map { |attr| ::Grape::Validations::ParamsScope::Attr.new(attr, opts[:declared_params_scope]) })
       end
 
-      # Get the full path of the parameter scope in the hierarchy.
-      #
-      # @return [Array<Symbol>] the nesting/path of the current parameter scope
-      def full_path
+      private
+
+      def build_full_path
         if nested?
-          (@parent.full_path + [@element])
+          @parent.full_path + [@element]
         elsif lateral?
           @parent.full_path
         else
@@ -203,8 +204,6 @@ module Grape
         end
       end
 
-      private
-
       # Add a new parameter which should be renamed when using the +#declared+
       # method.
       #
@@ -219,9 +218,9 @@ module Grape
         api_route_setting[:renamed_params] = base
       end
 
-      def require_required_and_optional_fields(context, opts)
-        except_fields = Array.wrap(opts[:except])
-        using_fields = opts[:using].keys.delete_if { |f| except_fields.include?(f) }
+      def require_required_and_optional_fields(context, using:, except: nil)
+        except_fields = Array.wrap(except)
+        using_fields = using.keys.delete_if { |f| except_fields.include?(f) }
 
         if context == :all
           optional_fields = except_fields
@@ -231,56 +230,55 @@ module Grape
           optional_fields = using_fields
         end
         required_fields.each do |field|
-          field_opts = opts[:using][field]
+          field_opts = using[field]
           raise ArgumentError, "required field not exist: #{field}" unless field_opts
 
           requires(field, **field_opts)
         end
         optional_fields.each do |field|
-          field_opts = opts[:using][field]
+          field_opts = using[field]
           optional(field, **field_opts) if field_opts
         end
       end
 
-      def require_optional_fields(context, opts)
-        optional_fields = opts[:using].keys
+      def require_optional_fields(context, using:, except: nil)
+        optional_fields = using.keys
         unless context == :all
-          except_fields = Array.wrap(opts[:except])
+          except_fields = Array.wrap(except)
           optional_fields.delete_if { |f| except_fields.include?(f) }
         end
         optional_fields.each do |field|
-          field_opts = opts[:using][field]
+          field_opts = using[field]
           optional(field, **field_opts) if field_opts
         end
       end
 
-      def validate_attributes(attrs, opts, &block)
-        validations = opts.clone
-        validations[:type] ||= Array if block
-        validates(attrs, validations)
+      def validate_attributes(attrs, **opts, &block)
+        opts[:type] ||= Array if block
+        validates(attrs, opts)
       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
+      # under the given element.
+      # @param element [Symbol] the parameter name under which this scope is nested
+      # @param type [Class] the type governing this scope
+      # @param as [Symbol, nil] optional renamed name for the element
+      # @param optional [Boolean] whether the parameter this scope is nested under
       #   is optional or not (and hence, whether this block's params will be).
       # @yield parameter scope
-      def new_scope(attrs, opts, optional = false, &)
+      def new_scope(element, type:, as:, optional: false, &)
         # if required params are grouped and no type or unsupported type is provided, raise an error
-        type = opts[:type]
-        if attrs.first && !optional
+        if element && !optional
           raise Grape::Exceptions::MissingGroupType if type.nil?
           raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
         end
 
         self.class.new(
           api: @api,
-          element: attrs.first,
-          element_renamed: opts[:as],
+          element:,
+          element_renamed: as,
           parent: self,
-          optional: optional,
+          optional:,
           type: type || Array,
           group: @group,
           &
@@ -289,46 +287,50 @@ module Grape
 
       # 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
+      # @param 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, &)
+      def new_lateral_scope(dependent_on:, &)
         self.class.new(
           api: @api,
-          element: nil,
           parent: self,
-          options: @optional,
+          optional: @optional,
           type: type == Array ? Array : Hash,
-          dependent_on: options[:dependent_on],
+          dependent_on:,
           &
         )
       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.
+      # Returns a new parameter scope, subordinate to the current one, sharing
+      # the given group options with all parameters defined within.
+      # @param group [Hash] common options to merge into each parameter in the scope
       # @yield parameter scope
-      def new_group_scope(attrs, &)
-        self.class.new(api: @api, parent: self, group: attrs.first, &)
+      def new_group_scope(group, &)
+        self.class.new(api: @api, parent: self, group:, &)
       end
 
-      # Pushes declared params to parent or settings
+      # Pushes declared params to parent or settings, then clears @declared_params.
+      # Clearing here (rather than in initialize) keeps the lifecycle ownership in
+      # one place: this method both consumes and invalidates the ivar so that
+      # push_declared_params cannot be called on the frozen scope later.
       def configure_declared_params
         push_renamed_param(full_path, @element_renamed) if @element_renamed
 
         if nested?
-          @parent.push_declared_params [element => @declared_params]
+          @parent.push_declared_params [@element => @declared_params]
         else
           @api.inheritable_setting.namespace_stackable[:declared_params] = @declared_params
         end
-
-        # params were stored in settings, it can be cleaned from the params scope
+      ensure
         @declared_params = nil
       end
 
+      def find_nearest_array_ancestor
+        scope = @parent
+        scope = scope.parent while scope && scope.type != Array
+        scope
+      end
+
       def validates(attrs, validations)
         coerce_type = infer_coercion(validations)
         required = validations.key?(:presence)
@@ -349,7 +351,7 @@ module Grape
 
         document_params attrs, validations, coerce_type, values, except_values
 
-        opts = derive_validator_options(validations)
+        opts = derive_validator_options(validations).freeze
 
         # Validate for presence before any other validators
         validates_presence(validations, attrs, opts)
@@ -357,7 +359,7 @@ module Grape
         # Before we run the rest of the validators, let's handle
         # whatever coercion so that we are working with correctly
         # type casted values
-        coerce_type validations, attrs, required, opts
+        coerce_type validations.extract!(:coerce, :coerce_with, :coerce_message), attrs, required, opts
 
         validations.each do |type, options|
           # Don't try to look up validators for documentation params that don't have one.
@@ -430,7 +432,12 @@ module Grape
       def coerce_type(validations, attrs, required, opts)
         check_coerce_with(validations)
 
-        return unless validations.key?(:coerce)
+        # Falsy check (not key?) is intentional: when a remountable API is first
+        # evaluated on its base instance (no configuration supplied yet),
+        # configuration[:some_type] evaluates to nil. Skipping instantiation
+        # here is correct — the real mounted instance will replay this step with
+        # the actual type value.
+        return unless validations[:coerce]
 
         coerce_options = {
           type: validations[:coerce],
@@ -438,9 +445,6 @@ module Grape
           message: validations[:coerce_message]
         }
         validate('coerce', coerce_options, attrs, required, opts)
-        validations.delete(:coerce_with)
-        validations.delete(:coerce)
-        validations.delete(:coerce_message)
       end
 
       def guess_coerce_type(coerce_type, *values_list)
@@ -464,15 +468,15 @@ module Grape
       end
 
       def validate(type, options, attrs, required, opts)
-        validator_options = {
-          attributes: attrs,
-          options: options,
-          required: required,
-          params_scope: self,
-          opts: opts,
-          validator_class: Validations.require_validator(type)
-        }
-        @api.inheritable_setting.namespace_stackable[:validations] = validator_options
+        validator_class = Validations.require_validator(type)
+        validator_instance = validator_class.new(
+          attrs,
+          options,
+          required,
+          self,
+          opts
+        )
+        @api.inheritable_setting.namespace_stackable[:validations] = validator_instance
       end
 
       def validate_value_coercion(coerce_type, *values_list)

data/lib/grape/validations/single_attribute_iterator.rb

@@ -5,10 +5,10 @@ module Grape
     class SingleAttributeIterator < AttributesIterator
       private
 
-      def yield_attributes(val, attrs)
+      def yield_attributes(val)
         return if skip?(val)
 
-        attrs.each do |attr_name|
+        @attrs.each do |attr_name|
           yield val, attr_name, empty?(val)
         end
       end

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

@@ -4,11 +4,14 @@ module Grape
   module Validations
     module Validators
       class AllOrNoneOfValidator < MultipleParamsBase
+        default_message_key :all_or_none
+
         def validate_params!(params)
-          keys = keys_in_common(params)
-          return if keys.empty? || keys.length == all_keys.length
+          known_keys = all_keys
+          keys = keys_in_common(params, known_keys)
+          return if keys.empty? || keys.length == @attrs.length
 
-          raise Grape::Exceptions::Validation.new(params: all_keys, message: message(:all_or_none))
+          validation_error!(known_keys)
         end
       end
     end

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

@@ -4,15 +4,20 @@ module Grape
   module Validations
     module Validators
       class AllowBlankValidator < Base
-        def validate_param!(attr_name, params)
-          return if (options_key?(:value) ? @option[:value] : @option) || !params.is_a?(Hash)
+        default_message_key :blank
+
+        def initialize(attrs, options, required, scope, opts)
+          super
+          @value = option_value
+        end
 
-          value = params[attr_name]
-          value = value.scrub if value.respond_to?(:valid_encoding?) && !value.valid_encoding?
+        def validate_param!(attr_name, params)
+          return if @value || !hash_like?(params)
 
+          value = scrub(params[attr_name])
           return if value == false || value.present?
 
-          raise Grape::Exceptions::Validation.new(params: [@scope.full_name(attr_name)], message: message(:blank))
+          validation_error!(attr_name)
         end
       end
     end

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

@@ -4,10 +4,13 @@ module Grape
   module Validations
     module Validators
       class AtLeastOneOfValidator < MultipleParamsBase
+        default_message_key :at_least_one
+
         def validate_params!(params)
-          return unless keys_in_common(params).empty?
+          known_keys = all_keys
+          return if hash_like?(params) && known_keys.intersect?(params.keys.map { |attr| @scope.full_name(attr) })
 
-          raise Grape::Exceptions::Validation.new(params: all_keys, message: message(:at_least_one))
+          validation_error!(known_keys)
         end
       end
     end

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

@@ -3,24 +3,64 @@
 module Grape
   module Validations
     module Validators
+      # Base class for all parameter validators.
+      #
+      # == Freeze contract
+      # Validator instances are shared across requests and are frozen after
+      # initialization (via +.new+). All inputs (+options+, +opts+, +attrs+)
+      # arrive pre-frozen from the DSL boundary, so subclass ivars derived
+      # from them are frozen by construction. Lazy ivar assignment
+      # (e.g. +memoize+, <tt>||=</tt>) will raise +FrozenError+ at request time.
       class Base
+        include Grape::Util::Translation
+
         attr_reader :attrs
 
+        class << self
+          # Declares the default I18n message key used by +validation_error!+.
+          # Subclasses that only need a single fixed error message can declare it
+          # at the class level instead of overriding +initialize+:
+          #
+          #   class MyValidator < Grape::Validations::Validators::Base
+          #     default_message_key :my_error
+          #   end
+          #
+          # The key is resolved through +message+, so a per-option +:message+
+          # override still takes precedence.
+          def default_message_key(key = nil)
+            if key
+              @default_message_key = key
+            else
+              @default_message_key || (superclass.respond_to?(:default_message_key) ? superclass.default_message_key : nil)
+            end
+          end
+
+          def new(...)
+            super.freeze
+          end
+
+          def inherited(klass)
+            super
+            Validations.register(klass)
+          end
+        end
+
         # Creates a new Validator from options specified
         # by a +requires+ or +optional+ directive during
         # parameter definition.
         # @param attrs [Array] names of attributes to which the Validator applies
-        # @param options [Object] implementation-dependent Validator options
+        # @param options [Object] implementation-dependent Validator options; deep-frozen on assignment
         # @param required [Boolean] attribute(s) are required or optional
         # @param scope [ParamsScope] parent scope for this Validator
         # @param opts [Hash] additional validation options
         def initialize(attrs, options, required, scope, opts)
-          @attrs = Array(attrs)
-          @option = options
+          @attrs = Array(attrs).freeze
+          @options = Grape::Util::DeepFreeze.deep_freeze(options)
+          @option = @options # TODO: remove in next major release
           @required = required
           @scope = scope
-          @fail_fast = opts[:fail_fast]
-          @allow_blank = opts[:allow_blank]
+          @fail_fast, @allow_blank = opts.values_at(:fail_fast, :allow_blank)
+          @exception_message = message(self.class.default_message_key) if self.class.default_message_key
         end
 
         # Validates a given request.
@@ -34,13 +74,18 @@ module Grape
           validate!(request.params)
         end
 
+        def fail_fast?
+          @fail_fast
+        end
+
         # Validates a given parameter hash.
-        # @note Override #validate if you need to access the entire request.
+        # @note Override #validate_param! for per-parameter validation,
+        #   or #validate if you need access to the entire request.
         # @param params [Hash] parameters to validate
         # @raise [Grape::Exceptions::Validation] if validation failed
         # @return [void]
         def validate!(params)
-          attributes = SingleAttributeIterator.new(self, @scope, params)
+          attributes = SingleAttributeIterator.new(@attrs, @scope, params)
           # we collect errors inside array because
           # there may be more than one error per field
           array_errors = []
@@ -49,7 +94,7 @@ module Grape
             next if !@scope.required? && empty_val
             next unless @scope.meets_dependency?(val, params)
 
-            validate_param!(attr_name, val) if @required || (val.respond_to?(:key?) && val.key?(attr_name))
+            validate_param!(attr_name, val) if @required || (hash_like?(val) && val.key?(attr_name))
           rescue Grape::Exceptions::Validation => e
             array_errors << e
           end
@@ -57,23 +102,55 @@ module Grape
           raise Grape::Exceptions::ValidationArrayErrors.new(array_errors) if array_errors.any?
         end
 
-        def self.inherited(klass)
-          super
-          Validations.register(klass)
+        protected
+
+        # Validates a single attribute. Override in subclasses.
+        # @param attr_name [Symbol, String] the attribute name
+        # @param params [Hash] the parameter hash containing the attribute
+        # @raise [Grape::Exceptions::Validation] if validation failed
+        # @return [void]
+        def validate_param!(attr_name, params)
+          raise NotImplementedError
+        end
+
+        private
+
+        def validation_error!(attr_name_or_params, message = @exception_message)
+          params = attr_name_or_params.is_a?(Array) ? attr_name_or_params : @scope.full_name(attr_name_or_params)
+          raise Grape::Exceptions::Validation.new(params:, message:)
         end
 
-        def message(default_key = nil)
-          options = instance_variable_get(:@option)
-          options_key?(:message) ? options[:message] : default_key
+        def hash_like?(obj)
+          obj.respond_to?(:key?)
         end
 
         def options_key?(key, options = nil)
-          options = instance_variable_get(:@option) if options.nil?
-          options.respond_to?(:key?) && options.key?(key) && !options[key].nil?
+          current_options = options || @options
+          hash_like?(current_options) && current_options.key?(key) && !current_options[key].nil?
         end
 
-        def fail_fast?
-          @fail_fast
+        # Returns the effective message for a validation error.
+        # Prefers an explicit +:message+ option, then +default_key+.
+        # If both are nil, the block (if given) is called to compute a fallback —
+        # useful for validators that build a message Hash for deferred i18n interpolation.
+        # @example
+        #   @exception_message = message(:presence)             # symbol key or custom message
+        #   @exception_message = message { build_hash_message } # computed fallback
+        def message(default_key = nil)
+          key = options_key?(:message) ? @options[:message] : default_key
+          return key unless key.nil?
+
+          yield if block_given?
+        end
+
+        def option_value
+          options_key?(:value) ? @options[:value] : @options
+        end
+
+        def scrub(value)
+          return value unless value.respond_to?(:valid_encoding?) && !value.valid_encoding?
+
+          value.scrub
         end
       end
     end