Make forward_match an internal kwarg instead of a route option

`forward_match` was threaded from the mount/route DSL through
`Endpoint::Options` and the route options hash, only to be read once in
`Route#initialize` to pick the match function. Since the value it derives
from (`config.app`) already lives on the endpoint, compute it locally in
`to_routes` and pass it to `Grape::Router::Route.new` as a keyword
argument.

This drops `forward_match` from `Endpoint::Options`, from the route
options hash, and removes the now-dead `BaseRoute#forward_match`
delegator (which had no callers). Adds a direct unit test for
`Route#match?` under both forward/non-forward modes and an UPGRADING note
for the removed introspection surface.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ericproulx

CHANGELOG.md

@@ -3,6 +3,7 @@
 #### 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).
 * Your contribution here.
 
 #### Fixes

UPGRADING.md

@@ -1,6 +1,14 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 4.0.0
+
+#### `forward_match` is no longer exposed on routes
+
+`forward_match` is an internal, construction-time detail that decides how a route matches incoming paths (a prefix match for mounted Rack apps, the compiled pattern otherwise). It is now passed to `Grape::Router::Route` as a keyword argument and derived from the mounted app instead of being carried in the route's options.
+
+As a result it is no longer readable through `route.options[:forward_match]` or the `route.forward_match` reader — both previously returned the flag. Nothing in Grape consumed either, so this only affects code that introspected routes directly; there is no replacement, as the value is now purely internal.
+
 ### Upgrading to >= 3.3
 
 #### Minimum required Ruby is now 3.3

lib/grape/dsl/routing.rb

@@ -160,7 +160,6 @@ def mount(mounts, *opts)
             path:,
             app:,
             route_options: { anchor: false },
-            forward_match: !app.respond_to?(:inheritable_setting),
             for: self
           )
         end

lib/grape/endpoint.rb

@@ -276,6 +276,7 @@ def to_routes
       default_route_options = prepare_default_route_attributes(route_options)
       complete_route_options = route_options.merge(default_route_options)
       path_settings = prepare_default_path_settings
+      forward_match = config.app && !config.app.respond_to?(:inheritable_setting)
 
       config.http_methods.flat_map do |method|
         config.path.map do |path|
@@ -289,7 +290,7 @@ def to_routes
             version: default_route_options[:version],
             requirements: default_route_options[:requirements]
           )
-          Grape::Router::Route.new(self, method, pattern, complete_route_options)
+          Grape::Router::Route.new(self, method, pattern, complete_route_options, forward_match:)
         end
       end
     end
@@ -301,8 +302,7 @@ def prepare_default_route_attributes(route_options)
         requirements: prepare_routes_requirements(route_options[:requirements]),
         prefix: inheritable_setting.namespace_inheritable[:root_prefix],
         anchor: route_options.fetch(:anchor, true),
-        settings: inheritable_setting.route.except(:declared_params, :saved_validations),
-        forward_match: config.forward_match
+        settings: inheritable_setting.route.except(:declared_params, :saved_validations)
       }
     end
 

lib/grape/endpoint/options.rb

@@ -8,11 +8,11 @@ class Endpoint
     # stays a plain Hash for downstream gems (e.g. grape-swagger).
     # +:method+ is renamed to +:http_methods+ on the value object to avoid
     # shadowing +Object#method+ via the generated Data accessor.
-    Options = Data.define(:path, :http_methods, :for, :route_options, :app, :format, :forward_match) do
-      def initialize(path:, method:, route_options: {}, app: nil, format: nil, forward_match: nil, **rest)
+    Options = Data.define(:path, :http_methods, :for, :route_options, :app, :format) do
+      def initialize(path:, method:, route_options: {}, app: nil, format: nil, **rest)
         path = Array(path)
         path << '/' if path.empty?
-        super(path:, http_methods: Array(method), route_options:, app:, format:, forward_match:, **rest)
+        super(path:, http_methods: Array(method), route_options:, app:, format:, **rest)
       end
     end
   end

lib/grape/router/base_route.rb

@@ -10,7 +10,7 @@ class BaseRoute
       attr_reader :options, :pattern
 
       def_delegators :@pattern, :path, :origin
