grape 2.4.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83e82bddb3698a0f659d7c58edcb20c2d7edd44cce6e78f31139a2cf3452da0e
-  data.tar.gz: d47076d4e1b7445029b7695b5cfcb0ddebf72a1106743817eb583f79e636c8fc
+  metadata.gz: 81a1d1ef86854a9cd7fe4d60a1207fba921bdee9f6fd53e2f9e83c648e85c2e0
+  data.tar.gz: 7a19d899e17d65141c9ce69a10e518a8d7ccec01cd1239f7c2557b77a4084ad4
 SHA512:
-  metadata.gz: a22fbee812a61d12aa8ca151cc53835df146d840173fc92d9bb4ae049b5b14a70f6d399fcd06440167312af7bd60116e8382f21424a7c8b494b0251a82e7cea5
-  data.tar.gz: cd3d6d737305696db1cb703639dcdc3d7a6a4e32c02a25fd3942bef3e91529a8acaf11bb5cd4039b108ef2c908461c233a54207d2c4f528959fd944afeac0b22
+  metadata.gz: b9ffeac5636c40b3ed53323c26eb7c5f525be4bf8268b85e4e8851cbbf2d3118e8ddc7387f81f06ef1342396cfe3af9562b5920e38548b5bf1de00536c9b136c
+  data.tar.gz: 7fed8d88f46a2d5af508fc0ab5e68333c3b2bde482b9e7b393ea12f2e38bb08b6d3fc9bd8c9f9dfe08adccc2816f2faaf89810d16138f803d1b009b1d0940f38

data/CHANGELOG.md

