ruby_routes 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59f7b87f3f7b94ce54fcc9a8a3d917833c93312412b160cf82268552fd0454ba
-  data.tar.gz: 40417f1672ac4e849f6a85a9170fd01f1619ef931b8bd58e1f52b8896d23605c
+  metadata.gz: 57b9470b49019746492c10fd0e202c6c544c78459f36e0d2c1f8d400103def93
+  data.tar.gz: 8e59a14f7854cadb955d381fcf7947b7769d0041de5067f3e3dc5827d13cbb26
 SHA512:
-  metadata.gz: 7c099d775cf22a7327e8f8b1cfdcb1d51495c08717f20eb879b89e6dbfe2e4ae56cb028ae494e13a72c311c668454d6a6ab8f4e4c7a26a76d0d02ec99ca3c342
-  data.tar.gz: 754386d02e0387500ae507f5a2e0ad7c11b46a04c7a461aafbee34fd7ad1d19ef7d7ff1ad207375e2e3be205d8af4afa11c06be8d4e2dbedcb8f4e571055994c
+  metadata.gz: c746c95407c222fdd209e464c3f1b89971987d8b41a557b7f173e1acb55fa5d6626b030bab26aed81c7ff766bd9da8c4ba4c2895ce167558a61c089923e14f12
+  data.tar.gz: 6b512f5e810f19fa4031b33f29d3efa72feabb841e8ac3558af67ce6ec43556cacc85577993015cde7f3f400c10e9a36cbc8e007831808a798fa80204fd57046

data/README.md

@@ -4,7 +4,7 @@ A high-performance, lightweight routing system for Ruby applications providing a
 
 ## Features
 
-- **🚀 High Performance**: 40x faster routing with 99.99% cache hit rate
+- **🚀 High Performance**: Fast routing with 99.99% cache hit rate
 - **🔄 Rails-like DSL**: Familiar syntax for defining routes
 - **🛣️ RESTful Resources**: Automatic generation of RESTful routes
 - **🔒 Secure Constraints**: Built-in security with comprehensive constraint system
