ruby_routes 2.3.0 → 2.5.0

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.

data/lib/ruby_routes/route/query_helpers.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'rack'
+require 'rack/utils'
 
 module RubyRoutes
   class Route
@@ -43,12 +43,12 @@ module RubyRoutes
         query_part = path[(query_index + 1)..]
         return RubyRoutes::Constant::EMPTY_HASH if query_part.empty? || query_part.match?(/^\?+$/)
 
-        if (cached_result = @query_cache.get(query_part))
+        if (cached_result = @cache_mutex.synchronize { @query_cache.get(query_part) })
           return cached_result
         end
 
         parsed_result = Rack::Utils.parse_query(query_part)
-        @query_cache.set(query_part, parsed_result)
+        @cache_mutex.synchronize { @query_cache.set(query_part, parsed_result) }
         parsed_result
       end
     end

data/lib/ruby_routes/route/segment_compiler.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'set'
+require_relative '../utility/path_utility'
+
 module RubyRoutes
   class Route
     # SegmentCompiler: path analysis + extraction
@@ -8,9 +11,9 @@ module RubyRoutes
     # a route path. It includes utilities for compiling path segments, required
     # parameters, and static paths, as well as extracting parameters from a
     # request path.
-    #
-    # @module RubyRoutes::Route::SegmentCompiler
     module SegmentCompiler
+      include RubyRoutes::Utility::PathUtility
+
       private
 
       # Compile the segments from the path.
@@ -43,7 +46,7 @@ module RubyRoutes
                                   dynamic_param_names.freeze
                                 else
                                   dynamic_param_names.reject do |name|
-                                    @defaults.key?(name) || @defaults.key?(name.to_sym)
+                                    @defaults.key?(name) || (@defaults.key?(name.to_sym) if name.is_a?(String))
                                   end.freeze
                                 end
         @required_params_set  = @required_params.to_set.freeze

data/lib/ruby_routes/route/validation_helpers.rb

@@ -39,19 +39,31 @@ module RubyRoutes
       # Validate required parameters once.
       #
       # This method validates that all required parameters are present and not
-      # nil. It ensures that validation is performed only once per request.
+      # nil. It uses per-params caching to avoid re-validation for the same
+      # frozen params.
       #
       # @param params [Hash] The parameters to validate.
       # @raise [RouteNotFound] If required parameters are missing or nil.
       # @return [void]
       def validate_required_once(params)
-        return if @required_params.empty? || @required_validated_once
+        return if @required_params.empty?
 
-        missing, nils = validate_required_params(params)
+        # Check cache for existing validation result
+        cached_result = get_cached_validation(params)
+        if cached_result
+          missing, nils = cached_result
+        else
+          # Perform validation
+          missing, nils = validate_required_params(params)
+          # Cache the result only if params are frozen
+          if params.frozen?
+            cache_validation_result(params, [missing, nils])
+          end
+        end
+
+        # Raise if invalid
         raise RouteNotFound, "Missing params: #{missing.join(', ')}" unless missing.empty?
         raise RouteNotFound, "Missing or nil params: #{nils.join(', ')}" unless nils.empty?
-
-        @required_validated_once = true
       end
 
       # Validate required parameters.
@@ -64,13 +76,20 @@ module RubyRoutes
       #   - `nils` [Array<String>] The keys of parameters that are nil.
       def validate_required_params(params)
         return RubyRoutes::Constant::EMPTY_PAIR if @required_params.empty?
+        params ||= {}
+
+        if (cached = get_cached_validation(params))
+          return cached
+        end
 
         missing = []
         nils = []
         @required_params.each do |required_key|
           process_required_key(required_key, params, missing, nils)
         end
-        [missing, nils]
+        result = [missing, nils]
+        cache_validation_result(params, result)
+        result
       end
 
       # Per-key validation helper used by `validate_required_params`.
@@ -85,10 +104,13 @@ module RubyRoutes
       def process_required_key(required_key, params, missing, nils)
         if params.key?(required_key)
           nils << required_key if params[required_key].nil?
-        elsif params.key?(symbol_key = required_key.to_sym)
-          nils << required_key if params[symbol_key].nil?
         else
