ruby_routes 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb6b2a38cb8f31bb3e79fa66dbbb1a0620c6eec1f668680e152efe38e7926b42
-  data.tar.gz: db5d62093e15a422d85e6c7ec373327ca1f37fd24f7b851c12bdb2f70cf81622
+  metadata.gz: 66764348265233b0904630e4193e21fc93f79e3257ec4d0e43e5c533faf1f7e1
+  data.tar.gz: de32cc9f5f42398b12e829c4da34aa82afd071fa63ed869180a56203834beecd
 SHA512:
-  metadata.gz: 7e84488c6309cea2dab99be9a350139f2042f3d9601e4a0d1d20eb3d66c5530934f2c4f0c5b384dec7fa3095802f4d710ab2cc4f1a0158486cd5bba618995801
-  data.tar.gz: 0fda0c79e0a935ba9227faba495030c9ff2144ebcc289969eed0a0eb95596d0d69289d1a12b160ef37c18d4021fd5ae172c12b7db48b3beeddb32435e6a2d7ad
+  metadata.gz: 21442f1a73e4045fedbb9bd215c639770c55135f6d55c78c17384996515d1347851d7b3afa952db345793a5aa92d5c14368d28faf0e35d4c985d608d94c8b980
+  data.tar.gz: 5570f4054ceaf76569bb4f28eca4d94347a559a24febe1936e39dfb9896ccfa281cdd1e2ce24e8e2b157b3d7f3870a67cc9ecdb61b62338bce7e28b5d0c32e4e

data/lib/ruby_routes/node.rb

@@ -1,65 +1,64 @@
 require_relative 'segment'
 
 module RubyRoutes
+  # Node represents a single node in the radix tree structure.
+  # Each node can have static children (exact matches), one dynamic child (parameter capture),
+  # and one wildcard child (consumes remaining path segments).
   class Node
-    attr_accessor :static_children, :dynamic_child, :wildcard_child,
-                  :handlers, :param_name, :is_endpoint
+    attr_accessor :param_name, :is_endpoint, :dynamic_child, :wildcard_child
+    attr_reader :handlers, :static_children
 
     def initialize
+      @is_endpoint = false
+      @handlers = {}
       @static_children = {}
       @dynamic_child = nil
       @wildcard_child = nil
-      @handlers = {}
       @param_name = nil
-      @is_endpoint = false
     end
 
-    # Fast traversal: minimal allocations, streamlined branching
-    # Returns [next_node_or_nil, should_break_bool] or [nil, false] if no match.
-    def traverse_for(segment, index, segments, params)
-      # Static match: O(1) hash lookup
-      child = @static_children[segment]
-      return [child, false] if child
+    def add_handler(method, handler)
+      method_str = normalize_method(method)
+      @handlers[method_str] = handler
+      @is_endpoint = true
+    end
 
-      # Dynamic match: single segment capture
-      if (dyn = @dynamic_child)
-        params[dyn.param_name] = segment if params
-        return [dyn, false]
-      end
+    def get_handler(method)
+      @handlers[method]
+    end
 
-      # Wildcard match: consume remainder (last resort)
-      if (wild = @wildcard_child)
-        if params
-          # Build remainder path without intermediate array allocation
-          remainder = segments[index..-1]
-          params[wild.param_name] = remainder.size == 1 ? remainder[0] : remainder.join('/')
+    # Fast traversal method with minimal allocations and streamlined branching.
+    # Matching order: static (most specific) → dynamic → wildcard (least specific)
+    # Returns [next_node_or_nil, should_break_bool] where should_break indicates
+    # wildcard capture that consumes remaining path segments.
+    def traverse_for(segment, index, segments, params)
+      # Try static child first (most specific) - O(1) hash lookup
+      if @static_children.key?(segment)
+        return [@static_children[segment], false]
+      # Try dynamic child (parameter capture) - less specific than static
+      elsif @dynamic_child
+        # Capture parameter if params hash provided and param_name is set
+        params[@dynamic_child.param_name] = segment if params && @dynamic_child.param_name
+        return [@dynamic_child, false]
+      # Try wildcard child (consumes remaining segments) - least specific
+      elsif @wildcard_child
+        # Capture remaining path segments for wildcard parameter
+        if params && @wildcard_child.param_name
+          remaining = segments[index..-1]
+          params[@wildcard_child.param_name] = remaining.join('/')
         end
-        return [wild, true]
+        return [@wildcard_child, true] # true signals to stop traversal
       end
 
-      # No match
+      # No match found at this node
       [nil, false]
     end
 
-    # Pre-cache param names as strings to avoid repeated .to_s calls
-    def param_name
-      @param_name_str ||= @param_name&.to_s
-    end
-
-    def param_name=(name)
-      @param_name = name
-      @param_name_str = nil  # invalidate cache
-    end
-
-    # Normalize method once and cache string keys
-    def add_handler(method, handler)
-      method_key = method.to_s.upcase
-      @handlers[method_key] = handler
-      @is_endpoint = true
-    end
+    private
 
-    def get_handler(method)
-      @handlers[method]  # assume already normalized upstream
+    # Fast method normalization - converts method to uppercase string
+    def normalize_method(method)
+      method.to_s.upcase
     end
   end
 end

data/lib/ruby_routes/radix_tree.rb

@@ -1,7 +1,13 @@
 require_relative 'segment'
+require_relative 'utility/path_utility'
 
 module RubyRoutes
+  # RadixTree provides an optimized tree structure for fast route matching.
+  # Supports static segments, dynamic parameters (:param), and wildcards (*splat).
+  # Features longest prefix matching and improved LRU caching for performance.
   class RadixTree
