grape 1.8.0 → 3.3.5

data/lib/grape/validations/validations_spec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    # Frozen value object holding everything {ParamsScope#validates} needs to
+    # know about a single +requires+/+optional+ declaration. Built once from
+    # the raw validations hash supplied by the DSL; the raw hash is never
+    # mutated.
+    #
+    # Splits the raw entries into three logical buckets:
+    #
+    # * Spec-consumed keys (type/types/coerce*, presence/message,
+    #   default/fail_fast, doc keys) — exposed via named accessors and never
+    #   handed to validator dispatch.
+    # * Shared opts (allow_blank, fail_fast) — read by every validator at
+    #   construction time via {#shared_opts}.
+    # * Validator entries (everything else, e.g. +regexp+, +length+, +values+,
+    #   +allow_blank+, custom validators) — exposed via {#validator_entries}
+    #   for the dispatch loop.
+    #
+    # Same key can land in more than one bucket (e.g. +allow_blank+ is both a
+    # shared opt and a validator entry; +length+ is both a doc source and a
+    # validator entry).
+    class ValidationsSpec
+      # Keys consumed by the spec itself; must NOT be dispatched as validators
+      # by the caller. Documentation-only keys are filtered through a separate
+      # set so that dual-purpose keys (length, default, values, except_values)
+      # aren't accidentally swallowed.
+      SPEC_CONSUMED_KEYS = %i[
+        type types coerce coerce_with coerce_message
+        presence message
+        fail_fast
+        desc description documentation
+      ].freeze
+
+      attr_reader :raw, :coerce_type, :coerce_method, :coerce_message, :presence_options, :values, :except_values, :default, :allow_blank, :fail_fast, :shared_opts, :validator_entries
+
+      def self.from(validations)
+        new(validations)
+      end
+
+      def initialize(raw)
+        raise ArgumentError, ':type may not be supplied with :types' if raw.key?(:type) && raw.key?(:types)
+
+        @raw = raw
+        @coerce_type, @coerce_message, @coerce_method = parse_coerce(raw)
+        @values = resolve_value(raw[:values])
+        @except_values = resolve_value(raw[:except_values])
+        @default = raw[:default]
+        @presence_options = raw[:presence]
+        @allow_blank = resolve_value(raw[:allow_blank])
+        @fail_fast = raw[:fail_fast] || false
+
+        @guessed_coerce_type = guess_coerce_type(declared_coerce_type, @values, @except_values)
+        @shared_opts = { allow_blank: @allow_blank, fail_fast: @fail_fast }.freeze
+        @validator_entries = build_validator_entries(raw)
+
+        validate!
+
+        freeze
+      end
+
+      def required?
+        !@presence_options.nil? && @presence_options != false
+      end
+
+      def coerce_options
+        CoerceOptions.new(type: @coerce_type, coerce_method: @coerce_method, message: @coerce_message)
+      end
+
+      private
+
+      # Cross-field consistency checks on the parsed declaration. Run at
+      # construction so an incoherent spec (e.g. a +default+ outside +values+,
+      # or +values+ whose elements don't match +type+) can never exist —
+      # callers no longer have to remember to invoke these separately.
+      #
+      # NB. +@guessed_coerce_type+ is used only for this check, never for
+      # +coerce_options+ — a bare +type: Array+ combined with scalar
+      # +values:+ must still coerce to +Array+ at runtime (only the elements
+      # are scalar), so the real +@coerce_type+ is never overwritten by it.
+      def validate!
+        check_incompatible_option_values(@default, @values, @except_values)
+        validate_value_coercion(@guessed_coerce_type, @values, @except_values)
+      end
+
+      def check_incompatible_option_values(default, values, except_values)
+        return if default.nil? || default.is_a?(Proc)
+
+        raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :values, values) if values && !values.is_a?(Proc) && Array(default).any? { |def_val| !values.include?(def_val) }
+
+        return unless except_values && !except_values.is_a?(Proc) && Array(default).any? { |def_val| except_values.include?(def_val) }
+
+        raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :except, except_values)
+      end
+
+      def validate_value_coercion(coerce_type, *values_list)
+        return unless coerce_type
+
+        coerce_type = coerce_type.first if coerce_type.is_a?(Enumerable)
+        values_list.each do |values|
+          next if !values || values.is_a?(Proc)
+
+          value_types = values.is_a?(Range) ? [values.begin, values.end].compact : values
+          value_types = value_types.map { |type| Grape::API::Boolean.build(type) } if coerce_type == Grape::API::Boolean
+          raise Grape::Exceptions::IncompatibleOptionValues.new(:type, coerce_type, :values, values) unless value_types.all?(coerce_type)
+        end
+      end
+
+      def build_validator_entries(raw)
+        raw.reject do |k, _|
+          SPEC_CONSUMED_KEYS.include?(k) || ParamsScope::RESERVED_DOCUMENTATION_KEYWORDS.include?(k)
+        end.freeze
+      end
+
+      def parse_coerce(raw)
+        if raw.key?(:type)
+          coerce, coerce_message = extract_value_and_message(raw[:type])
+          coerce_with = raw[:coerce_with]
+          return [Types::VariantCollectionCoercer.new(coerce, coerce_with), coerce_message, nil] if Types.multiple?(coerce)
+        elsif raw.key?(:types)
+          coerce, coerce_message = extract_value_and_message(raw[:types])
+          coerce_with = raw[:coerce_with]
+        else
+          coerce = raw[:coerce]
+          coerce_message = raw[:coerce_message]
+          coerce_with = raw[:coerce_with]
+        end
+
+        [coerce, coerce_message, coerce_with]
+      end
+
+      def extract_value_and_message(opt)
+        return [opt, nil] unless opt.is_a?(Hash)
+
+        [opt[:value], opt[:message]]
+      end
+
+      def resolve_value(opt)
+        opt.is_a?(Hash) ? opt[:value] : opt
+      end
+
+      # The type as written in the DSL. Identical to +@coerce_type+ except for
+      # a multiple-type declaration (+type: [Integer, String]+), where
+      # {#parse_coerce} wraps the declared list in a
+      # {Types::VariantCollectionCoercer} for runtime coercion — the
+      # definition-time coherence checks need the list back, since the wrapper
+      # matches nothing under +===+.
+      def declared_coerce_type
+        @coerce_type.is_a?(Types::VariantCollectionCoercer) ? @coerce_type.types : @coerce_type
+      end
+
+      def guess_coerce_type(coerce_type, *values_list)
+        return coerce_type unless coerce_type == Array
+
+        values_list.each do |values|
+          next if !values || values.is_a?(Proc)
+          return values.first.class if values.is_a?(Range) || !values.empty?
+        end
+        coerce_type
+      end
+    end
+  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.strip if value.respond_to?(:strip)
+        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,25 +3,76 @@
 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
