grape 4.0.0 → 4.1.0

data/UPGRADING.md

@@ -1,6 +1,370 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 4.1.0
+
+#### `Rack::Head` wraps the router instead of each endpoint's stack
+
+`Rack::Head` used to be the first middleware in each endpoint's stack. That missed a Rack app mounted with `mount`, which the router calls directly, and a middleware inserted ahead of it with `insert 0`: a `HEAD` request to either got the full body back. A single `Rack::Head` around the router now strips the body of every `HEAD` response the API gives ([#3042](https://github.com/ruby-grape/grape/pull/3042)).
+
+An endpoint's stack now starts with `Grape::Middleware::Error`, and three things follow from that:
+
+* `insert_before Rack::Head` and `insert_after Rack::Head` raise `No such middleware to insert before: Rack::Head` (or `after`) when the API compiles. Use `insert 0` to put a middleware first.
+* A middleware inserted by index lands one place further in. `insert 1` used to put it between `Rack::Head` and `Grape::Middleware::Error`; it now puts it inside `Grape::Middleware::Error`, so `rescue_from` handles what it raises. Use `insert 0` to keep it outside.
+* A middleware inserted with `insert 0` now sees the full body of a `HEAD` response, as one added with `use` always has.
+
+#### A `:jsonl` format you declared now gets Grape's JSON Lines formatter, parser and error formatter
+
+Grape now renders, parses and reports errors in JSON Lines under `:jsonl` ([#3029](https://github.com/ruby-grape/grape/pull/3029)). An API that declared `content_type :jsonl, ...` itself, with nothing of its own registered for it, gets Grape's:
+
+* A response body that is not a String renders as JSON Lines. A String is still served as it is.
+* A request body is parsed into an Array in `env['api.request.body']`, where it used to be the raw String. Keep the String with `parser :jsonl, nil`.
+* An error renders as a JSON line instead of through `default_error_formatter`.
+
+A formatter, parser or error formatter you register for `:jsonl` with `formatter`, `parser` or `error_formatter` still takes precedence.
+
+#### Formats named `:md` and `:markdown` have a built-in formatter
+
+`Grape::Formatter::Md` renders the `:md` format and `Grape::Formatter::Markdown` the `:markdown` one ([#3025](https://github.com/ruby-grape/grape/pull/3025)). Neither is a default content type, so only an API that declares one is affected. See [Serving Markdown](README.md#serving-markdown).
+
+* An API that declared `content_type :md` (or `:markdown`) without a matching `formatter` used to send its bodies unchanged. A String still is. An object answering `to_markdown` is now rendered with it, and any other object raises `Grape::Exceptions::InvalidFormatter`: it answers in the default format when the client negotiated Markdown, and `500` otherwise.
+* `:md` and `:markdown` now name the same format. An API that declared one of them used to answer the other extension (and `?format=`) in its default format, or `406`; it now answers it in Markdown, under the name it declared.
+* A `formatter :md` or `formatter :markdown` of your own still takes precedence.
+* A formatter class of your own named `Md` or `Markdown` that inherits `Grape::Formatter::Base` now replaces Grape's globally, with a warning that `md` or `markdown` is already registered. Rename it, and declare it with `formatter :md, YourFormatter` (or `:markdown`) in the APIs that use it.
+
+#### `logger` applies to the API it is set on
+
+`logger` kept the logger in settings shared by the whole process, so setting it on one API replaced it on every other: two APIs that each set a logger both logged to whichever was set last.
+
+A logger now belongs to the API it is set on, and to the APIs mounted under it that set none of their own ([#3024](https://github.com/ruby-grape/grape/pull/3024)). An API that sets none, and is mounted under none that does, still logs to a default shared by every such API, so a level set on that default reaches all of them as before.
+
+```ruby
+class Users < Grape::API
+  logger Logger.new('users.log')
+end
+
+class Orders < Grape::API
+  logger Logger.new('orders.log')
+end
+
+# Users.logger  Before: the orders.log logger  After: the users.log logger
+```
+
+If an API logged to a logger set on another API that does not mount it, set the logger on that API as well, or on an API that mounts both. Setting one on `Grape::API::Instance` no longer reaches the APIs you define.
+
+#### `error!` raises `Grape::Exceptions::Halt` instead of throwing `:error`
+
+`error!` used to `throw :error`, and a throw is not an exception. Active Record commits a transaction that a throw leaves, so `error!` inside `transaction` saved what the block had written while the client was told the request failed ([#2197](https://github.com/ruby-grape/grape/issues/2197)). A throw cannot leave the fiber or thread it was thrown in either, so `error!` inside an `Async` task answered 500 instead of its status.
+
+`error!` now raises `Grape::Exceptions::Halt` ([#3023](https://github.com/ruby-grape/grape/pull/3023)), a `StandardError` carrying the same response (`#response`, also `#status` and `#headers`). Grape renders it as it rendered the thrown error, without handing it to a `rescue_from` handler, `rescue_from :all` included.
+
+* A `rescue => e` or `rescue StandardError` around `error!` now catches it, whether in a route, a helper, a filter or a middleware added with `use`. Narrow the rescue, or let `Halt` through:
+
+  ```ruby
+  rescue Grape::Exceptions::Halt
+    raise
+  rescue StandardError => e
+    # ...
+  ```
+
+* Code that wraps `error!` in `catch(:error)`, a spec for instance, now gets the exception. Rescue `Grape::Exceptions::Halt` and read `#response`, the `Grape::Exceptions::ErrorResponse` that used to be thrown.
+* An `ActiveSupport::Notifications` subscriber to `endpoint_run.grape`, `endpoint_render.grape` or `endpoint_run_filters.grape` now finds `:exception` and `:exception_object` in the payload when `error!` ends the request, as it does for any exception.
+
+`throw :error` from your own middleware or `rescue_from` handlers still works.
+
+#### `Grape::Exceptions::ErrorResponse` is no longer a `Data`
+
+Every error response builds at least two `ErrorResponse`s, and building a `Data` costs several times what building a plain object does. It is now a plain frozen class ([#3023](https://github.com/ruby-grape/grape/pull/3023)). It is still built with keywords, each optional, and still answers its readers.
+
+It no longer copies itself with `#with`, compares by value (`==`, `eql?`, `hash`), converts with `#to_h`, lists `members`, takes positional arguments or takes part in pattern matching. Build a new one with `ErrorResponse.new` instead of calling `#with`. To check a payload, read its fields, for instance with `have_attributes(status: 404, message: 'Not Found')` in a spec.
+
+#### `Grape::Middleware::Versioner::Header` answers a common Accept header without `#before`
+
+`Middleware::Base#call` copied the header versioner for every request so that `#before` could keep the env and the Accept header it scrubs in instance variables. When the API is not strict and the Accept header is one the versioner worked out when it was built (a media type it declares, `*/*` or none), it now records the media type and calls the app from the one instance the stack built ([#3017](https://github.com/ruby-grape/grape/pull/3017)). Any other request still goes through `#before`.
+
+A subclass that overrides `#before` is therefore not called for those requests. Override `#call` instead, and keep what a request needs in locals or in the env rather than in instance variables: the instance is shared by every request.
+
+#### `Grape::Middleware::Auth::Base#call` no longer goes through `#call!`
+
+`Middleware::Base#call` copied the auth middleware for every request so that `#call!` could keep the env in an instance variable, which only the strategy's block read, to find the endpoint that checks the credentials. The block now takes the endpoint from the request's env, and `#call` answers from the one instance the stack built ([#3018](https://github.com/ruby-grape/grape/pull/3018)). `#call!` still answers a request when called directly.
+
+A subclass that overrides `#call!` is therefore no longer called for a request. Override `#call` instead, and keep what a request needs in locals or in the env rather than in instance variables: the instance is shared by every request. A strategy registered with `Grape::Middleware::Auth::Strategies.add` is a middleware of its own and is not affected.
+
+#### `Grape::Middleware::Error#call` no longer goes through `#call!`
+
+`Grape::Middleware::Error` is in every endpoint's stack, and `Middleware::Base#call` copied it for every request so that `#call!` could keep the env in an ivar, which only rendering an error reads. It now answers from the one instance the stack built, and copies itself only once there is an error to render ([#3016](https://github.com/ruby-grape/grape/pull/3016)). `#call!` still answers a request when called directly.
+
+A subclass that overrides `#call!` to wrap every request is therefore no longer called for one. Override `#call` instead, and keep what a request needs in locals or in the env rather than in instance variables: the instance is shared by every request.
+
+#### A blank element of an optional Array block is validated when others are not blank
+
+An optional Array param given a block used to pass over every empty element, even one sent with others ([#3014](https://github.com/ruby-grape/grape/pull/3014)). So `[{"sku":"A"}, {}]` passed `requires :sku` inside the block, and `[{"sku":"A"}, null]` or `[{"sku":"A"}, ""]` reached the endpoint, where `params[:variants].map { |variant| variant[:sku] }` raised. Such an element is now validated like any other:
+
+```ruby
+params do
+  optional :variants, type: Array do
+    requires :sku
+  end
+end
+
+# {"variants": [{"sku": "A"}, {}]}
+# Before: 201, the second variant has no sku
+# After:  400, variants[1][sku] is missing
+
+# {"variants": [{"sku": "A"}, null]}
+# Before: 201, the endpoint gets nil
+# After:  400, variants[1] is invalid, variants[1][sku] is missing
+```
+
+A blank element that is not a Hash is also rejected in a required Array param whose block declares only optional params: `{"tags": [" ", {"label": "y"}]}` against `requires :tags, type: Array do optional :label end` now answers `tags[0] is invalid`.
+
+An Array whose elements are all blank is still passed over, as the whole param is when it is left out, and so is an optional Array scope left out of an element of an Array further up. To keep accepting placeholder elements, leave them out on the client, or declare the param without a block (`optional :variants, type: Array`) and check its elements in the endpoint.
+
+#### A header version holding a hyphen is read whole
+
+With `version ..., using: :header`, a version holding a hyphen, such as a date (`2024-06-20`) or `2.0-beta`, is now read whole ([#3013](https://github.com/ruby-grape/grape/pull/3013)). The Accept header was split at the version's last hyphen, so the request was routed to the right version but reported the wrong one:
+
+```
+# version '2024-06-20', using: :header, vendor: 'acme'
+# Accept: application/vnd.acme-2024-06-20+json
+# Before
+version            # => "20"
+env['api.vendor']  # => "acme-2024-06"
+# After
+version            # => "2024-06-20"
+env['api.vendor']  # => "acme"
+```
+
+An undeclared version of that shape now fails with `Grape::Exceptions::InvalidVersionHeader` (`API version not found.`), where it failed with `Grape::Exceptions::InvalidAcceptHeader` (`API vendor not found.`).
+
+#### An `Integer` param rejects a number with a fractional part
+
+A param of `type: Integer` now rejects a number with a fractional part instead of truncating it ([#3011](https://github.com/ruby-grape/grape/pull/3011)). A JSON body's `2.99` became `2` and `-0.5` became `0`, while the same value sent as a string, `"2.99"` in a query, was already rejected. The same applies to `Array[Integer]` and `Set[Integer]` elements. A whole number such as `1.0` still becomes `1`.
+
+```
+# {"quantity": 2.99} against `requires :quantity, type: Integer`
+# Before
+201, params[:quantity] == 2
+# After
+400, quantity is invalid
+```
+
+`types: [Integer, Float]` now answers `2.99` for that body, as it already did for the query string, where it used to answer `2`. To keep accepting and truncating fractional numbers, declare the param `type: Float` and call `to_i` on it, or pass `coerce_with: ->(value) { Integer(value.to_f) }`.
+
+#### A required param with `values` rejects `nil` in a nested scope
+
+A `requires` param with `values:` now rejects `nil` in a Hash scope, an Array scope or a `given` block, not only at the root ([#3010](https://github.com/ruby-grape/grape/pull/3010)). So does a value that coerces to `nil`, such as `""` for `type: Integer`. Before, only the root scope rejected it, so `{"lines":[{"qty":null}]}` passed the declaration below and reached the endpoint with `qty` set to `nil`:
+
+```ruby
+params do
+  requires :lines, type: Array do
+    requires :qty, type: Integer, values: 1..99
+  end
+end
+```
+
+That request now answers `400` with `lines[0][qty] does not have a valid value`. A nested param that is missing now reports that message after `is missing`, as a root param already did:
+
+```
+# Before
+address[country] is missing
+# After
+address[country] is missing, address[country] does not have a valid value
+```
+
+A child scope whose optional parent is absent is still not validated. To keep accepting `nil`, declare the param with `optional` instead.
+
+#### A mounted Rack app is an ANY route
+
+A Rack app mounted with `mount` (a lambda, Sinatra, Rails engine, anything that is not a Grape API) is now routed as an ANY route, like `route :any`, and keeps the place it was mounted in ([#3012](https://github.com/ruby-grape/grape/pull/3012)). Before, its route carried the method `ANY`, which the router has no routes for. The app was reached only as the fallback that answers `405` and auto `OPTIONS`, and that had these effects:
+
+* A `route :any, '*path'` catch-all took every request meant for the app, even one declared after the `mount`.
+* The app's env carried `grape.allowed_methods` (`["OPTIONS", "ANY"]`).
+* A method the app should have answered got `405` when a Grape route used the same path for another method.
+
+```ruby
+mount RackApp => '/rack'
+route(:any, '*path') { error!('not found', 404) }
+
+# GET /rack/x  Before: 404 from the catch-all  After: RackApp
+```
+
+```ruby
+mount RackApp => '/rack'
+get('rack/status') { 'ok' }
+
+# POST /rack/status  Before: 405 (Allow: OPTIONS, GET, HEAD)  After: RackApp
+```
+
+The mount's route reports `request_method` as `'*'` instead of `'ANY'`. Code that picks mounted apps out of `API.routes` by that value should compare with `'*'`.
+
+#### A validation error without a message says the param is invalid
+
+A `Grape::Exceptions::Validation` created without a `message:` now carries the `:invalid` message key and the message `is invalid` ([#2993](https://github.com/ruby-grape/grape/pull/2993)). Before, its `message_key` was `nil`, and its message was the exception's class name, which went into the response. A custom validator with no `default_message_key` that calls `validation_error!(attr_name)` answered:
+
+```
+# Before
+number Grape::Exceptions::Validation
+# After
+number is invalid
+```
+
+Code that checked `message_key` for `nil` to find such errors should check for `:invalid` instead. The message can be translated or overridden under `grape.errors.messages.invalid`.
+
+#### A `requires` or `optional` block needs exactly one name
+
+A `requires` or `optional` given a block now raises `ArgumentError` unless it names exactly one parameter ([#2991](https://github.com/ruby-grape/grape/pull/2991)). Both forms were accepted before, and both declared something other than what they read:
+
+```ruby
+# No name: the block's params were declared one level up, and under
+# `optional` they were still required.
+optional type: Hash do
+  requires :x
+end
+
+# Several names: `b` was required, but only `a` got the block's params,
+# and `b` was left out of `declared`.
+requires :a, :b, type: Hash do
+  requires :x
+end
+```
+
+Name the one parameter the block describes, and repeat the block for each parameter that shares its shape:
+
+```ruby
+requires :a, type: Hash do
+  requires :x
+end
+requires :b, type: Hash do
+  requires :x
+end
+```
+#### A query string Grape does not parse no longer decides the response
+
+Grape parsed the query string of every request that had one, only to look for a `?format=` override ([#2972](https://github.com/ruby-grape/grape/pull/2972)). It now parses it only when the string could name that param, and leaves it to whoever reads the params otherwise.
+
+A query string Rack refuses to parse -- nested past `Rack::Utils.param_depth_limit`, naming one key as both a value and a hash, or carrying more pairs than the parser accepts -- therefore no longer answers `400` on an endpoint that reads no params. Such a request is answered the way any other request for that route is:
+
+```ruby
+get('/ping') { 'pong' }
+
+# Before
+GET /ping?a[a][a]...=1 # => 400
+# After
+GET /ping?a[a][a]...=1 # => 200
+```
+
+An endpoint that reads the params -- one with a `params` block, or whose code asks for `params` -- still answers `400`, from the parse it asked for.
+
+#### A `redirect` body you pass carries the API's content type
+
+A body given to `redirect` with `body:` is rendered by the API's formatter, and the response now carries that format's content type instead of `text/plain` ([#2968](https://github.com/ruby-grape/grape/pull/2968)). On a JSON API, `redirect '/there', body: { message: 'moved' }` sent `{"message":"moved"}` labelled `text/plain`; it is now labelled `application/json`. The message Grape generates when no body is given is still plain text under `text/plain`.
+
+A client that picked the redirect body's parser by its `Content-Type` now gets the format the body is in; one that relied on `text/plain` for every redirect sees the API's own content type on those that pass a body.
+
+#### Every `middleware` entry ends in its block
+
+Each entry `API.middleware` returns now ends in the block its `use`, `insert`, `insert_before` or `insert_after` was given, `nil` when there was none ([#2967](https://github.com/ruby-grape/grape/pull/2967)). A Proc passed as the last argument used to be taken for the block, so `use SomeMiddleware, ->(env) { ... }` built the middleware without its callable and raised `ArgumentError`.
+
+```ruby
+use SomeMiddleware, 'abc'
+
+# Before
+API.middleware # => [[:use, SomeMiddleware, 'abc']]
+# After
+API.middleware # => [[:use, SomeMiddleware, 'abc', nil]]
+```
+
+Code that reads these entries should take the last element as the block.
+
+#### Minimum required Ruby is now 3.3.1
+
+Grape no longer supports Ruby 3.3.0; 3.3.1 is now the minimum (`required_ruby_version = '>= 3.3.1'`) ([#2966](https://github.com/ruby-grape/grape/pull/2966)). Ruby 3.3.0 rejects forwarding an anonymous parameter (`*`, `**`, `&`) from inside a block, which Grape does, so Grape could not be loaded on it; 3.3.1 fixed that. Upgrade your runtime to Ruby 3.3.1 or newer before bumping Grape.
+
+#### An Array param given a block rejects elements that are not a Hash
+
+The block of `requires :items, type: Array do ... end` declares the keys of each element, and an element that is not a Hash now answers `400` with `items[1] is invalid` ([#2957](https://github.com/ruby-grape/grape/pull/2957)). It used to fail only where the block required a key of it, so a block whose params are all optional let a String, a number or a nested Array through to the endpoint, and an Array nested one level too deep in a nested Array scope passed validation and then made `declared` raise. An Array whose elements are all blank — `nil`, `''`, `false`, `[]`, `{}` — is still passed over; a blank element sent with others is not (see above).
+
+Where a block does require a key, the element's own error now comes first:
+
+```
+# Before
+items[0][key] is missing
+# After
+items[0] is invalid, items[0][key] is missing
+```
+
+An API that accepts elements of other shapes in the same list should declare the param without a block (`type: Array`) and check the elements itself.
+
+#### A collection with multiple member types rejects what it cannot coerce
+
+A param declared as a collection whose members may be of several types — `type: Array[Integer, String]`, or such a collection listed in `types:` — is now validated the way a collection of one type is ([#2955](https://github.com/ruby-grape/grape/pull/2955)). A value that is not an Array, and an Array holding a member none of the types accepts, answer `400` with `is invalid`. The first used to reach the endpoint as `nil`, even under `requires`, and the second with an internal `Grape::Validations::Types::InvalidValue` object where the member was. A `nil` value or an empty String is still `nil`.
+
+A `coerce_with` method given to such a param is now handed every value, as it is for `types:`, instead of only an Array. A method that splits a String into the collection works now; one that only ever expected an Array may raise on a String, which answers `400`.
+#### A route's failure entity no longer presents a String error message
+
+An entity named for a status in a route's `failure` (or `http_codes`) is now applied to a structured `error!` message only — a Hash or an object — and a String message renders as it does without one ([#2953](https://github.com/ruby-grape/grape/pull/2953)). An entity exposing attributes cannot read any off a String, so `error!('Unauthorized', 401)` under `desc failure: [[401, 'Unauthorized', API::Error]]` raised while rendering and was answered with a `500`; it now answers `401` with the message. An entity written to take the String itself is no longer handed one; give it a Hash to expose from instead:
+
+```ruby
+# Before
+class API::Error < Grape::Entity
+  expose(:message) { |message, _options| message }
+end
+error!('Unauthorized', 401)
+
+# After
+class API::Error < Grape::Entity
+  expose :message
+end
+error!({ message: 'Unauthorized' }, 401)
+```
+#### `lint!` checks every response once, from the API that is served
+
+`lint!` and `Grape.config.lint` used to put `Rack::Lint` in each endpoint's stack, which missed two kinds of response: the 404 the router answers for a path nothing matches, and those of a Rack app mounted with `mount`, which the router calls directly. A single `Rack::Lint` around the router now checks every response the API gives ([#2960](https://github.com/ruby-grape/grape/pull/2960)). Two things follow from that.
+
+`lint!` counts only at the top level of the API that is served. Declared inside a namespace, or in an API mounted into another one, it no longer does anything: declare it on the API you serve, or set `Grape.config.lint`.
+
+A test suite that lints its API may start raising `Rack::Lint::LintError` where a mounted Rack app breaks the Rack SPEC — returning a frozen headers Hash, for instance — or where a spec calls the API with an incomplete env:
+
+```ruby
+# Before: passed under Grape.config.lint
+MyAPI.call({})
+
+# After
+MyAPI.call(Rack::MockRequest.env_for('/'))
+```
+#### The header versioner's `api.*` env values are frozen
+
+`version ..., using: :header` now answers the Accept headers most requests send from a table built once, so every request sending the same header is handed the same parsed media type ([#2936](https://github.com/ruby-grape/grape/pull/2936)). The strings it writes into the env — `api.type`, `api.subtype`, `api.vendor`, `api.version` and `api.format` — are therefore frozen, as is `Grape::Util::MediaType` itself. Code that altered one of them in place now raises `FrozenError`; build a new String instead:
+
+```ruby
+# Before
+env['api.version'] << '-beta'
+
+# After
+env['api.version'] = "#{env['api.version']}-beta"
+```
+
+#### `Grape::Util::Lazy` no longer builds a tree of value wrappers
+
+A configuration read is now a single `Grape::Util::Lazy::Value` holding the configuration it was read from and the path of keys walked into it, rather than a node in a tree mirroring the whole `with:` Hash ([#2950](https://github.com/ruby-grape/grape/pull/2950)). `Grape::Util::Lazy::ValueHash`, `Grape::Util::Lazy::ValueArray` and `Grape::Util::Lazy::ValueEnumerable` are gone, as are `Value#reached_by` and `Value#fetch`; `Value#access_keys` is now `Value#path`. The `configuration` DSL is unchanged — only code reaching into these internals is affected.
+
+`Grape::Util::EndpointConfiguration#evaluate` also answers the configuration Hash itself now, instead of rebuilding a copy on each call. Mutating what `configuration` returns inside an endpoint therefore persists for later requests, where it used to be discarded:
+
+```ruby
+# Before: mutated a throwaway copy
+# After: mutates the configuration every later request reads
+get '/x' do
+  configuration[:list] << 'item'
+end
+
+# Treat it as read-only, or copy it first
+get '/x' do
+  list = configuration[:list].dup
+  list << 'item'
+end
+```
+
 ### Upgrading to >= 4.0.0
 
 #### A positional options Hash is no longer accepted by `auth`, `http_basic` or `desc`

data/grape.gemspec

@@ -29,5 +29,5 @@ Gem::Specification.new do |s|
 
   s.files = Dir['lib/**/*', 'CHANGELOG.md', 'CONTRIBUTING.md', 'README.md', 'grape.png', 'UPGRADING.md', 'LICENSE', 'grape.gemspec']
   s.require_paths = ['lib']
-  s.required_ruby_version = '>= 3.3'
+  s.required_ruby_version = '>= 3.3.1'
 end

data/lib/grape/api/instance.rb

@@ -15,6 +15,8 @@ module Grape
       extend Grape::DSL::Middleware
       extend Grape::DSL::RequestResponse
       extend Grape::DSL::Routing
+      extend Grape::DSL::Mounting
+      extend Grape::DSL::Versioning
       extend Grape::DSL::Helpers
       extend Grape::Middleware::Auth::DSL
 
@@ -94,7 +96,6 @@ module Grape
         def inherited(subclass)
           super
           subclass.reset!
-          subclass.logger logger.clone
         end
       end
 
@@ -111,23 +112,33 @@ module Grape
 
         @router.compile!
         @router.freeze
-        @cascade = resolve_cascade
+        # One Rack::Head around the router strips the body of every HEAD
+        # response the API gives, including the router's own 404 and a mounted
+        # Rack app's, which go through no endpoint's stack. Rack::Lint goes
+        # outside it, where it sees the response that is served.
+        @app = Rack::Head.new(@router)
+        @app = Rack::Lint.new(@app) if lint?
+        @cascade = self.class.cascade
       end
 
       # Handle a request. See Rack documentation for what `env` is.
       def call(env)
-        status, headers, response = @router.call(env)
-        unless @cascade
-          # +merge!+, not +merge+: the latter is a `dup` plus a `merge!`, so the
-          # Header built on this line would be allocated only to be discarded.
-          # The copy stays because +headers+ can come from a mounted Rack app,
-          # which is free to hand back a frozen or shared Hash that the delete
-          # below must not reach into.
-          headers = Grape::Util::Header.new.merge!(headers)
-          headers.delete('X-Cascade')
-        end
-
-        [status, headers, response]
+        response = @app.call(env)
+        return response if @cascade
+
+        headers = response[1]
+        # A Grape::Util::Header folds case the way the copy below does, so it can
+        # answer for it; any other Hash cannot, and still goes through the copy.
+        return response if headers.is_a?(Grape::Util::Header) && !headers.key?('X-Cascade')
+
+        # +merge!+, not +merge+: the latter is a `dup` plus a `merge!`, so the
+        # Header built on this line would be allocated only to be discarded.
+        # The copy stays because +headers+ can come from a mounted Rack app,
+        # which is free to hand back a frozen or shared Hash that the delete
+        # below must not reach into.
+        headers = Grape::Util::Header.new.merge!(headers)
+        headers.delete('X-Cascade')
+        [response[0], headers, response[2]]
       end
 
       # Some requests may return a HTTP 404 error if grape cannot find a matching
@@ -136,7 +147,7 @@ module Grape
       # looking for a matching route on other resources.
       #
       # In some applications (e.g. mounting grape on rails), one might need to trap
-      # errors from reaching upstream. This is effectivelly done by unsetting
+      # errors from reaching upstream. This is effectively done by unsetting
       # X-Cascade. Default :cascade is true.
       #
       # Resolved in the constructor rather than per request: answering it walks
@@ -167,29 +178,45 @@ module Grape
         setting = self.class.inheritable_setting
         routes_by_regexp = all_routes.group_by(&:pattern_regexp)
 
-        # Build the configuration based on the first endpoint and the collection of methods supported.
+        # Build the configuration from the collection of methods supported.
         routes_by_regexp.each_value do |routes|
           next if routes.any? { |route| route.request_method == '*' }
 
-          last_route = routes.last # Most of the configuration is taken from the last endpoint
-          allowed_methods = routes.map(&:request_method)
-          allowed_methods |= [Rack::HEAD] if !setting.do_not_route_head? && allowed_methods.include?(Rack::GET)
+          associate_greedy_route(routes, setting)
+        end
+      end
 
-          allow_header = setting.do_not_route_options? ? allowed_methods : [Rack::OPTIONS] | allowed_methods
-          last_route.app.options_route_enabled = true unless setting.do_not_route_options? || allowed_methods.include?(Rack::OPTIONS)
+      # The greedy route answering 405 and auto-OPTIONS for the path +routes+
+      # share. Most of the configuration is taken from the last endpoint.
+      def associate_greedy_route(routes, setting)
+        last_route = routes.last
+        allowed_methods = allowed_methods_for(routes, setting)
 
-          greedy_route = Grape::Router::GreedyRoute.new(last_route.pattern, endpoint: last_route.app, allow_header:)
-          @router.associate_routes(greedy_route)
-        end
+        allow_header = setting.do_not_route_options? ? allowed_methods : [Rack::OPTIONS] | allowed_methods
+        last_route.app.options_route_enabled = true unless setting.do_not_route_options? || allowed_methods.include?(Rack::OPTIONS)
+
+        greedy_route = Grape::Router::GreedyRoute.new(last_route.pattern, endpoint: last_route.app, allow_header:)
+        @router.associate_routes(greedy_route)
       end
 
-      # Backs {#cascade?}; called once, from the constructor.
-      def resolve_cascade
-        setting = self.class.inheritable_setting
-        return setting.cascade if setting.cascade_defined?
-        return setting.version_options.cascade if setting.version_options
+      # The methods +routes+ answer, with HEAD alongside GET unless the API
+      # declared +do_not_route_head!+.
+      def allowed_methods_for(routes, setting)
+        allowed_methods = routes.map(&:request_method)
+        return allowed_methods if setting.do_not_route_head? || !allowed_methods.include?(Rack::GET)
+
+        allowed_methods | [Rack::HEAD]
+      end
 
-        true
+      # +lint!+ declared at the top of this API, or Grape.config.lint: one
+      # Rack::Lint around the router then checks every response the API gives
+      # -- an endpoint's, the 404 the router answers itself, a mounted Rack
+      # app's -- exactly once. Linting inside each endpoint's stack instead
+      # missed the last two, and wrapping a second Rack::Lint around those
+      # breaks a middleware that calls +to_ary+ on the body, as Rack::ETag does.
+      # Called once, from the constructor.
+      def lint?
+        self.class.inheritable_setting.lint? || Grape.config.lint
       end
     end
   end

data/lib/grape/api.rb

@@ -7,21 +7,28 @@ module Grape
     # Marks this and every subclass as a mountable Grape app (see Grape::Mountable).
     extend Grape::Mountable
 
-    # Class methods that we want to call on the API rather than on the API object
-    NON_OVERRIDABLE = %i[base= base_instance? call change! configuration compile! inherit_settings recognize_path reset! routes top_level_setting= top_level_setting].freeze
+    # Class methods that we want to call on the API rather than on the API object.
+    # +inherit_settings+ is protected on the base instance, and +.methods+ answers
+    # protected methods too, so it has to be named here for {.override_all_methods!}
+    # to leave it alone. +base+ is read on the API class itself whenever a mount
+    # is refreshed, so recording it would refresh every mount below it again.
+    NON_OVERRIDABLE = %i[base base= base_instance? call change! configuration compile! inherit_settings recognize_path reset! routes top_level_setting].freeze
+
+    # DSL methods that answer a setting when called with nothing to set -- no
+    # argument, keyword or block -- and change none. Such a call is a read, and
+    # is answered without being recorded: as a setup step it was replayed on
+    # every mount and, like any step, refreshed every mount made before it,
+    # which discards the compiled API, so a read after boot made the next
+    # request recompile it. +helpers+ is left out: called bare it includes the
+    # helpers in scope and calls +change!+ itself.
+    SETTING_READERS = %i[
+      auth cascade content_types default_error_formatter default_error_status default_format endpoints format
+      group inheritable_setting logger middleware namespace prefix resource resources segment version versions
+    ].freeze
 
     Helpers = Grape::DSL::Helpers::BaseHelper
 
-    class Boolean
-      VALUES = [true, false].freeze
-      private_constant :VALUES
-
-      def self.build(val)
-        return unless VALUES.include?(val)
-
-        new
-      end
-    end
+    Boolean = Class.new
 
     class << self
       extend Forwardable
@@ -30,12 +37,30 @@ module Grape
 
       delegate_missing_to :base_instance
 
-      # This is the interface point between Rack and Grape; it accepts a request
-      # from Rack and ultimately returns an array of three values: the status,
-      # the headers, and the body. See [the rack specification]
+      # Every NON_OVERRIDABLE name the base instance answers is forwarded here
+      # rather than left to +delegate_missing_to+, which stays for the names
+      # this list cannot know: anything defined on Grape::API::Instance after
+      # an API class was created, since {.override_all_methods!} copies the
+      # methods it finds at that moment.
+      #
+      # +inherit_settings+ is left out: it is protected on the base instance, so
+      # a delegator would raise NoMethodError just as the missing one does.
+      # +call+ is written out below.
+      def_delegators :base_instance, :new, :configuration, :change!, :compile!, :recognize_path, :routes,
+                     :base, :base=, :base_instance?, :reset!, :top_level_setting
+
+      # The interface point between Rack and Grape; it accepts a request from
+      # Rack and ultimately returns an array of three values: the status, the
+      # headers, and the body. See [the rack specification]
       # (https://github.com/rack/rack/blob/main/SPEC.rdoc) for more.
       # NOTE: This will only be called on an API directly mounted on RACK
-      def_delegators :base_instance, :new, :configuration, :call, :change!, :compile!, :recognize_path, :routes
+      #
+      # Not delegated with the rest because it runs on every request, and a
+      # Forwardable delegator checks its target with +defined?+ and forwards
+      # through +...+ each time: about as much again as the call it makes.
+      def call(env)
+        base_instance.call(env)
+      end
 
       # Initialize the instance variables on the remountable class, and the base_instance
       # an instance that will be used to create the set up but will not be mounted
@@ -46,11 +71,16 @@ module Grape
         @base_instance = mount_instance
       end
 
-      # Redefines all methods so that are forwarded to add_setup and be recorded
+      # Redefines all methods so that are forwarded to add_setup and be recorded.
+      # A read (see SETTING_READERS) is answered by the last instance, which is
+      # where add_setup takes its answer from, without being recorded.
       def override_all_methods!
         (base_instance.methods - Class.methods - NON_OVERRIDABLE).each do |method_override|
           define_singleton_method(method_override) do |*args, **kwargs, &block|
-            add_setup(method: method_override, args:, kwargs:, block:)
+            step = { method: method_override, args:, kwargs:, block: }
+            return replay_step_on(@instances.last, **step) if setting_read?(method_override, args, kwargs, block)
+
+            add_setup(**step)
           end
         end
       end
@@ -136,6 +166,10 @@ module Grape
         evaluate_arguments(instance.configuration, response).first
       end
 
+      def setting_read?(method, args, kwargs, block)
+        SETTING_READERS.include?(method) && args.empty? && kwargs.empty? && block.nil?
+      end
+
       # Skips steps that contain arguments to be lazily executed (on re-mount time)
       def skip_immediate_run?(instance, args, kwargs)
         instance.base_instance? &&