+    include RubyRoutes::Utility::PathUtility
+
     class << self
       # Allow RadixTree.new(path, options...) to act as a convenience factory
       def new(*args, &block)
@@ -17,156 +23,239 @@ module RubyRoutes
       @root = Node.new
       @split_cache = {}
       @split_cache_order = []
-      @split_cache_max = 2048      # larger cache for better hit rates
-      @empty_segments = [].freeze  # reuse for root path
+      @split_cache_max = 2048
+      @empty_segments = [].freeze
     end
 
+    # Add a route to the radix tree with specified path, HTTP methods, and handler.
+    # Returns the handler for method chaining.
     def add(path, methods, handler)
-      current = @root
-      segments = split_path_raw(path)
+      # Normalize path
+      normalized_path = normalize_path(path)
+
+      # Insert into the tree
+      insert_route(normalized_path, methods, handler)
+
+      # Return handler for chaining
+      handler
+    end
+
+    # Insert a route into the tree structure, creating nodes as needed.
+    # Supports static segments, dynamic parameters (:param), and wildcards (*splat).
+    def insert_route(path_str, methods, handler)
+      # Skip empty paths
+      return handler if path_str.nil? || path_str.empty?
+
+      path_parts = split_path(path_str)
+      current_node = @root
+
+      # Add path segments to tree
+      path_parts.each_with_index do |segment, i|
+        if segment.start_with?(':')
+          # Dynamic segment (e.g., :id)
+          param_name = segment[1..-1]
+
+          # Create dynamic child if needed
+          unless current_node.dynamic_child
+            current_node.dynamic_child = Node.new
+            current_node.dynamic_child.param_name = param_name
+          end
+
+          current_node = current_node.dynamic_child
+        elsif segment.start_with?('*')
+          # Wildcard segment (e.g., *path)
+          param_name = segment[1..-1]
 
-      segments.each do |raw_seg|
-        seg = RubyRoutes::Segment.for(raw_seg)
-        current = seg.ensure_child(current)
-        break if seg.wildcard?
+          # Create wildcard child if needed
+          unless current_node.wildcard_child
+            current_node.wildcard_child = Node.new
+            current_node.wildcard_child.param_name = param_name
+          end
+
+          current_node = current_node.wildcard_child
+          break  # Wildcard consumes the rest of the path
+        else
+          # Static segment - freeze key for memory efficiency and performance
+          segment_key = segment.freeze
+          unless current_node.static_children[segment_key]
+            current_node.static_children[segment_key] = Node.new
+          end
+
+          current_node = current_node.static_children[segment_key]
+        end
+      end
+
+      # Mark node as endpoint and add handler for methods
+      current_node.is_endpoint = true
+      Array(methods).each do |method|
+        method_str = method.to_s.upcase
+        current_node.handlers[method_str] = handler
       end
 
-      # Normalize methods once during registration
-      Array(methods).each { |method| current.add_handler(method.to_s.upcase, handler) }
+      handler
     end
 
-    def find(path, method, params_out = nil)
-      # Handle nil path and method cases
-      path ||= ''
-      method = method.to_s.upcase if method
-      # Strip query string before matching
-      clean_path = path.split('?', 2).first || ''
-      # Fast path: root route
-      if clean_path == '/' || clean_path.empty?
-        handler = @root.get_handler(method)
-        if @root.is_endpoint && handler
-          return [handler, params_out || {}]
+    # Find a matching route in the radix tree with longest prefix match support.
+    # Tracks the deepest endpoint node during traversal so partial matches return
+    # the longest valid prefix, increasing matching flexibility and correctness
+    # for overlapping/static/dynamic/wildcard routes.
+    def find(path, method, params_out = {})
+      # Handle empty path as root
+      path_str = path.to_s
+      method_str = method.to_s.upcase
+
+      # Special case for root path
+      if path_str.empty? || path_str == '/'
+        if @root.is_endpoint && @root.handlers[method_str]
+          return [@root.handlers[method_str], params_out || {}]
         else
-          return [nil, {}]
+          return [nil, params_out || {}]
         end
       end
 
-      segments = split_path_cached(clean_path)
-      current = @root
+      # Split path into segments
+      segments = split_path_cached(path_str)
+      return [nil, params_out || {}] if segments.empty?
+
       params = params_out || {}
-      params.clear if params_out
-
-      # Unrolled traversal for common case (1-3 segments)
-      case segments.size
-      when 1
-        next_node, _ = current.traverse_for(segments[0], 0, segments, params)
-        current = next_node
-      when 2
-        next_node, should_break = current.traverse_for(segments[0], 0, segments, params)
-        return [nil, {}] unless next_node
-        current = next_node
-        unless should_break
-          next_node, _ = current.traverse_for(segments[1], 1, segments, params)
-          current = next_node
-        end
-      when 3
-        next_node, should_break = current.traverse_for(segments[0], 0, segments, params)
-        return [nil, {}] unless next_node
-        current = next_node
-        unless should_break
-          next_node, should_break = current.traverse_for(segments[1], 1, segments, params)
-          return [nil, {}] unless next_node
-          current = next_node
-          unless should_break
-            next_node, _ = current.traverse_for(segments[2], 2, segments, params)
-            current = next_node
+      
+      # Track the longest prefix match (deepest endpoint found during traversal)
+      # Only consider nodes that actually match some part of the path
+      longest_match_node = nil
+      longest_match_params = nil
+
+      # Traverse the tree to find matching route
+      current_node = @root
+      segments.each_with_index do |segment, i|
+        next_node, should_break = current_node.traverse_for(segment, i, segments, params)
+
+        # No match found for this segment
+        unless next_node
+          # Return longest prefix match if we found any valid endpoint during traversal
+          if longest_match_node
+            handler = longest_match_node.handlers[method_str]
+            if handler.respond_to?(:constraints)
+              constraints = handler.constraints
+              if constraints && !constraints.empty?
+                return check_constraints(handler, longest_match_params) ? [handler, longest_match_params] : [nil, params]
+              end
+            end
+            return [handler, longest_match_params]
           end