+        extend Forwardable
+        include Grape::Util::Translation
+
         attr_reader :attrs
 
+        # +allow_blank+ / +fail_fast+ are read straight off the internal
+        # {Grape::Validations::SharedOptions} value object; no per-validator
+        # ivars. The object is built from the +opts+ Hash in #initialize, so
+        # the public 5th-argument contract stays a plain Hash.
+        def_delegators :@opts, :allow_blank, :fail_fast
+
+        alias fail_fast? fail_fast
+        alias allow_blank? allow_blank
+
+        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 [Array] additional validation options
-        def initialize(attrs, options, required, scope, *opts)
-          @attrs = Array(attrs)
-          @option = options
+        # @param opts [Hash] shared validator options; only +:allow_blank+ and
+        #   +:fail_fast+ are consulted (other keys ignored, as before)
+        def initialize(attrs, options, required, scope, opts)
+          @attrs = Array(attrs).freeze
+          @options = Grape::Util::DeepFreeze.deep_freeze(options)
+          @option = @options # TODO: remove in next major release
           @required = required
           @scope = scope
-          opts = opts.any? ? opts.shift : {}
-          @fail_fast = opts.fetch(:fail_fast, false)
-          @allow_blank = opts.fetch(:allow_blank, false)
+          @opts = SharedOptions.new(**opts.slice(:allow_blank, :fail_fast))
+          @exception_message = message(self.class.default_message_key) if self.class.default_message_key
+          @iterator = iterator_class.new(@attrs, @scope).freeze
         end
 
         # Validates a given request.
@@ -30,62 +81,95 @@ module Grape
         # @raise [Grape::Exceptions::Validation] if validation failed
         # @return [void]
         def validate(request)
-          return unless @scope.should_validate?(request.params)
+          return unless scope.should_validate?(request.params)
 
           validate!(request.params)
         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)
           # we collect errors inside array because
           # there may be more than one error per field
-          array_errors = []
+          array_errors = nil
 
-          attributes.each do |val, attr_name, empty_val|
-            next if !@scope.required? && empty_val
-            next unless @scope.meets_dependency?(val, params)
+          @iterator.each(params) do |val, attr_name, empty_val|
+            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
+            (array_errors ||= []) << e
           end
 