-          missing << required_key
+          symbol_key = required_key.to_sym
+          if params.key?(symbol_key)
+            nils << required_key if params[symbol_key].nil?
+          else
+            missing << required_key
+          end
         end
       end
 
@@ -104,7 +126,7 @@ module RubyRoutes
         return unless params.frozen?
         return unless @validation_cache && @validation_cache.size < 64
 
-        @validation_cache.set(params.hash, result)
+        @cache_mutex.synchronize { @validation_cache.set(params.hash, result) }
       end
 
       # Fetch cached validation result.
@@ -114,7 +136,8 @@ module RubyRoutes
       # @param params [Hash] The parameters used for validation.
       # @return [Object, nil] The cached validation result, or `nil` if not found.
       def get_cached_validation(params)
-        @validation_cache&.get(params.hash)
+        return nil unless params && @validation_cache
+        @cache_mutex.synchronize { @validation_cache.get(params.hash) }
       end
 
       # Return hash to pool.

data/lib/ruby_routes/route/warning_helpers.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'set'
+require 'thread'
+
 module RubyRoutes
   class Route
     # WarningHelpers: encapsulate deprecation / warning helpers.
@@ -17,12 +20,14 @@ module RubyRoutes
       # @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)
+      def warn_proc_constraint_deprecation(param)
+        key = param.to_sym
+        @warnings_mutex ||= Mutex.new
+        @warnings_mutex.synchronize do
+          @proc_warnings_shown ||= Set.new
+          warn_proc_warning(key) if @proc_warnings_shown.add?(key)
+        end
       end
 
       # Warn about `Proc` constraint deprecation.

data/lib/ruby_routes/route.rb

@@ -3,6 +3,7 @@
 require 'uri'
 require 'timeout'
 require 'rack'
+require 'set'
 require_relative 'constant'
 require_relative 'node'
 require_relative 'route/small_lru'
@@ -35,9 +36,10 @@ module RubyRoutes
   # - Minimal object allocation in hot paths
   #
   # Thread Safety:
-  # - Instance is effectively read‑only after initialization aside from
-  #   internal caches which are not synchronized but safe for typical
-  #   single writer (boot) + many reader (request) usage.
+  # - Instance is effectively read‑only after initialization.
+  # - Internal caches (@query_cache, @gen_cache, @validation_cache) are protected
+  #   by a mutex for safe concurrent access across multiple threads.
+  # - Designed for "build during boot, read per request" usage pattern.
   #
   # Public API Surface (stable):
   # - #match?
@@ -81,7 +83,7 @@ module RubyRoutes
       setup_controller_and_action(options)
 
       @name = options[:as]
-      @constraints = options[:constraints] || {}
+      @constraints = (options[:constraints] || {}).freeze
       @defaults = (options[:defaults] || {}).transform_keys(&:to_s).freeze
       @param_key_slots = [[nil, nil], [nil, nil]]
       @required_validated_once = false
@@ -143,8 +145,9 @@ module RubyRoutes
     # @param options [Hash] The options for the route.
     # @return [String, nil] The inferred controller name.
     def extract_controller(options)
+      return options[:controller] if options[:controller]
       to = options[:to]
-      return options[:controller] unless to
+      return nil unless to
 
       to.to_s.split('#', 2).first
     end
@@ -166,6 +169,7 @@ module RubyRoutes
       @is_resource = @path.match?(%r{/:id(?:$|\.)})
       @gen_cache = SmallLru.new(512)
       @query_cache = SmallLru.new(RubyRoutes::Constant::QUERY_CACHE_SIZE)
+      @cache_mutex = Mutex.new  # Thread-safe access to caches
       initialize_validation_cache
       compile_segments
       compile_required_params

data/lib/ruby_routes/route_set/cache_helpers.rb

@@ -40,104 +40,6 @@ module RubyRoutes
         @recognition_cache_max = 2048
         @cache_hits = 0
         @cache_misses = 0
-        @request_key_pool = {}
-        @request_key_ring = Array.new(RubyRoutes::Constant::REQUEST_KEY_CAPACITY)
-        @entry_count = 0
-        @ring_index = 0
-      end
-
-      # Fetch (or build) a composite request cache key with ring-buffer eviction.
-      #
-      # Ensures consistent use of frozen method/path keys to avoid mixed key space bugs.
-      #
-      # @param http_method [String, Symbol] The HTTP method (e.g., `:get`, `:post`).
-      # @param request_path [String] The request path.
-      # @return [String] The composite request key.
-      def fetch_request_key(http_method, request_path)
-        method_key, path_key = normalize_keys(http_method, request_path)
-        composite_key = build_composite_key(method_key, path_key)
-
-        return composite_key if handle_cache_hit(method_key, path_key, composite_key)
-
-        handle_cache_miss(method_key, path_key, composite_key)
-        composite_key
-      end
-
-      # Normalize keys.
-      #
-      # Converts the HTTP method and request path into frozen strings for consistent
-      # key usage.
-      #
-      # @param http_method [String, Symbol] The HTTP method.
-      # @param request_path [String] The request path.
-      # @return [Array<String>] An array containing the normalized method and path keys.
-      def normalize_keys(http_method, request_path)
-        method_key = http_method.is_a?(String) ? http_method.upcase.freeze : http_method.to_s.upcase.freeze
-        path_key = request_path.is_a?(String) ? request_path.freeze : request_path.to_s.freeze
-        [method_key, path_key]
-      end
-
-      # Build composite key.
-      #
-      # Combines the HTTP method and path into a single composite key.
-      #
-      # @param method_key [String] The normalized HTTP method key.
-      # @param path_key [String] The normalized path key.
-      # @return [String] The composite key.
-      def build_composite_key(method_key, path_key)
-        "#{method_key}:#{path_key}".freeze
-      end
-
-      # Handle cache hit.
-      #
-      # Checks if the composite key already exists in the request key pool.
-      #
-      # @param method_key [String] The normalized HTTP method key.
-      # @param path_key [String] The normalized path key.
-      # @param _composite_key [String] The composite key (unused).
-      # @return [Boolean] `true` if the key exists, `false` otherwise.
-      def handle_cache_hit(method_key, path_key, _composite_key)
-        return true if @request_key_pool[method_key]&.key?(path_key)
-
-        false
-      end
-
-      # Handle cache miss.
-      #
-      # Adds the composite key to the request key pool and manages the ring buffer
-      # for eviction.
-      #
-      # @param method_key [String] The normalized HTTP method key.
-      # @param path_key [String] The normalized path key.
-      # @param composite_key [String] The composite key.
-      # @return [void]
-      def handle_cache_miss(method_key, path_key, composite_key)
-        @request_key_pool[method_key][path_key] = composite_key if @request_key_pool[method_key]
-        @request_key_pool[method_key] = { path_key => composite_key } unless @request_key_pool[method_key]
-
-        if @entry_count < RubyRoutes::Constant::REQUEST_KEY_CAPACITY
-          @request_key_ring[@entry_count] = [method_key, path_key]
-          @entry_count += 1
-        else
-          evict_old_entry(method_key, path_key)
-        end
-      end
-
-      # Evict old entry.
-      #
-      # Removes the oldest entry from the request key pool and updates the ring buffer.
-      #
-      # @param method_key [String] The normalized HTTP method key.
-      # @param path_key [String] The normalized path key.
-      # @return [void]
-      def evict_old_entry(method_key, path_key)
-        evict_method, evict_path = @request_key_ring[@ring_index]
-        if (evict_bucket = @request_key_pool[evict_method]) && evict_bucket.delete(evict_path) && evict_bucket.empty?
-          @request_key_pool.delete(evict_method)
-        end
-        @request_key_ring[@ring_index] = [method_key, path_key]
-        @ring_index += 1
-        @ring_index = 0 if @ring_index == RubyRoutes::Constant::REQUEST_KEY_CAPACITY
       end
 
       # Fetch cached recognition entry while updating hit counter.
@@ -162,12 +64,15 @@ module RubyRoutes
       # @param entry [Hash] The cache entry.
       # @return [void]
       def insert_cache_entry(cache_key, entry)
-        if @recognition_cache.size >= @recognition_cache_max
-          @recognition_cache.keys.first(@recognition_cache_max / 4).each do |evict_key|
-            @recognition_cache.delete(evict_key)
+        @cache_mutex ||= Mutex.new
+        @cache_mutex.synchronize do
+          if @recognition_cache.size >= @recognition_cache_max
+            @recognition_cache.keys.first(@recognition_cache_max / 4).each do |evict_key|
+              @recognition_cache.delete(evict_key)
+            end
           end
+          @recognition_cache[cache_key] = entry
         end
-        @recognition_cache[cache_key] = entry
       end
     end
   end

data/lib/ruby_routes/route_set/collection_helpers.rb

@@ -18,9 +18,11 @@ module RubyRoutes
       # @param route [Route] The route to add.
       # @return [Route] The added route.
       def add_to_collection(route)
-        @routes << route
-        @radix_tree.add(route.path, route.methods, route)
+        return route if @routes.include?(route) # Prevent duplicate insertion
+
         @named_routes[route.name] = route if route.named?
+        @radix_tree.add(route.path, route.methods, route)
+        @routes << route
         route
       end
       alias add_route add_to_collection
@@ -33,8 +35,7 @@ module RubyRoutes
       # @param route [Route] The route to register.
       # @return [Route] The registered route.
       def register(route)
-        (@routes ||= []) << route
-        route
+        add_to_collection(route)
       end
 
       # Find any route (no params) for a method/path.
@@ -55,7 +56,7 @@ module RubyRoutes
       # This method retrieves a route by its name from the named routes collection.
       # If no route is found, it raises a `RouteNotFound` error.
       #
-      # @param name [Symbol, String] The name of the route.
+      # @param name [Symbol] The name of the route.
       # @return [Route] The named route.
       # @raise [RouteNotFound] If no route with the given name is found.
       def find_named_route(name)
@@ -68,21 +69,21 @@ module RubyRoutes
       # Clear all routes and caches.
       #
       # This method clears the internal route collection, named routes, recognition
-      # cache, and radix tree. It also resets cache hit/miss counters and the
-      # request key pool.
+      # cache, and radix tree. It also resets cache hit/miss counters and clears
+      # the global request key cache.
       #
       # @return [void]
       def clear!
-        @routes.clear
-        @named_routes.clear
-        @recognition_cache.clear
-        @cache_hits = 0
-        @cache_misses = 0
-        @radix_tree = RadixTree.new
-        @request_key_pool.clear
-        @request_key_ring.fill(nil)
-        @entry_count = 0
-        @ring_index = 0
+        @cache_mutex ||= Mutex.new
+        @cache_mutex.synchronize do
+          @routes.clear
+          @named_routes.clear
+          @recognition_cache.clear
+          @cache_hits = 0
+          @cache_misses = 0
+          @radix_tree = RadixTree.new
+          RubyRoutes::Utility::KeyBuilderUtility.clear!
+        end
       end
 
       # Get the number of routes.

data/lib/ruby_routes/route_set.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'radix_tree'
 require_relative 'utility/key_builder_utility'
 require_relative 'utility/method_utility'
 require_relative 'route_set/cache_helpers'
@@ -18,7 +19,11 @@ module RubyRoutes
   #   a small in‑memory recognition cache.
   # - Delegate structural path matching to an internal RadixTree.
   #
-  # Thread safety: not thread‑safe; build during boot, read per request.
+  # Thread Safety:
+  # - RouteSet instances are not fully thread-safe for modifications.
+  # - Build during boot/initialization, then use read-only per request.
+  # - Global caches (via KeyBuilderUtility) are thread-safe for concurrent reads.
+  # - Per-instance recognition cache is not protected (single-threaded usage assumed).
   #
   # @api public (primary integration surface)
   class RouteSet
@@ -117,7 +122,11 @@ module RubyRoutes
       return nil unless matched_route
 
       # Ensure we have a mutable hash for merging defaults / query params.
-      extracted_params = extracted_params.dup if extracted_params&.frozen?
+      if extracted_params.nil?
+        extracted_params = {}
+      elsif extracted_params.frozen?
+        extracted_params = extracted_params.dup
+      end
 
       merge_query_params(matched_route, raw_path, extracted_params)
       merge_defaults(matched_route, extracted_params)

data/lib/ruby_routes/router/build_helpers.rb

@@ -17,7 +17,12 @@ module RubyRoutes
       def build
         router = Router.new
         validate_calls(@recorded_calls)
-        router.freeze
+        RubyRoutes::Constant::RECORDED_METHODS.each do |method_name|
+          define_method(method_name) do |*arguments, &definition_block|
+            @recorded_calls << [__method__, arguments, definition_block]
+            nil
+          end
+        end
         router.finalize!
         router
       end

data/lib/ruby_routes/router/builder.rb

@@ -42,7 +42,10 @@ module RubyRoutes
       # @return [Array<Array(Symbol, Array, Proc|NilClass)>]
       #   A snapshot of the recorded calls to avoid external mutation.
       def recorded_calls
-        @recorded_calls.dup.freeze
+        # Deep-copy each recorded call’s args array and freeze the result to prevent mutation
+        @recorded_calls
+          .map { |(method_name, args, block)| [method_name, args.dup.freeze, block] }
+          .freeze
       end
 
       # Initialize the Builder.
@@ -62,8 +65,9 @@ module RubyRoutes
       # `RubyRoutes::Constant::RECORDED_METHODS`. Each method records its
       # invocation (method name, arguments, and block) in `@recorded_calls`.
       #
-      # @param *arguments [Array] The arguments passed to the DSL method.
-      # @param definition_block [Proc, nil] The block passed to the DSL method.
+      # The dynamically defined methods accept arbitrary arguments and an optional block,
+      # which are recorded for later processing by the router.
+      #
       # @return [nil]
       RubyRoutes::Constant::RECORDED_METHODS.each do |method_name|
         define_method(method_name) do |*arguments, &definition_block|
@@ -71,26 +75,6 @@ module RubyRoutes
           nil
         end
       end
-
-      private
-
-      # Validate the recorded calls.
-      #
-      # This method ensures that all recorded calls use valid router methods
-      # as defined in `RubyRoutes::Constant::RECORDED_METHODS`.
-      #
-      # @param recorded_calls [Array<Array(Symbol, Array, Proc|NilClass)>]
-      #   The recorded calls to validate.
-      # @raise [ArgumentError] If any recorded call uses an invalid method.
-      # @return [void]
-      def validate_calls(recorded_calls)
-        allowed_router_methods = RubyRoutes::Constant::RECORDED_METHODS
-        recorded_calls.each do |(router_method, _arguments, _definition_block)|
-          unless router_method.is_a?(Symbol) && allowed_router_methods.include?(router_method)
-            raise ArgumentError, "Invalid router method: #{router_method.inspect}"
-          end
-        end
-      end
     end
   end
 end

data/lib/ruby_routes/router/http_helpers.rb

@@ -83,7 +83,12 @@ module RubyRoutes
         via = options[:via]
         raise ArgumentError, 'match requires :via (e.g., via: [:get, :post])' if via.nil? || Array(via).empty?
 
-        add_route(path, options)
+        normalized_via = Array(via)
+        opts = options.dup
+        # Keep :via in opts only if BuildHelpers expects it; otherwise delete.
+        # If BuildHelpers infers from the second arg, delete it:
+        opts.delete(:via)
+        add_route(path, build_route_options(opts, normalized_via))
         self
       end
 
@@ -108,7 +113,7 @@ module RubyRoutes
       # @raise [RuntimeError] If the router is frozen.
       # @return [void]
       def ensure_unfrozen!
-        raise 'Router finalized (immutable)' if @frozen
+        raise 'Router finalized (immutable)' if @frozen || frozen?
       end
 
       # Define routes for a singular resource.

data/lib/ruby_routes/router/resource_helpers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'build_helpers'
+require_relative '../utility/inflector_utility'
 
 module RubyRoutes
   class Router
@@ -13,8 +14,6 @@ module RubyRoutes
     module ResourceHelpers
       include RubyRoutes::Router::BuildHelpers
 
-      private
-
       # Define RESTful routes for a resource.
       #
       # @param resource_name [Symbol, String] The name of the resource.
@@ -35,6 +34,8 @@ module RubyRoutes
         end
       end
 
+      private
+
       # Prepare options by removing the `:to` key if present.
       #
       # @param options [Hash] The options hash.