+          return [nil, params]
         end
-      else
-        # General case for longer paths
-        segments.each_with_index do |text, idx|
-          next_node, should_break = current.traverse_for(text, idx, segments, params)
-          return [nil, {}] unless next_node
-          current = next_node
-          break if should_break
+
+        current_node = next_node
+        
+        # Check if current node is a valid endpoint after successful traversal
+        if current_node.is_endpoint && current_node.handlers[method_str]
+          # Store this as our current best match
+          longest_match_node = current_node
+          longest_match_params = params.dup
         end
+        
+        break if should_break  # For wildcard paths
       end
 
-      return [nil, {}] unless current
-      handler = current.get_handler(method)
-      return [nil, {}] unless current.is_endpoint && handler
+      # Check if final node is an endpoint and has a handler for the method
+      if current_node.is_endpoint && current_node.handlers[method_str]
+        handler = current_node.handlers[method_str]
+
+        # Handle constraints correctly - only check constraints
+        # Don't try to call matches? which test doubles won't have properly stubbed
+        if handler.respond_to?(:constraints)
+          constraints = handler.constraints
+          if constraints && !constraints.empty?
+            if check_constraints(handler, params)
+              return [handler, params]
+            else
+              # If constraints fail, try longest prefix match as fallback
+              if longest_match_node && longest_match_node != current_node
+                fallback_handler = longest_match_node.handlers[method_str]
+                return [fallback_handler, longest_match_params] if fallback_handler
+              end
+              return [nil, params]
+            end
+          end
+        end
 
-      # Fast constraint check
-      if handler.respond_to?(:constraints) && !handler.constraints.empty?
-        return [nil, {}] unless constraints_match_fast(handler.constraints, params)
+        return [handler, params]
       end
 
-      [handler, params]
+      # If we reach here, final node isn't an endpoint - return longest prefix match
+      if longest_match_node
+        handler = longest_match_node.handlers[method_str]
+        if handler.respond_to?(:constraints)
+          constraints = handler.constraints
+          if constraints && !constraints.empty?
+            return check_constraints(handler, longest_match_params) ? [handler, longest_match_params] : [nil, params]
+          end
+        end
+        return [handler, longest_match_params]
+      end
+
+      [nil, params]
     end
 
     private
 
-    # Cached path splitting with optimized common cases
+    # Improved LRU Path Segment Cache: Accessed keys are moved to the end of the 
+    # order array to ensure proper LRU eviction behavior
     def split_path_cached(path)
-      return @empty_segments if path == '/' || path.empty?
+      return @empty_segments if path == '/'
 
-      if (cached = @split_cache[path])
-        return cached
+      # Check if path is in cache
+      if @split_cache.key?(path)
+        # Move accessed key to end for proper LRU behavior
+        @split_cache_order.delete(path)
+        @split_cache_order << path
+        return @split_cache[path]
       end
 
-      result = split_path_raw(path)
+      # Split path and add to cache
+      segments = split_path(path)
 
-      # Cache with simple LRU eviction
-      @split_cache[path] = result
-      @split_cache_order << path
-      if @split_cache_order.size > @split_cache_max
-        oldest = @split_cache_order.shift
-        @split_cache.delete(oldest)
+      # Manage cache size - evict oldest entries when limit reached
+      if @split_cache.size >= @split_cache_max
+        old_key = @split_cache_order.shift
+        @split_cache.delete(old_key)
       end
 
-      result
+      @split_cache[path] = segments
+      @split_cache_order << path
+
+      segments
     end
 
-    # Raw path splitting without caching (for registration)
-    def split_path_raw(path)
-      return [] if path == '/' || path.empty?
+    # Validates route constraints against extracted parameters.
+    # Returns true if all constraints pass, false otherwise.
+    def check_constraints(handler, params)
+      return true unless handler.respond_to?(:constraints)
 
-      # Optimized trimming: avoid string allocations when possible
-      start_idx = path.start_with?('/') ? 1 : 0
-      end_idx = path.end_with?('/') ? -2 : -1
+      constraints = handler.constraints
+      return true unless constraints && !constraints.empty?
 
-      if start_idx == 0 && end_idx == -1
-        path.split('/')
-      else
-        path[start_idx..end_idx].split('/')
-      end
-    end
-
-    # Optimized constraint matching with fast paths
-    def constraints_match_fast(constraints, params)
+      # Check each constraint
       constraints.each do |param, constraint|
-        # Try both string and symbol keys (common pattern)
-        value = params[param.to_s]
-        value ||= params[param] if param.respond_to?(:to_s)
+        param_key = param.to_s
+        value = params[param_key]
         next unless value
 
         case constraint
         when Regexp
-          return false unless constraint.match?(value)
-        when Proc
-          return false unless constraint.call(value)
+          return false unless constraint.match?(value.to_s)
         when :int
-          # Fast integer check without regex
-          return false unless value.is_a?(String) && value.match?(/\A\d+\z/)
+          return false unless value.to_s.match?(/\A\d+\z/)
         when :uuid
