Land #2775–#2779 on master (stacked-merge recovery) (#2780)

* Pass http_methods to Grape::Endpoint as a keyword instead of via options

`method` was pulled out of the endpoint's `**options` Hash, normalized in
place (`@options[:method] = Array(...)`), and renamed to `http_methods` on
the `Options` value object purely to dodge the `Object#method` shadow on
the generated Data accessor.

Expose it directly as a required `http_methods:` keyword on
`Grape::Endpoint#initialize` and pass it straight into `Options`, whose
field is now genuinely named `http_methods` (no rename, no shadow). The
value stays in `config` so endpoint equality — `config == other.config`,
which keeps same-path/different-verb endpoints distinct — is unchanged.

The endpoint's public `options` Hash no longer carries the redundant
`:method` entry; nothing read it, and grape-swagger reads the verb from
`route.request_method`. Documented in UPGRADING.

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

* Pass path to Grape::Endpoint as a keyword instead of via options

`path` was pulled from the endpoint's `**options` Hash and normalized in
place (`@options[:path] = Array(...)`), duplicating the normalization
`Options` already does.

Expose it as a required `path:` keyword on `Grape::Endpoint#initialize`
and pass it straight into `Options`, which stays the single normalized
source of truth. `path` remains in `config` because it is load-bearing
for route building (`config.path`) and for endpoint equality
(`config == other.config`, which keeps same-path/different-verb endpoints
distinct).

The endpoint's public `options` Hash no longer carries `:path`. Its only
reader was an internal test; `route.path` (the compiled pattern) is the
public path API and is what grape-swagger already uses. Documented in
UPGRADING.

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

* 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>

* Rename Grape::Endpoint's for: keyword to api: and expose #api

`for` identified the API an endpoint belongs to, but it is a reserved
word: it can only reach `Options` through `**rest` and its value can't be
referenced as a local. Rename it to `api:`, an explicit keyword on
`Grape::Endpoint#initialize`, and drop the `**rest` workaround from
`Options`.

`api` stays in `config` because it is load-bearing: the endpoint reaches
the mounting API's live `configuration` (used by remountable APIs and
read lazily at request time) through it, so it cannot be captured at
construction. `logger` and the new public `#api` reader are exposed via
`Forwardable` delegation to the config value object.

The owning API is no longer carried on the endpoint's public options Hash
(`endpoint.options[:for]` is gone); use `endpoint.api` instead. Only
in-repo reader was one spec. Documented in UPGRADING.

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

* Promote route metadata to Route keyword arguments

`version`, `namespace`, `prefix`, `requirements`, `anchor` and `settings`
were computed in `Endpoint#prepare_default_route_attributes`, merged into
the route options Hash, and read back through `Grape::Router::BaseRoute`'s
`def_delegators :@options`. They are route metadata, not part of the
user-declared options bag grape-swagger consumes.

They are now passed to `Grape::Router::Route` as explicit keyword
arguments and exposed as plain readers on `BaseRoute`. `Endpoint#to_routes`
computes each as a local and passes `config.route_options` straight
through, so `prepare_default_route_attributes` (and the intermediate
`default_route_options`/`complete_route_options`) is gone. `Route`
forwards the attributes to `super` via `**route_attributes` to keep its
signature lean.

`route.options` now carries only what was declared for the route; the
`@options` delegation is down to `description` plus the documentation
`DSL_METHODS`. The readers are unchanged, so grape-swagger (which reads
`route.prefix` and `route.settings`) is unaffected. `requirements` and
`anchor` can still be declared as route options, so any explicit value
stays in `route.options`; the effective value comes from the reader.

Also drop the vestigial `:format` member from the endpoint's `Options`.
Nothing ever passed `format:` to `Grape::Endpoint.new`, so `config.format`
was always `nil`; the format capture comes from the path suffix built by
`Grape::Path`, not from `Pattern`'s `format`. `Pattern#initialize` keeps
`format:` (now optional) since it remains a valid capture constraint used
by external callers.

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

---------

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

