grape 2.4.0 → 4.0.1

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, 4.0.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.3 or newer is required.
 
 Grape is available as a gem, to install it run:
 
@@ -458,7 +311,7 @@ mount ::Some::Api => '/some/api', with: { condition: true }
 
 You can access `configuration` on the class (to use as dynamic attributes), inside blocks (like namespace)
 
-If you want logic happening given on an `configuration`, you can use the helper `given`.
+If you want logic happening based on a `configuration`, you can use the helper `given`.
 
 ```ruby
 class ConditionalEndpoint::API < Grape::API
@@ -609,7 +462,7 @@ vnd.vendor-and-or-resource-v1234+format
 
 Basically all tokens between the final `-` and the `+` will be interpreted as the version.
 
-Using this versioning strategy, clients should pass the desired version in the HTTP `Accept` head.
+Using this versioning strategy, clients should pass the desired version in the HTTP `Accept` header.
 
     curl -H Accept:application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline
 
@@ -631,7 +484,7 @@ Using this versioning strategy, clients should pass the desired version in the H
 
     curl -H "Accept-Version:v1" http://localhost:9292/statuses/public_timeline
 
-By default, the first matching version is used when no `Accept-Version` header is supplied. This behavior is similar to routing in Rails. To circumvent this default behavior, one could use the `:strict` option. When this option is set to `true`, a `406 Not Acceptable` error is returned when no correct `Accept` header is supplied and the `:cascade` option is set to `false`. Otherwise a `404 Not Found` error is returned by Rack if no other route matches.
+By default, the first matching version is used when no `Accept-Version` header is supplied. This behavior is similar to routing in Rails. To circumvent this default behavior, one could use the `:strict` option. When this option is set to `true`, a `406 Not Acceptable` error is returned when no correct `Accept-Version` header is supplied and the `:cascade` option is set to `false`. Otherwise a `404 Not Found` error is returned by Rack if no other route matches.
 
 #### Param
 
@@ -671,13 +524,13 @@ Grape.config.lint = true
 ```
 
 ### Bug in Rack::ETag under Rack 3.X
-If you're using Rack 3.X and the `Rack::Etag` middleware (used by [Rails](https://guides.rubyonrails.org/rails_on_rack.html#inspecting-middleware-stack)), a [bug](https://github.com/rack/rack/pull/2324) related to linting has been fixed in [3.1.13](https://github.com/rack/rack/blob/v3.1.13/CHANGELOG.md#3113---2025-04-13) and [3.0.15](https://github.com/rack/rack/blob/v3.1.13/CHANGELOG.md#3015---2025-04-13) respectively.
+If you're using Rack 3.X and the `Rack::ETag` middleware (used by [Rails](https://guides.rubyonrails.org/rails_on_rack.html#inspecting-middleware-stack)), a [bug](https://github.com/rack/rack/pull/2324) related to linting has been fixed in [3.1.13](https://github.com/rack/rack/blob/v3.1.13/CHANGELOG.md#3113---2025-04-13) and [3.0.15](https://github.com/rack/rack/blob/v3.1.13/CHANGELOG.md#3015---2025-04-13) respectively.
 
 ## Describing Methods
 
 You can add a description to API methods and namespaces. The description would be used by [grape-swagger][grape-swagger] to generate swagger compliant documentation.
 
-Note: Description block is only for documentation and won't affects API behavior.
+Note: Description block is only for documentation and won't affect API behavior.
 
 ```ruby
 desc 'Returns your public timeline.' do
@@ -713,7 +566,7 @@ end
 * `params`: Define parameters directly from an `Entity`
 * `success`: (former entity) The `Entity` to be used to present the success response for this route.
 * `failure`: (former http_codes) A definition of the used failure HTTP Codes and Entities.
-* `default`: The definition and `Entity` used to present the default response for this route.
+* `default_response`: (former `default`) The definition and `Entity` used to present the default response for this route.
 * `named`: A helper to give a route a name and find it with this name in the documentation Hash
 * `headers`: A definition of the used Headers
 * Other options can be found in [grape-swagger][grape-swagger]
@@ -726,6 +579,7 @@ Use `Grape.configure` to set up global settings at load time.
 Currently the configurable settings are:
 
 * `param_builder`: Sets the [Parameter Builder](#parameters), defaults to `Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder`.
+* `raise_rendering_errors`: Lets an error response that cannot be rendered propagate out of the middleware stack instead of being answered with a failsafe `500`, defaults to `false`. See [When the error response itself cannot be rendered](#when-the-error-response-itself-cannot-be-rendered).
 
 To change a setting value make sure that at some point during load time the following code runs
 
@@ -766,7 +620,7 @@ get :public_timeline do
 end
 ```
 