-          # Fast UUID check
-          return false unless value.is_a?(String) && value.length == 36 &&
-                             value.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
-        when Symbol
-          # Handle other symbolic constraints
-          next  # unknown symbol constraint — allow
+          return false unless value.to_s.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
+        when Hash
+          if constraint[:range].is_a?(Range)
+            value_num = value.to_i
+            return false unless constraint[:range].include?(value_num)
+          end
         end
       end
+
       true
     end
   end

data/lib/ruby_routes/route/small_lru.rb

@@ -31,6 +31,10 @@ module RubyRoutes
         val
       end
 
+      def size
+        @h.size
+      end
+
       def increment_hits
         @hits += 1
       end

data/lib/ruby_routes/route.rb

@@ -3,23 +3,32 @@ require 'timeout'
 require 'set'
 require 'rack'
 require_relative 'route/small_lru'
+require_relative 'utility/path_utility'
+require_relative 'utility/key_builder_utility'
 
 module RubyRoutes
   class Route
+    include RubyRoutes::Utility::PathUtility
+    include RubyRoutes::Utility::KeyBuilderUtility
+
     attr_reader :path, :methods, :controller, :action, :name, :constraints, :defaults
 
+    EMPTY_ARRAY = [].freeze
+    EMPTY_PAIR  = [EMPTY_ARRAY, EMPTY_ARRAY].freeze
+    EMPTY_STRING = ''.freeze
+
     def initialize(path, options = {})
       @path = normalize_path(path)
       # Pre-normalize and freeze methods at creation time
-      raw_methods = Array(options[:via] || :get)
-      @methods = raw_methods.map { |m| normalize_method(m) }.freeze
-      @methods_set = @methods.to_set.freeze
-      @controller = extract_controller(options)
-      @action = options[:action] || extract_action(options[:to])
-      @name = options[:as]
-      @constraints = options[:constraints] || {}
+      raw_methods   = Array(options[:via] || :get)
+      @methods      = raw_methods.map { |m| normalize_method(m) }.freeze
+      @methods_set  = @methods.to_set.freeze
+      @controller   = extract_controller(options)
+      @action       = options[:action] || extract_action(options[:to])
+      @name         = options[:as]
+      @constraints  = options[:constraints] || {}
       # Pre-normalize defaults to string keys and freeze
-      @defaults = (options[:defaults] || {}).transform_keys(&:to_s).freeze
+      @defaults     = (options[:defaults] || {}).transform_keys(&:to_s).freeze
 
       # Pre-compile everything at initialization
       precompile_route_data
@@ -59,35 +68,17 @@ module RubyRoutes
 
     # Optimized path generation with better caching and fewer allocations
     def generate_path(params = {})
-      return ROOT_PATH if @path == ROOT_PATH
+      return @static_path if @static_path && (params.nil? || params.empty?)
+      params ||= {}
+      missing, nils = validate_required_params(params)
+      raise RouteNotFound, "Missing params: #{missing.join(', ')}" unless missing.empty?
+      raise RouteNotFound, "Missing or nil params: #{nils.join(', ')}" unless nils.empty?
 
-      # Fast path: empty params and no required params
-      if params.empty? && @required_params.empty?
-        return @static_path if @static_path
-      end
-
-      # Build merged params efficiently
       merged = build_merged_params(params)
-
-      # Check required params (fast Set operation)
-      missing_params = @required_params_set - merged.keys
-      unless missing_params.empty?
-        raise RubyRoutes::RouteNotFound, "Missing params: #{missing_params.to_a.join(', ')}"
-      end
-
-      # Check for nil values in required params
-      nil_params = @required_params_set.select { |param| merged[param].nil? }
-      unless nil_params.empty?
-        raise RubyRoutes::RouteNotFound, "Missing or nil params: #{nil_params.to_a.join(', ')}"
-      end
-
-      # Cache lookup
-      cache_key = build_cache_key_fast(merged)
+      cache_key = cache_key_for_params(@required_params, merged)
       if (cached = @gen_cache.get(cache_key))
         return cached
       end
-
-      # Generate path using string buffer (avoid array allocations)
       path_str = generate_path_string(merged)
       @gen_cache.set(cache_key, path_str)
       path_str
@@ -134,6 +125,7 @@ module RubyRoutes
       @is_resource = @path.match?(/\/:id(?:$|\.)/)
       @gen_cache = SmallLru.new(512)  # larger cache
       @query_cache = SmallLru.new(QUERY_CACHE_SIZE)
+      initialize_validation_cache
 
       compile_segments
       compile_required_params
@@ -193,7 +185,7 @@ module RubyRoutes
       # Validate constraints efficiently
       validate_constraints_fast!(result) unless @constraints.empty?
 
-      result.dup
+      result
     end
 
     def get_thread_local_hash
@@ -222,7 +214,7 @@ module RubyRoutes
       return EMPTY_HASH if @compiled_segments.empty? && request_path == ROOT_PATH
       return nil if @compiled_segments.empty?
 
-      path_parts = split_path_fast(request_path)
+      path_parts = split_path(request_path)
 
       # Check for wildcard/splat segment
       has_splat = @compiled_segments.any? { |seg| seg[:type] == :splat }
@@ -236,14 +228,6 @@ module RubyRoutes
       extract_params_from_parts(path_parts)
     end
 
-    def split_path_fast(request_path)
-      # Remove query string before splitting
-      path = request_path.split('?', 2).first
-      path = path[1..-1] if path.start_with?('/')
-      path = path[0...-1] if path.end_with?('/') && path != ROOT_PATH
-      path.empty? ? [] : path.split('/')
-    end
-
     def extract_params_from_parts(path_parts)
       params = {}
 
@@ -264,22 +248,16 @@ module RubyRoutes
 
     # Optimized merged params building
     def build_merged_params(params)