-      def_delegators :@options, :description, :version, :requirements, :prefix, :anchor, :settings, :forward_match, *Grape::Util::ApiDescription::DSL_METHODS
+      def_delegators :@options, :description, :version, :requirements, :prefix, :anchor, :settings, *Grape::Util::ApiDescription::DSL_METHODS
 
       def initialize(pattern, options = {})
         @pattern = pattern

lib/grape/router/route.rb

@@ -12,11 +12,11 @@ class Route < BaseRoute
 
       def_delegators :@app, :call
 
-      def initialize(endpoint, method, pattern, options)
+      def initialize(endpoint, method, pattern, options, forward_match:)
         super(pattern, options)
         @app = endpoint
         @request_method = upcase_method(method)
-        @match_function = options[:forward_match] ? FORWARD_MATCH_METHOD : NON_FORWARD_MATCH_METHOD
+        @match_function = forward_match ? FORWARD_MATCH_METHOD : NON_FORWARD_MATCH_METHOD
       end
 
       def convert_to_head_request!

spec/grape/api_spec.rb

@@ -3708,6 +3708,21 @@ def self.call(object, _env)
         expect(last_response.body).to eq('sauce')
       end
 
+      it 'does not forward unknown subpaths to a mounted API' do
+        subject.namespace :cool do
+          app = Class.new(Grape::API) # rubocop:disable RSpec/DescribedClass
+          app.get('/awesome') { 'sauce' }
+          mount app
+        end
+
+        get '/cool/awesome'
+        expect(last_response).to be_successful
+        get '/cool/awesome/subpath'
+        expect(last_response).to be_not_found
+        get '/cool/unknown'
+        expect(last_response).to be_not_found
+      end
+
       it 'mounts on a nested path' do
         app1 = Class.new(described_class)
         app2 = Class.new(described_class)

spec/grape/endpoint_spec.rb

@@ -1034,7 +1034,6 @@ def memoized
         path: '/path',
         app: {},
         route_options: { anchor: false },
-        forward_match: true,
         for: Class.new
       }
     end

spec/grape/router/route_spec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+RSpec.describe Grape::Router::Route do
+  let(:instance) { described_class.new(endpoint, :get, pattern, options, forward_match:) }
+  let(:endpoint) { instance_double(Grape::Endpoint) }
+  let(:options) { {} }
+  let(:pattern) do
+    Grape::Router::Pattern.new(
+      origin: '/mounty',
+      suffix: '',
+      anchor: true,
+      params: {},
+      format: nil,
+      version: nil,
+      requirements: {}
+    )
+  end
+
+  describe 'inheritance' do
+    subject { described_class.new(endpoint, :get, pattern, options, forward_match: false) }
+
+    it { is_expected.to be_a(Grape::Router::BaseRoute) }
+  end
+
+  describe '#match?' do
+    subject { instance.match?(input) }
+
+    context 'when forward_match is true' do
+      let(:forward_match) { true }
+
+      context 'with the exact origin' do
+        let(:input) { '/mounty' }
+
+        it { is_expected.to be_truthy }
+      end
+
+      context 'with a subpath under the origin' do
+        let(:input) { '/mounty/awesome/deep' }
+
+        it 'matches on the origin prefix' do
+          expect(subject).to be_truthy
+        end
+      end
+
+      context 'with a path outside the origin' do
+        let(:input) { '/other' }
+
+        it { is_expected.to be_falsey }
+      end
+
+      context 'with a blank input' do
+        let(:input) { '' }
+
+        it { is_expected.to be(false) }
+      end
+    end
+
+    context 'when forward_match is false' do
+      let(:forward_match) { false }
+
+      context 'with the exact origin' do
+        let(:input) { '/mounty' }
+
+        it { is_expected.to be_truthy }
+      end
+
+      context 'with a subpath under the origin' do
+        let(:input) { '/mounty/awesome/deep' }
+
+        it 'does not match beyond the anchored pattern' do
+          expect(subject).to be_falsey
+        end
+      end
+
+      context 'with a blank input' do
+        let(:input) { '' }
+
+        it { is_expected.to be(false) }
+      end
+    end
+  end
+end