Instantiate validators at definition time

  - Store validator instances in ParamsScope/ContractScope and have
    Endpoint#run_validators read them directly
  - Remove ValidatorFactory indirection and eagerly compute validator
    messages/options in constructors
  - Extract Grape::Util::Translation module shared by Exceptions::Base
    and Validators::Base for I18n translate with fallback locale
  - Support Hash messages in translate_message for deferred translation
    with interpolation parameters (e.g. { key: :length, min: 2 })
  - Normalize Grape::Exceptions::Validation params handling and refactor
    validator specs to define routes per example group
  - Drop test-prof dependency and its spec config

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ericproulx

CHANGELOG.md

@@ -3,6 +3,7 @@
 #### Features
 
 * [#2656](https://github.com/ruby-grape/grape/pull/2656): Remove useless instance_variable_defined? checks - [@ericproulx](https://github.com/ericproulx).
+* [#2657](https://github.com/ruby-grape/grape/pull/2657): Instantiate validators at compile time - [@ericproulx](https://github.com/ericproulx).
 * Your contribution here.
 
 #### Fixes

Gemfile

@@ -32,7 +32,6 @@ group :test do
   gem 'rspec', '~> 3.13'
   gem 'simplecov', '~> 0.21', require: false
   gem 'simplecov-lcov', '~> 0.8', require: false
-  gem 'test-prof', require: false
 end
 
 platforms :jruby do

UPGRADING.md

@@ -1,6 +1,70 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 3.2
+
+#### Validators Instantiated at Compile Time
+
+Previously, validators were instantiated at request time but they are now instantiated at compile time. Validators are thread safe since their initial state always stay the same. It also reduces object allocations overtime since instances are reused.
+
+#### `Grape::Exceptions::Validation` Changes
+
+**`params` and `message_key` are now read-only.** `attr_accessor` has been changed to `attr_reader`. If you were assigning to these after initialization, set them via the constructor keyword arguments instead.
+
+**`params` is now always coerced to an array.** You can now pass a single string instead of wrapping it in an array:
+
+```ruby
+# Before
+Grape::Exceptions::Validation.new(params: ['my_param'], message: 'is invalid')
+
+# After (both work, single string is now accepted)
+Grape::Exceptions::Validation.new(params: 'my_param', message: 'is invalid')
+Grape::Exceptions::Validation.new(params: ['my_param'], message: 'is invalid')
+```
+
+#### `Validators::Base` Method Visibility Changes
+
+The following methods on `Grape::Validations::Validators::Base` are now **private**: `validate!`, `message`, `options_key?`. If your custom validator subclass calls these via `super` from a private method, no change is needed. If you were calling them from outside the class, you'll need to adjust.
+
+Three new private helpers have been added:
+- `hash_like?(obj)` — returns `obj.respond_to?(:key?)`
+- `option_value` — returns `@option[:value]` if present, otherwise `@option`
+- `scrub(value)` — scrubs invalid-encoding strings
+
+#### `Validators::Base#message` Now Accepts a Block
+
+`message` now accepts an optional block for lazy default message generation. The block is only called when no custom `:message` option is set and no `default_key` is provided:
+
+```ruby
+# Before
+def message(default_key = nil)
+  options_key?(:message) ? @option[:message] : default_key
+end
+
+# After
+def message(default_key = nil)
+  options_key?(:message) ? @option[:message] : default_key || yield
+end
+```
+
+If your custom validator overrides `message` or passes a `default_key`, the behavior is unchanged. If you relied on `message` returning `nil` when no custom message and no default key were set, it now yields to the block instead.
+
+#### `ContractScopeValidator` No Longer Inherits from `Base`
+
+`ContractScopeValidator` is now a standalone class that no longer inherits from `Grape::Validations::Validators::Base`. Its constructor takes a single `schema:` keyword argument instead of the standard 5-argument validator signature:
+
+```ruby
+# Before
+ContractScopeValidator.new(attrs, options, required, scope, opts)
+
+# After
+ContractScopeValidator.new(schema: contract)
+```
+
+#### Validator Constructor Caching
+
+All built-in validators now eagerly compute and cache values in their constructors (exception messages, option values, lambdas for proc-based defaults/values). This is transparent to API consumers but relevant if you subclass built-in validators and override `initialize` — ensure you call `super` so caching is properly set up.
+
 ### Upgrading to >= 3.1
 
 #### Explicit kwargs for `namespace` and `route_param`

lib/grape/endpoint.rb

@@ -176,7 +176,7 @@ def run
             status 204
           else
             run_filters before_validations, :before_validation
-            run_validators validations, request
+            run_validators request: request
             run_filters after_validations, :after_validation
             response_object = execute
           end
@@ -205,10 +205,13 @@ def execute
       end
     end
 
-    def run_validators(validators, request)
+    def run_validators(request:)
+      validators = inheritable_setting.route[:saved_validations]
+      return if validators.blank?
+
       validation_errors = []
 
-      ActiveSupport::Notifications.instrument('endpoint_run_validators.grape', endpoint: self, validators: validators, request: request) do
+      ActiveSupport::Notifications.instrument('endpoint_run_validators.grape', endpoint: self, validators: validators, request:) do
         validators.each do |validator|
           validator.validate(request)
         rescue Grape::Exceptions::Validation => e
@@ -237,16 +240,6 @@ def run_filters(filters, type = :other)
       end
     end
 
-    def validations
-      saved_validations = inheritable_setting.route[:saved_validations]
-      return if saved_validations.nil?
-      return enum_for(:validations) unless block_given?
-
-      saved_validations.each do |saved_validation|
-        yield Grape::Validations::ValidatorFactory.create_validator(saved_validation)
-      end
-    end
-
     def options?
       options[:options_route_enabled] &&
         env[Rack::REQUEST_METHOD] == Rack::OPTIONS

lib/grape/exceptions/base.rb

@@ -3,9 +3,7 @@
 module Grape
   module Exceptions
     class Base < StandardError
-      BASE_MESSAGES_KEY = 'grape.errors.messages'
-      BASE_ATTRIBUTES_KEY = 'grape.errors.attributes'
-      FALLBACK_LOCALE = :en
+      include Grape::Util::Translation
 
       attr_reader :status, :headers
 
@@ -25,50 +23,39 @@ def [](index)
       # TODO: translate attribute first
       # if BASE_ATTRIBUTES_KEY.key respond to a string message, then short_message is returned
       # if BASE_ATTRIBUTES_KEY.key respond to a Hash, means it may have problem , summary and resolution
-      def compose_message(key, **attributes)
-        short_message = translate_message(key, attributes)
+      def compose_message(key, **)
+        short_message = translate_message(key, **)
         return short_message unless short_message.is_a?(Hash)
 
-        each_steps(key, attributes).with_object(+'') do |detail_array, message|
+        each_steps(key, **).with_object(+'') do |detail_array, message|
           message << "\n#{detail_array[0]}:\n  #{detail_array[1]}" unless detail_array[1].blank?
         end
       end
 
-      def each_steps(key, attributes)
-        return enum_for(:each_steps, key, attributes) unless block_given?
+      def each_steps(key, **)
+        return enum_for(:each_steps, key, **) unless block_given?
 
-        yield 'Problem', translate_message(:"#{key}.problem", attributes)
-        yield 'Summary', translate_message(:"#{key}.summary", attributes)
-        yield 'Resolution', translate_message(:"#{key}.resolution", attributes)
+        yield 'Problem', translate_message(:"#{key}.problem", **)
+        yield 'Summary', translate_message(:"#{key}.summary", **)
+        yield 'Resolution', translate_message(:"#{key}.resolution", **)
       end
 
-      def translate_attributes(keys, options = {})
+      def translate_attributes(keys, **)
         keys.map do |key|
-          translate("#{BASE_ATTRIBUTES_KEY}.#{key}", options.merge(default: key.to_s))
+          translate(key, scope: 'grape.errors.attributes', default: key.to_s, **)
         end.join(', ')
       end
 
-      def translate_message(key, options = {})
-        case key
+      def translate_message(translation_key, **)
+        case translation_key
         when Symbol
-          translate("#{BASE_MESSAGES_KEY}.#{key}", options.merge(default: ''))
+          translate(translation_key, scope: 'grape.errors.messages', **)
+        when Hash
+          translate(translation_key[:key], scope: 'grape.errors.messages', **translation_key.except(:key))
         when Proc
-          key.call
+          translation_key.call
         else
-          key
-        end
-      end
-
-      def translate(key, options)
-        message = ::I18n.translate(key, **options)
-        message.presence || fallback_message(key, options)
-      end
-
-      def fallback_message(key, options)
-        if ::I18n.enforce_available_locales && !::I18n.available_locales.include?(FALLBACK_LOCALE)
-          key
-        else
-          ::I18n.translate(key, locale: FALLBACK_LOCALE, **options)
+          translation_key
         end
       end
     end

lib/grape/exceptions/validation.rb

@@ -3,10 +3,10 @@
 module Grape
   module Exceptions
     class Validation < Base
-      attr_accessor :params, :message_key
+      attr_reader :params, :message_key
 
       def initialize(params:, message: nil, status: nil, headers: nil)
-        @params = params
+        @params = params.is_a?(Array) ? params : [params]
         if message
           @message_key = message if message.is_a?(Symbol)
           message = translate_message(message)

lib/grape/util/translation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Translation
+      FALLBACK_LOCALE = :en
+
+      private
+
+      def translate(key, default: '', scope: nil, **)
+        message = ::I18n.translate(key, default:, scope:, **)
+        return message if message.present?
+
+        if ::I18n.enforce_available_locales && !::I18n.available_locales.include?(FALLBACK_LOCALE)
+          scope ? "#{scope}.#{key}" : key
+        else
+          ::I18n.translate(key, default:, scope:, locale: FALLBACK_LOCALE, **)
+        end
+      end
+    end
+  end
+end

lib/grape/validations/contract_scope.rb

@@ -21,13 +21,7 @@ def initialize(api, contract = nil, &block)
         end
 
         api.inheritable_setting.namespace_stackable[:contract_key_map] = key_map
-
-        validator_options = {
-          validator_class: Grape::Validations.require_validator(:contract_scope),
-          opts: { schema: contract, fail_fast: false }
-        }
-
-        api.inheritable_setting.namespace_stackable[:validations] = validator_options
+        api.inheritable_setting.namespace_stackable[:validations] = Validators::ContractScopeValidator.new(schema: contract)
       end
     end
   end

lib/grape/validations/params_scope.rb

@@ -357,7 +357,7 @@ def validates(attrs, validations)
         # 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,17 +430,14 @@ def check_coerce_with(validations)
       def coerce_type(validations, attrs, required, opts)
         check_coerce_with(validations)
 
-        return unless validations.key?(:coerce)
+        return unless validations[:coerce]
 
         coerce_options = {
           type: validations[:coerce],
           method: validations[:coerce_with],
           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 +461,15 @@ def check_incompatible_option_values(default, values, except_values)
       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)