-      return @defaults if params.empty?
-
-      merged = get_thread_local_merged_hash
-
-      # Merge defaults first if they exist
-      merged.update(@defaults) unless @defaults.empty?
-
-      # Use merge! with transform_keys for better performance
-      if params.respond_to?(:transform_keys)
-        merged.merge!(params.transform_keys(&:to_s))
-      else
-        # Fallback for older Ruby versions
-        params.each { |k, v| merged[k.to_s] = v }
+      return @defaults if params.nil? || params.empty?
+      h = Thread.current[:ruby_routes_merge_hash] ||= {}
+      h.clear
+      @defaults.each { |k,v| h[k] = v }
+      params.each do |k,v|
+        next if v.nil?
+        ks = k.is_a?(String) ? k : k.to_s
+        h[ks] = v
       end
-
-      merged
+      h
     end
 
     def get_thread_local_merged_hash
@@ -288,41 +266,43 @@ module RubyRoutes
       hash
     end
 
-    # Fast cache key building with minimal allocations
-    def build_cache_key_fast(merged)
-      return '' if @required_params.empty?
-
-      # Use array join which is faster than string concatenation
-      parts = @required_params.map do |name|
-        value = merged[name]
-        value.is_a?(Array) ? value.join('/') : value.to_s
-      end
-      parts.join('|')
-    end
-
     # Optimized path generation
     def generate_path_string(merged)
       return ROOT_PATH if @compiled_segments.empty?
 
-      # Pre-allocate array for parts to avoid string buffer operations
-      parts = []
-
+      # Estimate final path length to avoid resizing
+      estimated_size = 1 # For leading slash
       @compiled_segments.each do |seg|
         case seg[:type]
         when :static
-          parts << seg[:value]
+          estimated_size += seg[:value].length + 1 # +1 for slash
+        when :param, :splat
+          estimated_size += 20 # Average param length estimate
+        end
+      end
+
+      # Use string buffer with pre-allocated capacity
+      path = String.new(capacity: estimated_size)
+      path << '/'
+
+      # Generate path directly into buffer
+      last_idx = @compiled_segments.size - 1
+      @compiled_segments.each_with_index do |seg, i|
+        case seg[:type]
+        when :static
+          path << seg[:value]
         when :param
           value = merged.fetch(seg[:name]).to_s
-          parts << encode_segment_fast(value)
+          path << encode_segment_fast(value)
         when :splat
           value = merged.fetch(seg[:name], '')
-          parts << format_splat_value(value)
+          path << format_splat_value(value)
         end
+
+        path << '/' unless i == last_idx
       end
 
-      # Single join operation is faster than multiple string concatenations
-      path = "/#{parts.join('/')}"
-      path == '/' ? ROOT_PATH : path
+      path
     end
 
     def format_splat_value(value)
@@ -366,13 +346,6 @@ module RubyRoutes
       result
     end
 
-    def normalize_path(path)
-      path_str = path.to_s
-      path_str = "/#{path_str}" unless path_str.start_with?('/')
-      path_str = path_str.chomp('/') unless path_str == ROOT_PATH
-      path_str
-    end
-
     def extract_controller(options)
       to = options[:to]
       return options[:controller] unless to
@@ -384,6 +357,84 @@ module RubyRoutes
       to.to_s.split('#', 2).last
     end
 
+
+    def validate_required_params(params)
+      return EMPTY_PAIR if @required_params.empty?
+      missing = nil
+      nils    = nil
+      @required_params.each do |rk|
+        if params.key?(rk)
+          (nils ||= []) << rk if params[rk].nil?
+        elsif params.key?(sym = rk.to_sym)
+          (nils ||= []) << rk if params[sym].nil?
+        else
+          (missing ||= []) << rk
+        end
+      end
+      [missing || EMPTY_ARRAY, nils || EMPTY_ARRAY]
+    end
+
+    # Add this validation cache management
+    def initialize_validation_cache
+      @validation_cache = SmallLru.new(64)
+    end
+
+    def cache_validation_result(params, result)
+      # Only cache immutable params to prevent subtle bugs
+      if params.frozen? && @validation_cache && @validation_cache.size < 64
+        @validation_cache.set(params.hash, result)
+      end
+    end
+
+    def get_cached_validation(params)
+      return nil unless @validation_cache
+      @validation_cache.get(params.hash)
+    end
+
+    # Fast parameter type detection with result caching
+    def params_type(params)
+      # Cache parameter type detection results
+      @params_type_cache ||= {}
+      param_obj_id = params.object_id
+
+      # Return cached type if available
+      return @params_type_cache[param_obj_id] if @params_type_cache.key?(param_obj_id)
+
+      # Type detection with explicit checks
+      type = if params.is_a?(Hash)
+        # Further refine hash type for optimization
+        refine_hash_type(params)
+      elsif params.respond_to?(:each) && params.respond_to?(:[])
+        # Hash-like enumerable
+        :enumerable
+      else
+        # Last resort - may
+        :mehod_missing
+      end
+
+      # Keep cache small
+      if @params_type_cache.size > 100
+        @params_type_cache.clear
+      end
+
+      # Cache result
+      @params_type_cache[param_obj_id] = type
+    end
+
+    # Further refine hash type for potential optimization
+    def refine_hash_type(params)
+      # Only sample a few keys to determine type tendency
+      key_samples = params.keys.take(3)
+
+      if key_samples.all? { |k| k.is_a?(String) }
+        :string_keyed_hash
+      elsif key_samples.all? { |k| k.is_a?(Symbol) }
+        :symbol_keyed_hash
+      else
+        :hash # Mixed keys
+      end
+    end
+
     # Optimized constraint validation
     def validate_constraints_fast!(params)
       @constraints.each do |param, constraint|