-Parameters are automatically populated from the request body on `POST` and `PUT` for form input, JSON and XML content-types.
+Parameters are automatically populated from the request body on `POST`, `PUT` and `QUERY` for form input, JSON and XML content-types.
 
 The request:
 
@@ -1329,28 +1183,6 @@ The following are all valid types, supported out of the box by Grape:
 * Rack::Multipart::UploadedFile (alias `File`)
 * JSON
 
-### Integer/Fixnum and Coercions
-
-Please be aware that the behavior differs between Ruby 2.4 and earlier versions.
-In Ruby 2.4, values consisting of numbers are converted to Integer, but in earlier versions it will be treated as Fixnum.
-
-```ruby
-params do
-  requires :integers, type: Hash do
-    requires :int, coerce: Integer
-  end
-end
-get '/int' do
-  params[:integers][:int].class
-end
-
-...
-
-get '/int' integers: { int: '45' }
-  #=> Integer in ruby 2.4
-  #=> Fixnum in earlier ruby versions
-```
-
 ### Custom Types and Coercions
 
 Aside from the default set of supported types listed above, any class can be used as a type as long as an explicit coercion method is supplied. If the type implements a class-level `parse` method, Grape will use it automatically. This method must take one string argument and return an instance of the correct type, or return an instance of `Grape::Types::InvalidValue` which optionally accepts a message to be returned in the response.
@@ -1503,6 +1335,56 @@ end
 client.get('/', status_codes: %w(1 two)) # => [1, "two"]
 ```
 
+### Multiple Hash Schemas with `oneof`
+
+A Hash parameter that may take one of several different shapes can be declared with the `oneof:` option. Each variant is a `Proc` that uses the normal `params` DSL — so the full validator surface (`requires`, `optional`, `regexp:`, `values:`, `allow_blank:`, nested `Hash`/`Array`, etc.) is available inside.
+
+```ruby
+params do
+  requires :value, type: Hash, oneof: [
+    proc { requires :fixed_price, type: Float },
+    proc do
+      requires :time_unit, type: String
+      requires :rate, type: Float
+    end
+  ]
+end
+post '/pricing' do
+  params[:value]
+end
+```
+
+Both of these requests succeed:
+
+```bash
+curl -d '{"value":{"fixed_price":100.0}}' -H 'Content-Type: application/json' /pricing
+curl -d '{"value":{"time_unit":"hour","rate":50.0}}' -H 'Content-Type: application/json' /pricing
+```
+
+A request that doesn't match any variant returns `400` with `value does not match any of the allowed schemas`.
+
+Variants are tried in declaration order; the first variant that validates without errors wins, and any coercions it performed (e.g. `"150.5"` → `150.5`) are applied to the request params. Nested hash structures inside variants work the same as elsewhere in Grape:
+
+```ruby
+params do
+  requires :options, type: Hash, oneof: [
+    proc do
+      requires :form, type: Hash do
+        requires :colour, type: String
+        optional :size, type: Integer
+      end
+    end,
+    proc do
+      requires :api, type: Hash do
+        requires :authenticated, type: Grape::API::Boolean
+      end
+    end
+  ]
+end
+```
+
+`oneof:` requires `type: Hash`. The variants array must be non-empty and each entry must be a `Proc`; violating either raises an `ArgumentError` at definition time.
+
 ### Validation of Nested Parameters
 
 Parameters can be nested using `group` or by calling `requires` or `optional` with a block.
@@ -1589,7 +1471,7 @@ params do
 end
 ```
 
