Warn when a rescue_from handler can never run

[ericproulx]

Summary

Grape::Middleware::Error resolves a registered handler with #find, so within a scope the first matching class wins. A handler registered for a class an earlier one already covers is therefore dead code, and silently so:

rescue_from StandardError do ... end   # wins
rescue_from ArgumentError do ... end   # never runs

Swapping the two lines is all it takes, but nothing said so — and the neighbouring rescue_from :all behaves the other way round, since it lives in all_rescue_handler and is consulted only after the registered handlers:

declaration	raising ArgumentError
rescue_from :all then rescue_from ArgumentError	ArgumentError handler ✅
rescue_from StandardError then rescue_from ArgumentError	StandardError handler

Two documented ways of saying "catch everything", ordering differently against a later specific handler — while the README describes rescue_from :all as rescuing "all StandardError exceptions".

Approach

Warn at definition time rather than reorder. Which handler should win is the author's call, and :all already offers "broad first, specific still wins" to anyone who wants it. No behaviour changes.

Grape: rescue_from ArgumentError will never run — StandardError was registered earlier
in the same scope and is matched first. Register the more specific class before the broader one.

Deliberately quiet in the cases that are not mistakes:

case	warns?
broader class registered first	✅
same class registered twice (first handler is kept)	✅ (own message)
narrower class registered first	—
unrelated classes	—
rescue_from A, B sharing one handler	—
same handler via with: on both	—
rescue_subclasses: false pairs	—
inner scope shadowing an enclosing one	—
rescue_from :all then a specific class	—

Across scopes the nearest registration deliberately wins, so an inner rescue_from StandardError shadowing an outer rescue_from ArgumentError is documented behaviour, not a mistake. Exact-match handlers are consulted before the subclass-matching ones and never match a descendant, so they cannot shadow each other either.

The check lives in Grape::Util::ShadowedRescueHandlers, called from #add_rescue_handlers where a scope's own registrations are known — kept out of InheritableSetting itself, which is at its Metrics/ClassLength limit and is a settings store rather than a place for DSL diagnostics.

README gains the ordering rule, which was only implied.

Test plan

• 7 new examples in inheritable_setting_spec.rb covering both warning messages and the five quiet cases; verified the two warning ones fail without the lib/ change.
• Full RSpec suite passes locally (2550 examples, 0 failures) — no existing spec registers a shadowed handler, so no new noise.
• RuboCop clean.
• CI green.

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run