@@ -497,9 +548,5 @@ module RubyRoutes
       raise InvalidRoute, "Action is required" if @action.nil?
       raise InvalidRoute, "Invalid HTTP method: #{@methods}" if @methods.empty?
     end
-
-    # Additional constants
-    EMPTY_ARRAY = [].freeze
-    EMPTY_STRING = ''.freeze
   end
  end

data/lib/ruby_routes/route_set.rb

@@ -1,94 +1,103 @@
+require_relative 'utility/key_builder_utility'
+
 module RubyRoutes
   class RouteSet
     attr_reader :routes
 
+    include RubyRoutes::Utility::KeyBuilderUtility
+
     def initialize
-      @tree = RubyRoutes::RadixTree.new
-      @named_routes = {}
       @routes = []
-      # Optimized recognition cache with better data structures
+      @named_routes = {}
       @recognition_cache = {}
+      @recognition_cache_max = 2048
       @cache_hits = 0
       @cache_misses = 0
-      @recognition_cache_max = 8192  # larger for better hit rates
+      @radix_tree = RadixTree.new
     end
 
-    def add_route(route)
+    def add_to_collection(route)
       @routes << route
-      @tree.add(route.path, route.methods, route)
+      @radix_tree.add(route.path, route.methods, route)
       @named_routes[route.name] = route if route.named?
-      # Clear recognition cache when routes change
-      @recognition_cache.clear if @recognition_cache.size > 100
-      route
     end
 
-    def find_route(request_method, request_path)
-      # Optimized: avoid repeated string allocation
-      method_up = request_method.to_s.upcase
-      handler, _params = @tree.find(request_path, method_up)
-      handler
+    alias_method :add_route, :add_to_collection
+
+    def find_route(method, path)
+      route, _ = @radix_tree.find(path, method)
+      route
     end
 
     def find_named_route(name)
       route = @named_routes[name]
-      return route if route
-      raise RouteNotFound, "No route named '#{name}'"
+      raise RouteNotFound.new("No route named '#{name}'") unless route
+      route
     end
 
-    def match(request_method, request_path)
-      # Fast path: normalize method once
-      method_up = method_lookup(request_method)
+    FAST_METHOD_MAP = {
+      get: 'GET', post: 'POST', put: 'PUT', patch: 'PATCH',
+      delete: 'DELETE', head: 'HEAD', options: 'OPTIONS'
+    }.freeze
+
+    def normalize_method_input(method)
+      case method
+      when Symbol
+        FAST_METHOD_MAP[method] || method.to_s.upcase
+      when String
+        # Fast path: assume already correct; fallback only for common lowercase
+        return method if method.length <= 6 && method == method.upcase
+        FAST_METHOD_MAP[method.downcase.to_sym] || method.upcase
+      else
+        s = method.to_s
+        FAST_METHOD_MAP[s.downcase.to_sym] || s.upcase
+      end
+    end
+    private :normalize_method_input
 
-      # Optimized cache key: avoid string interpolation when possible
-      cache_key = build_cache_key(method_up, request_path)
+    def match(method, path)
+      m = normalize_method_input(method)
+      raw = path.to_s
+      cache_key = cache_key_for_request(m, raw)
 
-      # Cache hit: return immediately (cached result includes full structure)
-      if (cached_result = @recognition_cache[cache_key])
+      # Single cache lookup with proper hit accounting
+      if (hit = @recognition_cache[cache_key])
         @cache_hits += 1
-        return cached_result
+        return hit
       end
 
       @cache_misses += 1
 
-      # Use thread-local params to avoid allocations
-      params = get_thread_local_params
-      handler, _ = @tree.find(request_path, method_up, params)
-      return nil unless handler
+      path_without_query, _qs = raw.split('?', 2)
 
-      route = handler
+      # Use normalized method (m) for trie lookup
+      route, params = @radix_tree.find(path_without_query, m)
+      return nil unless route
 
-      # Fast path: merge defaults only if they exist
-      merge_defaults(route, params) if route.defaults && !route.defaults.empty?
+      merge_query_params(route, raw, params)
 
-      # Fast path: parse query params only if needed
-      if request_path.include?('?')
-        merge_query_params(route, request_path, params)
+      if route.respond_to?(:defaults) && route.defaults
+        route.defaults.each { |k,v| params[k.to_s] = v unless params.key?(k.to_s) }
       end
 
-      # Create return hash and cache the complete result
-      result_params = params.dup
       result = {
         route: route,
-        params: result_params,
+        params: params,
         controller: route.controller,
         action: route.action
-      }.freeze
+      }
 
       insert_cache_entry(cache_key, result)
       result
     end
 
-    def recognize_path(path, method = :get)
+    def recognize_path(path, method = 'GET')
       match(method, path)
     end
 
     def generate_path(name, params = {})
-      route = @named_routes[name]
-      if route
-        route.generate_path(params)
-      else
-        raise RouteNotFound, "No route named '#{name}'"
-      end
+      route = find_named_route(name)
+      route.generate_path(params)
     end
 
     def generate_path_from_route(route, params = {})
@@ -99,94 +108,76 @@ module RubyRoutes
       @routes.clear
       @named_routes.clear
       @recognition_cache.clear
-      @tree = RadixTree.new
-      @cache_hits = @cache_misses = 0
+      @cache_hits = 0
+      @cache_misses = 0
+      # Create a new radix tree since we can't clear it
+      @radix_tree = RadixTree.new
     end
 
     def size
       @routes.size
     end