-You can organize settings into layers using nested `with' blocks. Each layer can use, add to, or change the settings of the layer above it. This helps to keep complex parameters organized and consistent, while still allowing for specific customizations to be made.
+You can organize settings into layers using nested `with` blocks. Each layer can use, add to, or change the settings of the layer above it. This helps to keep complex parameters organized and consistent, while still allowing for specific customizations to be made.
 
 ```ruby
 params do
@@ -1677,6 +1559,27 @@ params do
 end
 ```
 
+An exclusive upper bound is expressed with the standard Ruby `...` range (three dots). Ruby has no range syntax for an exclusive *lower* bound; an arity-one `:values` Proc predicate (see below) is the recommended way to express one, though excluding a specific endpoint (e.g. zero) via `:except_values` also works:
+
+```ruby
+params do
+  requires :score,    type: Float, values: 0.0...5.0                    # 0.0 <= score < 5.0
+  requires :positive, type: Float, values: ->(v) { v > 0.0 }            # amount > 0.0 (recommended)
+  requires :other,    type: Float, values: 0.0.., except_values: [0.0]  # amount > 0.0 (alternative)
+end
+```
+
+Combined with `:type`, ranges (open or closed) cover common numeric bound checks without a dedicated validator:
+
+```ruby
+params do
+  requires :quantity, type: Integer, values: 1..       # must be a positive integer
+  requires :discount, type: Float, values: 0.0..100.0  # must be between 0 and 100
+  requires :rating,   type: Integer, values: 5..5      # must be exactly 5
+  requires :numbers,  type: [Integer], values: 1..     # every element must be positive
+end
+```
+
 The `:values` option can also be supplied with a `Proc`, evaluated lazily with each request.
 If the Proc has arity zero (i.e. it takes no arguments) it is expected to return either a list or a range which will then be used to validate the parameter.
 
@@ -1698,24 +1601,27 @@ end
 
 While Procs are convenient for single cases, consider using [Custom Validators](#custom-validators) in cases where a validation is used more than once.
 
-Note that [allow_blank](#allow_blank) validator applies while using `:values`. In the following example the absence of `:allow_blank` does not prevent `:state` from receiving blank values because `:allow_blank` defaults to `true`.
+When using `optional` together with `:values`, a missing key, a `nil` value, and any value that coerces to `nil` (such as `""` for `type: Symbol`) all pass validation — `optional` collapses "key may be absent" with "value may be nil". To reject blank values while still allowing the key to be absent, add `allow_blank: false`:
 
 ```ruby
 params do
-  requires :state, type: Symbol, values: [:active, :inactive]
+  optional :state, type: Symbol, values: [:active, :inactive], allow_blank: false
 end
 ```
 
+With `requires`, blank values are already rejected: `requires` enforces presence and `:values` rejects `nil`.
+
 #### `except_values`
 
 Parameters can be restricted from having a specific set of values with the `:except_values` option.
 
-The `except_values` validator behaves similarly to the `values` validator in that it accepts either an Array, a Range, or a Proc.  Unlike the `values` validator, however, `except_values` only accepts Procs with arity zero.
+The `except_values` validator behaves similarly to the `values` validator in that it accepts either an Array, a Range (including open/beginless/endless ranges), or a Proc.  Unlike the `values` validator, however, `except_values` only accepts Procs with arity zero.
 
 ```ruby
 params do
   requires :browser, except_values: [ 'ie6', 'ie7', 'ie8' ]
   requires :port, except_values: { value: 0..1024, message: 'is not allowed' }
+  requires :negative, type: Integer, except_values: ..-1
   requires :hashtag, except_values: -> { Hashtag.FORBIDDEN_LIST }
 end
 ```
@@ -1920,9 +1826,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 +1844,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 +1868,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 +1886,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
 
@@ -2023,8 +1972,8 @@ To skip all subsequent validation checks when a specific param is found invalid,
 The following example will not check if `:wine` is present unless it finds `:beer`.
 ```ruby
 params do
