ruby_routes 2.2.0 → 2.4.0

data/lib/ruby_routes/radix_tree/inserter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class RadixTree
+    # Inserter module for adding routes to the RadixTree.
+    # Handles tokenization, node advancement, and endpoint finalization.
+    module Inserter
+      private
+
+      # Inserts a route into the RadixTree for the given path and HTTP methods.
+      #
+      # @param path_string [String] the path to insert
+      # @param http_methods [Array<String>] the HTTP methods for the route
+      # @param route_handler [Object] the handler for the route
+      # @return [Object] the route handler
+      def insert_route(path_string, http_methods, route_handler)
+        return route_handler if path_string.nil? || path_string.empty?
+
+        tokens = split_path(path_string)
+        current_node = @root
+        tokens.each { |token| current_node = advance_node(current_node, token) }
+        finalize_endpoint(current_node, http_methods, route_handler)
+        route_handler
+      end
+
+      # Advances to the next node based on the token type.
+      #
+      # @param current_node [Node] the current node in the tree
+      # @param token [String] the token to process
+      # @return [Node] the next node
+      def advance_node(current_node, token)
+        case token[0]
+        when ':'
+          handle_dynamic(current_node, token)
+        when '*'
+          handle_wildcard(current_node, token)
+        else
+          handle_static(current_node, token)
+        end
+      end
+
+      # Handles dynamic parameter tokens (e.g., :id).
+      #
+      # @param current_node [Node] the current node
+      # @param token [String] the dynamic token
+      # @return [Node] the dynamic child node
+      def handle_dynamic(current_node, token)
+        param_name = token[1..]
+        current_node.dynamic_child ||= build_param_node(param_name)
+        current_node.dynamic_child
+      end
+
+      # Handles wildcard tokens (e.g., *splat).
+      #
+      # @param current_node [Node] the current node
+      # @param token [String] the wildcard token
+      # @return [Node] the wildcard child node
+      def handle_wildcard(current_node, token)
+        param_name = token[1..]
+        param_name = 'splat' if param_name.nil? || param_name.empty?
+        current_node.wildcard_child ||= build_param_node(param_name)
+        current_node.wildcard_child
+      end
+
+      # Handles static literal tokens.
+      #
+      # @param current_node [Node] the current node
+      # @param token [String] the static token
+      # @return [Node] the static child node
+      def handle_static(current_node, token)
+        literal_token = token.freeze
+        current_node.static_children[literal_token] ||= Node.new
+        current_node.static_children[literal_token]
+      end
+
+      # Builds a new node for parameter capture.
+      #
+      # @param param_name [String] the parameter name
+      # @return [Node] the new parameter node
+      def build_param_node(param_name)
+        node = Node.new
+        node.param_name = param_name
+        node
+      end
+
+      # Finalizes the endpoint by adding handlers for HTTP methods.
+      #
+      # @param node [Node] the endpoint node
+      # @param http_methods [Array<String>] the HTTP methods
+      # @param route_handler [Object] the route handler
+      def finalize_endpoint(node, http_methods, route_handler)
+        http_methods.each { |http_method| node.add_handler(http_method, route_handler) }
+      end
+    end
+  end
+end

data/lib/ruby_routes/radix_tree.rb

@@ -1,15 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'route/small_lru'
 require_relative 'segment'
 require_relative 'utility/path_utility'
+require_relative 'utility/method_utility'
+require_relative 'node'
+require_relative 'radix_tree/inserter'
+require_relative 'radix_tree/finder'
 
 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.