-    alias_method :length, :size
 
     def empty?
       @routes.empty?
     end
 
-    def each(&block)
-      return enum_for(:each) unless block_given?
-      @routes.each(&block)
-    end
-
-    def include?(route)
-      @routes.include?(route)
-    end
-
-    # Performance monitoring
     def cache_stats
-      total = @cache_hits + @cache_misses
-      hit_rate = total > 0 ? (@cache_hits.to_f / total * 100).round(2) : 0
+      lookups = @cache_hits + @cache_misses
       {
         hits: @cache_hits,
         misses: @cache_misses,
-        hit_rate: "#{hit_rate}%",
+        hit_rate: lookups.zero? ? 0.0 : (@cache_hits.to_f / lookups * 100.0),
         size: @recognition_cache.size
       }
     end
 
-    private
-
-    # Method lookup table to avoid repeated upcasing with interned strings
-    def method_lookup(method)
-      @method_cache ||= Hash.new { |h, k| h[k] = k.to_s.upcase.freeze }
-      @method_cache[method]
-    end
-
-    # Optimized cache key building - avoid string interpolation
-    def build_cache_key(method, path)
-      # String interpolation creates a new string directly without intermediate allocations
-      "#{method}:#{path}"
+    def each(&block)
+      @routes.each(&block)
     end
 
-    # Get thread-local params hash, reusing when possible
-    def get_thread_local_params
-      # Use single thread-local hash that gets cleared, avoiding pool management overhead
-      hash = Thread.current[:ruby_routes_params_hash] ||= {}
-      hash.clear
-      hash
+    def include?(route)
+      @routes.include?(route)
     end
 
-    def return_params_to_pool(params)
-      # No-op since we're using a single reusable hash per thread
-    end
+    private
 
-    # Fast defaults merging
-    def merge_defaults(route, params)
-      route.defaults.each do |key, value|
-        params[key] = value unless params.key?(key)
+    def insert_cache_entry(key, value)
+      # unchanged cache insert (key already frozen & reusable)
+      if @recognition_cache.size >= @recognition_cache_max
+        @recognition_cache.keys.first(@recognition_cache_max / 4).each { |k| @recognition_cache.delete(k) }
+      end
+      @recognition_cache[key] = value
+    end
+
+    # Add the missing method for merging query params
+    def merge_query_params(route, path, params)
+      # Check for query string
+      if path.to_s.include?('?')
+        if route.respond_to?(:parse_query_params)
+          query_params = route.parse_query_params(path)
+          params.merge!(query_params) if query_params
+        elsif route.respond_to?(:query_params)
+          query_params = route.query_params(path)
+          params.merge!(query_params) if query_params
+        end
       end
     end
 
-    # Fast query params merging
-    def merge_query_params(route, request_path, params)
-      if route.respond_to?(:parse_query_params)
-        qp = route.parse_query_params(request_path)
-        params.merge!(qp) unless qp.empty?
-      elsif route.respond_to?(:query_params)
-        qp = route.query_params(request_path)
-        params.merge!(qp) unless qp.empty?
+    # Add thread-local params pool methods
+    def get_thread_local_params
+      thread_params = Thread.current[:ruby_routes_params_pool] ||= []
+      if thread_params.empty?
+        {}
+      else
+        thread_params.pop.clear
       end
     end
 
-    # Efficient cache insertion with LRU eviction
-    def insert_cache_entry(cache_key, cache_entry)
-      @recognition_cache[cache_key] = cache_entry
-
-      # Simple eviction: clear cache when it gets too large
-      if @recognition_cache.size > @recognition_cache_max
-        # Keep most recently used half
-        keys_to_delete = @recognition_cache.keys[0...(@recognition_cache_max / 2)]
-        keys_to_delete.each { |k| @recognition_cache.delete(k) }
-      end
+    def return_params_to_pool(params)
+      params.clear
+      thread_pool = Thread.current[:ruby_routes_params_pool] ||= []
+      thread_pool << params if thread_pool.size < 10 # Limit pool size
     end
   end
 end

data/lib/ruby_routes/router.rb

@@ -1,9 +1,12 @@
+require_relative 'utility/route_utility'
+
 module RubyRoutes
   class Router
     attr_reader :route_set
 
     def initialize(&block)
       @route_set = RouteSet.new
+      @route_utils = RubyRoutes::Utility::RouteUtility.new(@route_set)
       @scope_stack = []
       @concerns = {}
       instance_eval(&block) if block_given?
@@ -102,7 +105,14 @@ module RubyRoutes
     end
 
     # Scope support
-    def scope(options = {}, &block)
+    def scope(options_or_path = {}, &block)
+      # Handle the case where the first argument is a string (path)
+      options = if options_or_path.is_a?(String)
+                  { path: options_or_path }
+                else
+                  options_or_path
+                end
+
       @scope_stack.push(options)
 
       if block_given?
@@ -165,14 +175,9 @@ module RubyRoutes
 
     private
 
-    def add_route(path, options = {})
-      # Apply current scope
-      scoped_options = apply_scope(path, options)
-
-      # Create and add the route
-      route = Route.new(scoped_options[:path], scoped_options)
-      @route_set.add_route(route)
-      route
+    def add_route(path, options={})
+      scoped = apply_scope(path, options)
+      @route_utils.define(scoped[:path], scoped)
     end
 
     def apply_scope(path, options)

data/lib/ruby_routes/utility/key_builder_utility.rb

