Nest Grape::Path inside Grape::Router::Pattern (#2792)

ericproulx · claude · web-flow · commit d7137976aa5b · 2026-07-12T12:30:08.000-04:00
Grape::Path only ever existed to compute the origin/suffix strings that
Grape::Router::Pattern compiles into a matcher — it had a single caller
(Endpoint#to_routes) yet sat at the top level of the Grape namespace as if
it were public.

Move it to Grape::Router::Pattern::Path and add a Pattern.build factory that
takes the raw path, namespace and inheritable settings and constructs the
Path internally, so the endpoint makes one call instead of building a Path
and threading its origin/suffix into Pattern.new. Pattern.new stays
value-based (origin:/suffix:/...), so the matcher never learns about the
settings-hash shape; only Path (and the thin factory) is settings-aware.

Grape::Path is kept as a deprecated constant proxy to the new location.

Co-authored-by: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@
 * [#2782](https://github.com/ruby-grape/grape/pull/2782): Remove the dead `format` keyword from `Grape::Router::Pattern` - [@ericproulx](https://github.com/ericproulx).
 * [#2783](https://github.com/ruby-grape/grape/pull/2783): Read a route's `version`, `anchor` and `requirements` from its pattern instead of storing them again on the route - [@ericproulx](https://github.com/ericproulx).
 * [#2784](https://github.com/ruby-grape/grape/pull/2784): Move HEAD route creation into `Grape::Router::Route#to_head` - [@ericproulx](https://github.com/ericproulx).
+* [#2792](https://github.com/ruby-grape/grape/pull/2792): Move `Grape::Path` to `Grape::Router::Pattern::Path` and add a `Grape::Router::Pattern.build` factory (`Grape::Path` kept as a deprecated constant) - [@ericproulx](https://github.com/ericproulx).
 * [#2785](https://github.com/ruby-grape/grape/pull/2785): Make route `params` a first-class endpoint input and split `Grape::Router::Route#params` into `#params` (declared definitions) and `#params_for(input)` (extracted values) - [@ericproulx](https://github.com/ericproulx).
 * [#2786](https://github.com/ruby-grape/grape/pull/2786): Make route `requirements` and `anchor` explicit keyword arguments and first-class endpoint inputs instead of opaque `route_options` keys - [@ericproulx](https://github.com/ericproulx).
 * Your contribution here.
diff --git a/lib/grape/endpoint.rb b/lib/grape/endpoint.rb
@@ -299,10 +299,10 @@ def to_routes
 
       config.http_methods.flat_map do |method|
         config.path.map do |path|
-          prepared_path = Path.new(path, namespace, path_settings)
-          pattern = Grape::Router::Pattern.new(
-            origin: prepared_path.origin,
-            suffix: prepared_path.suffix,
+          pattern = Grape::Router::Pattern.build(
+            path:,
+            namespace:,
+            settings: path_settings,
             anchor:,
             params:,
             version:,
diff --git a/lib/grape/path.rb b/lib/grape/path.rb
@@ -1,73 +1,12 @@
 # frozen_string_literal: true
 
 module Grape
-  # Represents a path to an endpoint.
-  class Path
-    DEFAULT_FORMAT_SEGMENT = '(/.:format)'
-    NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT = '(.:format)'
-    VERSION_SEGMENT = ':version'
-
-    attr_reader :origin, :suffix
-
-    def initialize(raw_path, raw_namespace, settings)
-      @origin = PartsCache[build_parts(raw_path, raw_namespace, settings)]
-      @suffix = build_suffix(raw_path, raw_namespace, settings)
-    end
-
-    def to_s
-      "#{origin}#{suffix}"
-    end
-
-    private
-
-    def build_suffix(raw_path, raw_namespace, settings)
-      return "(.#{settings[:format]})" if uses_specific_format?(settings)
-      return NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT if !uses_path_versioning?(settings) || valid_part?(raw_namespace) || valid_part?(raw_path)
-
-      DEFAULT_FORMAT_SEGMENT
-    end
-
-    def build_parts(raw_path, raw_namespace, settings)
-      parts = []
-      add_part(parts, settings[:mount_path])
-      add_part(parts, settings[:root_prefix])
-      parts << VERSION_SEGMENT if uses_path_versioning?(settings)
-      add_part(parts, raw_namespace)
-      add_part(parts, raw_path)
-      parts
-    end
-
-    def add_part(parts, value)
-      parts << value if value && not_slash?(value)
-    end
-
-    def not_slash?(value)
-      value != '/'
-    end
-
-    def uses_specific_format?(settings)
-      return false unless settings.key?(:format) && settings.key?(:content_types)
-
-      settings[:format] && Array(settings[:content_types]).size == 1
-    end
-
-    def uses_path_versioning?(settings)
-      return false unless settings.key?(:version) && settings[:version_options]
-
-      settings[:version] && settings[:version_options].using == :path
-    end
-
-    def valid_part?(part)
-      part&.match?(/^\S/) && not_slash?(part)
-    end
-
-    class PartsCache < Grape::Util::Cache
-      def initialize
-        super
-        @cache = Hash.new do |h, parts|
-          h[parts] = Grape::Util::PathNormalizer.call(parts.join('/'))
-        end
-      end
-    end
-  end
+  # @deprecated +Grape::Path+ moved to {Grape::Router::Pattern::Path}, since it
+  #   is a router-internal detail that only exists to build a
+  #   {Grape::Router::Pattern}. Reference the new constant instead.
+  Path = ActiveSupport::Deprecation::DeprecatedConstantProxy.new(
+    'Grape::Path',
+    'Grape::Router::Pattern::Path',
+    Grape.deprecator
+  )
 end
diff --git a/lib/grape/router/pattern.rb b/lib/grape/router/pattern.rb
@@ -13,6 +13,14 @@ class Pattern
       def_delegators :to_regexp, :===
       alias match? ===
 
+      # Build a Pattern from a raw path, namespace and the API's inheritable
+      # settings. {Path} owns the settings-aware assembly of +origin+/+suffix+;
+      # the Pattern itself stays value-based (see {#initialize}).
+      def self.build(path:, namespace:, settings:, anchor:, params:, version:, requirements:)
+        built_path = Path.new(path, namespace, settings)
+        new(origin: built_path.origin, suffix: built_path.suffix, anchor:, params:, version:, requirements:)
+      end
+
       def initialize(origin:, suffix:, anchor:, params:, version:, requirements:)
         @origin = origin
         @anchor = anchor
diff --git a/lib/grape/router/pattern/path.rb b/lib/grape/router/pattern/path.rb
@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Grape
+  class Router
+    class Pattern
+      # Assembles the path template a {Pattern} compiles into a matcher. It turns
+      # a raw path plus the API's inheritable settings (mount path, root prefix,
+      # path-versioning and format) into an +origin+ (the route prefix) and a
+      # +suffix+ (the format segment). {Pattern.build} is the entry point that
+      # wires this into pattern construction.
+      class Path
+        DEFAULT_FORMAT_SEGMENT = '(/.:format)'
+        NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT = '(.:format)'
+        VERSION_SEGMENT = ':version'
+
+        attr_reader :origin, :suffix
+
+        def initialize(raw_path, raw_namespace, settings)
+          @origin = PartsCache[build_parts(raw_path, raw_namespace, settings)]
+          @suffix = build_suffix(raw_path, raw_namespace, settings)
+        end
+
+        def to_s
+          "#{origin}#{suffix}"
+        end
+
+        private
+
+        def build_suffix(raw_path, raw_namespace, settings)
+          return "(.#{settings[:format]})" if uses_specific_format?(settings)
+          return NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT if !uses_path_versioning?(settings) || valid_part?(raw_namespace) || valid_part?(raw_path)
+
+          DEFAULT_FORMAT_SEGMENT
+        end
+
+        def build_parts(raw_path, raw_namespace, settings)
+          parts = []
+          add_part(parts, settings[:mount_path])
+          add_part(parts, settings[:root_prefix])
+          parts << VERSION_SEGMENT if uses_path_versioning?(settings)
+          add_part(parts, raw_namespace)
+          add_part(parts, raw_path)
+          parts
+        end
+
+        def add_part(parts, value)
+          parts << value if value && not_slash?(value)
+        end
+
+        def not_slash?(value)
+          value != '/'
+        end
+
+        def uses_specific_format?(settings)
+          return false unless settings.key?(:format) && settings.key?(:content_types)
+
+          settings[:format] && Array(settings[:content_types]).size == 1
+        end
+
+        def uses_path_versioning?(settings)
+          return false unless settings.key?(:version) && settings[:version_options]
+
+          settings[:version] && settings[:version_options].using == :path
+        end
+
+        def valid_part?(part)
+          part&.match?(/^\S/) && not_slash?(part)
+        end
+
+        class PartsCache < Grape::Util::Cache
+          def initialize
+            super
+            @cache = Hash.new do |h, parts|
+              h[parts] = Grape::Util::PathNormalizer.call(parts.join('/'))
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/spec/grape/path_spec.rb b/spec/grape/path_spec.rb
@@ -1,90 +1,9 @@
 # frozen_string_literal: true
 
-describe Grape::Path do
-  describe '#origin' do
-    context 'mount_path' do
-      it 'is not included when it is nil' do
-        path = described_class.new(nil, nil, mount_path: '/foo/bar')
-        expect(path.origin).to eql '/foo/bar'
-      end
-
-      it 'is included when it is not nil' do
-        path = described_class.new(nil, nil, {})
-        expect(path.origin).to eql('/')
-      end
-    end
-
-    context 'root_prefix' do
-      it 'is not included when it is nil' do
-        path = described_class.new(nil, nil, {})
-        expect(path.origin).to eql('/')
-      end
-
-      it 'is included after the mount path' do
-        path = described_class.new(
-          nil,
-          nil,
-          mount_path: '/foo',
-          root_prefix: '/hello'
-        )
-
-        expect(path.origin).to eql('/foo/hello')
-      end
-    end
-
-    it 'uses the namespace after the mount path and root prefix' do
-      path = described_class.new(
-        nil,
-        'namespace',
-        mount_path: '/foo',
-        root_prefix: '/hello'
-      )
-
-      expect(path.origin).to eql('/foo/hello/namespace')
-    end
-
-    it 'uses the raw path after the namespace' do
-      path = described_class.new(
-        'raw_path',
-        'namespace',
-        mount_path: '/foo',
-        root_prefix: '/hello'
-      )
-
-      expect(path.origin).to eql('/foo/hello/namespace/raw_path')
-    end
-  end
-
-  describe '#suffix' do
-    context 'when using a specific format' do
-      it 'accepts specified format' do
-        path = described_class.new(nil, nil, format: 'json', content_types: 'application/json')
-        expect(path.suffix).to eql('(.json)')
-      end
-    end
-
-    context 'when path versioning is used' do
-      it "includes a '/'" do
-        path = described_class.new(nil, nil, version: :v1, version_options: Grape::DSL::VersionOptions.new)
-        expect(path.suffix).to eql('(/.:format)')
-      end
-    end
-
-    context 'when path versioning is not used' do
-      it "does not include a '/' when the path has a namespace" do
-        path = described_class.new(nil, 'namespace', {})
-        expect(path.suffix).to eql('(.:format)')
-      end
-
-      it "does not include a '/' when the path has a path" do
-        path = described_class.new('/path', nil, version: :v1, version_options: Grape::DSL::VersionOptions.new)
-        expect(path.suffix).to eql('(.:format)')
-      end
-
-      it "includes a '/' otherwise" do
-        path = described_class.new(nil, nil, version: :v1, version_options: Grape::DSL::VersionOptions.new)
-        expect(path.suffix).to eql('(/.:format)')
-      end
-    end
+RSpec.describe 'Grape::Path' do
+  it 'is deprecated and points at Grape::Router::Pattern::Path' do
+    expect { Grape::Path.new(nil, nil, {}) }.to raise_error(
+      ActiveSupport::DeprecationException, /Grape::Path is deprecated.*Grape::Router::Pattern::Path/m
+    )
   end
 end
diff --git a/spec/grape/router/pattern/path_spec.rb b/spec/grape/router/pattern/path_spec.rb
@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+RSpec.describe Grape::Router::Pattern::Path do
+  describe '#origin' do
+    context 'mount_path' do
+      it 'is not included when it is nil' do
+        path = described_class.new(nil, nil, mount_path: '/foo/bar')
+        expect(path.origin).to eql '/foo/bar'
+      end
+
+      it 'is included when it is not nil' do
+        path = described_class.new(nil, nil, {})
+        expect(path.origin).to eql('/')
+      end
+    end
+
+    context 'root_prefix' do
+      it 'is not included when it is nil' do
+        path = described_class.new(nil, nil, {})
+        expect(path.origin).to eql('/')
+      end
+
+      it 'is included after the mount path' do
+        path = described_class.new(
+          nil,
+          nil,
+          mount_path: '/foo',
+          root_prefix: '/hello'
+        )
+
+        expect(path.origin).to eql('/foo/hello')
+      end
+    end
+
+    it 'uses the namespace after the mount path and root prefix' do
+      path = described_class.new(
+        nil,
+        'namespace',
+        mount_path: '/foo',
+        root_prefix: '/hello'
+      )
+
+      expect(path.origin).to eql('/foo/hello/namespace')
+    end
+
+    it 'uses the raw path after the namespace' do
+      path = described_class.new(
+        'raw_path',
+        'namespace',
+        mount_path: '/foo',
+        root_prefix: '/hello'
+      )
+
+      expect(path.origin).to eql('/foo/hello/namespace/raw_path')
+    end
+  end
+
+  describe '#suffix' do
+    context 'when using a specific format' do
+      it 'accepts specified format' do
+        path = described_class.new(nil, nil, format: 'json', content_types: 'application/json')
+        expect(path.suffix).to eql('(.json)')
+      end
+    end
+
+    context 'when path versioning is used' do
+      it "includes a '/'" do
+        path = described_class.new(nil, nil, version: :v1, version_options: Grape::DSL::VersionOptions.new)
+        expect(path.suffix).to eql('(/.:format)')
+      end
+    end
+
+    context 'when path versioning is not used' do
+      it "does not include a '/' when the path has a namespace" do
+        path = described_class.new(nil, 'namespace', {})
+        expect(path.suffix).to eql('(.:format)')
+      end
+
+      it "does not include a '/' when the path has a path" do
+        path = described_class.new('/path', nil, version: :v1, version_options: Grape::DSL::VersionOptions.new)
+        expect(path.suffix).to eql('(.:format)')
+      end
+
+      it "includes a '/' otherwise" do
+        path = described_class.new(nil, nil, version: :v1, version_options: Grape::DSL::VersionOptions.new)
+        expect(path.suffix).to eql('(/.:format)')
+      end
+    end
+  end
+end
diff --git a/spec/grape/router/pattern_spec.rb b/spec/grape/router/pattern_spec.rb