+  # RadixTree
+  #
+  # Compact routing trie supporting:
+  # - Static segments  (/users)
+  # - Dynamic segments (/users/:id)
+  # - Wildcard splat   (/assets/*path)
+  #
+  # Design / Behavior:
+  # - Traversal keeps track of the deepest valid endpoint encountered
+  #   (best_match_node) so that if a later branch fails, we can still
+  #   return a shorter matching route.
+  # - Dynamic and wildcard captures are written directly into the caller
+  #   supplied params Hash (or a fresh one) to avoid intermediate objects.
+  # - A very small manual LRU (Hash + order Array) caches the result of
+  #   splitting raw paths into their segment arrays.
+  #
+  # Matching Precedence:
+  #   static > dynamic > wildcard
+  #
+  # Thread Safety:
+  # - Not thread‑safe for mutation (intended for boot‑time construction).
+  #   Safe for concurrent reads after routes are added.
+  #
+  # @api internal
   class RadixTree
     include RubyRoutes::Utility::PathUtility
+    include RubyRoutes::Utility::MethodUtility
+    include Inserter
+    include Finder
 
     class << self
-      # Allow RadixTree.new(path, options...) to act as a convenience factory
+      # Backwards DSL convenience: RadixTree.new(args) → Route
       def new(*args, &block)
         if args.any?
           RubyRoutes::Route.new(*args, &block)
@@ -19,244 +50,48 @@ module RubyRoutes
       end
     end
 
+    # Initialize empty tree and split cache.
     def initialize
-      @root = Node.new
-      @split_cache = {}
-      @split_cache_order = []
-      @split_cache_max = 2048
-      @empty_segments = [].freeze
+      @root          = Node.new
+      @split_cache        = RubyRoutes::Route::SmallLru.new(2048)
+      @split_cache_max    = 2048
+      @split_cache_order  = []
+      @empty_segment_list = [].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)
-      # 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]
-
-          # 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
-
-      handler
+    # Add a route to the tree (delegates insertion logic).
+    #
+    # @param raw_path [String]
+    # @param http_methods [Array<String,Symbol>]
+    # @param route_handler [Object]
+    # @return [Object] route_handler
+    def add(raw_path, http_methods, route_handler)
+      normalized_path    = normalize_path(raw_path)
+      normalized_methods = http_methods.map { |m| normalize_http_method(m) }
+      insert_route(normalized_path, normalized_methods, route_handler)
+      route_handler
     end
 
-    # 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, params_out || {}]
-        end
-      end
-
-      # Split path into segments
-      segments = split_path_cached(path_str)
-      return [nil, params_out || {}] if segments.empty?
-
-      params = params_out || {}
-      
-      # 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
-
-        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
-
-      # 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
-
-        return [handler, params]
-      end
-
-      # 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]
+    # Public find delegates to Finder#find (now simplified on this class).
+    def find(request_path_input, request_method_input, params_out = {})
+      super
     end
 
     private
 
-    # 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 == '/'
+    # Split path with small manual LRU cache.
+    #
+    # @param raw_path [String]
+    # @return [Array<String>]
+    def split_path_cached(raw_path)
+      return @empty_segment_list if raw_path == '/'
 
-      # 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
-
-      # Split path and add to cache
-      segments = split_path(path)
-
-      # 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
-
-      @split_cache[path] = segments
-      @split_cache_order << path
+      cached = @split_cache.get(raw_path)
+      return cached if cached
 
+      segments = split_path(raw_path)
+      @split_cache.set(raw_path, segments)
       segments
     end
-
-    # 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)
-
-      constraints = handler.constraints
-      return true unless constraints && !constraints.empty?
-
-      # Check each constraint
-      constraints.each do |param, constraint|
-        param_key = param.to_s
-        value = params[param_key]
-        next unless value
-
-        case constraint
-        when Regexp
-          return false unless constraint.match?(value.to_s)
-        when :int
-          return false unless value.to_s.match?(/\A\d+\z/)
-        when :uuid
-          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
 end