@@ -0,0 +1,102 @@
+module RubyRoutes
+  module Utility
+    module KeyBuilderUtility
+      # ------------------------------------------------------------------
+      # Fast reusable key storage for "METHOD:PATH" strings.
+      # O(1) insert + O(1) eviction using a fixed-size ring buffer.
+      # Only allocates a new String on the *first* time a (method,path) pair appears.
+      # ------------------------------------------------------------------
+      REQUEST_KEY_CAPACITY = 4096
+
+      @pool      = {}                        # { method_string => { path_string => frozen_key_string } }
+      @ring      = Array.new(REQUEST_KEY_CAPACITY) # ring entries: [method_string, path_string]
+      @ring_pos  = 0
+      @entry_cnt = 0
+
+      class << self
+        attr_reader :pool
+        def fetch_request_key(method, path)
+          # Method & path must be strings already (callers ensure)
+          if (paths = @pool[method])
+            if (key = paths[path])
+              return key
+            end
+          end
+
+            # MISS: build & freeze once
+          key = "#{method}:#{path}".freeze
+          if paths
+            paths[path] = key
+          else
+            @pool[method] = { path => key }
+          end
+
+          # Evict if ring full (overwrite oldest slot)
+          if @entry_cnt < REQUEST_KEY_CAPACITY
+            @ring[@entry_cnt] = [method, path]
+            @entry_cnt += 1
+          else
+            ev_m, ev_p = @ring[@ring_pos]
+            bucket = @pool[ev_m]
+            if bucket&.delete(ev_p) && bucket.empty?
+              @pool.delete(ev_m)
+            end
+            @ring[@ring_pos] = [method, path]
+            @ring_pos += 1
+            @ring_pos = 0 if @ring_pos == REQUEST_KEY_CAPACITY
+          end
+
+          key
+        end
+      end
+
+      # ------------------------------------------------------------------
+      # Public helpers mixed into instances
+      # ------------------------------------------------------------------
+
+      # Generic key (rarely hot): joins parts with delim; single allocation.
+      def build_key(parts, delim = ':')
+        return ''.freeze if parts.empty?
+        buf = Thread.current[:ruby_routes_key_buf] ||= String.new
+        buf.clear
+        i = 0
+        while i < parts.length
+          buf << delim unless i.zero?
+          buf << parts[i].to_s
+          i += 1
+        end
+        buf.dup
+      end
+
+      # HOT: request cache key (reused frozen interned string)
+      def cache_key_for_request(method, path)
+        KeyBuilderUtility.fetch_request_key(method, path.to_s)
+      end
+
+      # HOT: params key – produces a short-lived String (dup, not re-frozen each time).
+      # Callers usually put it into an LRU that duplicates again, so keep it lean.
+      def cache_key_for_params(required_params, merged)
+        return ''.freeze if required_params.nil? || required_params.empty?
+        buf = Thread.current[:ruby_routes_param_key_buf] ||= String.new
+        buf.clear
+        i = 0
+        while i < required_params.length
+          buf << '|' unless i.zero?
+          v = merged[required_params[i]]
+          if v.is_a?(Array)
+            j = 0
+            while j < v.length
+              buf << '/' unless j.zero?
+              buf << v[j].to_s
+              j += 1
+            end
+          else
+            buf << v.to_s
+          end
+          i += 1
+        end
+        buf.dup
+      end
+    end
+  end
+end

data/lib/ruby_routes/utility/path_utility.rb

@@ -0,0 +1,42 @@
+module RubyRoutes
+  module Utility
+    module PathUtility
+      ROOT_PATH = '/'.freeze
+
+      def normalize_path(path)
+        path = path.to_s
+        # Add leading slash if missing
+        path = '/' + path unless path.start_with?('/')
+        # Remove trailing slash if present (unless root)
+        path = path[0..-2] if path.length > 1 && path.end_with?('/')
+        path
+      end
+
+      def split_path(path)
+        # Remove query string before splitting
+        path = path.split('?', 2).first
+        path = path[1..-1] if path.start_with?('/')
+        path = path[0...-1] if path.end_with?('/') && path != ROOT_PATH
+        path.empty? ? [] : path.split('/')
+      end
+
+      def join_path_parts(parts)
+        # Pre-calculate the size to avoid buffer resizing
+        size = parts.sum { |p| p.length + 1 } # +1 for slash
+
+        # Use string buffer for better performance
+        result = String.new(capacity: size)
+        result << '/'
+
+        # Join with explicit concatenation rather than array join
+        last_idx = parts.size - 1
+        parts.each_with_index do |part, i|
+          result << part
+          result << '/' unless i == last_idx
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/ruby_routes/utility/route_utility.rb

@@ -0,0 +1,21 @@
+module RubyRoutes
+  module Utility
+    class RouteUtility
+      def initialize(route_set)
+        @route_set = route_set
+      end
+
+      # DSL wants to merge scope, RouteSet wants to add a pre‐built Route,
+      # so we offer two entry points:
+      def define(path, options = {})
+        route = Route.new(path, options)
+        register(route)
+      end
+
+      def register(route)
+        @route_set.add_to_collection(route)
+        route
+      end
+    end
+  end
+end

data/lib/ruby_routes/version.rb

@@ -1,3 +1,3 @@
 module RubyRoutes
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_routes
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Yosef Benny Widyokarsono
@@ -92,6 +92,9 @@ files:
 - lib/ruby_routes/segments/wildcard_segment.rb
 - lib/ruby_routes/string_extensions.rb
 - lib/ruby_routes/url_helpers.rb
+- lib/ruby_routes/utility/key_builder_utility.rb
+- lib/ruby_routes/utility/path_utility.rb
+- lib/ruby_routes/utility/route_utility.rb
 - lib/ruby_routes/version.rb
 homepage: https://github.com/yosefbennywidyo/ruby_routes
 licenses: