grape 3.3.4 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d4db45369305583b4816671ba1e0934dc034bda07ad61bc68b1b9d09d67d776
-  data.tar.gz: fcb5fc7921a0f619f3d644a8c7caee4e306f71215c05f01770df4a94d301db34
+  metadata.gz: 85a54d2cd2bfc91b5b60cf30c317884e37b9ddfce15a8792d03247908a447393
+  data.tar.gz: ea8ad0d56df3c5a53f0540c98f7bbc5f12d79069b845625a63c7746ba47521c4
 SHA512:
-  metadata.gz: ea6e0e3bab2b7f79e395e2aa649d5a15bfc0fef1d22be86465a650d1c92c73ed3cb6133fbb67d184aad3cf9ba0f7e920ec507e5d94bc3fb55b7ca9d0c54ea89a
-  data.tar.gz: ab97e8a2ed312cfce30641914ed08986aeee8bad45742deabea86b7b41177c402daab21ffd16f023ea7be8e83d1e202407ad10bbbcf41703a0834ad9183f82cd
+  metadata.gz: 59aee78aea73250cc78f34e4eb87a380b709b2568310959331455b99b6c562d1085d43b99897a3063006f9d2e64adc0286ac2319245d1ffc645b28519c1358f6
+  data.tar.gz: 716b1feb2c1b5ad32213515353dab9b5dc9fd9dc7c6560bc4b6f7b4a82326df1c21c6c2bee517e86b7a252217bf55515ca1005507f737fa57c1c82d759e17fcf

data/CHANGELOG.md

