Instantiate validators at definition time

[ericproulx]

Summary

Validators are now instantiated once at route definition time rather than per-request via `ValidatorFactory`. This eliminates repeated object allocation on every request and moves expensive setup (option parsing, converter building, message formatting) out of the hot path.

Because validator instances are shared across all concurrent requests they are frozen after initialization, enforced by a `Validators::Base.new` override that calls `super.freeze`. All inputs (`options`, `opts`, `attrs`) arrive pre-frozen from the DSL boundary via `DeepFreeze` and `Array#freeze`, so subclass ivars derived from them are frozen by construction. A new `Grape::Util::DeepFreeze` helper recursively freezes Hash/Array/String values while intentionally leaving Procs, coercers, Classes, and other mutable objects unfrozen.

Fix #2519

Changes

Core

• `ParamsScope#validate` instantiates the validator class directly and stores the instance in `namespace_stackable[:validations]`; removes `ValidatorFactory`
• `Endpoint#run_validators` reads validator instances directly from `saved_validations` and removes the `validations` enumerator method
• `ParamsScope` is frozen at the end of `initialize`; `element` is no longer a public reader; `parent` and `Attr#key`/`Attr#scope` changed from `attr_accessor` to `attr_reader`
• `full_path` is now cached at init time as `@full_path` (via private `build_full_path`) and exposed as an `attr_reader`, making it safe to call on a frozen scope
• `coerce_type` now receives only the pre-extracted coercion keys (`validations.extract!(:coerce, :coerce_with, :coerce_message)`) so callers don't need to delete them afterwards
• `derive_validator_options` result is frozen before being passed to validators
• `depends_on_met?` refactored to use `Enumerable#all?` with destructuring

`Validators::Base`

• `Base.new` overrides `.new` to call `super.freeze`, ensuring every validator is immutable after construction
• `@attrs` frozen via `Array(attrs).freeze`; `@option` deep-frozen via `Grape::Util::DeepFreeze.deep_freeze`
• `fail_fast?` promoted to explicit public method
• `validate_param!` promoted to `protected` with a `NotImplementedError` default
• New private helpers extracted: `validation_error!`, `hash_like?` (replaces inline `respond_to?(:key?)` checks), `option_value`, `scrub`, and a refactored `message` with optional block for computed fallbacks

`Grape::Util::DeepFreeze`

• New module with a single `deep_freeze(obj)` function
• Freezes Hash (keys + values), Array (elements), and String recursively
• Returns all other types (Proc, Class, coercers, etc.) untouched

Validator-level eager initialization

• `AllowBlankValidator`: caches `@value` and `@exception_message`
• `AllOrNoneOfValidator` / `AtLeastOneOfValidator` / `MutuallyExclusiveValidator`: cache exception messages; minor logic cleanups (`.any?`, `@attrs.length`)
• `CoerceValidator`: resolves type and builds converter at definition time; `@converter` is left unfrozen automatically (DeepFreeze skips non-Hash/Array/String types); `valid_type?` removed in favour of inline `is_a?(Types::InvalidValue)`; `params:` argument now passes a scalar instead of a single-element array
• `ContractScopeValidator`: no longer inherits from `Base`; simple `initialize(schema:)` called directly from `ContractScope`; adds standalone `fail_fast?` returning `false`
• `DefaultValidator`: pre-builds `@default_call` lambda at init; reads `@option` directly (drops separate `@default` ivar)
• `ExactlyOneOfValidator`: caches both `@exactly_one_exception_message` and `@mutual_exclusion_exception_message`
• `ExceptValuesValidator`: validates that Proc must have arity zero at init (raises `ArgumentError` otherwise); wraps value in `@excepts_call` lambda for a uniform call interface
• `LengthValidator`: uses `values_at` for option extraction
• `PresenceValidator` / `RegexpValidator` / `SameAsValidator`: cache exception messages
• `ValuesValidator`: splits into `@values_call` + `@values_is_predicate` to distinguish zero-arity collection procs from per-element predicate procs

Specs

• New `DeepFreezeSpec`
• New specs for `SameAsValidator` and `ExceptValuesValidator`
• `ContractScopeValidatorSpec` / `custom_validations_spec` updated for the new instantiation model

Test plan

• `bundle exec rspec`
• Verify no regressions in validation behaviour
• Confirm frozen validator instances raise `FrozenError` on any attempt to mutate state at request time

[github-actions]

Danger Report

No issues found.

View run

[ericproulx]

Missing UPGRADING notes. Working on it

[dblock]

Is there a tradeoff with things like @exception_message = message(:all_or_none) being always allocated? can they become class variables?

[ericproulx]

Is there a tradeoff with things like @exception_message = message(:all_or_none) being always allocated? can they become class variables?
message involves @option so it can't be a class variable.

[ericproulx]

Code review

Found 2 issues:

1. pr_description.md is committed to the repo root and tracked by git — this file should not be part of the repository.

grape/pr_description.md

Lines 1 to 5 in c4df5d3

	## Summary
	Validators are now instantiated once at route definition time rather than per-request via `ValidatorFactory`. This eliminates repeated object allocation on every request and moves expensive setup (option parsing, converter building, message formatting) out of the hot path.
	Because validator instances are shared across all concurrent requests they are frozen after initialization, enforced by a `Validators::Base.new` override that calls `freeze_state!` then `freeze`. A new `Grape::Util::DeepFreeze` helper recursively freezes Hash/Array/String values while intentionally leaving Procs, coercers, and other mutable objects unfrozen.

2. endpoint_run_validators.grape instrumentation event is no longer fired when validators is empty. run_validators now returns early before the ActiveSupport::Notifications.instrument call, so consumers subscribing to this event won't receive it for routes with no validators. The README documents this as a public API (with validators in the payload), and UPGRADING.md doesn't mention this behavioral change.

grape/lib/grape/endpoint.rb

Lines 208 to 217 in c4df5d3

	def run_validators(request:)
	validators = inheritable_setting.route[:saved_validations]
	return if validators.empty?
	validation_errors = []
	Grape::Validations::ParamScopeTracker.track do
	ActiveSupport::Notifications.instrument('endpoint_run_validators.grape', endpoint: self, validators: validators, request:) do
	validators.each do |validator|
	validator.validate(request)

🤖 Generated with Claude Code

_{If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[dblock]

Nice work. I think deep_freeze can't return on obj.frozen?.

[dblock]

So will users have to rewrite custom validators? Explain how if so with a simple example.

[numbata]

@ericproulx Hi! Was there a specific reason to remove the public accessor, or was it just not needed internally anymore after switching to @schema.call?

I rely on it in grape-oas to extract the contract schema for OpenAPI spec generation. Without the accessor we have to fall back to instance_variable_get(:@schema), which feels fragile. If there's no objection, we'd be happy to open a small PR restoring attr_reader :schema.

[numbata]

To add more context: for libraries that generate OpenAPI specs from Grape APIs, ContractScopeValidator is the only path to the Dry contract/schema when endpoints use the contract DSL. Unlike params do ... end which populates route.params, the contract DSL stores the schema exclusively inside the validator instance (via ContractScope pushing it into namespace_stackable[:validations]). There is no alternative public API to retrieve it.

With 3.2, the validator is now frozen and has no public accessor, so instance_variable_get(:@schema) is the only option. Restoring attr_reader :schema would give downstream libraries a stable interface for this.

This is how I see it now.

[ericproulx]

Hello @numbata,

Thank you for addressing the situation. It makes total sense to restore the attr_reader. You can open a PR to restore it.

Thanks

[ericproulx]

I opened the PR. Will make a release today

[ericproulx]

3.2.1 released