-          raise Grape::Exceptions::ValidationArrayErrors.new(array_errors) if array_errors.any?
+          raise Grape::Exceptions::ValidationArrayErrors.new(array_errors) if array_errors
+        end
+
+        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
+
+        attr_reader :options, :scope, :required, :exception_message
+
+        alias required? required
+
+        # The AttributesIterator subclass used to walk this validator's
+        # attributes. Built once in #initialize and reused across requests.
+        def iterator_class
+          SingleAttributeIterator
+        end
+
+        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 self.inherited(klass)
-          return if klass.name.blank?
+        def hash_like?(obj)
+          obj.respond_to?(:key?)
+        end
 
-          short_validator_name = klass.name.demodulize.underscore.delete_suffix('_validator')
-          Validations.register_validator(short_validator_name, klass)
+        def options_key?(key, given_options = nil)
+          current_options = given_options || options
+          hash_like?(current_options) && current_options.key?(key) && !current_options[key].nil?
         end
 
+        # 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)
-          options = instance_variable_get(:@option)
-          options_key?(:message) ? options[:message] : default_key
+          key = options_key?(:message) ? options[:message] : default_key
+          return key unless key.nil?
+
+          yield if block_given?
         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?
+        def option_value
+          options_key?(:value) ? options[:value] : options
         end
 
-        def fail_fast?
-          @fail_fast
+        def scrub(value)
+          return value if !value.respond_to?(:valid_encoding?) || value.valid_encoding?
+
+          value.scrub
         end
       end
     end
   end
 end
-
-Grape::Validations::Base = Class.new(Grape::Validations::Validators::Base) do
-  def self.inherited(*)
-    ActiveSupport::Deprecation.warn 'Grape::Validations::Base is deprecated! Use Grape::Validations::Validators::Base instead.'
-    super
-  end
-end

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

@@ -4,22 +4,29 @@ module Grape
   module Validations
     module Validators
       class CoerceValidator < Base
-        def initialize(attrs, options, required, scope, **opts)
+        default_message_key :coerce
+
+        def initialize(attrs, options, required, scope, opts)
           super
 
-          @converter = if type.is_a?(Grape::Validations::Types::VariantCollectionCoercer)
-                         type
-                       else
-                         Types.build_coercer(type, method: @option[:method])
-                       end
+          @exception_message = options.message if options.message
+
+          raw_type = options.type
+          type = hash_like?(raw_type) ? raw_type[:value] : raw_type
+          @converter =
+            if type.is_a?(Grape::Validations::Types::VariantCollectionCoercer)
+              type
+            else
+              Types.build_coercer(type, method: options.coerce_method)
+            end
         end
 
         def validate_param!(attr_name, params)
-          raise validation_exception(attr_name) unless params.is_a? Hash
+          validation_error!(attr_name) unless hash_like?(params)
 
           new_value = coerce_value(params[attr_name])
 
-          raise validation_exception(attr_name, new_value.message) unless valid_type?(new_value)
+          validation_error!(attr_name, new_value.message || exception_message) if new_value.is_a?(Types::InvalidValue)
 
           # Don't assign a value if it is identical. It fixes a problem with Hashie::Mash
           # which looses wrappers for hashes and arrays after reassigning values
@@ -37,38 +44,13 @@ module Grape
 
         private
 
-        # @!attribute [r] converter
-        # Object that will be used for parameter coercion and type checking.
-        #
-        # See {Types.build_coercer}
-        #
-        # @return [Object]
-        attr_reader :converter
-
-        def valid_type?(val)
-          !val.is_a?(Types::InvalidValue)
-        end
-
+        # Calls the converter built at definition time.
+        # Custom coercers may raise; any StandardError is treated as an invalid value.
         def coerce_value(val)
-          converter.call(val)
-          # Some custom types might fail, so it should be treated as an invalid value
+          @converter.call(val)
         rescue StandardError
           Types::InvalidValue.new
         end
-
-        # Type to which the parameter will be coerced.
-        #
-        # @return [Class]
-        def type
-          @option[:type].is_a?(Hash) ? @option[:type][:value] : @option[:type]
-        end
-
-        def validation_exception(attr_name, custom_msg = nil)
-          Grape::Exceptions::Validation.new(
-            params: [@scope.full_name(attr_name)],
-            message: custom_msg || message(:coerce)
-          )
-        end
       end
     end
   end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Validators