@@ -1,3 +1,131 @@
+### 4.0.0 (2026-09-07)
+
+#### Features
+
+* [#2768](https://github.com/ruby-grape/grape/pull/2768): Remove Guard - [@ericproulx](https://github.com/ericproulx).
+* [#2774](https://github.com/ruby-grape/grape/pull/2774): Make `forward_match` an internal kwarg instead of a route option - [@ericproulx](https://github.com/ericproulx).
+* [#2775](https://github.com/ruby-grape/grape/pull/2775): Pass `http_methods` to `Grape::Endpoint` as a keyword instead of via options - [@ericproulx](https://github.com/ericproulx).
+* [#2776](https://github.com/ruby-grape/grape/pull/2776): Pass `path` to `Grape::Endpoint` as a keyword instead of via options - [@ericproulx](https://github.com/ericproulx).
+* [#2777](https://github.com/ruby-grape/grape/pull/2777): Add `Grape::Endpoint#mounted_app` reader and `app:` keyword - [@ericproulx](https://github.com/ericproulx).
+* [#2778](https://github.com/ruby-grape/grape/pull/2778): Rename `Grape::Endpoint`'s `for:` keyword to `api:` and expose `#api` - [@ericproulx](https://github.com/ericproulx).
+* [#2779](https://github.com/ruby-grape/grape/pull/2779): Promote route metadata (`version`, `namespace`, `prefix`, `requirements`, `anchor`, `settings`) to `Grape::Router::Route` keyword arguments, and drop the unused `Grape::Endpoint::Options` `format` member - [@ericproulx](https://github.com/ericproulx).
+* [#2782](https://github.com/ruby-grape/grape/pull/2782): Remove the dead `format` keyword from `Grape::Router::Pattern` - [@ericproulx](https://github.com/ericproulx).
+* [#2783](https://github.com/ruby-grape/grape/pull/2783): Read a route's `version`, `anchor` and `requirements` from its pattern instead of storing them again on the route - [@ericproulx](https://github.com/ericproulx).
+* [#2784](https://github.com/ruby-grape/grape/pull/2784): Move HEAD route creation into `Grape::Router::Route#to_head` - [@ericproulx](https://github.com/ericproulx).
+* [#2787](https://github.com/ruby-grape/grape/pull/2787): Stop populating the write-only `namespace_setting(:description)` in `desc` - [@ericproulx](https://github.com/ericproulx).
+* [#2795](https://github.com/ruby-grape/grape/pull/2795): Make `Grape::Util::InheritableSetting#namespace_reverse_stackable` internal, exposing `rescue_handlers` / `base_only_rescue_handlers` / `add_rescue_handlers` instead - [@ericproulx](https://github.com/ericproulx).
+* [#2793](https://github.com/ruby-grape/grape/pull/2793): Add a `Grape::Mountable` marker to identify a Grape app instead of duck-typing on `respond_to?(:inheritable_setting)` - [@ericproulx](https://github.com/ericproulx).
+* [#2792](https://github.com/ruby-grape/grape/pull/2792): Move `Grape::Path` to `Grape::Router::Pattern::Path` and add a `Grape::Router::Pattern.build` factory (`Grape::Path` kept as a deprecated constant) - [@ericproulx](https://github.com/ericproulx).
+* [#2785](https://github.com/ruby-grape/grape/pull/2785): Make route `params` a first-class endpoint input and split `Grape::Router::Route#params` into `#params` (declared definitions) and `#params_for(input)` (extracted values) - [@ericproulx](https://github.com/ericproulx).
+* [#2786](https://github.com/ruby-grape/grape/pull/2786): Make route `requirements` and `anchor` explicit keyword arguments and first-class endpoint inputs instead of opaque `route_options` keys - [@ericproulx](https://github.com/ericproulx).
+* [#2788](https://github.com/ruby-grape/grape/pull/2788): Compare the base API instead of `to_s` when refreshing a mounted app - [@ericproulx](https://github.com/ericproulx).
+* [#2796](https://github.com/ruby-grape/grape/pull/2796): Remove `Grape::Util::ReverseStackableValues`, storing rescue handlers in plain per-scope hashes merged over `InheritableSetting#parent` - [@ericproulx](https://github.com/ericproulx).
+* [#2797](https://github.com/ruby-grape/grape/pull/2797): Internalize params state (validations, declared params, param documentation, named params) behind `Grape::Util::InheritableSetting` accessors, and remove the unused `api_class` / `point_in_time_copies` readers - [@ericproulx](https://github.com/ericproulx).
+* [#2798](https://github.com/ruby-grape/grape/pull/2798): Internalize callback filters behind `Grape::Util::InheritableSetting` accessors (`callbacks` / `add_callback`) - [@ericproulx](https://github.com/ericproulx).
+* [#2799](https://github.com/ruby-grape/grape/pull/2799): Internalize the remaining rescue configuration (`rescue_options`, meta-selector handlers and flags) behind `Grape::Util::InheritableSetting` accessors - [@ericproulx](https://github.com/ericproulx).
+* [#2800](https://github.com/ruby-grape/grape/pull/2800): Internalize content negotiation state (content types, formatters, parsers, error formatters) behind `Grape::Util::InheritableSetting` accessors - [@ericproulx](https://github.com/ericproulx).
+* [#2801](https://github.com/ruby-grape/grape/pull/2801): Internalize `represent` registrations behind `Grape::Util::InheritableSetting` accessors (`representations` / `add_representation`), and remove the inert `:representations` seeding in `Grape::Endpoint#initialize` - [@ericproulx](https://github.com/ericproulx).
+* [#2802](https://github.com/ruby-grape/grape/pull/2802): Internalize middleware and helper registrations behind `Grape::Util::InheritableSetting` accessors (`middleware` / `add_middleware`, `helpers` / `add_helper`) - [@ericproulx](https://github.com/ericproulx).
+* [#2803](https://github.com/ruby-grape/grape/pull/2803): Internalize namespace and mount-path registrations behind `Grape::Util::InheritableSetting` accessors (`namespaces` / `add_namespace` / `namespace_path` / `namespace_requirements`, `mount_path` / `add_mount_path`) - [@ericproulx](https://github.com/ericproulx).
+* [#2804](https://github.com/ruby-grape/grape/pull/2804): Internalize contract key maps behind `Grape::Util::InheritableSetting` accessors (`contract_key_maps` / `add_contract_key_map`) - [@ericproulx](https://github.com/ericproulx).
+* [#2805](https://github.com/ruby-grape/grape/pull/2805): Internalize format and error-response defaults behind `Grape::Util::InheritableSetting` accessors (`format`, `default_format`, `default_error_formatter`, `default_error_status`) - [@ericproulx](https://github.com/ericproulx).
+* [#2806](https://github.com/ruby-grape/grape/pull/2806): Internalize versioning state behind `Grape::Util::InheritableSetting` accessors (`version`, `version_options`, `root_prefix`, `cascade` / `cascade_defined?`) - [@ericproulx](https://github.com/ericproulx).
+* [#2808](https://github.com/ruby-grape/grape/pull/2808): Internalize `build_params_with` and `auth` behind `Grape::Util::InheritableSetting` accessors - [@ericproulx](https://github.com/ericproulx).
+* [#2807](https://github.com/ruby-grape/grape/pull/2807): Internalize routing scope flags behind `Grape::Util::InheritableSetting` accessors (`do_not_route_head`, `do_not_route_options`, `do_not_document`, `lint` — `!` writers / `?` readers), and drop the vestigial `namespace_inheritable` hash copy in `Grape::API::Instance`'s route-config collection - [@ericproulx](https://github.com/ericproulx).
+* [#2810](https://github.com/ruby-grape/grape/pull/2810): Make `Grape::Util::InheritableSetting`'s raw stores internal where the ecosystem allows: `namespace_inheritable` is now protected and `namespace_stackable_with_hash` private, while `namespace_stackable` stays public for grape-swagger; `Router::Pattern::Path` reads a dedicated `path_settings` snapshot, and `mount_paths` exposes the full mount-path stack - [@ericproulx](https://github.com/ericproulx).
+* [#2811](https://github.com/ruby-grape/grape/pull/2811): Internalize the route scope behind `Grape::Util::InheritableSetting` accessors (`route_validations`, `route_declared_params`, `route_renamed_params` / `add_route_renamed_param`, `route_description`, `route_settings`, `route_setting`, `inherit_route_params`), so no external code touches the raw `route` store - [@ericproulx](https://github.com/ericproulx).
+* [#2823](https://github.com/ruby-grape/grape/pull/2823): Move stackable settings storage onto `Grape::Util::InheritableSetting`, resolving inheritance by walking `parent` instead of a second chain; `Grape::Util::StackableValues` becomes a read-only view kept for grape-swagger, and `Grape::Util::BaseInheritable` is removed - [@ericproulx](https://github.com/ericproulx).
+* [#2828](https://github.com/ruby-grape/grape/pull/2828): Compare `Grape::Util::InheritableSetting` by own state instead of serializing both chains through `to_hash`, and give `Grape::Util::InheritableValues` an `==`, so the duplicate-route check in `route` stops costing O(n²) `to_hash` calls on APIs whose namespaces share relative paths - [@ericproulx](https://github.com/ericproulx).
+* [#2831](https://github.com/ruby-grape/grape/pull/2831): Document and test open (beginless/endless) `Range`s as a `values:`/`except_values:` alternative to a dedicated numericality validator - [@dblock](https://github.com/dblock).
+* [#2830](https://github.com/ruby-grape/grape/pull/2830): Remove `Grape::Util::InheritableValues`, resolving inheritable settings by walking `Grape::Util::InheritableSetting#parent` instead of layering a second chain of stores, and keep namespace settings in a plain Hash - [@ericproulx](https://github.com/ericproulx).
+* [#2837](https://github.com/ruby-grape/grape/pull/2837): Document the definition-time rejection of an `Array`/`Set` of an uncoercible element type introduced by #2817, and pin it with specs - [@ericproulx](https://github.com/ericproulx).
+* [#2836](https://github.com/ruby-grape/grape/pull/2836): Define `#hash` alongside the `eql?`/`==` pairs on `Grape::Endpoint`, `Grape::Util::InheritableSetting`, `Grape::Middleware::Stack::Middleware`, `Grape::ServeStream::StreamResponse` and `Grape::ServeStream::FileBody`, so equal objects hash alike in a `Hash`, `Set` or `uniq` - [@ericproulx](https://github.com/ericproulx).
+* [#2835](https://github.com/ruby-grape/grape/pull/2835): Return the compiled instance from `Grape::API::Instance.compile!` so `call` and `recognize_path` no longer re-read `@instance`, which a concurrent `change!` could nil between the two reads - [@ericproulx](https://github.com/ericproulx).
+* [#2849](https://github.com/ruby-grape/grape/pull/2849): Remove `http_digest`, which has had no strategy behind it since 2.0.0 and raised on the first request rather than when the API was defined (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2862](https://github.com/ruby-grape/grape/pull/2862): Rename the `desc` `default` key to `default_response`, the name grape-swagger reads, deprecating `default` (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2866](https://github.com/ruby-grape/grape/pull/2866): Take `as` as a keyword argument in `requires` and `optional` instead of carrying it in the options Hash, where it was dispatched as a no-op `AsValidator` - [@ericproulx](https://github.com/ericproulx).
+* [#2867](https://github.com/ruby-grape/grape/pull/2867): Extract the shared body of `requires` and `optional` into one private declaration, and drop `validate_attributes`, whose only step defaulted a type that no declaration could reach - [@ericproulx](https://github.com/ericproulx).
+* [#2870](https://github.com/ruby-grape/grape/pull/2870): Take `declared_params_scope` as a keyword argument in `push_declared_params` instead of stamping it into the caller's options Hash - [@ericproulx](https://github.com/ericproulx).
+* [#2869](https://github.com/ruby-grape/grape/pull/2869): Add `Grape::PrecompiledJson`, a body wrapper the JSON formatters serve verbatim instead of encoding a second time - [@ericproulx](https://github.com/ericproulx).
+* [#2878](https://github.com/ruby-grape/grape/pull/2878): Build an error response's backtrace only when `rescue_from ..., backtrace: true` asked for one (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2873](https://github.com/ruby-grape/grape/pull/2873): Read `Grape.config[:param_builder]` instead of routing the per-request lookup through dry-configurable's `method_missing` - [@ericproulx](https://github.com/ericproulx).
+* [#2877](https://github.com/ruby-grape/grape/pull/2877): Write `route_info` into the path captures in `Grape::Router#process_route` instead of merging a second Hash into it - [@ericproulx](https://github.com/ericproulx).
+* [#2874](https://github.com/ruby-grape/grape/pull/2874): Test the `Grape::Util::PathNormalizer` fast path with two `String#include?` calls instead of a regexp - [@ericproulx](https://github.com/ericproulx).
+* [#2876](https://github.com/ruby-grape/grape/pull/2876): Return a bare Rack tuple from `Grape::Middleware::Formatter` instead of a `Rack::Response` the enclosing middleware immediately unwraps - [@ericproulx](https://github.com/ericproulx).
+* [#2875](https://github.com/ruby-grape/grape/pull/2875): Skip the query-string parse and the `script_name + path_info` concatenation during content negotiation when neither can affect the result - [@ericproulx](https://github.com/ericproulx).
+* [#2879](https://github.com/ruby-grape/grape/pull/2879): Skip path-param extraction for routes whose compiled pattern captures nothing, instead of re-running the regexp to build an empty Hash - [@ericproulx](https://github.com/ericproulx).
+* [#2880](https://github.com/ruby-grape/grape/pull/2880): Remove `Grape::Middleware::Versioner`'s `pattern` option, a leftover of the 2010 versioner that `versions:` superseded and the `version` DSL never exposed (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2872](https://github.com/ruby-grape/grape/pull/2872): Include an endpoint's helpers once at compile time instead of on every request, so a request no longer builds a singleton class whose method cache starts cold (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2882](https://github.com/ruby-grape/grape/pull/2882): Strip mount path and prefix in `Grape::Middleware::Versioner::Path` with `each` instead of `Enumerable#reduce` - [@ericproulx](https://github.com/ericproulx).
+* [#2881](https://github.com/ruby-grape/grape/pull/2881): Decide whether a request carries a body from the env, so `Grape::Middleware::Formatter` no longer builds a `Rack::Request` for GET, HEAD and OPTIONS - [@ericproulx](https://github.com/ericproulx).
+* [#2883](https://github.com/ruby-grape/grape/pull/2883): Resolve a format's content type through a plain Hash carrying both spellings instead of a `HashWithIndifferentAccess` that converts the key on every read - [@ericproulx](https://github.com/ericproulx).
+* [#2887](https://github.com/ruby-grape/grape/pull/2887): Add support for the HTTP `QUERY` method (RFC 10008), including the `query` DSL verb and parsing the request content into `params` - [@ericproulx](https://github.com/ericproulx).
+* [#2885](https://github.com/ruby-grape/grape/pull/2885): Share the content-type lookup and mime-type tables between middleware instances that register the same content types, instead of building a copy per API - [@ericproulx](https://github.com/ericproulx).
+* [#2891](https://github.com/ruby-grape/grape/pull/2891): Look registrations up in a plain Hash carrying both spellings instead of a `HashWithIndifferentAccess` - [@ericproulx](https://github.com/ericproulx).
+* [#2888](https://github.com/ruby-grape/grape/pull/2888): Resolve an API instance's cascade setting once at compile time instead of walking the settings chain on every request - [@ericproulx](https://github.com/ericproulx).
+* [#2889](https://github.com/ruby-grape/grape/pull/2889): Constrain the `:version` capture with a `Regexp` so Mustermann stops registering an identity param converter, which was defeating its `identity_params?` fast path on every path-versioned request - [@ericproulx](https://github.com/ericproulx).
+* [#2890](https://github.com/ruby-grape/grape/pull/2890): Read the path version off the route the router already matched instead of re-deriving it from `PATH_INFO` in `Grape::Middleware::Versioner::Path` - [@ericproulx](https://github.com/ericproulx).
+* [#2892](https://github.com/ruby-grape/grape/pull/2892): Resolve the params builder when `params` are first read rather than in every `Grape::Request` - [@ericproulx](https://github.com/ericproulx).
+* [#2893](https://github.com/ruby-grape/grape/pull/2893): Scrub the format extension rather than the whole request path when negotiating a format - [@ericproulx](https://github.com/ericproulx).
+* [#2894](https://github.com/ruby-grape/grape/pull/2894): Read the request method once in `default_status` instead of asking through `post?` and `delete?` - [@ericproulx](https://github.com/ericproulx).
+* [#2895](https://github.com/ruby-grape/grape/pull/2895): Cut per-request work out of the endpoint, validation and router paths: scan the router's compiled union by capture number rather than by name, skip the Array boxing in `AttributesIterator` for a flat scope, read a coerced attribute once instead of three times, and resolve the formatter's config and the coercers' type checks once at build time - [@ericproulx](https://github.com/ericproulx).
+* [#2900](https://github.com/ruby-grape/grape/pull/2900): Remove the deprecations announced in 3.2 and 3.3: `Grape::Router.normalize_path`, Hash access on middleware `Options` and their `DEFAULT_OPTIONS` constants, the positional options Hash for `auth`/`http_basic`/`desc`, a Hash returned from a `rescue_from` handler, and `@option` on validators (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2896](https://github.com/ruby-grape/grape/pull/2896): Bring test suite line coverage to 100% - [@dblock](https://github.com/dblock).
+* [#2897](https://github.com/ruby-grape/grape/pull/2897): Improve test suite branch coverage - [@dblock](https://github.com/dblock).
+* [#2909](https://github.com/ruby-grape/grape/pull/2909): Standardize bare Ruby exception messages (`ArgumentError`, etc.) to lowercase, unpunctuated, matching Ruby's own core/stdlib style, and wrap interpolated values in backticks via `rubocop-exception_messages` - [@dblock](https://github.com/dblock).
+
+#### Fixes
+
+* [#2899](https://github.com/ruby-grape/grape/pull/2899): Derive `Grape.deprecator`'s deprecation horizon from `Grape::VERSION` instead of the hardcoded `2.0` it has announced since 2023 - [@ericproulx](https://github.com/ericproulx).
+* [#2898](https://github.com/ruby-grape/grape/pull/2898): Stop eager loading `grape/testing`, so the module is opt-in as its 3.3 release note has always said instead of being installed in every process (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2767](https://github.com/ruby-grape/grape/pull/2767): Update rubocop to 1.88.0 and rubocop-rspec to 3.10.2 - [@ericproulx](https://github.com/ericproulx).
+* [#2863](https://github.com/ruby-grape/grape/pull/2863): Enable `Style/MutableConstant`'s `Recursive` option, so a literal nested inside a frozen constant has to be frozen too - [@ericproulx](https://github.com/ericproulx).
+* [#2816](https://github.com/ruby-grape/grape/pull/2816): Guard `length`, `same_as` and `oneof` validators against non-hash params (500 → 400) - [@ericproulx](https://github.com/ericproulx).
+* [#2815](https://github.com/ruby-grape/grape/pull/2815): Fix line-anchored regexes: `type: JSON` payloads containing a blank line were silently coerced to `nil` - [@ericproulx](https://github.com/ericproulx).
+* [#2817](https://github.com/ruby-grape/grape/pull/2817): Remove request-time mutable state from Array and custom-type coercers, which also makes an `Array`/`Set` of an uncoercible element type raise when the API is defined instead of on the first request that supplies it (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2819](https://github.com/ruby-grape/grape/pull/2819): Freeze coercers at construction, synchronize `Grape::Util::Cache` lookups, and assign `Route#regexp_capture_index` eagerly - [@ericproulx](https://github.com/ericproulx).
+* [#2825](https://github.com/ruby-grape/grape/pull/2825): Stop `present` entity autodetection from picking up a top-level `::Entity` constant - [@ericproulx](https://github.com/ericproulx).
+* [#2827](https://github.com/ruby-grape/grape/pull/2827): Make the `cascade` DSL getter return the configured value (`cascade false` read back as `true`) - [@ericproulx](https://github.com/ericproulx).
+* [#2829](https://github.com/ruby-grape/grape/pull/2829): Fix a cascading route handing over only to the last route registered for the path, making a middle version (3+ mounted versions with a catch-all) answer 406 - [@ericproulx](https://github.com/ericproulx).
+* [#2826](https://github.com/ruby-grape/grape/pull/2826): Fix `api.version` not being set for the root route of a path-versioned API (`GET /v1`) - [@ericproulx](https://github.com/ericproulx).
+* [#2844](https://github.com/ruby-grape/grape/pull/2844): Look an entity up by the presented object's own class before treating it as a collection, so `represent` is no longer skipped for models that respond to `#first` or `#klass` - [@ericproulx](https://github.com/ericproulx).
+* [#2847](https://github.com/ruby-grape/grape/pull/2847): Match `Accept` media types case-insensitively, so a differently-cased header still negotiates the content type and resolves a vendor version - [@ericproulx](https://github.com/ericproulx).
+* [#2838](https://github.com/ruby-grape/grape/pull/2838): Reject request params nested in more arrays than the block declares, instead of silently unwrapping them and passing validation, and report `type: Array[JSON]` errors against the element that failed - [@ericproulx](https://github.com/ericproulx).
+* [#2842](https://github.com/ruby-grape/grape/pull/2842): Warn at definition time when a `rescue_from` class is already covered by one registered earlier in the same scope, since the later handler never runs - [@ericproulx](https://github.com/ericproulx).
+* [#2853](https://github.com/ruby-grape/grape/pull/2853): Restore, behind a deprecation warning, the trailing positional options Hash of `requires`, `optional` and `use`, which #2618 turned into a parameter name - [@ericproulx](https://github.com/ericproulx).
+* [#2856](https://github.com/ruby-grape/grape/pull/2856): Update simplecov - [@ericproulx](https://github.com/ericproulx).
+* [#2841](https://github.com/ruby-grape/grape/pull/2841): Stop `use`, `helpers`, `rescue_from` and other registrations declared below a route from reaching it when an earlier registration had seeded the same key (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2846](https://github.com/ruby-grape/grape/pull/2846): Keep a `:version` path capture in `params` when the API declares no version, instead of always dropping it as Grape's own - [@ericproulx](https://github.com/ericproulx).
+* [#2839](https://github.com/ruby-grape/grape/pull/2839): Tag path params as UTF-8 instead of leaving them ASCII-8BIT, so they compare equal to the non-ASCII literals an API declares (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2845](https://github.com/ruby-grape/grape/pull/2845): Render `redirect`'s default message as the plain text its content type announces, instead of letting the API's formatter re-encode it (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2840](https://github.com/ruby-grape/grape/pull/2840): Answer 500 instead of letting an exception escape the middleware stack when an error response cannot be rendered, exposing it on `rack.exception` and writing it to `rack.errors` so error trackers keep reporting it, with `Grape.config.raise_rendering_errors` to opt back out (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2855](https://github.com/ruby-grape/grape/pull/2855): Expose an unhandled exception raised inside a `rescue_from` block on `rack.exception`, so error trackers report it instead of the generic 500 arriving silently - [@ericproulx](https://github.com/ericproulx).
+* [#2843](https://github.com/ruby-grape/grape/pull/2843): Let `rescue_from :grape_exceptions` take precedence over a catch-all registered as a class, so Grape errors keep their own status (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2858](https://github.com/ruby-grape/grape/pull/2858): Define `Grape::Router::GreedyRoute#params_for` instead of letting the call fall through to the route's options Hash - [@ericproulx](https://github.com/ericproulx).
+* [#2859](https://github.com/ruby-grape/grape/pull/2859): Answer `Grape::Router::Route#success` and `#failure` from the description whichever way it was written - [@ericproulx](https://github.com/ericproulx).
+* [#2861](https://github.com/ruby-grape/grape/pull/2861): Read `Grape::Router::Route#default` from the description instead of from the options Hash's own default value, which was always `nil` - [@ericproulx](https://github.com/ericproulx).
+* [#2864](https://github.com/ruby-grape/grape/pull/2864): Apply a group's type check to `optional` the same way as `requires`, so a type supplied by an enclosing `with` is no longer invisible to it (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2865](https://github.com/ruby-grape/grape/pull/2865): Pass `required` from `requires`/`optional` as an argument instead of writing a `presence` key into the caller's options, deprecating a user-supplied `presence` and letting a `with` block's `message` reach the presence validator (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2871](https://github.com/ruby-grape/grape/pull/2871): Move the endpoint replacement behind `mount`'s private re-mounting path, deprecating the undocumented `refresh_already_mounted` option, and recognise a mount mapping by `Hash` rather than by `respond_to?(:each_pair)` (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2886](https://github.com/ruby-grape/grape/pull/2886): Compile the router's optimized map from the registered routes, so a route declared with a verb outside `Grape::HTTP_SUPPORTED_METHODS` is served instead of being advertised in `Allow` and answered with 405 - [@ericproulx](https://github.com/ericproulx).
+* [#2901](https://github.com/ruby-grape/grape/pull/2901): Reject `error_formatter` without a formatter instead of registering `nil`, which left the format with no error formatter at all and answered every error for it with a failsafe 500 (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2902](https://github.com/ruby-grape/grape/pull/2902): Make `Grape::ErrorFormatter.formatter_for` a lookup that answers `nil` for an unregistered format, like `Grape::Parser.parser_for`, and move the `default_error_formatter` / `Grape::ErrorFormatter::Txt` fallback to `Grape::Middleware::Error`, which owns it; `default_error_formatter` naming nothing registered now raises `Grape::Exceptions::UnknownErrorFormatter` instead of silently storing `Txt` (see UPGRADING) - [@ericproulx](https://github.com/ericproulx).
+* [#2904](https://github.com/ruby-grape/grape/pull/2904): Document and spec route `requirements` given as a Mustermann capture type, which constrains the match and hands the endpoint the converted value - [@ericproulx](https://github.com/ericproulx).
+* [#2905](https://github.com/ruby-grape/grape/pull/2905): Nest any `route_param` requirement under the param name, not just a Regexp, and reject the `requirements` shapes that have no param to attach to where they are written rather than on the first request - [@ericproulx](https://github.com/ericproulx).
+* [#2908](https://github.com/ruby-grape/grape/pull/2908): Stop reassigning method parameters across `lib`, so a parameter keeps the value its caller passed for the whole method; the `oneof` collection in `Grape::Validations::ParamsScope` no longer writes into the Hash it was given - [@ericproulx](https://github.com/ericproulx).
+* [#2910](https://github.com/ruby-grape/grape/pull/2910): Restore `Grape::Middleware::Formatter`'s in-place content-type negotiation as `ensure_content_type!`, which #2908 had turned into a copy of the response headers on every response - [@ericproulx](https://github.com/ericproulx).
+* [#2911](https://github.com/ruby-grape/grape/pull/2911): Copy response headers with `merge!` instead of `merge` in `Grape::API::Instance#call` and `Grape::Middleware::Error`, which allocated a `Grape::Util::Header` only to discard it - [@ericproulx](https://github.com/ericproulx).
+* [#2907](https://github.com/ruby-grape/grape/pull/2907): Stop `Grape::Endpoint::Options` from appending the default `'/'` into the path Array it was given, so declaring a route with an empty Array of paths inside a `namespace`, `resource`, `group` or `route_param` block no longer mutates the caller's Array — and raises `FrozenError` at boot when it is frozen - [@ericproulx](https://github.com/ericproulx).
+* [#2912](https://github.com/ruby-grape/grape/pull/2912): Correct the 4.0.0 release notes and file the `http_digest` removal note under `Upgrading to >= 4.0.0` - [@ericproulx](https://github.com/ericproulx).
+
+### 3.3.5 (2026-07-30)
+
+#### Fixes
+
+* [#2814](https://github.com/ruby-grape/grape/pull/2814): Fix `type: [A, B]` combined with `values:`/`except_values:` raising `IncompatibleOptionValues` at definition time - [@ericproulx](https://github.com/ericproulx).
+* [#2833](https://github.com/ruby-grape/grape/pull/2833): Fix `Grape::API::Instance.to_s` returning an empty string instead of the class name when the instance has no base (regression since 3.0.0) - [@ericproulx](https://github.com/ericproulx).
+* [#2834](https://github.com/ruby-grape/grape/pull/2834): Fix cascaded routes (`X-Cascade: pass`) leaking `route_info` and path captures into the next matched route's `route` and `params` - [@ericproulx](https://github.com/ericproulx).
+
 ### 3.3.4 (2026-07-25)
 
 #### Fixes

data/CONTRIBUTING.md

@@ -74,6 +74,22 @@ Ruby style is enforced with [Rubocop](https://github.com/bbatsov/rubocop), run `
 
 Make sure that `bundle exec rake` completes without errors.
 
+##### Exception Messages
+
+When you `raise` a bare Ruby exception (`ArgumentError`, `NotImplementedError`, etc.) for programmer errors — invalid DSL usage, misconfiguration and the like — write the message as a lowercase fragment with no trailing period, matching Ruby's own core exceptions (e.g. `TypeError: no implicit conversion from nil to integer`). This reads naturally when Ruby prints it after the exception class name and colon in a backtrace:
+
+```ruby
+raise ArgumentError, 'a block is required'
+```
+
+rather than:
+
+```ruby
+raise ArgumentError, 'A block is required.'
+```
+
+This does not apply to `Grape::Exceptions::*` messages meant to be rendered in an API response body, which are already lowercase and unpunctuated by convention and typically come from locale YAML rather than inline strings.
+
 #### Write Documentation
 
 Document any external behavior in the [README](README.md).

data/README.md

@@ -10,7 +10,7 @@ Grape is a REST-like API framework for Ruby. It's designed to run on Rack or com
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, 3.3.4.
+You're reading the documentation for the stable release of Grape, 4.0.0.
 
 ## Project Resources
 
@@ -566,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]
@@ -579,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
 
@@ -619,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:
 
@@ -1558,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.
 
@@ -1593,12 +1615,13 @@ With `requires`, blank values are already rejected: `requires` enforces presence
 
 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
 ```
@@ -2278,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.
@@ -2714,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
@@ -2724,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
@@ -2801,7 +2932,9 @@ 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 `env['grape.exception']` 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.
+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`:
 
@@ -2957,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.
@@ -3165,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.
@@ -3765,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
 ```