ruby_routes 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4017abab11dd0945bcfe1659b2ed1456c2cf82a8993db55d094d283c48c8ebd0
-  data.tar.gz: 07f0aba728bf81cdfdc245e20a212f1775b2314a826c88f0e25b8ff2b608c195
+  metadata.gz: 66764348265233b0904630e4193e21fc93f79e3257ec4d0e43e5c533faf1f7e1
+  data.tar.gz: de32cc9f5f42398b12e829c4da34aa82afd071fa63ed869180a56203834beecd
 SHA512:
-  metadata.gz: a4aa77ba441b9e87cdcb31cae5b5f12babaf93396e400723d5f845392ac132520c4398e19d49d0755e05fc305791b54a3676a460ba8c73cd4b5ee55647fb2589
-  data.tar.gz: a3b883c253731dfad5eaf34a28fb89684d0f9fa921127f6e428225743a93d87934508e49f59c3710964cc8a444b729f9278872aa8d991c4302abbb7ff8645b66
+  metadata.gz: 21442f1a73e4045fedbb9bd215c639770c55135f6d55c78c17384996515d1347851d7b3afa952db345793a5aa92d5c14368d28faf0e35d4c985d608d94c8b980
+  data.tar.gz: 5570f4054ceaf76569bb4f28eca4d94347a559a24febe1936e39dfb9896ccfa281cdd1e2ce24e8e2b157b3d7f3870a67cc9ecdb61b62338bce7e28b5d0c32e4e

data/lib/ruby_routes/constant.rb

@@ -1,3 +1,4 @@
+require_relative 'segments/base_segment'
 require_relative 'segments/dynamic_segment'
 require_relative 'segments/static_segment'
 require_relative 'segments/wildcard_segment'

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,151 +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)
-      # Fast path: root route
-      if path == '/' || 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(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