ruby_routes 2.3.0 → 2.4.0

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,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module RubyRoutes
   class Route
     # WarningHelpers: encapsulate deprecation / warning helpers.
@@ -18,11 +20,12 @@ module RubyRoutes
       #   is being emitted.
       # @return [void]
       def warn_proc_constraint_deprecation(param)
-        return if @proc_warnings_shown&.include?(param)
+        key = param.to_sym
+        return if @proc_warnings_shown&.include?(key)
 
         @proc_warnings_shown ||= Set.new
-        @proc_warnings_shown << param
-        warn_proc_warning(param)
+        @proc_warnings_shown << key
+        warn_proc_warning(key)
       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?
@@ -166,6 +168,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.

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)
         @named_routes[route.name] = route if route.named?
+        @radix_tree.add(route.path, route.methods, route)
+        return route if @routes.include?(route) # Prevent duplicate insertion
+
+        @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,8 +69,8 @@ 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!
@@ -79,10 +80,7 @@ module RubyRoutes
         @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
+        RubyRoutes::Utility::KeyBuilderUtility.clear!
       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
@@ -85,6 +90,18 @@ module RubyRoutes
       route.generate_path(params)
     end
 
+    # Replay recorded calls on the router instance.
+    #
+    # This method replays all the recorded route definitions and other
+    # configuration calls on the given router instance.
+    #
+    # @param router [Router] The router instance to replay calls on.
+    # @return [void]
+    def replay_recorded_calls(router)
+      # Placeholder for actual implementation
+      # Iterate over recorded calls and apply them to the router
+    end
+
     private
 
     # Set up the radix tree for structural path matching.
@@ -117,7 +134,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,6 @@ module RubyRoutes
       def build
         router = Router.new
         validate_calls(@recorded_calls)
-        router.freeze
         router.finalize!
         router
       end

data/lib/ruby_routes/router/builder.rb

@@ -62,8 +62,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|

data/lib/ruby_routes/router/http_helpers.rb

@@ -108,7 +108,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/scope_helpers.rb

@@ -61,7 +61,21 @@ module RubyRoutes
       # @param scoped_path [String] The path to prepend the scope's path to.
       # @return [void]
       def apply_path_scope(scope, scoped_path)
-        scoped_path.prepend(scope[:path]) if scope[:path]
+        path = scope[:path]&.to_s
+        return if path.nil? || path.empty?
+
+        if path.end_with?('/')
+          if scoped_path.start_with?('/')
+            scoped_path.prepend(path.chomp('/'))
+          else
+            scoped_path.prepend(path)
+          end
+        else
+          scoped_path.prepend(scoped_path.start_with?('/') ? path : "#{path}/")
+        end
+
+        # Normalize: Ensure the final path starts with '/'
+        scoped_path.prepend('/') unless scoped_path.start_with?('/')
       end
 
       # Apply the module from a scope to the given options.
@@ -73,13 +87,17 @@ module RubyRoutes
       # @param scoped_options [Hash] The options to update with the module.
       # @return [void]
       def apply_module_scope(scope, scoped_options)
-        return unless scope[:module]
+        module_string = scope[:module]&.to_s
+        return if module_string.nil? || module_string.empty?
 
-        if scoped_options[:to]
-          controller, action = scoped_options[:to].to_s.split('#', 2)
-          scoped_options[:to] = "#{scope[:module]}/#{controller}##{action}"
-        elsif scoped_options[:controller]
-          scoped_options[:controller].prepend("#{scope[:module]}/")
+        if (to_val = scoped_options[:to])
+          controller, action = to_val.to_s.split('#', 2)
+          return if controller.nil? || controller.empty?
+          scoped_options[:to] = action && !action.empty? ? "#{module_string}/#{controller}##{action}" : "#{module_string}/#{controller}"
+        elsif (controller = scoped_options[:controller])
+          controller_string = controller.to_s
+          return if controller_string.empty?
+          scoped_options[:controller] = "#{module_string}/#{controller_string}"
         end
       end
 
@@ -91,7 +109,7 @@ module RubyRoutes
       def apply_defaults_scope(scope, scoped_options)
         return unless scope[:defaults]
 
-        scoped_options[:defaults] = (scoped_options[:defaults] || {}).merge(scope[:defaults])
+        scoped_options[:defaults] = scope[:defaults].merge(scoped_options[:defaults] || {})
       end
 
       # Apply the constraints from a scope to the given options.
@@ -102,7 +120,7 @@ module RubyRoutes
       def apply_constraints_scope(scope, scoped_options)
         return unless scope[:constraints]
 
-        scoped_options[:constraints] = (scoped_options[:constraints] || {}).merge(scope[:constraints])
+        scoped_options[:constraints] = scope[:constraints].merge(scoped_options[:constraints] || {})
       end
     end
   end

data/lib/ruby_routes/router.rb

@@ -3,7 +3,8 @@
 require_relative 'utility/inflector_utility'
 require_relative 'utility/route_utility'
 require_relative 'router/http_helpers'
-
+require_relative 'constant'
+require_relative 'route_set'
 module RubyRoutes
   # RubyRoutes::Router
   #
@@ -117,6 +118,7 @@ module RubyRoutes
     # @return [Router] self.
     def resources(resource_name, options = {}, &nested_block)
       define_resource_routes(resource_name, options, &nested_block)
+      self
     end
 
     # Define a singular resource.

data/lib/ruby_routes/segments/wildcard_segment.rb

@@ -39,7 +39,9 @@ module RubyRoutes
       def ensure_child(parent_node)
         parent_node.wildcard_child ||= Node.new
         wildcard_child_node = parent_node.wildcard_child
-        wildcard_child_node.param_name = @param_name
+        if wildcard_child_node.param_name.nil?
+          wildcard_child_node.param_name = @param_name
+        end
         wildcard_child_node
       end
 

data/lib/ruby_routes/utility/key_builder_utility.rb

@@ -14,9 +14,7 @@ module RubyRoutes
     # Design goals:
     # - Zero garbage on hot cache hits.
     # - Bounded memory (REQUEST_KEY_CAPACITY ring).
-    # - Thread safety not required (intended for single request thread use).
-    #
-    # @module RubyRoutes::Utility::KeyBuilderUtility
+    # - Thread-safe for concurrent access across multiple threads.
     module KeyBuilderUtility
       # @!visibility private
       # { "GET" => { "/users" => "GET:/users" } }
@@ -28,12 +26,21 @@ module RubyRoutes
       @ring_index  = 0
       # @!visibility private
       @entry_count = 0
+      # @!visibility private
+      @mutex = Mutex.new
 
       class << self
-        # Expose pool for diagnostics (read‑only).
+        # Clear all cached request keys.
         #
-        # @return [Hash] A shallow copy of the request key pool for diagnostics.
-        attr_reader :request_key_pool
+        # @return [void]
+        def clear!
+          @mutex.synchronize do
+            @request_key_pool.clear
+            @request_key_ring.fill(nil)
+            @entry_count = 0
+            @ring_index = 0
+          end
+        end
 
         # Fetch (or create) a frozen "METHOD:PATH" composite key.
         #
@@ -46,12 +53,14 @@ module RubyRoutes
         # @param request_path [String] The request path (e.g., "/users").
         # @return [String] A frozen canonical key.
         def fetch_request_key(http_method, request_path)
-          method_key, path_key = prepare_keys(http_method, request_path)
+          @mutex.synchronize do
+            method_key, path_key = prepare_keys(http_method, request_path)
 
-          bucket = @request_key_pool[method_key] ||= {}
-          return bucket[path_key] if bucket[path_key]
+            bucket = @request_key_pool[method_key] ||= {}
+            return bucket[path_key] if bucket[path_key]
 
-          handle_cache_miss(bucket, method_key, path_key)
+            handle_cache_miss(bucket, method_key, path_key)
+          end
         end
 
         private
@@ -116,7 +125,7 @@ module RubyRoutes
 
       # Build a generic delimited key from components (non‑hot path).
       #
-      # Uses a thread‑local mutable buffer to avoid transient objects.
+      # Simple join; acceptable for non‑hot paths.
       #
       # @param components [Array<#to_s>] The components to join into a key.
       # @param delimiter [String] The separator (default is ':').
@@ -159,8 +168,16 @@ module RubyRoutes
       # @param buffer [String] The buffer to build the key into.
       # @return [void]
       def build_param_key_buffer(required_params, merged, buffer)
-        key_components = required_params.map { |param| format_param_value(merged[param]) }
-        buffer << key_components.join('|')
+        first = true
+        required_params.each do |param|
+          value = format_param_value(merged[param])
+          if first
+            buffer << value
+            first = false
+          else
+            buffer << '|' << value
+          end
+        end
       end
 
       # Format a parameter value for inclusion in the key.

data/lib/ruby_routes/utility/method_utility.rb

@@ -78,9 +78,9 @@ module RubyRoutes
       # @param method_input [String] The HTTP method input.
       # @return [String] The normalized HTTP method.
       def normalize_string_method(method_input)
-        key = method_input
-        return key if already_upper_ascii?(key)
+        return method_input if already_upper_ascii?(method_input)
 
+        key = method_input.dup
         METHOD_CACHE[key] ||= ascii_upcase(key).freeze
       end
 
@@ -98,9 +98,9 @@ module RubyRoutes
       # @return [String] The normalized HTTP method.
       def normalize_other_method(method_input)
         coerced = method_input.to_s
-        key = coerced
-        return key if already_upper_ascii?(key)
+        return coerced if already_upper_ascii?(coerced)
 
+        key = coerced.dup
         METHOD_CACHE[key] ||= ascii_upcase(key).freeze
       end
 

data/lib/ruby_routes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyRoutes
-  VERSION = '2.3.0'
+  VERSION = '2.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_routes
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Yosef Benny Widyokarsono