@@ -1,3 +1,111 @@
+### 3.2.1 (2026-04-16)
+
+#### Fixes
+* [#2680](https://github.com/ruby-grape/grape/pull/2680): Restore public `schema` reader on ContractScope validator - [@ericproulx](https://github.com/ericproulx).
+
+### 3.2.0 (2026-04-08)
+
+#### Features
+
+* [#2662](https://github.com/ruby-grape/grape/pull/2662): Extract `Grape::Util::Translation` for shared I18n fallback logic - [@ericproulx](https://github.com/ericproulx).
+* [#2656](https://github.com/ruby-grape/grape/pull/2656): Remove useless instance_variable_defined? checks - [@ericproulx](https://github.com/ericproulx).
+* [#2619](https://github.com/ruby-grape/grape/pull/2619): Remove TOC from README.md and danger-toc check - [@alexanderadam](https://github.com/alexanderadam).
+* [#2663](https://github.com/ruby-grape/grape/pull/2663): Refactor `ParamsScope` and `Parameters` DSL to use named kwargs - [@ericproulx](https://github.com/ericproulx).
+* [#2664](https://github.com/ruby-grape/grape/pull/2664): Drop `test-prof` dependency - [@ericproulx](https://github.com/ericproulx).
+* [#2665](https://github.com/ruby-grape/grape/pull/2665): Pass `attrs` directly to `AttributesIterator` instead of `validator` - [@ericproulx](https://github.com/ericproulx).
+* [#2657](https://github.com/ruby-grape/grape/pull/2657): Instantiate validators at definition time - [@ericproulx](https://github.com/ericproulx).
+* [#2667](https://github.com/ruby-grape/grape/pull/2667): Skip instrumentation in run_validators when no validators present - [@ericproulx](https://github.com/ericproulx).
+* [#2670](https://github.com/ruby-grape/grape/pull/2670): Added support for Rack 3.2.6 and better handling to rack exceptions - [@ericproulx](https://github.com/ericproulx).
+* [#2671](https://github.com/ruby-grape/grape/pull/2671): Use ruby 3.1 shorthand kwargs syntax - [@ericproulx](https://github.com/ericproulx).
+* [#2672](https://github.com/ruby-grape/grape/pull/2672): Minor ruby optimizations - [@ericproulx](https://github.com/ericproulx).
+* [#2675](https://github.com/ruby-grape/grape/pull/2675): Add `AGENTS.md` to please our future A.I. overlords - [@dblock](https://github.com/dblock).
+
+#### Fixes
+
+* [#2670](https://github.com/ruby-grape/grape/pull/2670): Fix `UnknownAuthStrategy` raised when custom auth strategy class inherits from `Grape::Middleware::Auth::Base` - [@dblock](https://github.com/dblock).
+* [#2655](https://github.com/ruby-grape/grape/pull/2655): Fix `before_each` method to handle `nil` parameter correctly - [@ericproulx](https://github.com/ericproulx).
+* [#2660](https://github.com/ruby-grape/grape/pull/2660): Fix thread safety: move mutable `ParamsScope` state (`index`, `params_meeting_dependency`) into a per-request `ParamScopeTracker` stored in `Fiber[]` - [@ericproulx](https://github.com/ericproulx).
+* [#2666](https://github.com/ruby-grape/grape/pull/2666): Endpoint cleanup and minor optimizations - [@ericproulx](https://github.com/ericproulx).
+* [#2676](https://github.com/ruby-grape/grape/pull/2676): Exclude ruby 3.2 for rails_edge - [@ericproulx](https://github.com/ericproulx).
+* [#2677](https://github.com/ruby-grape/grape/pull/2677): Update actions/checkout to v6 - [@ericproulx](https://github.com/ericproulx).
+
+### 3.1.0 (2026-01-25)
+
+#### Features
+
+* [#2629](https://github.com/ruby-grape/grape/pull/2629): Refactor Router Architecture - [@ericproulx](https://github.com/ericproulx).
+* [#2633](https://github.com/ruby-grape/grape/pull/2633): Refactor API::Instance and reorganize DSL modules - [@ericproulx](https://github.com/ericproulx).
+* [#2636](https://github.com/ruby-grape/grape/pull/2636): Refactor router to simplify method signatures and reduce duplication - [@ericproulx](https://github.com/ericproulx).
+* [#2640](https://github.com/ruby-grape/grape/pull/2640): Compute available_media_types once - [@ericproulx](https://github.com/ericproulx).
+* [#2637](https://github.com/ruby-grape/grape/pull/2637): Refactor declared method - [@ericproulx](https://github.com/ericproulx).
+* [#2639](https://github.com/ruby-grape/grape/pull/2639): Refactor mime_types_for - [@ericproulx](https://github.com/ericproulx).
+* [#2638](https://github.com/ruby-grape/grape/pull/2638): Remove unnecessary path string duplication - [@ericproulx](https://github.com/ericproulx).
+* [#2643](https://github.com/ruby-grape/grape/pull/2638): Remove `try` method in codebase - [@ericproulx](https://github.com/ericproulx).
+* [#2646](https://github.com/ruby-grape/grape/pull/2646): Call `valid_encoding?` before scrub - [@ericproulx](https://github.com/ericproulx).
+* [#2644](https://github.com/ruby-grape/grape/pull/2644): Clean useless/not valuable dependencies - [@ericproulx](https://github.com/ericproulx).
+* [#2649](https://github.com/ruby-grape/grape/pull/2644): Drop support Ruby 3.0 and ActiveSupport 7.0 - [@ericproulx](https://github.com/ericproulx).
+* [#2648](https://github.com/ruby-grape/grape/pull/2648): Remove deprecated ParamsBuilders extensions - [@ericproulx](https://github.com/ericproulx).
+* [#2645](https://github.com/ruby-grape/grape/pull/2645): Endpoints are compiled when API is compiled - [@ericproulx](https://github.com/ericproulx).
+* [#2647](https://github.com/ruby-grape/grape/pull/2647): Explicit kwargs for `namespace` and `route_param` - [@ericproulx](https://github.com/ericproulx).
+* [#2651](https://github.com/ruby-grape/grape/pull/2651): Migrate Danger to use danger-pr-comment workflow - [@dblock](https://github.com/dblock).
+
+#### Fixes
+    
+* [#2633](https://github.com/ruby-grape/grape/pull/2633): Fix cascade reading - [@ericproulx](https://github.com/ericproulx).
+* [#2641](https://github.com/ruby-grape/grape/pull/2641): Restore support for `return` in endpoint blocks - [@ericproulx](https://github.com/ericproulx).
+* [#2642](https://github.com/ruby-grape/grape/pull/2642): Fix array allocation in base_route.rb - [@ericproulx](https://github.com/ericproulx).
+* Fix `before_each` method to handle `nil` parameter correctly - [@ericproulx](https://github.com/ericproulx).
+
+### 3.0.1 (2025-11-24)
+
+#### Features
+
+* [#2625](https://github.com/ruby-grape/grape/pull/2625): Update rubocop to 1.81.7 and fix style offenses - [@ericproulx](https://github.com/ericproulx).
+* [#2626](https://github.com/ruby-grape/grape/pull/2626): Add rails 8.1 to CI test matrix - [@ericproulx](https://github.com/ericproulx).
+
+#### Fixes
+
+* [#2628](https://github.com/ruby-grape/grape/pull/2628): Fix helpers inheritance - [@giorni](https://github.com/giorni).
+
+### 3.0.0 (2025-11-15)
+
+#### Features
+
+* [#2572](https://github.com/ruby-grape/grape/pull/2572): Drop support ruby 2.7 and active_support 6.1 - [@ericproulx](https://github.com/ericproulx).
+* [#2573](https://github.com/ruby-grape/grape/pull/2573): Clean up deprecated code - [@ericproulx](https://github.com/ericproulx).
+* [#2575](https://github.com/ruby-grape/grape/pull/2575): Refactor Api description class - [@ericproulx](https://github.com/ericproulx).
+* [#2577](https://github.com/ruby-grape/grape/pull/2577): Deprecate `return` in endpoint execution - [@ericproulx](https://github.com/ericproulx).
+* [#2580](https://github.com/ruby-grape/grape/pull/2580): Refactor endpoint helpers and error middleware integration - [@ericproulx](https://github.com/ericproulx).
+* [#2581](https://github.com/ruby-grape/grape/pull/2581): Delegate `to_s` in Grape::API::Instance - [@ericproulx](https://github.com/ericproulx).
+* [#2582](https://github.com/ruby-grape/grape/pull/2582): Fix leaky slash when normalizing - [@ericproulx](https://github.com/ericproulx).
+* [#2583](https://github.com/ruby-grape/grape/pull/2583): Optimize api parameter documentation and memory usage - [@ericproulx](https://github.com/ericproulx).
+* [#2589](https://github.com/ruby-grape/grape/pull/2589): Replace `send` by `__send__` in codebase - [@ericproulx](https://github.com/ericproulx).
+* [#2598](https://github.com/ruby-grape/grape/pull/2598): Refactor settings DSL to use explicit methods instead of dynamic generation - [@ericproulx](https://github.com/ericproulx).
+* [#2599](https://github.com/ruby-grape/grape/pull/2599): Simplify settings DSL get_or_set method and optimize logger implementation - [@ericproulx](https://github.com/ericproulx).
+* [#2600](https://github.com/ruby-grape/grape/pull/2600): Refactor versioner middleware: simplify base class and improve consistency - [@ericproulx](https://github.com/ericproulx).
+* [#2601](https://github.com/ruby-grape/grape/pull/2601): Refactor route_setting internal usage to use inheritable_setting.route for improved consistency and performance - [@ericproulx](https://github.com/ericproulx).
+* [#2602](https://github.com/ruby-grape/grape/pull/2602): Remove `namespace_reverse_stackable` from public DSL interface and use direct inheritable_setting access - [@ericproulx](https://github.com/ericproulx).
+* [#2603](https://github.com/ruby-grape/grape/pull/2603): Remove `namespace_stackable_with_hash` from public interface and move to internal InheritableSetting - [@ericproulx](https://github.com/ericproulx).
+* [#2604](https://github.com/ruby-grape/grape/pull/2604): Enable branch coverage  - [@ericproulx](https://github.com/ericproulx).
+* [#2605](https://github.com/ruby-grape/grape/pull/2605): Add Rack 3.2 support with new gemfile and CI integration - [@ericproulx](https://github.com/ericproulx).
+* [#2607](https://github.com/ruby-grape/grape/pull/2607): Remove namespace_stackable and namespace_inheritable from public API - [@ericproulx](https://github.com/ericproulx).
+* [#2615](https://github.com/ruby-grape/grape/pull/2615): Remove manual toc and tod danger check - [@alexanderadam](https://github.com/alexanderadam).
+* [#2612](https://github.com/ruby-grape/grape/pull/2612): Avoid multiple mount pollution - [@alexanderadam](https://github.com/alexanderadam).
+* [#2617](https://github.com/ruby-grape/grape/pull/2617): Migrate from `ActiveSupport::Configurable` to `Dry::Configurable` - [@ericproulx](https://github.com/ericproulx).
+* [#2618](https://github.com/ruby-grape/grape/pull/2618): Modernize argument delegation for Ruby 3+ compatibility - [@ericproulx](https://github.com/ericproulx).
+* [#2623](https://github.com/ruby-grape/grape/pull/2623): Refactor coercer caching to use `Grape::Util::Cache` - [@ericproulx](https://github.com/ericproulx).
+
+#### Fixes
+
+* [#2586](https://github.com/ruby-grape/grape/pull/2586): Limit helpers DSL public scope - [@ericproulx](https://github.com/ericproulx).
+* [#2588](https://github.com/ruby-grape/grape/pull/2588): Fix defaut format regression on */* - [@ericproulx](https://github.com/ericproulx).
+* [#2593](https://github.com/ruby-grape/grape/pull/2593): Fix warning message when overriding global registry key - [@ericproulx](https://github.com/ericproulx).
+* [#2594](https://github.com/ruby-grape/grape/pull/2594): Fix routes memoization - [@ericproulx](https://github.com/ericproulx).
+* [#2595](https://github.com/ruby-grape/grape/pull/2595): Keep `within_namespace` as part of our internal api - [@ericproulx](https://github.com/ericproulx).
+* [#2596](https://github.com/ruby-grape/grape/pull/2596): Remove `namespace_reverse_stackable_with_hash` from public scope - [@ericproulx](https://github.com/ericproulx).
+* [#2621](https://github.com/ruby-grape/grape/pull/2621): Update upgrading notes regarding `return` usage and simplify endpoint execution - [@ericproulx](https://github.com/ericproulx).
+* [#2622](https://github.com/ruby-grape/grape/pull/2622): Use `require_relative` instead of `$LOAD_PATH` in gemspec - [@ericproulx](https://github.com/ericproulx).
+
 ### 2.4.0 (2025-06-18)
 
 #### Features
@@ -1165,3 +1273,4 @@
 ### 0.1.0 (2010/11/13)
 
 * Initial public release - [@mbleigh](https://github.com/mbleigh).
+

data/CONTRIBUTING.md

@@ -48,8 +48,8 @@ Here are some examples:
 - running rspec on a specific file `docker-compose run --rm --build grape rspec spec/:file_path`
 - running task `docker-compose run --rm --build grape rake <task_name>`
 - running rubocop `docker-compose run --rm --build grape rubocop`
-- running all specs on a specific ruby version (e.g 2.7.7) `RUBY_VERSION=2.7.7 docker-compose run --rm --build grape rspec`
-- running specs on a specific gemfile (e.g rails_7_0.gemfile) `docker-compose run -e GEMFILE=rails_7_0 --rm --build grape rspec`
+- running all specs on a specific ruby version (e.g 3.4) `RUBY_VERSION=3.4 docker-compose run --rm --build grape rspec`
+- running specs on a specific gemfile (e.g rails_8_1.gemfile) `docker-compose run -e GEMFILE=rails_8_1 --rm --build grape rspec`
 
 #### Bundle Install and Test
 
@@ -60,14 +60,6 @@ bundle install
 bundle exec rake
 ```
 
-Run tests against all supported versions of Rails.
-
-```
-gem install appraisal
-appraisal install
-appraisal rake spec
-```
-
 #### Write Tests
 
 Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [spec/grape](spec/grape).

data/README.md

@@ -4,160 +4,13 @@
 [![test](https://github.com/ruby-grape/grape/actions/workflows/test.yml/badge.svg)](https://github.com/ruby-grape/grape/actions/workflows/test.yml)
 [![Coverage Status](https://coveralls.io/repos/github/ruby-grape/grape/badge.svg?branch=master)](https://coveralls.io/github/ruby-grape/grape?branch=master)
 
-## Table of Contents
-
-- [What is Grape?](#what-is-grape)
-- [Stable Release](#stable-release)
-- [Project Resources](#project-resources)
-- [Grape for Enterprise](#grape-for-enterprise)
-- [Installation](#installation)
-- [Basic Usage](#basic-usage)
-- [Rails 7.1](#rails-71)
-- [Mounting](#mounting)
-  - [All](#all)
-  - [Rack](#rack)
-  - [Alongside Sinatra (or other frameworks)](#alongside-sinatra-or-other-frameworks)
-  - [Rails](#rails)
-    - [Zeitwerk](#zeitwerk)
-  - [Modules](#modules)
-- [Remounting](#remounting)
-  - [Mount Configuration](#mount-configuration)
-- [Versioning](#versioning)
-  - [Strategies](#strategies)
-    - [Path](#path)
-    - [Header](#header)
-    - [Accept-Version Header](#accept-version-header)
-    - [Param](#param)
-- [Linting](#linting)
-  - [Bug in Rack::ETag under Rack 3.X](#bug-in-racketag-under-rack-3x)
-- [Describing Methods](#describing-methods)
-- [Configuration](#configuration)
-- [Parameters](#parameters)
-  - [Params Class](#params-class)
-  - [Declared](#declared)
-  - [Include Parent Namespaces](#include-parent-namespaces)
-  - [Include Missing](#include-missing)
-  - [Evaluate Given](#evaluate-given)
-  - [Parameter Precedence](#parameter-precedence)
-- [Parameter Validation and Coercion](#parameter-validation-and-coercion)
-  - [Supported Parameter Types](#supported-parameter-types)
-  - [Integer/Fixnum and Coercions](#integerfixnum-and-coercions)
-  - [Custom Types and Coercions](#custom-types-and-coercions)
-  - [Multipart File Parameters](#multipart-file-parameters)
-  - [First-Class JSON Types](#first-class-json-types)
-  - [Multiple Allowed Types](#multiple-allowed-types)
-  - [Validation of Nested Parameters](#validation-of-nested-parameters)
-  - [Dependent Parameters](#dependent-parameters)
-  - [Group Options](#group-options)
-  - [Renaming](#renaming)
-  - [Built-in Validators](#built-in-validators)
-    - [allow_blank](#allow_blank)
-    - [values](#values)
-    - [except_values](#except_values)
-    - [same_as](#same_as)
-    - [length](#length)
-    - [regexp](#regexp)
-    - [mutually_exclusive](#mutually_exclusive)
-    - [exactly_one_of](#exactly_one_of)
-    - [at_least_one_of](#at_least_one_of)
-    - [all_or_none_of](#all_or_none_of)
-    - [Nested mutually_exclusive, exactly_one_of, at_least_one_of, all_or_none_of](#nested-mutually_exclusive-exactly_one_of-at_least_one_of-all_or_none_of)
-  - [Namespace Validation and Coercion](#namespace-validation-and-coercion)
-  - [Custom Validators](#custom-validators)
-  - [Validation Errors](#validation-errors)
-  - [I18n](#i18n)
-  - [Custom Validation messages](#custom-validation-messages)
-    - [presence, allow_blank, values, regexp](#presence-allow_blank-values-regexp)
-    - [same_as](#same_as-1)
-    - [length](#length-1)
-    - [all_or_none_of](#all_or_none_of-1)
-    - [mutually_exclusive](#mutually_exclusive-1)
-    - [exactly_one_of](#exactly_one_of-1)
-    - [at_least_one_of](#at_least_one_of-1)
-    - [Coerce](#coerce)
-    - [With Lambdas](#with-lambdas)
-    - [Pass symbols for i18n translations](#pass-symbols-for-i18n-translations)
-    - [Overriding Attribute Names](#overriding-attribute-names)
-    - [With Default](#with-default)
-  - [Using dry-validation or dry-schema](#using-dry-validation-or-dry-schema)
-- [Headers](#headers)
-  - [Request](#request)
-    - [Header Case Handling](#header-case-handling)
-  - [Response](#response)
-- [Routes](#routes)
-- [Helpers](#helpers)
-- [Path Helpers](#path-helpers)
-- [Parameter Documentation](#parameter-documentation)
-- [Cookies](#cookies)
-- [HTTP Status Code](#http-status-code)
-- [Redirecting](#redirecting)
-- [Recognizing Path](#recognizing-path)
-- [Allowed Methods](#allowed-methods)
-- [Raising Exceptions](#raising-exceptions)
-  - [Default Error HTTP Status Code](#default-error-http-status-code)
-  - [Handling 404](#handling-404)
-- [Exception Handling](#exception-handling)
-    - [Rescuing exceptions inside namespaces](#rescuing-exceptions-inside-namespaces)
-    - [Unrescuable Exceptions](#unrescuable-exceptions)
-    - [Exceptions that should be rescued explicitly](#exceptions-that-should-be-rescued-explicitly)
-- [Logging](#logging)
-- [API Formats](#api-formats)
-  - [JSONP](#jsonp)
-  - [CORS](#cors)
-- [Content-type](#content-type)
-- [API Data Formats](#api-data-formats)
-- [JSON and XML Processors](#json-and-xml-processors)
-- [RESTful Model Representations](#restful-model-representations)
-  - [Grape Entities](#grape-entities)
-  - [Hypermedia and Roar](#hypermedia-and-roar)
-  - [Rabl](#rabl)
-  - [Active Model Serializers](#active-model-serializers)
-- [Sending Raw or No Data](#sending-raw-or-no-data)
-- [Authentication](#authentication)
-  - [Basic Auth](#basic-auth)
-  - [Register custom middleware for authentication](#register-custom-middleware-for-authentication)
-- [Describing and Inspecting an API](#describing-and-inspecting-an-api)
-- [Current Route and Endpoint](#current-route-and-endpoint)
-- [Before, After and Finally](#before-after-and-finally)
-- [Anchoring](#anchoring)
-- [Instance Variables](#instance-variables)
-- [Using Custom Middleware](#using-custom-middleware)
-  - [Grape Middleware](#grape-middleware)
-  - [Rails Middleware](#rails-middleware)
-  - [Remote IP](#remote-ip)
-- [Writing Tests](#writing-tests)
-  - [Writing Tests with Rack](#writing-tests-with-rack)
-    - [RSpec](#rspec)
-    - [Airborne](#airborne)
-    - [MiniTest](#minitest)
-  - [Writing Tests with Rails](#writing-tests-with-rails)
-    - [RSpec](#rspec-1)
-    - [MiniTest](#minitest-1)
-  - [Stubbing Helpers](#stubbing-helpers)
-- [Reloading API Changes in Development](#reloading-api-changes-in-development)
-  - [Reloading in Rack Applications](#reloading-in-rack-applications)
-  - [Reloading in Rails Applications](#reloading-in-rails-applications)
-- [Performance Monitoring](#performance-monitoring)
-  - [Active Support Instrumentation](#active-support-instrumentation)
-    - [endpoint_run.grape](#endpoint_rungrape)
-    - [endpoint_render.grape](#endpoint_rendergrape)
-    - [endpoint_run_filters.grape](#endpoint_run_filtersgrape)
-    - [endpoint_run_validators.grape](#endpoint_run_validatorsgrape)
-    - [format_response.grape](#format_responsegrape)
-  - [Monitoring Products](#monitoring-products)
-- [Contributing to Grape](#contributing-to-grape)
-- [Security](#security)
-- [License](#license)
-- [Copyright](#copyright)
-
 ## What is Grape?
 
 Grape is a REST-like API framework for Ruby. It's designed to run on Rack or complement existing web application frameworks such as Rails and Sinatra by providing a simple DSL to easily develop RESTful APIs. It has built-in support for common conventions, including multiple formats, subdomain/prefix restriction, content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, 2.4.0.
-Please read [UPGRADING](https://github.com/ruby-grape/grape/blob/v2.4.0/UPGRADING.md) when upgrading from a previous version.
+You're reading the documentation for the stable release of Grape, 3.2.1.
 
 ## Project Resources
 
@@ -174,7 +27,7 @@ The maintainers of Grape are working with Tidelift to deliver commercial support
 
 ## Installation
 
-Ruby 2.7 or newer is required.
+Ruby 3.2 or newer is required.
 
 Grape is available as a gem, to install it run:
 
@@ -1920,9 +1773,9 @@ end
 ```ruby
 class AlphaNumeric < Grape::Validations::Validators::Base
   def validate_param!(attr_name, params)
-    unless params[attr_name] =~ /\A[[:alnum:]]+\z/
-      raise Grape::Exceptions::Validation.new params: [@scope.full_name(attr_name)], message: 'must consist of alpha-numeric characters'
-    end
+    return if params[attr_name].match?(/\A[[:alnum:]]+\z/)
+
+    validation_error!(attr_name, 'must consist of alpha-numeric characters')
   end
 end
 ```
@@ -1938,9 +1791,9 @@ You can also create custom classes that take parameters.
 ```ruby
 class Length < Grape::Validations::Validators::Base
   def validate_param!(attr_name, params)
-    unless params[attr_name].length <= @option
-      raise Grape::Exceptions::Validation.new params: [@scope.full_name(attr_name)], message: "must be at the most #{@option} characters long"
-    end
+    return if params[attr_name].length <= @options
+
+    validation_error!(attr_name, "must be at the most #{@options} characters long")
   end
 end
 ```
@@ -1962,10 +1815,10 @@ class Admin < Grape::Validations::Validators::Base
     # @attrs being [:admin_field] and once with @attrs being [:admin_false_field]
     return unless request.params.key?(@attrs.first)
     # check if admin flag is set to true
-    return unless @option
+    return unless @options
     # check if user is admin or not
     # as an example get a token from request and check if it's admin or not
-    raise Grape::Exceptions::Validation.new params: @attrs, message: 'Can not set admin-only field.' unless request.headers['X-Access-Token'] == 'admin'
+    validation_error!(@attrs, 'Can not set admin-only field.') unless request.headers['X-Access-Token'] == 'admin'
   end
 end
 ```
@@ -1980,7 +1833,50 @@ params do
 end
 ```
 
-Every validation will have its own instance of the validator, which means that the validator can have a state.
+Each validator is instantiated once at route definition time and frozen. Any setup (option parsing, message building) should happen in `initialize`, not in `validate_param!` or `validate`.
+
+#### Available helpers
+
+The following protected/private helpers are available in any `Grape::Validations::Validators::Base` subclass:
+
+| Helper | Description |
+|---|---|
+| `default_message_key(key)` | Class-level macro. Declares the default I18n key for `validation_error!`. A per-option `:message` override still takes precedence. |
+| `validation_error!(attr_name_or_params, message = @exception_message)` | Raises `Grape::Exceptions::Validation`. Accepts a single attribute name or a pre-computed array of full param names. |
+| `@options` | The validator option value, deep-frozen at initialization. |
+| `@attrs` | Frozen array of attribute names this validator applies to. |
+| `@scope` | The `ParamsScope` — use `@scope.full_name(attr_name)` for the fully-qualified param name. |
+| `option_value` | Returns `@options[:value]` if present, otherwise `@options`. |
+| `options_key?(key)` | Returns true if `@options` is a hash with a non-nil `key`. |
+| `hash_like?(obj)` | Returns true if `obj` responds to `key?`. |
+| `scrub(value)` | Returns `value` with invalid byte sequences scrubbed. |
+| `translate(key, **opts)` | I18n lookup with `:en` fallback and `grape.errors.messages` scope. Called at request time to respect per-request locale. |
+
+Use `default_message_key` for a fixed I18n key. The message is resolved once at route definition time via `message`, so a per-option `:message` override still wins:
+
+```ruby
+class SpecialValidator < Grape::Validations::Validators::Base
+  default_message_key :special
+
+  def validate_param!(attr_name, params)
+    return if valid?(params[attr_name])
+
+    validation_error!(attr_name)
+  end
+end
+```
+
+For interpolated messages that must respect per-request locale, call `translate` directly inside `validate_param!`:
+
+```ruby
+class SpecialValidator < Grape::Validations::Validators::Base
+  def validate_param!(attr_name, params)
+    return if valid?(params[attr_name])
+
+    validation_error!(attr_name, translate(:special, min: 2, max: 10))
+  end
+end
+```
 
 ### Validation Errors
 
@@ -2042,6 +1938,28 @@ Grape supports I18n for parameter-related error messages, but will fallback to E
 
 In case your app enforces available locales only and :en is not included in your available locales, Grape cannot fall back to English and will return the translation key for the error message. To avoid this behaviour, either provide a translation for your default locale or add :en to your available locales.
 
+Custom validators that inherit from `Grape::Validations::Validators::Base` have access to a `translate` helper (see `Grape::Util::Translation`) and should use it instead of calling `I18n` directly. It applies the same `:en` fallback as built-in validators, defaults `scope` to `'grape.errors.messages'`, and handles interpolation without needing `format`:
+
+```ruby
+# Good — scope defaults to 'grape.errors.messages', interpolation forwarded automatically
+translate(:special, min: 2, max: 10)
+
+# Bad — format is unnecessary and risks conflicting with I18n reserved keys
+format I18n.t(:special, scope: 'grape.errors.messages'), min: 2, max: 10
+```
+
+Example custom validator using an interpolated i18n message:
+
+```ruby
+class SpecialValidator < Grape::Validations::Validators::Base
+  def validate_param!(attr_name, params)
+    return if valid?(params[attr_name])
+
+    validation_error!(attr_name, translate(:special, min: 2, max: 10))
+  end
+end
+```
+
 ### Custom Validation messages
 
 Grape supports custom validation messages for parameter-related and coerce-related error messages.
@@ -4077,6 +3995,25 @@ Use [grape-reload](https://github.com/AlexYankee/grape-reload).
 
 ### Reloading in Rails Applications
 
+#### Rails 7+ (Zeitwerk)
+
+Rails 7+ uses [Zeitwerk](https://github.com/fxn/zeitwerk) as the default autoloader, which automatically handles reloading of code in development mode without any additional configuration.
+
+If your API files are in `app/api`, Zeitwerk will automatically autoload and reload them. No additional configuration is needed.
+
+If you encounter issues with reloading, ensure that:
+
+1. Your API files follow Zeitwerk naming conventions (file names should match class names).
+2. The `config.enable_reloading` is set to `true` in `config/environments/development.rb` (this is the default).
+
+For troubleshooting autoloading issues, have a look at the [Rails documentation](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html#troubleshooting).
+
+See the [Rails Autoloading and Reloading Constants guide](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html) for more information.
+
+#### Rails 6 and Earlier
+
+For Rails versions before 7, you need to configure reloading manually.
+
 Add API paths to `config/application.rb`.
 
 ```ruby
@@ -4095,28 +4032,12 @@ if Rails.env.development?
   api_reloader = ActiveSupport::FileUpdateChecker.new(api_files) do
     Rails.application.reload_routes!
   end
-  ActionDispatch::Callbacks.to_prepare do
+  ActiveSupport::Reloader.to_prepare do
     api_reloader.execute_if_updated
   end
 end
 ```
 
-For Rails >= 5.1.4, change this:
-
-```ruby
-ActionDispatch::Callbacks.to_prepare do
-  api_reloader.execute_if_updated
-end
-```
-
-to this:
-
-```ruby
-ActiveSupport::Reloader.to_prepare do
-  api_reloader.execute_if_updated
-end
-```
-
 See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-rails-3-reload-lib-directory-for-each-request/4368838#4368838) for more information.
 
 ## Performance Monitoring
@@ -4125,27 +4046,30 @@ See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-
 
 Grape has built-in support for [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) which provides simple hook points to instrument key parts of your application.
 
-The following are currently supported:
 
-#### endpoint_run.grape
+#### Hook Points
+
+The following hook points are currently supported:
+
+##### endpoint_run.grape
 
 The main execution of an endpoint, includes filters and rendering.
 
 * *endpoint* - The endpoint instance
 
-#### endpoint_render.grape
+##### endpoint_render.grape
 
 The execution of the main content block of the endpoint.
 
 * *endpoint* - The endpoint instance
 
-#### endpoint_run_filters.grape
+##### endpoint_run_filters.grape
 
 * *endpoint* - The endpoint instance
 * *filters* - The filters being executed
 * *type* - The type of filters (before, before_validation, after_validation, after)
 
-#### endpoint_run_validators.grape
+##### endpoint_run_validators.grape
 
 The execution of validators.
 
@@ -4153,7 +4077,7 @@ The execution of validators.
 * *validators* - The validators being executed
 * *request* - The request being validated
 
-#### format_response.grape
+##### format_response.grape
 
 Serialization or template rendering.
 
@@ -4162,12 +4086,44 @@ Serialization or template rendering.
 
 See the [ActiveSupport::Notifications documentation](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) for information on how to subscribe to these events.
 
+#### Subscribe to Hooks
+
+Once subscribed to the instrumentation, you can intercept the events reported above.
+
+```ruby
+ActiveSupport::Notifications.subscribe(/<api_path>/) do |name, start, finish, id, payload|
+  # your code to intercept the notification
+end
+```
+
+The request data, the API’s internal data, and the response can be retrieved from the payload.
+
+You can use `payload.fetch(:endpoint)` or directly `payload[:endpoint]`.
+
+The `:endpoint` contains the data currently being processed, and access to attributes such as `body`, `request`, `params`, `headers`, `cookies` and `response_cookies`
+
+For example, `payload[:endpoint].body` provides the current state of the response.
+
+```ruby
+ActiveSupport::Notifications.subscribe(/v1/) do |name, start, finish, id, payload|
+  hook_record = {
+    hook: name
+    status: payload[:env]&.dig("api.endpoint")&.status
+    format: payload[:env]&.dig("api.format")
+    body: payload[:endpoint]&.body
+    duration: (finish - start) * 1000
+  }
+  # your code to save the notification
+end
+```
+
 ### Monitoring Products
 
 Grape integrates with following third-party tools:
 
 * **New Relic** - [built-in support](https://docs.newrelic.com/docs/agents/ruby-agent/frameworks/grape-instrumentation) from v3.10.0 of the official [newrelic_rpm](https://github.com/newrelic/rpm) gem, also [newrelic-grape](https://github.com/xinminlabs/newrelic-grape) gem
 * **Librato Metrics** - [grape-librato](https://github.com/seanmoon/grape-librato) gem
+* **Rails Performance** - [rails_performance](https://github.com/igorkasyanchuk/rails_performance) gem
 * **[Skylight](https://www.skylight.io/)** - [skylight](https://github.com/skylightio/skylight-ruby) gem, [documentation](https://docs.skylight.io/grape/)
 * **[AppSignal](https://www.appsignal.com)** - [appsignal-ruby](https://github.com/appsignal/appsignal-ruby) gem, [documentation](http://docs.appsignal.com/getting-started/supported-frameworks.html#grape)
 * **[ElasticAPM](https://www.elastic.co/products/apm)** - [elastic-apm](https://github.com/elastic/apm-agent-ruby) gem, [documentation](https://www.elastic.co/guide/en/apm/agent/ruby/3.x/getting-started-rack.html#getting-started-grape)