|
1 | 1 | Upgrading Grape |
2 | 2 | =============== |
3 | 3 |
|
| 4 | +### Upgrading to >= 3.2 |
| 5 | + |
| 6 | +#### Validators Instantiated at Definition Time |
| 7 | + |
| 8 | +Previously, validators were instantiated at request time but they are now instantiated at definition time. This reduces object allocations since instances are reused across requests. |
| 9 | + |
| 10 | +#### `Grape::Util::Translation` Module |
| 11 | + |
| 12 | +I18n translation logic (translate with fallback locale) has been extracted into `Grape::Util::Translation`, included by both `Grape::Exceptions::Base` and `Grape::Validations::Validators::Base`. The `FALLBACK_LOCALE` constant has moved from `Grape::Exceptions::Base` to `Grape::Util::Translation`. |
| 13 | + |
| 14 | +#### `Grape::Exceptions::Base#translate_message` Supports Hash Messages |
| 15 | + |
| 16 | +`translate_message` now accepts a Hash with a `:key` and interpolation parameters for deferred I18n translation: |
| 17 | + |
| 18 | +```ruby |
| 19 | +# Symbol (unchanged) |
| 20 | +translate_message(:presence) |
| 21 | + |
| 22 | +# Hash (new) — key + interpolation params, translated at error-raise time |
| 23 | +translate_message({ key: :length, min: 2, max: 5 }) |
| 24 | +``` |
| 25 | + |
| 26 | +This is used by validators that need locale-sensitive messages with interpolation (e.g. `LengthValidator`, `SameAsValidator`). |
| 27 | + |
| 28 | +#### `Grape::Exceptions::Validation` Changes |
| 29 | + |
| 30 | +**`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. |
| 31 | + |
| 32 | +**`params` is now always coerced to an array.** You can now pass a single string instead of wrapping it in an array: |
| 33 | + |
| 34 | +```ruby |
| 35 | +# Before |
| 36 | +Grape::Exceptions::Validation.new(params: ['my_param'], message: 'is invalid') |
| 37 | + |
| 38 | +# After (both work, single string is now accepted) |
| 39 | +Grape::Exceptions::Validation.new(params: 'my_param', message: 'is invalid') |
| 40 | +Grape::Exceptions::Validation.new(params: ['my_param'], message: 'is invalid') |
| 41 | +``` |
| 42 | + |
| 43 | +#### `Validators::Base` Method Visibility Changes |
| 44 | + |
| 45 | +The following methods on `Grape::Validations::Validators::Base` are now **private**: `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. |
| 46 | + |
| 47 | +New private helpers have been added: |
| 48 | +- `hash_like?(obj)` — returns `obj.respond_to?(:key?)` |
| 49 | +- `option_value` — returns `@option[:value]` if present, otherwise `@option` |
| 50 | +- `scrub(value)` — scrubs invalid-encoding strings |
| 51 | +- `translate_message(key, **)` — translates a message key using the `grape.errors.messages` I18n scope with fallback locale support |
| 52 | + |
| 53 | +`validate_param!` now has a base implementation that raises `NotImplementedError`. Custom validators that override `validate!` directly are unaffected, but any subclass that relies on `validate_param!` being absent (e.g. calling `super` expecting no-op behaviour) will now receive a `NotImplementedError`. |
| 54 | + |
| 55 | +#### `Validators::Base#message` Now Accepts a Block |
| 56 | + |
| 57 | +`message` now accepts an optional block for lazy default message generation. When no custom `:message` option is set and no `default_key` is provided, the block is called: |
| 58 | + |
| 59 | +```ruby |
| 60 | +# Before |
| 61 | +def message(default_key = nil) |
| 62 | + options_key?(:message) ? @option[:message] : default_key |
| 63 | +end |
| 64 | + |
| 65 | +# After |
| 66 | +def message(default_key = nil) |
| 67 | + key = options_key?(:message) ? @option[:message] : default_key |
| 68 | + return key unless key.nil? |
| 69 | + |
| 70 | + yield if block_given? |
| 71 | +end |
| 72 | +``` |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +#### `ContractScopeValidator` No Longer Inherits from `Base` |
| 77 | + |
| 78 | +`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: |
| 79 | + |
| 80 | +```ruby |
| 81 | +# Before |
| 82 | +ContractScopeValidator.new(attrs, options, required, scope, opts) |
| 83 | + |
| 84 | +# After |
| 85 | +ContractScopeValidator.new(schema: contract) |
| 86 | +``` |
| 87 | + |
| 88 | +Because it no longer inherits from `Base`, it is not registered via `Validations.register` and will not appear in `Grape::Validations.validators`. |
| 89 | + |
| 90 | +#### `endpoint_run_validators.grape` Notification No Longer Fires Without Validators |
| 91 | + |
| 92 | +The `endpoint_run_validators.grape` ActiveSupport notification is no longer emitted for routes that have no validators. Previously it fired unconditionally (with an empty `validators` array); now the instrumentation block is skipped entirely via an early return. If your observability or tracing code subscribes to this notification and expects it for every request, you will need to handle its absence for validator-free routes. |
| 93 | + |
| 94 | +#### Validator Constructor Caching |
| 95 | + |
| 96 | +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. |
| 97 | + |
| 98 | +#### Thread Safety: `ParamScopeTracker` and Fiber-Local State |
| 99 | + |
| 100 | +`ParamsScope` instances are now shared across requests (frozen at definition time) and all per-request mutable state (array indices, qualifying params for `dependent_on`) lives in `Grape::Validations::ParamScopeTracker`, stored in a fiber-local variable (`Fiber[:grape_param_scope_tracker]`). |
| 101 | + |
| 102 | +`Endpoint#run_validators` wraps validation in `ParamScopeTracker.track {}`, which sets up and tears down the tracker around each request. This is transparent for the standard request path. |
| 103 | + |
| 104 | +**Impact on custom validators:** If you call `validator.validate!` or `@scope.full_name` directly outside of `Endpoint#run_validators` (e.g., in standalone tests), no tracker is active. Array indices in error messages will be `nil`, producing names like `items[][name]` instead of `items[0][name]`. Additionally, `ParamsScope#qualifying_params` returns an empty array (falling back to parent params) instead of the filtered array elements that satisfy a `dependent_on` condition. Wrap such calls in `Grape::Validations::ParamScopeTracker.track { }` if you need accurate indices or qualifying params. |
| 105 | + |
| 106 | +**Fiber-local, not thread-local:** The tracker uses `Fiber[]` (Ruby 3.0+) rather than `Thread.current[]`. This ensures each fiber on fiber-based servers (e.g. Falcon) gets its own tracker, preventing cross-request state leakage. |
| 107 | + |
4 | 108 | ### Upgrading to >= 3.1 |
5 | 109 |
|
6 | 110 | #### Explicit kwargs for `namespace` and `route_param` |
|
0 commit comments