@@ -36,7 +36,7 @@ A high-performance, lightweight routing system for Ruby applications providing a
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'ruby_routes', '~> 2.1.0'
+gem 'ruby_routes', '~> 2.3.0'
 ```
 
 And then execute:
@@ -358,6 +358,7 @@ Rack::Handler::WEBrick.run RubyRoutesApp.new, Port: 9292
 - `scope(options = {})` - Group routes with shared options
 - `concern(name, &block)` - Define a reusable route concern
 - `concerns(names)` - Use defined concerns in the current context
+- `build(&block)` - Create a thread-safe, finalized router by accumulating routes in a builder
 
 ### RouteSet Methods
 
@@ -370,7 +371,7 @@ Rack::Handler::WEBrick.run RubyRoutesApp.new, Port: 9292
 
 Ruby Routes is optimized for high-performance applications:
 
-- **40x faster** routing compared to many alternatives
+- **Fast** routing
 - **99.99% cache hit rate** for common access patterns
 - **Low memory footprint** with bounded caches and object reuse
 - **Zero memory leaks** in long-running applications
@@ -388,30 +389,36 @@ Performance metrics (from `benchmark/` directory):
 Ruby Routes prioritizes security with these protections:
 
 ### 🔒 Security Features
-- **XSS Protection**: All HTML output is properly escaped
+
 - **ReDoS Protection**: Regular expression constraints have timeout protection
 - **Secure Constraints**: Type-safe constraint system without code execution
 - **Thread Safety**: All shared resources are thread-safe
 - **Input Validation**: Comprehensive parameter validation
 
 ### ⚠️ Security Notice
+
 **Proc constraints are deprecated due to security risks** and will be removed in a future version. They allow arbitrary code execution which can be exploited for:
+
 - Code injection attacks
 - Denial of service attacks
 - System compromise
 
 **Migration Required**: If you're using Proc constraints, please migrate to secure alternatives using our [Migration Guide](MIGRATION_GUIDE.md).
 
+**Note**: RubyRoutes is a routing library and does not provide application-level security features such as XSS protection, CSRF protection, or authentication. These should be handled by your web framework or additional security middleware.
+
 ## Documentation
 
 ### Core Documentation
+
 - **[CONSTRAINTS.md](CONSTRAINTS.md)** - Complete guide to route constraints and security
 - **[MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)** - Guide for migrating from deprecated Proc constraints
-- **[SECURITY_FIXES.md](SECURITY_FIXES.md)** - Details on security improvements
 - **[USAGE.md](USAGE.md)** - Extended usage scenarios
 
 ### Examples
+
 See the `examples/` directory for more detailed examples:
+
 - `examples/basic_usage.rb` - Basic routing examples
 - `examples/rack_integration.rb` - Full Rack application example
 - `examples/constraints.rb` - Route constraint examples

data/lib/ruby_routes/constant.rb

@@ -28,7 +28,7 @@ module RubyRoutes
   # @api internal
   module Constant
     # Shared, canonical root path constant (single source of truth).
-    ROOT_PATH = '/'
+    ROOT_PATH = '/'.freeze
 
     # Maps a segment's first byte (ASCII) to a Segment class.
     #
@@ -119,7 +119,7 @@ module RubyRoutes
     # Empty constants for reuse.
     EMPTY_ARRAY  = [].freeze
     EMPTY_PAIR   = [EMPTY_ARRAY, EMPTY_ARRAY].freeze
-    EMPTY_STRING = ''
+    EMPTY_STRING = ''.freeze
     EMPTY_HASH   = {}.freeze
 
     # Maximum number of distinct (method, path) composite keys retained
@@ -146,7 +146,7 @@ module RubyRoutes
     # Default result for no traversal match.
     #
     # @return [Array]
-    NO_TRAVERSAL_RESULT = [nil, false].freeze
+    NO_TRAVERSAL_RESULT = [nil, false, {}].freeze
 
     # Built-in validators for constraints.
     #

data/lib/ruby_routes/node.rb

@@ -2,6 +2,7 @@
 
 require_relative 'segment'
 require_relative 'utility/path_utility'
+require_relative 'utility/method_utility'
 
 module RubyRoutes
   # Node
@@ -28,6 +29,7 @@ module RubyRoutes
     attr_reader :handlers, :static_children
 
     include RubyRoutes::Utility::PathUtility
+    include RubyRoutes::Utility::MethodUtility
 
     def initialize
       @is_endpoint     = false
@@ -44,8 +46,8 @@ module RubyRoutes
     # @param handler [Object] route or callable
     # @return [Object] handler
     def add_handler(method, handler)
-      method_str = normalize_method(method)
-      @handlers[method_str] = handler
+      method_key = normalize_http_method(method)
+      @handlers[method_key] = handler
       @is_endpoint = true
       handler
     end
@@ -55,24 +57,30 @@ module RubyRoutes
     # @param method [String, Symbol]
     # @return [Object, nil]
     def get_handler(method)
-      @handlers[normalize_method(method)]
+      @handlers[normalize_http_method(method)]
     end
 
     # Traverses from this node using a single path segment.
-    # Returns [next_node_or_nil, stop_traversal(Boolean)].
+    # Returns [next_node_or_nil, stop_traversal(Boolean), captured_params(Hash)].
     #
     # Optimized + simplified (cyclomatic / perceived complexity, length).
+    #
+    # @param segment [String] the path segment to match
+    # @param index [Integer] the segment index in the full path
+    # @param segments [Array<String>] all path segments
+    # @param params [Hash] (unused in this method; mutation deferred)
+    # @return [Array] [next_node, stop, captured] or NO_TRAVERSAL_RESULT
     def traverse_for(segment, index, segments, params)
-      return [@static_children[segment], false] if @static_children[segment]
+      return [@static_children[segment], false, {}] if @static_children[segment]
 
       if @dynamic_child
-        capture_dynamic_param(params, @dynamic_child, segment)
-        return [@dynamic_child, false]
+        captured = capture_dynamic_param(@dynamic_child, segment)
+        return [@dynamic_child, false, captured]
       end
 
       if @wildcard_child
-        capture_wildcard_param(params, @wildcard_child, segments, index)
-        return [@wildcard_child, true]
+        captured = capture_wildcard_param(@wildcard_child, segments, index)
+        return [@wildcard_child, true, captured]
       end
 
       RubyRoutes::Constant::NO_TRAVERSAL_RESULT
@@ -80,27 +88,27 @@ module RubyRoutes
 
     private
 
-    # Captures a dynamic parameter value into the params hash if applicable.
+    # Captures a dynamic parameter value and returns it for later assignment.
     #
-    # @param params [Hash, nil] the parameters hash to update
-    # @param dyn_node [Node] the dynamic child node
+    # @param dynamic_node [Node] the dynamic child node
     # @param value [String] the segment value to capture
-    def capture_dynamic_param(params, dyn_node, value)
-      return unless params && dyn_node.param_name
+    # @return [Hash] captured parameter hash or empty hash if no param
+    def capture_dynamic_param(dynamic_node, value)
+      return {} unless dynamic_node.param_name
 
-      params[dyn_node.param_name] = value
+      { dynamic_node.param_name => value }
     end
 
-    # Captures a wildcard parameter value into the params hash if applicable.
+    # Captures a wildcard parameter value and returns it for later assignment.
     #
-    # @param params [Hash, nil] the parameters hash to update
     # @param wc_node [Node] the wildcard child node
     # @param segments [Array<String>] the full path segments
     # @param index [Integer] the current segment index
-    def capture_wildcard_param(params, wc_node, segments, index)
-      return unless params && wc_node.param_name
+    # @return [Hash] captured parameter hash or empty hash if no param
+    def capture_wildcard_param(wildcard_node, segments, index)
+      return {} unless wildcard_node.param_name
 
-      params[wc_node.param_name] = segments[index..].join('/')
+      { wildcard_node.param_name => segments[index..].join('/') }
     end
   end
 end

data/lib/ruby_routes/radix_tree/finder.rb

@@ -4,11 +4,27 @@ require_relative '../constant'
 
 module RubyRoutes
   class RadixTree
-    # Finder module for traversing the RadixTree and matching routes.
+    # Finder module for traversing the RadixTree and finding routes.
     # Handles path normalization, segment traversal, and parameter extraction.
-    #
-    # @module RubyRoutes::RadixTree::Finder
     module Finder
+
+      # Evaluate constraint rules for a candidate route.
+      #
+      # @param route_handler [Object]
+      # @param captured_params [Hash]
+      # @return [Boolean]
+      def check_constraints(route_handler, captured_params)
+        return true unless route_handler.respond_to?(:validate_constraints_fast!)
+
+        begin
+          # Use a duplicate to avoid unintended mutation by validators.
+          route_handler.validate_constraints_fast!(captured_params)
+          true
+        rescue RubyRoutes::ConstraintViolation
+          false
+        end
+      end
+
       private
 
       # Finds a route handler for the given path and HTTP method.
@@ -17,7 +33,7 @@ module RubyRoutes
       # @param method_input [String, Symbol] the HTTP method
       # @param params_out [Hash] optional output hash for captured parameters
       # @return [Array] [handler, params] or [nil, params] if no match
-      def find(path_input, method_input, params_out = {})
+      def find(path_input, method_input, params_out = nil)
         path = path_input.to_s
         method = normalize_http_method(method_input)
         return root_match(method, params_out) if path.empty? || path == RubyRoutes::Constant::ROOT_PATH
@@ -27,20 +43,23 @@ module RubyRoutes
 
         params = params_out || {}
         state = traversal_state
+        captured_params = {}
 
-        perform_traversal(segments, state, method, params)
+        result = perform_traversal(segments, state, method, params, captured_params)
+        return result unless result.nil?
 
-        finalize_success(state, method, params)
+        finalize_success(state, method, params, captured_params)
       end
 
       # Initializes the traversal state for route matching.
       #
-      # @return [Hash] state hash with :current, :best_node, :best_params, :matched
+      # @return [Hash] state hash with :current, :best_node, :best_params, :best_captured, :matched
       def traversal_state
         {
-          current: @root_node,
+          current: @root,
           best_node: nil,
           best_params: nil,
+          best_captured: nil,
           matched: false # Track if any segment was successfully matched
         }
       end
@@ -51,16 +70,19 @@ module RubyRoutes
       # @param state [Hash] traversal state
       # @param method [String] normalized HTTP method
       # @param params [Hash] parameters hash
-      def perform_traversal(segments, state, method, params)
+      # @param captured_params [Hash] hash to collect captured parameters
+      # @return [nil, Array] nil if traversal succeeds, Array from finalize_on_fail if traversal fails
+      def perform_traversal(segments, state, method, params, captured_params)
         segments.each_with_index do |segment, index|
-          next_node, stop = traverse_for_segment(state[:current], segment, index, segments, params)
-          return finalize_on_fail(state, method, params) unless next_node
+          next_node, stop = traverse_for_segment(state[:current], segment, index, segments, params, captured_params)
+          return finalize_on_fail(state, method, params, captured_params) unless next_node
 
           state[:current] = next_node
           state[:matched] = true # Set matched to true if at least one segment matched
-          record_candidate(state, method, params) if endpoint_with_method?(state[:current], method)
+          record_candidate(state, method, params, captured_params) if endpoint_with_method?(state[:current], method)
           break if stop
         end
+        nil # Return nil to indicate successful traversal
       end
 
       # Traverses to the next node for a given segment.
@@ -70,9 +92,12 @@ module RubyRoutes
       # @param index [Integer] segment index
       # @param segments [Array<String>] all segments
       # @param params [Hash] parameters hash
-      # @return [Array] [next_node, stop_traversal]
-      def traverse_for_segment(node, segment, index, segments, params)
-        node.traverse_for(segment, index, segments, params)
+      # @param captured_params [Hash] hash to collect captured parameters
+      # @return [Array] [next_node, stop_traversal, segment_captured]
+      def traverse_for_segment(node, segment, index, segments, params, captured_params)
+        next_node, stop, segment_captured = node.traverse_for(segment, index, segments, params)
+        captured_params.merge!(segment_captured) if segment_captured
+        [next_node, stop]
       end
 
       # Records the current node as a candidate match.
@@ -80,9 +105,11 @@ module RubyRoutes
       # @param state [Hash] traversal state
       # @param _method [String] HTTP method (unused)
       # @param params [Hash] parameters hash
-      def record_candidate(state, _method, params)
+      # @param captured_params [Hash] captured parameters from traversal
+      def record_candidate(state, _method, params, captured_params)
         state[:best_node] = state[:current]
         state[:best_params] = params.dup
+        state[:best_captured] = captured_params.dup
       end
 
       # Checks if the node is an endpoint with a handler for the method.
@@ -99,13 +126,12 @@ module RubyRoutes
       # @param state [Hash] traversal state
       # @param method [String] HTTP method
       # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
       # @return [Array] [handler, params] or [nil, params]
-      def finalize_on_fail(state, method, params)
-        if state[:best_node]
-          handler = state[:best_node].handlers[method]
-          return constraints_pass?(handler, state[:best_params]) ? [handler, state[:best_params]] : [nil, params]
-        end
-        [nil, params]
+      def finalize_on_fail(state, method, params, captured_params)
+        best_params = state[:best_params] || params
+        best_captured = state[:best_captured] || captured_params
+        finalize_match(state[:best_node], method, best_params, best_captured)
       end
 
       # Finalizes the result after successful traversal.
@@ -113,15 +139,20 @@ module RubyRoutes
       # @param state [Hash] traversal state
       # @param method [String] HTTP method
       # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
       # @return [Array] [handler, params] or [nil, params]
-      def finalize_success(state, method, params)
-        node = state[:current]
-        if endpoint_with_method?(node, method) && state[:matched]
-          handler = node.handlers[method]
-          return [handler, params] if constraints_pass?(handler, params)
+      def finalize_success(state, method, params, captured_params)
+        result = finalize_match(state[:current], method, params, captured_params)
+        return result if result[0]
+
+        # Try best candidate if current failed
+        if state[:best_node]
+          best_params = state[:best_params] || params
+          best_captured = state[:best_captured] || captured_params
+          finalize_match(state[:best_node], method, best_params, best_captured)
+        else
+          result
         end
-        # For non-matching paths, return nil
-        [nil, params]
       end
 
       # Falls back to the best candidate if no exact match.
@@ -129,12 +160,31 @@ module RubyRoutes
       # @param state [Hash] traversal state
       # @param method [String] HTTP method
       # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
       # @return [Array] [handler, params] or [nil, params]
-      def fallback_candidate(state, method, params)
-        if state[:best_node] && state[:best_node] != @root_node
-          handler = state[:best_node].handlers[method]
-          return [handler, state[:best_params]] if handler && constraints_pass?(handler, state[:best_params])
+      def fallback_candidate(state, method, params, captured_params)
+        finalize_match(state[:best_node], method, state[:best_params], state[:best_captured])
+      end
+
+      # Common method to finalize a match attempt.
+      # Assumes the node is already validated as an endpoint.
+      #
+      # @param node [Node] the node to check for a handler
+      # @param method [String] HTTP method
+      # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
+      # @return [Array] [handler, params] or [nil, params]
+      def finalize_match(node, method, params, captured_params)
+        if node && endpoint_with_method?(node, method)
+          handler = node.handlers[method]
+          # Apply captured params before constraint validation
+          apply_captured_params(params, captured_params)
+          if check_constraints(handler, params)
+            return [handler, params]
+          end
         end
+        # For non-matching paths, return nil
+        apply_captured_params(params, captured_params)
         [nil, params]
       end
 
@@ -144,20 +194,19 @@ module RubyRoutes
       # @param params_out [Hash] parameters hash
       # @return [Array] [handler, params] or [nil, params]
       def root_match(method, params_out)
-        if @root_node.is_endpoint && (handler = @root_node.handlers[method])
+        if @root.is_endpoint && (handler = @root.handlers[method])
           [handler, params_out || {}]
         else
           [nil, params_out || {}]
         end
       end
 
-      # Checks if constraints pass for the handler.
+      # Applies captured parameters to the final params hash.
       #
-      # @param handler [Object] the route handler
-      # @param params [Hash] parameters hash
-      # @return [Boolean] true if constraints pass
-      def constraints_pass?(handler, params)
-        check_constraints(handler, params&.dup || {})
+      # @param params [Hash] the final parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
+      def apply_captured_params(params, captured_params)
+        params.merge!(captured_params) if captured_params && !captured_params.empty?
       end
     end
   end

data/lib/ruby_routes/radix_tree/inserter.rb

@@ -4,8 +4,6 @@ module RubyRoutes
   class RadixTree
     # Inserter module for adding routes to the RadixTree.
     # Handles tokenization, node advancement, and endpoint finalization.
-    #
-    # @module RubyRoutes::RadixTree::Inserter
     module Inserter
       private
 
@@ -19,7 +17,7 @@ module RubyRoutes
         return route_handler if path_string.nil? || path_string.empty?
 
         tokens = split_path(path_string)
-        current_node = @root_node
+        current_node = @root
         tokens.each { |token| current_node = advance_node(current_node, token) }
         finalize_endpoint(current_node, http_methods, route_handler)
         route_handler

data/lib/ruby_routes/radix_tree.rb

@@ -52,7 +52,7 @@ module RubyRoutes
 
     # Initialize empty tree and split cache.
     def initialize
-      @root_node          = Node.new
+      @root          = Node.new
       @split_cache        = RubyRoutes::Route::SmallLru.new(2048)
       @split_cache_max    = 2048
       @split_cache_order  = []
@@ -93,22 +93,5 @@ module RubyRoutes
       @split_cache.set(raw_path, segments)
       segments
     end
-
-    # Evaluate constraint rules for a candidate route.
-    #
-    # @param route_handler [Object]
-    # @param captured_params [Hash]
-    # @return [Boolean]
-    def check_constraints(route_handler, captured_params)
-      return true unless route_handler.respond_to?(:validate_constraints_fast!)
-
-      begin
-        # Use a duplicate to avoid unintended mutation by validators.
-        route_handler.validate_constraints_fast!(captured_params)
-        true
-      rescue RubyRoutes::ConstraintViolation
-        false
-      end
-    end
   end
 end

data/lib/ruby_routes/route/check_helpers.rb

@@ -20,7 +20,7 @@ module RubyRoutes
       # @raise [RubyRoutes::ConstraintViolation] If the value is shorter than the minimum length.
       # @return [void]
       def check_min_length(constraint, value)
-        return unless constraint[:min_length] && value.length < constraint[:min_length]
+        return unless (min = constraint[:min_length]) && value && value.length < min
 
         raise RubyRoutes::ConstraintViolation, "Value too short (minimum #{constraint[:min_length]} characters)"
       end
@@ -36,7 +36,7 @@ module RubyRoutes
       # @raise [RubyRoutes::ConstraintViolation] If the value exceeds the maximum length.
       # @return [void]
       def check_max_length(constraint, value)
-        return unless constraint[:max_length] && value.length > constraint[:max_length]
+        return unless (max = constraint[:max_length]) && value && value.length > max
 
         raise RubyRoutes::ConstraintViolation, "Value too long (maximum #{constraint[:max_length]} characters)"
       end
@@ -52,7 +52,7 @@ module RubyRoutes
       # @raise [RubyRoutes::ConstraintViolation] If the value does not match the required format.
       # @return [void]
       def check_format(constraint, value)
-        return unless constraint[:format] && !value.match?(constraint[:format])
+        return unless (format = constraint[:format]) && value && !value.match?(format)
 
         raise RubyRoutes::ConstraintViolation, 'Value does not match required format'
       end
@@ -100,9 +100,15 @@ module RubyRoutes
       # @raise [RubyRoutes::ConstraintViolation] If the value is not in the allowed range.
       # @return [void]
       def check_range(constraint, value)
-        return unless constraint[:range] && !constraint[:range].cover?(value.to_i)
+        range = constraint[:range]
+        return unless range
+        begin
+          integer_value = Integer(value) # raises on nil, floats, or junk like "10abc"
+        rescue ArgumentError, TypeError
+          raise RubyRoutes::ConstraintViolation, 'Value not in allowed range'
+        end
 
-        raise RubyRoutes::ConstraintViolation, 'Value not in allowed range'
+        raise RubyRoutes::ConstraintViolation, 'Value not in allowed range' unless range.cover?(integer_value)
       end
     end
   end

data/lib/ruby_routes/route/constraint_validator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'timeout'
 require_relative '../constant'
 
 module RubyRoutes
@@ -25,6 +26,7 @@ module RubyRoutes
 
           validate_constraint_for(rule, key, params[param_key])
         end
+        nil
       end
 
       # Dispatch a single constraint check.
@@ -51,8 +53,20 @@ module RubyRoutes
       # @param value [Object] The value to validate.
       # @return [void]
       def validate_builtin_constraint(rule, value)
-        method_sym = RubyRoutes::Constant::BUILTIN_VALIDATORS[rule.to_sym] if rule
-        send(method_sym, value) if method_sym
+        case rule.to_s
+        when 'int'
+          validate_int_constraint(value)
+        when 'uuid'
+          validate_uuid_constraint(value)
+        when 'email'
+          validate_email_constraint(value)
+        when 'slug'
+          validate_slug_constraint(value)
+        when 'alpha'
+          validate_alpha_constraint(value)
+        when 'alphanumeric'
+          validate_alphanumeric_constraint(value)
+        end
       end
 
       # Validate a regexp constraint.

data/lib/ruby_routes/route/param_support.rb

@@ -12,8 +12,6 @@ module RubyRoutes
     # hashes for performance and includes a 2-slot LRU cache for param key generation.
     #
     # Thread-safety: Thread-local storage is used to avoid allocation and cross-thread mutation.
-    #
-    # @module RubyRoutes::Route::ParamSupport
     module ParamSupport
       include RubyRoutes::Route::WarningHelpers
 
@@ -127,7 +125,7 @@ module RubyRoutes
 
         merge_defaults_fast(params_hash) unless @defaults.empty?
         validate_constraints_fast!(params_hash) unless @constraints.empty?
-        params_hash
+        params_hash.dup
       end
 
       # Merge query parameters (if any) from full path into param hash.

data/lib/ruby_routes/route/path_builder.rb

@@ -3,8 +3,6 @@
 module RubyRoutes
   class Route
     # PathBuilder: generation + segment encoding
-    #
-    # @module RubyRoutes::Route::PathBuilder
     module PathBuilder
       private
 

data/lib/ruby_routes/route/path_generation.rb

@@ -40,41 +40,26 @@ module RubyRoutes
       # @return [String] The generated or cached path string.
       def build_or_fetch_generated_path(merged_params)
         generation_cache_key = build_generation_cache_key(merged_params)
-        if (cached_path = @gen_cache.get(generation_cache_key))
+        if (cached_path = @cache_mutex.synchronize { @gen_cache.get(generation_cache_key) })
           return cached_path
         end
 
         generated_path = generate_path_string(merged_params)
-        @gen_cache.set(generation_cache_key, generated_path)
-        generated_path
+        frozen_path = generated_path.frozen? ? generated_path : generated_path.dup.freeze
+        @cache_mutex.synchronize { @gen_cache.set(generation_cache_key, frozen_path) }
+        frozen_path
       end
 
       # Build a generation cache key for merged params.
       #
-      # This method creates a cache key based on the required parameters and
-      # their values in the merged parameters.
+      # This method creates a cache key from all dynamic path parameters
+      # (required + optional, including splats) present in the merged parameters.
       #
       # @param merged_params [Hash] The merged parameters for path generation.
       # @return [String] The cache key for the generation cache.
       def build_generation_cache_key(merged_params)
-        @required_params.empty? ? RubyRoutes::Constant::EMPTY_STRING : build_param_cache_key(merged_params)
-      end
-
-      # Emit deprecation warning for `Proc` constraints once per parameter.
-      #
-      # This method ensures that a deprecation warning for a `Proc` constraint
-      # is only emitted once per parameter. It tracks parameters for which
-      # warnings have already been shown.
-      #
-      # @param param [String, Symbol] The parameter name for which the warning
-      #   is being emitted.
-      # @return [void]
-      def warn_proc_constraint_deprecation(param)
-        return if @proc_warnings_shown&.include?(param)
-
-        @proc_warnings_shown ||= Set.new
-        @proc_warnings_shown << param
-        warn_proc_warning(param)
+        names = @required_params.empty? ? @param_names : @required_params
+        names.empty? ? RubyRoutes::Constant::EMPTY_STRING : cache_key_for_params(names, merged_params)
       end
 
       # Determine if the route can short-circuit to a static path.
@@ -85,7 +70,7 @@ module RubyRoutes
       # @param params [Hash] The parameters for path generation.
       # @return [Boolean] `true` if the route can short-circuit, `false` otherwise.
       def static_short_circuit?(params)
-        @static_path && (params.nil? || params.empty?)
+        !!@static_path && (params.nil? || params.empty?)
       end
 
       # Determine if the route is trivial.