data/lib/ruby_routes/route/check_helpers.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class Route
+    # CheckHelpers: small helpers for validating hash-form constraints.
+    #
+    # This module provides methods for validating various hash-form constraints,
+    # such as minimum length, maximum length, format, inclusion, exclusion, and range.
+    # Each method raises a `RubyRoutes::ConstraintViolation` exception if the
+    # validation fails.
+    module CheckHelpers
+      # Check minimum length constraint.
+      #
+      # This method validates that the value meets the minimum length specified
+      # in the constraint. If the value is shorter than the minimum length, a
+      # `ConstraintViolation` is raised.
+      #
+      # @param constraint [Hash] The constraint hash containing `:min_length`.
+      # @param value [String] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is shorter than the minimum length.
+      # @return [void]
+      def check_min_length(constraint, value)
+        return unless (min = constraint[:min_length]) && value && value.length < min
+
+        raise RubyRoutes::ConstraintViolation, "Value too short (minimum #{constraint[:min_length]} characters)"
+      end
+
+      # Check maximum length constraint.
+      #
+      # This method validates that the value does not exceed the maximum length
+      # specified in the constraint. If the value is longer than the maximum length,
+      # a `ConstraintViolation` is raised.
+      #
+      # @param constraint [Hash] The constraint hash containing `:max_length`.
+      # @param value [String] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value exceeds the maximum length.
+      # @return [void]
+      def check_max_length(constraint, value)
+        return unless (max = constraint[:max_length]) && value && value.length > max
+
+        raise RubyRoutes::ConstraintViolation, "Value too long (maximum #{constraint[:max_length]} characters)"
+      end
+
+      # Check format constraint.
+      #
+      # This method validates that the value matches the format specified in the
+      # constraint. If the value does not match the format, a `ConstraintViolation`
+      # is raised.
+      #
+      # @param constraint [Hash] The constraint hash containing `:format` (a Regexp).
+      # @param value [String] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value does not match the required format.
+      # @return [void]
+      def check_format(constraint, value)
+        return unless (format = constraint[:format]) && value && !value.match?(format)
+
+        raise RubyRoutes::ConstraintViolation, 'Value does not match required format'
+      end
+
+      # Check in list constraint.
+      #
+      # This method validates that the value is included in the list specified
+      # in the constraint. If the value is not in the list, a `ConstraintViolation`
+      # is raised.
+      #
+      # @param constraint [Hash] The constraint hash containing `:in` (an Array).
+      # @param value [String] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not in the allowed list.
+      # @return [void]
+      def check_in_list(constraint, value)
+        return unless constraint[:in] && !constraint[:in].include?(value)
+
+        raise RubyRoutes::ConstraintViolation, 'Value not in allowed list'
+      end
+
+      # Check not in list constraint.
+      #
+      # This method validates that the value is not included in the list specified
+      # in the constraint. If the value is in the forbidden list, a `ConstraintViolation`
+      # is raised.
+      #
+      # @param constraint [Hash] The constraint hash containing `:not_in` (an Array).
+      # @param value [String] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is in the forbidden list.
+      # @return [void]
+      def check_not_in_list(constraint, value)
+        return unless constraint[:not_in]&.include?(value)
+
+        raise RubyRoutes::ConstraintViolation, 'Value in forbidden list'
+      end
+
+      # Check range constraint.
+      #
+      # This method validates that the value falls within the range specified
+      # in the constraint. If the value is outside the range, a `ConstraintViolation`
+      # is raised.
+      #
+      # @param constraint [Hash] The constraint hash containing `:range` (a Range).
+      # @param value [String] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not in the allowed range.
+      # @return [void]
+      def check_range(constraint, value)
+        range = constraint[:range]
+        return unless range
+        begin
+          integer_value = Integer(value) # raises on nil, floats, or junk like "10abc"
+        rescue ArgumentError, TypeError
+          raise RubyRoutes::ConstraintViolation, 'Value not in allowed range'
+        end
+
+        raise RubyRoutes::ConstraintViolation, 'Value not in allowed range' unless range.cover?(integer_value)
+      end
+    end
+  end
+end