-  required :beer, fail_fast: true
-  required :wine
+  requires :beer, fail_fast: true
+  requires :wine
 end
 ```
 The result of empty params would be a single `Grape::Exceptions::ValidationErrors` error.
@@ -2032,7 +1981,7 @@ The result of empty params would be a single `Grape::Exceptions::ValidationError
 Similarly, no regular expression test will be performed if `:blah` is blank in the following example.
 ```ruby
 params do
-  required :blah, allow_blank: false, regexp: /blah/, fail_fast: true
+  requires :blah, allow_blank: false, regexp: /blah/, fail_fast: true
 end
 ```
 
@@ -2042,6 +1991,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.
@@ -2330,6 +2301,78 @@ namespace :outer, requirements: { id: /[0-9]*/ } do
 end
 ```
 
+A requirement can also name one of the capture types of [Mustermann](https://github.com/sinatra/mustermann), the pattern library Grape routes with, instead of a regular expression. Besides constraining the match, a capture type that carries a converter hands the endpoint the converted value rather than a String.
+
+```ruby
+get ':id', requirements: { id: Integer } do
+  params[:id] # => 23, an Integer, for GET /23 — GET /michael is a 404
+end
+
+get 'events/:on', requirements: { on: :date } do
+  params[:on] # => #<Date: 2020-01-02>, for GET /events/2020-01-02
+end
+```
+
+`Integer`, `Float`, `Symbol`, `Date` and `Gem::Version` convert, as do their symbol spellings `:integer`, `:float`, `:symbol`, `:date` and `:version`. `:uuid`, `:slug` and `:locale` constrain the match without converting. A name Mustermann has no capture type for raises when the API is defined.
+
+A `params` block still owns what the endpoint sees, since validation runs after the router: declaring `requires :id, type: String` alongside `requirements: { id: Integer }` hands the endpoint `"23"`.
+
+`route_param` names the parameter itself, so it takes the constraint on its own — `route_param :id, requirements: Integer` — and refuses a Hash, which would name the parameter a second time. A namespace or an endpoint can carry several captures, so requirements there are the Hash form keyed by param name.
+
+`route_param :id` defines the parameter on its own — `params[:id]` reaches the endpoint, and the route documents it as a path capture. `type:` and `requirements:` are two ways of typing it, and they work at different layers. `type: Integer` declares `requires :id, type: Integer`: the value is coerced, appears in `declared(params)` and carries its type into the route's documented params, and a value the path let through but the type rejects is a 400. `requirements: Integer` types the route instead: a segment that does not match is not this route at all, so it is a 404, and the value arrives already converted by the router, undeclared and documented only as a capture. A declared `type: Integer` also narrows the path, but to digits alone, so `/-7` is a 404 there while the requirement matches it. Given both, the requirement decides what the route matches and the declared type decides what the endpoint sees.
+
+#### Dots in a path segment
+
+A path capture matches `[^/?#.]+`: a dot introduces the format suffix, so a captured segment never contains one. A dotted value therefore either fails to route or arrives truncated, and the declared type makes no difference — `type: String` and `type: Float` compile the same pattern as an untyped parameter, only `type: Integer` narrows it to digits.
+
+```ruby
+class WithFormat < Grape::API
+  format :json
+  route_param :name do
+    get { params[:name] } # GET /report.pdf => 404, the segment cannot hold the dot
+  end
+end
+
+class WithoutFormat < Grape::API
+  route_param :name do
+    # GET /report.pdf => 200, params[:name] is "report" and params[:format] is "pdf"
+    get { params[:name] }
+  end
+end
+```
+
+The second one is the one to watch: the extension is taken as the format, so the endpoint is handed a truncated value and the client still gets a 200.
+
+Percent-encoding the dot routes it through — `GET /report%2Epdf` hands the endpoint `"report.pdf"` — and so does a requirement that admits dots:
+
+```ruby
+route_param :name, requirements: /.+/ do
+  get { params[:name] } # => "report.pdf" for GET /report.pdf, "1.2.3" for GET /1.2.3
+end
+```
+
+Such a regexp claims the extension as well, so `GET /a.b.json` hands the endpoint `"a.b.json"` and format-by-extension no longer applies to that route. A narrower constraint leaves the suffix alone: `get ':n', requirements: { n: Float }` matches `/4.2` and still reads `.json` as the format.
+
+### The QUERY Method
+
+Grape supports [`QUERY`](https://www.rfc-editor.org/info/rfc10008/), a safe and idempotent method that carries its query in the request content rather than in the URI. It is the method to reach for when a query is too large, too structured, or too sensitive to encode into a query string.
+
+```ruby
+params do
+  requires :q, type: String
+  optional :limit, type: Integer
+end
+query '/search' do
+  Status.search(params[:q], limit: params[:limit])
+end
+```
+
+```
+curl -X QUERY 'http://localhost:9292/search' -H Content-Type:application/json -d '{"q": "grape", "limit": 10}'
+```
+
+The content is parsed into `params` exactly as it is for `POST`, and a successful response defaults to `200`, not `201`. Because the content *is* the query, a `QUERY` request that arrives without a `Content-Type` is rejected with `400` instead of falling back to the API's default format.
+
 ## Helpers
 
 You can define helper methods that your endpoints can use with the `helpers` macro by either giving a block or an array of modules.
@@ -2679,7 +2722,7 @@ You can set additional headers for the response. They will be merged with header
 error!('Something went wrong', 500, 'X-Error-Detail' => 'Invalid token.')
 ```
 
-You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
+You can present documented errors with a Grape entity using the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
 
 ```ruby
 module API
@@ -2766,6 +2809,19 @@ rescue_from :grape_exceptions do |e|
 end
 ```
 
+The opt-in takes precedence over a catch-all handler, whether that catch-all is written as `rescue_from :all` or as a class such as `rescue_from StandardError`. So a validation failure stays a `400` rather than becoming whatever the catch-all returns:
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from StandardError do
+    error!('server error', 500)
+  end
+  rescue_from :grape_exceptions   # validation errors still answer 400
+end
+```
+
+A handler registered for a specific Grape exception class is more precise than the opt-in and still wins, so `rescue_from Grape::Exceptions::ValidationErrors` keeps its own handler. The opt-in only outranks handlers that matched through a non-Grape ancestor.
+
 You can also rescue specific exceptions.
 
 ```ruby
@@ -2776,6 +2832,29 @@ end
 
 In this case ```UserDefinedError``` must be inherited from ```StandardError```.
 
+When several classes could match, the one registered **first** in a scope wins — as with the clauses of a Ruby `rescue`. Register the more specific class before the broader one, or the narrower handler never runs:
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from ArgumentError do ... end   # matched first
+  rescue_from StandardError do ... end   # everything else
+end
+```
+
+Grape warns when a `rescue_from` is registered for a class an earlier one in the same scope already covers. This is about ordering within a scope; a handler in a nested namespace or a mounted API always takes precedence over one inherited from an enclosing scope, whatever the classes are.
+
+A `rescue_from` also has to be declared **above** the routes it should cover. A route captures the handlers registered before it, so one declared below a route never runs for it:
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from :all do ... end   # covers GET /statuses
+  get :statuses do ... end
+  rescue_from ArgumentError do ... end   # never runs for GET /statuses
+end
+```
+
+The same goes for `use`, `helpers` and the `before`/`after` callbacks.
+
 Notice that you could combine these two approaches (rescuing custom errors takes precedence). For example, it's useful for handling all exceptions except Grape validation errors.
 
 ```ruby
@@ -2790,12 +2869,12 @@ end
 
 The error format will match the request format. See "Content-Types" below.
 
-Custom error formatters for existing and additional types can be defined with a proc.
+Custom error formatters for existing and additional types can be defined with a proc. The formatter receives a `Grape::Exceptions::ErrorResponse` value object as `error:` plus three context kwargs — `env:`, `include_backtrace:`, `include_original_exception:`. Pull just the keys you need with `**` to ignore the rest:
 
 ```ruby
 class Twitter::API < Grape::API
-  error_formatter :txt, ->(message, backtrace, options, env, original_exception) {
-    "error: #{message} from #{backtrace}"
+  error_formatter :txt, ->(error:, **) {
+    "error #{error.status}: #{error.message} from #{error.backtrace}"
   }
 end
 ```
@@ -2804,8 +2883,8 @@ You can also use a module or class.
 
 ```ruby
 module CustomFormatter
-  def self.call(message, backtrace, options, env, original_exception)
-    { message: message, backtrace: backtrace }
+  def self.call(error:, **)
+    { status: error.status, message: error.message, backtrace: error.backtrace }
   end
 end
 
@@ -2835,6 +2914,43 @@ class Twitter::API < Grape::API
 end
 ```
 
+#### Re-raising from inside a `rescue_from` block
+
+A `rescue_from` block can re-raise an exception to invoke a different handler. This is useful for translating one exception class into another:
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from Grape::Exceptions::ValidationErrors do |e|
+    raise Api::Exceptions::InvalidValueError, e.full_messages
+  end
+
+  rescue_from Api::Exceptions::InvalidValueError do |e|
+    error!({ errors: e.message }, 422)
+  end
+end
+```
+
+The first handler re-raises; the second handler runs against the new exception.
+
+If the re-raised exception has no registered `rescue_from` and is a `Grape::Exceptions::Base` subclass, it is rendered through the default Grape error path (using its own `status` and `message`). Anything else — typos, `NoMethodError`, an unrelated `StandardError` — is treated as an internal error: it is exposed on the rack env for upstream Rack middleware to observe, and rendered to the API consumer as a generic `500 Internal Server Error`. This avoids leaking internal detail in the response body.
+
+Because the exception is answered rather than raised, nothing above Grape catches it, so it is published under `rack.exception` — the key error trackers read for a handled exception — as well as Grape's own `grape.exception`. Grape does no logging of its own here; register a `rescue_from :internal_grape_exceptions` handler to take that over.
+
+You can take control of the internal-error path by opting in with `rescue_from :internal_grape_exceptions`:
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from :internal_grape_exceptions do |e|
+    Sentry.capture_exception(e)
+    error!({ message: 'Something went wrong' }, 500)
+  end
+end
+```
+
+When this handler is registered the framework hands the original exception to you, and you own the response shape and any logging. The framework deliberately does not log internal errors itself — it has no way to know your preferred format or destination.
+
+A second raise inside the redispatched handler is not redispatched again — it goes straight to the framework's generic 500. This bounds the chain at one redispatch and prevents loops.
+
 You can also rescue all exceptions with a code block and handle the Rack response at the lowest level.
 
 ```ruby
@@ -2974,6 +3090,38 @@ Any exception that is not subclass of `StandardError` should be rescued explicit
 Usually it is not a case for an application logic as such errors point to problems in Ruby runtime.
 This is following [standard recommendations for exceptions handling](https://ruby-doc.org/core/Exception.html).
 
+#### When the error response itself cannot be rendered
+
+A `rescue_from` handler can build a payload its error formatter cannot serialize. The common case is echoing request-derived text back to the client:
+
+```ruby
+class Missing < StandardError; end
+
+class API < Grape::API
+  format :json
+
+  rescue_from(Missing) { |e| error!({ error: 'not_found', detail: e.message }, 404) }
+
+  route_param(:id) { get { raise Missing, "no such thing: #{params[:id]}" } }
+end
+```
+
+`GET /%C3%28` puts an invalid UTF-8 byte in `params[:id]`, and the JSON formatter raises when it reaches that byte in the message — after the handler has already returned, so `rescue_from :all` does not help.
+
+Rather than let that exception escape the middleware stack, Grape answers `500`: first retrying the API's own format with the framework's `Internal Server Error` message, then falling back to a bare `text/plain` body if even that cannot be rendered.
+
+The exception is published on the rack env under `rack.exception` — the key error trackers read to find an exception that was handled rather than raised — and on Grape's own `grape.exception`. It is also written to `rack.errors`, so it reaches the log with no tracker installed.
+
+To opt out and have the exception propagate out of the middleware stack instead:
+
+```ruby
+Grape.configure do |config|
+  config.raise_rendering_errors = true
+end
+```
+
+With this on the failsafe never runs: the exception is re-raised untouched, so neither env key is set and nothing is written to `rack.errors`.
+
 ## Logging
 
 `Grape::API` provides a `logger` method which by default will return an instance of the `Logger` class from Ruby's standard library.
@@ -3182,6 +3330,41 @@ Built-in formatters are the following.
 * `:serializable_hash`: use object's `serializable_hash` when available, otherwise fallback to `:json`
 * `:binary`: data will be returned "as is"
 
+#### Serving pre-rendered JSON
+
+The `:json` and `:serializable_hash` formatters encode whatever the endpoint returned,
+so a String that already holds JSON gets encoded a second time. Wrap the body in
+`Grape::PrecompiledJson` to opt that response out of encoding.
+
+```ruby
+class API < Grape::API
+  format :json
+
+  get '/cached' do
+    body Grape::PrecompiledJson.new(Rails.cache.read('payload')) # => '{"id":1}', served as-is
+  end
+end
+```
+
+An `Array` is joined into a JSON array without its members being parsed, so a cached
+collection is spliced together rather than round-tripped. Members may themselves be
+`Grape::PrecompiledJson` instances.
+
+```ruby
+Grape::PrecompiledJson.new(['{"id":1}', '{"id":2}']).to_s # => '[{"id":1},{"id":2}]'
+```
+
+Bodies that are not wrapped keep encoding exactly as before, so this is opt-in per
+response rather than a mode the whole API is in. Wrap only the whole body: a wrapper
+nested inside a Hash or Array that is then handed to an encoder is serialized as an
+ordinary object, because no encoder knows to unwrap it. A value that is neither a
+String nor an Array raises `Grape::Exceptions::InvalidFormatter` and answers 500,
+rather than handing Rack a body it cannot serve. Nothing checks that the String
+actually holds JSON — that is the caller's responsibility.
+
+Errors are unaffected: they are rendered by the error formatter, so `error!` still
+returns properly encoded JSON.
+
 If a body is present in a request to an API, with a Content-Type header value that is of an unsupported type a "415 Unsupported Media Type" error code will be returned by Grape.
 
 Response statuses that indicate no content as defined by [Rack](https://github.com/rack) [here](https://github.com/rack/rack/blob/master/lib/rack/utils.rb#L567) will bypass serialization and the body entity - though there should be none - will not be modified.
@@ -3782,13 +3965,13 @@ class TwitterAPI < Grape::API
     @var = 1
   end
 
-  get '/' do
+  rescue_from :all do
     puts @var # => 1
-    raise
   end
 
-  rescue_from :all do
+  get '/' do
     puts @var # => 1
+    raise
   end
 end
 ```
@@ -4049,7 +4232,15 @@ end
 
 ### Stubbing Helpers
 
-Because helpers are mixed in based on the context when an endpoint is defined, it can be difficult to stub or mock them for testing. The `Grape::Endpoint.before_each` method can help by allowing you to define behavior on the endpoint that will run before every request.
+Because helpers are mixed in based on the context when an endpoint is defined, it can be difficult to stub or mock them for testing. `Grape::Endpoint.before_each` allows you to define behavior on the endpoint that will run before every request.
+
+This feature is provided by `Grape::Testing`, a standalone module intended for test environments only. Add it to your test helper:
+
+```ruby
+require 'grape/testing'
+```
+
+Then use it in your tests:
 
 ```ruby
 describe 'an endpoint that needs helpers stubbed' do
@@ -4060,7 +4251,7 @@ describe 'an endpoint that needs helpers stubbed' do
   end
 
   after do
-    Grape::Endpoint.before_each nil
+    Grape::Endpoint.reset_before_each
   end
 
   it 'stubs the helper' do
@@ -4077,6 +4268,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 +4305,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 +4319,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 +4350,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 +4359,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)