Add mounted_app reader and app: keyword to Grape::Endpoint

`app` (the Rack app or Grape API mounted at an endpoint) was reachable
only by digging into the public options bag as `endpoint.options[:app]`.

Introduce a first-class `mounted_app` reader (returning `config.app`,
`nil` for a plain block endpoint) and accept `app:` as an explicit
keyword on `Grape::Endpoint#initialize`. Grape's own mount-refresh dedup
now reads `endpoint.mounted_app` instead of `options[:app]`.

This is additive and non-breaking: `options[:app]` is still populated
exactly as before for downstream consumers (e.g. grape-swagger), which
can migrate to `mounted_app` before it is eventually dropped from the
options Hash. Also adds the previously-missing coverage for the
`refresh_already_mounted` dedup path.

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

Author: ericproulx

CHANGELOG.md

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

lib/grape/dsl/routing.rb

@@ -150,7 +150,7 @@ def mount(mounts, *opts)
           refresh_already_mounted = opts.any? ? opts.first[:refresh_already_mounted] : false
           if refresh_already_mounted && !endpoints.empty?
             endpoints.delete_if do |endpoint|
-              endpoint.options[:app].to_s == app.to_s
+              endpoint.mounted_app.to_s == app.to_s
             end
           end
 

lib/grape/endpoint.rb

@@ -24,6 +24,13 @@ def logger
       config.for.logger
     end
 
+    # The Rack app or Grape API mounted at this endpoint, or +nil+ for a plain
+    # block endpoint. Prefer this over +options[:app]+, which is retained only
+    # for backwards compatibility.
+    def mounted_app
+      config.app
+    end
+
     class << self
       def block_to_unbound_method(block)
         return unless block
@@ -42,13 +49,15 @@ def block_to_unbound_method(block)
     #   reach this endpoint.
     # @param path [String or Array] the path to this endpoint, within the
     #   current scope.
+    # @param app [#call, nil] the Rack app or Grape API mounted at this
+    #   endpoint; +nil+ for a plain block endpoint. Exposed as {#mounted_app}.
     # @param options [Hash] attributes of this endpoint, normalized into a
     #   +Grape::Endpoint::Options+ value object.
     # @option options route_options [Hash]
     # @note This happens at the time of API definition, so in this context the
     # endpoint does not know if it will be mounted under a different endpoint.
     # @yield a block defining what your API should do when this endpoint is hit
-    def initialize(new_settings, http_methods:, path:, **options, &block)
+    def initialize(new_settings, http_methods:, path:, app: nil, **options, &block)
       self.inheritable_setting = new_settings.point_in_time_copy
 
       # now +namespace_stackable(:declared_params)+ contains all params defined for
@@ -61,7 +70,10 @@ def initialize(new_settings, http_methods:, path:, **options, &block)
       inheritable_setting.namespace_inheritable[:default_error_status] ||= 500
 
       @options = options
-      @config = Options.new(http_methods:, path:, **options)
+      @config = Options.new(http_methods:, path:, app:, **options)
+      # +:app+ is still surfaced on the public options Hash for backwards
+      # compatibility (e.g. grape-swagger); prefer the +mounted_app+ reader.
+      @options[:app] = app if app
 
       @status = nil
       @stream = nil

spec/grape/api_spec.rb

@@ -3571,6 +3571,39 @@ def self.call(object, _env)
       end
     end
 
+    describe 'the mounted endpoint' do
+      it 'exposes the mounted app through #mounted_app' do
+        subject.mount mounted_app => '/mounty'
+        expect(subject.endpoints.last.mounted_app).to be(mounted_app)
+      end
+
+      it 'reports nil #mounted_app for a plain block endpoint' do
+        subject.get('/plain') { 'hi' }
+        expect(subject.endpoints.last.mounted_app).to be_nil
+      end
+
+      it 'still surfaces the mounted app on the options Hash' do
+        subject.mount mounted_app => '/mounty'
+        expect(subject.endpoints.last.options[:app]).to be(mounted_app)
+      end
+    end
+
+    context 'with refresh_already_mounted' do
+      let(:app) { Class.new(described_class) { get('/x') { 'x' } } }
+
+      it 'replaces a previously mounted app instead of duplicating it' do
+        subject.mount app => '/thing'
+        expect { subject.mount({ app => '/thing' }, refresh_already_mounted: true) }
+          .not_to(change { subject.endpoints.count })
+      end
+
+      it 'duplicates the endpoint without the flag' do
+        subject.mount app => '/thing'
+        expect { subject.mount app => '/thing' }
+          .to change { subject.endpoints.count }.by(1)
+      end
+    end
+
     context 'mounting an API' do
       it 'applies the settings of the mounting api' do
         subject.version 'v1', using: :path