Let a cascading route hand over to every remaining route

[ericproulx]

Problem

A route that answers with X-Cascade: pass is declining the request, asking the router to try the next matching route. Grape::Router#transaction did not do that. When the matched route cascaded and an ANY ('*') route existed, it took a shortcut:

return last_neighbor_route.call(env) if last_neighbor_route && last_response_cascade && route

last_neighbor_route is the greedy route — built per path pattern from routes.last (see API::Instance#collect_route_config_per_pattern), i.e. the last route registered for that path. So a cascading match handed over to exactly one route, the last one, and returned its answer as final. Every route registered in between was unreachable.

With two mounted versions this looks correct — "the last route" is the only sibling — which is why it survived a decade (the branch dates to the 2016 router rewrite, 499f6c6f, "Modify the priority of ANY routes, fixes #1089") and why the existing with catch-all shared example, which mounts exactly v1 and v2, passes.

Add a third version and the middle one disappears:

v1, v2, v3 = %w[v1 v2 v3].map { |v| versioned_api(v) }   # header versioning, cascade: true (default)

Class.new(Grape::API) do
  format :txt
  mount v1
  mount v2
  mount v3
  route(:any, '*path') { "catch-all: #{params[:path]}" }
end

request	before	after
Accept: …-v1+txt	200 v1 endpoint	200 v1 endpoint
Accept: …-v2+txt	406 API version not found	200 v2 endpoint
Accept: …-v3+txt	200 v3 endpoint	200 v3 endpoint
Accept: …-v999+txt	406 API version not found	200 catch-all: version

v1 works because it is matched first; v3 works because it is the greedy route; v2 is served by neither.

Fix

When a match cascades, try the method's remaining routes (#rotation) before falling back to the ANY routes and the greedy neighbour. The rest of the priority order — auto-OPTIONS, ANY routes, the greedy 405 — is unchanged, and #rotation is skipped entirely when nothing matched, since the compiled union it consults is the disjunction of the very patterns #rotation would walk.

#identity disappears (its two halves are now the first lines of #transaction), and Router#call no longer needs to run #rotation itself — the reason a request could previously reach #rotation only after the ANY route had already answered.

Behavior change: an unmatched version reaches a catch-all

Beyond the middle-version fix, one deliberate consequence, noted in UPGRADING: when a catch-all ANY route is present, a request whose version matches nothing now falls through to it instead of surfacing the versioner's 406 (last row of the table). That is what cascade: true — the default — asks for, and it is the same rule that already routes an unversioned path to the catch-all. version ..., cascade: false still answers 406 immediately and never consults the catch-all, so the hard-failure knob is unchanged.

Cascading bodies are now closed

#rotation discarded superseded cascading responses without closing their bodies. That was unreachable-ish before (rotation ran last); as soon as a third sibling made the path live, Rack::Lint flagged Body has not been closed. Superseded responses are now released through a shared #close_body, which #halt? also uses.

Verification

Beyond the suite, I diffed a 47-scenario probe of router behavior (versioned/unversioned, 1–3 versions, with and without a catch-all, cascade: false, path/header versioning, auto-OPTIONS, 405, HEAD, ANY-only, mixed specific+ANY, bare Rack mounts, nested mounts, 404s) between master and this branch. Exactly the four rows in the table above changed; the other 43 are byte-identical.

New specs: the shared versioning examples' with catch-all context gains a third version — so the existing v2 cases become middle-version cases across all four versioning strategies — plus an unknown-version case; router_spec.rb gains router-level specs pinning the contract without going through versioning. All new specs fail on master.

Relationship to #2824

#2824 fixes the routing-args leak on this same path (a cascaded-to route inheriting the previous attempt's route_info and path captures). They are independent, but complementary: this PR makes middle versions reachable, and #2824 is what makes the route that serves them see its own route_info and params. Both touch lib/grape/router.rb and spec/grape/router_spec.rb, and both add an UPGRADING entry, so whichever merges second needs a trivial rebase.

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run