Author: ericproulx

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 * [#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).
+* [#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).
+* [#2778](https://github.com/ruby-grape/grape/pull/2778): Rename `Grape::Endpoint`'s `for:` keyword to `api:` and expose `#api` - [@ericproulx](https://github.com/ericproulx).
+* [#2779](https://github.com/ruby-grape/grape/pull/2779): Promote route metadata (`version`, `namespace`, `prefix`, `requirements`, `anchor`, `settings`) to `Grape::Router::Route` keyword arguments - [@ericproulx](https://github.com/ericproulx).
 * Your contribution here.
 
 #### Fixes

UPGRADING.md

@@ -9,6 +9,51 @@ Upgrading Grape
 
 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.
 
+#### `Grape::Endpoint.new` takes `http_methods:` instead of `method:`
+
+`Grape::Endpoint.new` now receives the HTTP verb(s) under the `http_methods:` keyword instead of `method:`, matching the name used everywhere else. If you build endpoints directly (uncommon — this is an internal API normally driven by the routing DSL), rename the keyword:
+
+```ruby
+# before
+Grape::Endpoint.new(settings, method: :get, path: '/foo', for: self)
+
+# after
+Grape::Endpoint.new(settings, http_methods: :get, path: '/foo', for: self)
+```
+
+Relatedly, an endpoint's public `options` Hash no longer carries `:method` or `:path`. Nothing in Grape read `:method`, and the only reader of `:path` was an internal test; both values are available from the route instead — `route.request_method` for the verb and `route.path` for the (compiled) path, which is what grape-swagger and other introspection already use. The raw definition-time path array is no longer exposed on the endpoint.
+
+#### `Grape::Endpoint.new` takes `api:` instead of `for:`
+
+The keyword identifying the API an endpoint belongs to has been renamed from `for:` — a reserved word whose value can't be referenced as a local — to `api:`:
+
+```ruby
+# before
+Grape::Endpoint.new(settings, http_methods: :get, path: '/foo', for: my_api)
+
+# after
+Grape::Endpoint.new(settings, http_methods: :get, path: '/foo', api: my_api)
+```
+
+The owning API is no longer carried on the endpoint's public `options` Hash — `endpoint.options[:for]` is gone. Use the new `endpoint.api` reader instead.
+
+#### Route metadata is exposed through readers, not the `options` Hash
+
+A route's computed metadata — `version`, `namespace`, `prefix`, `requirements`, `anchor` and `settings` — is now passed to `Grape::Router::Route` as explicit keyword arguments and exposed as plain readers, instead of being merged into the route's `options` Hash.
+
+The readers are unchanged — keep using them:
+
+```ruby
+route.version       # => 'v1'
+route.namespace     # => '/things'
+route.prefix        # => 'api'
+route.requirements  # => {}
+route.anchor        # => true
+route.settings      # => { ... }
+```
+
+What changed is the raw bag. `route.options` now holds only what was declared for the route, so it no longer carries the *computed* values for these keys — `route.options[:version]`, `[:namespace]`, `[:prefix]` and `[:settings]` return `nil`. Nothing in Grape or grape-swagger read them that way (grape-swagger uses the `route.prefix` and `route.settings` readers). For `requirements` and `anchor`, which can be supplied as route options (e.g. a mount's `anchor: false`), any explicitly declared value still appears in `route.options`; the effective value always comes from the reader.
+
 ### Upgrading to >= 3.3
 
 #### Minimum required Ruby is now 3.3

lib/grape/dsl/inside_route.rb

@@ -15,7 +15,7 @@ def version
       end
 
       def configuration
-        config.for.configuration.evaluate
+        config.api.configuration.evaluate
       end
 
       # End the request and display an error to the

lib/grape/dsl/routing.rb

@@ -150,17 +150,17 @@ 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
 
           endpoints << Grape::Endpoint.new(
             in_setting,
-            method: :any,
+            http_methods: :any,
             path:,
             app:,
             route_options: { anchor: false },
-            for: self
+            api: self
           )
         end
       end
@@ -178,7 +178,7 @@ def mount(mounts, *opts)
       #     end
       #   end
       def route(methods, paths = ['/'], route_options = {}, &)
-        method = methods == :any ? '*' : methods
+        http_methods = methods == :any ? '*' : methods
         endpoint_params = inheritable_setting.namespace_stackable_with_hash(:params) || {}
         endpoint_description = inheritable_setting.route[:description]
         all_route_options = { params: endpoint_params }
@@ -187,9 +187,9 @@ def route(methods, paths = ['/'], route_options = {}, &)
 
         new_endpoint = Grape::Endpoint.new(
           inheritable_setting,
-          method:,
+          http_methods:,
           path: paths,
-          for: self,
+          api: self,
           route_options: all_route_options,
           &
         )

lib/grape/endpoint.rb

@@ -17,11 +17,19 @@ class Endpoint
     def_delegators :request, :params, :headers, :cookies
     def_delegator :cookies, :response_cookies
 
+    # The API (a +Grape::API+ instance) this endpoint belongs to.
+    def_delegator :@config, :api
+
     # The logger configured on the API this endpoint belongs to. Available
     # inside route handlers, +before+/+after+/+after_validation+/+finally+
     # filters, and +rescue_from+ blocks.
-    def logger
-      config.for.logger
+    def_delegator :api, :logger
+
+    # 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
@@ -38,17 +46,21 @@ def block_to_unbound_method(block)
     # Create a new endpoint.
     # @param new_settings [InheritableSetting] settings to determine the params,
     #   validations, and other properties from.
+    # @param http_methods [String or Array] which HTTP method(s) can be used to
+    #   reach this endpoint.
+    # @param path [String or Array] the path to this endpoint, within the
+    #   current scope.
+    # @param api [Grape::API] the API this endpoint belongs to. Exposed as
+    #   {#api}.
+    # @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 path [String or Array] the path to this endpoint, within
-    #   the current scope.
-    # @option options method [String or Array] which HTTP method(s) can be used
-    #   to reach this endpoint.
     # @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, **options, &block)
+    def initialize(new_settings, http_methods:, path:, api:, app: nil, **options, &block)
       self.inheritable_setting = new_settings.point_in_time_copy
 
       # now +namespace_stackable(:declared_params)+ contains all params defined for
@@ -61,10 +73,10 @@ def initialize(new_settings, **options, &block)
       inheritable_setting.namespace_inheritable[:default_error_status] ||= 500
 
       @options = options
-      @options[:path] = Array(@options[:path])
-      @options[:path] << '/' if @options[:path].empty?
-      @options[:method] = Array(@options[:method])
-      @config = Options.new(**options)
+      @config = Options.new(http_methods:, path:, api:, 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
@@ -273,39 +285,30 @@ def compile!
 
     def to_routes
       route_options = config.route_options
-      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)
+      version = prepare_version(inheritable_setting.namespace_inheritable[:version])
+      prefix = inheritable_setting.namespace_inheritable[:root_prefix]
+      requirements = prepare_routes_requirements(route_options[:requirements])
+      anchor = route_options.fetch(:anchor, true)
+      settings = inheritable_setting.route.except(:declared_params, :saved_validations)
 
       config.http_methods.flat_map do |method|
         config.path.map do |path|
-          prepared_path = Path.new(path, default_route_options[:namespace], path_settings)
+          prepared_path = Path.new(path, namespace, path_settings)
           pattern = Grape::Router::Pattern.new(
             origin: prepared_path.origin,
             suffix: prepared_path.suffix,
-            anchor: default_route_options[:anchor],
+            anchor:,
             params: route_options[:params],
-            format: config.format,
-            version: default_route_options[:version],
-            requirements: default_route_options[:requirements]
+            version:,
+            requirements:
           )
-          Grape::Router::Route.new(self, method, pattern, complete_route_options, forward_match:)
+          Grape::Router::Route.new(self, method, pattern, route_options, forward_match:, version:, namespace:, prefix:, requirements:, anchor:, settings:)
         end
       end
     end
 
-    def prepare_default_route_attributes(route_options)
-      {
-        namespace:,
-        version: prepare_version(inheritable_setting.namespace_inheritable[:version]),
-        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)
-      }
-    end
-
     def prepare_default_path_settings
       namespace_stackable_hash = inheritable_setting.namespace_stackable.to_hash
       namespace_inheritable_hash = inheritable_setting.namespace_inheritable.to_hash

lib/grape/endpoint/options.rb

@@ -6,13 +6,12 @@ class Endpoint
     # +Grape::Endpoint.new+. Internal to {Grape::Endpoint}, which builds it
     # from the +**options+ Hash in #initialize so the public +options+ reader
     # 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) do
-      def initialize(path:, method:, route_options: {}, app: nil, format: nil, **rest)
+    Options = Data.define(:path, :http_methods, :api, :route_options, :app) do
+      def initialize(path:, http_methods:, api:, route_options: {}, app: nil)
         path = Array(path)
         path << '/' if path.empty?
-        super(path:, http_methods: Array(method), route_options:, app:, format:, **rest)
+        http_methods = Array(http_methods)
+        super
       end
     end
   end

lib/grape/router/base_route.rb

@@ -7,19 +7,20 @@ class BaseRoute
 
       delegate_missing_to :@options
 
-      attr_reader :options, :pattern
+      attr_reader :options, :pattern, :version, :prefix, :requirements, :anchor, :settings, :namespace
 
       def_delegators :@pattern, :path, :origin
-      def_delegators :@options, :description, :version, :requirements, :prefix, :anchor, :settings, *Grape::Util::ApiDescription::DSL_METHODS
+      def_delegators :@options, :description, *Grape::Util::ApiDescription::DSL_METHODS
 
-      def initialize(pattern, options = {})
+      def initialize(pattern, options = {}, version: nil, namespace: nil, prefix: nil, requirements: nil, anchor: nil, settings: nil)
         @pattern = pattern
         @options = options.is_a?(ActiveSupport::OrderedOptions) ? options : ActiveSupport::OrderedOptions.new.update(options)
-      end
-
-      # see https://github.com/ruby-grape/grape/issues/1348
-      def namespace
-        @namespace ||= @options[:namespace]
+        @version = version
+        @namespace = namespace
+        @prefix = prefix
+        @requirements = requirements
+        @anchor = anchor
+        @settings = settings
       end
 
       def regexp_capture_index

lib/grape/router/pattern.rb

@@ -13,7 +13,7 @@ class Pattern
       def_delegators :to_regexp, :===
       alias match? ===
 
-      def initialize(origin:, suffix:, anchor:, params:, format:, version:, requirements:)
+      def initialize(origin:, suffix:, anchor:, params:, version:, requirements:, format: nil)
         @origin = origin
         @path = PatternCache[[build_path_from_pattern(@origin, anchor), suffix]]
         @pattern = MustermannPattern.new(@path, uri_decode: true, params:, capture: extract_capture(format, version, requirements))

lib/grape/router/route.rb

@@ -12,8 +12,8 @@ class Route < BaseRoute
 
       def_delegators :@app, :call
 
-      def initialize(endpoint, method, pattern, options, forward_match:)
-        super(pattern, options)
+      def initialize(endpoint, method, pattern, options, forward_match:, **route_attributes)
+        super(pattern, options, **route_attributes)
         @app = endpoint
         @request_method = upcase_method(method)
         @match_function = forward_match ? FORWARD_MATCH_METHOD : NON_FORWARD_MATCH_METHOD

spec/grape/api_spec.rb

@@ -3133,6 +3133,14 @@ def self.call(object, _env)
       it 'sets prefix' do
         expect(subject.routes[1].prefix).to eq('p')
       end
+
+      it 'does not carry computed attributes in the route options Hash' do
+        route = subject.routes[1]
+        expect(route.options).not_to have_key(:version)
+        expect(route.options).not_to have_key(:namespace)
+        expect(route.options).not_to have_key(:prefix)
+        expect(route.options).not_to have_key(:settings)
+      end
     end
 
     describe 'api structure with additional parameters' do
@@ -3571,6 +3579,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
@@ -3982,7 +4023,7 @@ def my_method
       subject.format :json
       subject.get '/endpoint/options' do
         {
-          path: options[:path],
+          path: route.path,
           source_location: source.source_location
         }
       end
@@ -3991,7 +4032,7 @@ def my_method
     it 'path' do
       get '/endpoint/options'
       options = Grape::Json.parse(last_response.body)
-      expect(options['path']).to eq(['/endpoint/options'])
+      expect(options['path']).to eq('/endpoint/options(.json)')
       expect(options['source_location'][0]).to include 'api_spec.rb'
       expect(options['source_location'][1].to_i).to be > 0
     end