+      class ContractScopeValidator
+        attr_reader :schema
+
+        def initialize(schema:)
+          @schema = schema
+          freeze
+        end
+
+        # Validates a given request.
+        # @param request [Grape::Request] the request currently being handled
+        # @raise [Grape::Exceptions::ValidationArrayErrors] if validation failed
+        # @return [void]
+        def validate(request)
+          res = schema.call(request.params)
+
+          if res.success?
+            request.params.deep_merge!(res.to_h)
+            return
+          end
+
+          raise Grape::Exceptions::ValidationArrayErrors.new(build_errors_from_messages(res.errors.messages))
+        end
+
+        def fail_fast?
+          false
+        end
+
+        private
+
+        def build_errors_from_messages(messages)
+          messages.map do |message|
+            full_name = message.path.first.to_s
+            full_name << "[#{message.path[1..].join('][')}]" if message.path.size > 1
+            Grape::Exceptions::Validation.new(params: full_name, message: message.text)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,27 +4,24 @@ module Grape
   module Validations
     module Validators
       class DefaultValidator < Base
-        def initialize(attrs, options, required, scope, **opts)
-          @default = options
+        def initialize(attrs, options, required, scope, opts)
           super
-        end
-
-        def validate_param!(attr_name, params)
-          params[attr_name] = if @default.is_a? Proc
-                                @default.call
-                              elsif @default.frozen? || !@default.duplicable?
-                                @default
-                              else
-                                @default.dup
-                              end
+          # !important, lazy call at runtime
+          @default_call =
+            if options.is_a?(Proc)
+              options.arity.zero? ? proc { options.call } : options
+            elsif options.duplicable?
+              proc { options.dup }
+            else
+              proc { options }
+            end
         end
 
         def validate!(params)
-          attrs = SingleAttributeIterator.new(self, @scope, params)
-          attrs.each do |resource_params, attr_name|
-            next unless @scope.meets_dependency?(resource_params, params)
+          @iterator.each(params) do |resource_params, attr_name|
+            next unless scope.meets_dependency?(resource_params, params)
 
-            validate_param!(attr_name, resource_params) if resource_params.is_a?(Hash) && resource_params[attr_name].nil?
+            resource_params[attr_name] = @default_call.call(resource_params) if hash_like?(resource_params) && resource_params[attr_name].nil?
           end
         end
       end

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

@@ -4,12 +4,19 @@ module Grape
   module Validations
     module Validators
       class ExactlyOneOfValidator < MultipleParamsBase
+        def initialize(attrs, options, required, scope, opts)
+          super
+          @exactly_one_exception_message = message(:exactly_one)
+          @mutual_exclusion_exception_message = message(:mutual_exclusion)
+        end
+
         def validate_params!(params)
-          keys = keys_in_common(params)
+          known_keys = all_keys
+          keys = keys_in_common(params, known_keys)
           return if keys.length == 1
-          raise Grape::Exceptions::Validation.new(params: all_keys, message: message(:exactly_one)) if keys.length.zero?
 
-          raise Grape::Exceptions::Validation.new(params: keys, message: message(:mutual_exclusion))
+          validation_error!(known_keys, @exactly_one_exception_message) if keys.empty?
+          validation_error!(keys, @mutual_exclusion_exception_message)
         end
       end
     end

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

@@ -4,19 +4,29 @@ module Grape
   module Validations
     module Validators
       class ExceptValuesValidator < Base
-        def initialize(attrs, options, required, scope, **opts)
-          @except = options.is_a?(Hash) ? options[:value] : options
+        default_message_key :except_values
+
+        def initialize(attrs, options, required, scope, opts)
           super
+          except = option_value
+          except_proc = except.is_a?(Proc)
+          raise ArgumentError, 'except_values Proc must have arity of zero (use values: with a one-arity predicate for per-element checks)' if except_proc && !except.arity.zero?
+
+          # Zero-arity procs (e.g. -> { User.pluck(:role) }) must be called per-request,
+          # not at definition time, so they are wrapped in a lambda to defer execution.
+          @excepts_call = except_proc ? except : -> { except }
         end
 
         def validate_param!(attr_name, params)
-          return unless params.respond_to?(:key?) && params.key?(attr_name)
+          return unless hash_like?(params) && params.key?(attr_name)
 
-          excepts = @except.is_a?(Proc) ? @except.call : @except
+          excepts = @excepts_call.call
           return if excepts.nil?
 
           param_array = params[attr_name].nil? ? [nil] : Array.wrap(params[attr_name])
-          raise Grape::Exceptions::Validation.new(params: [@scope.full_name(attr_name)], message: message(:except_values)) if param_array.any? { |param| excepts.include?(param) }
+          return if param_array.none? { |param| excepts.include?(param) }
+
+          validation_error!(attr_name)
         end
       end
     end