ruby_routes 2.2.0 → 2.3.0

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,65 @@ 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          = 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
+    # 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
 
-    # 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
-    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 == '/'
-
-      # 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 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 == '/'
 
-      @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
+    # Evaluate constraint rules for a candidate route.
+    #
+    # @param route_handler [Object]
+    # @param captured_params [Hash]
+    # @return [Boolean]
+    def check_constraints(route_handler, captured_params)
+      return true unless route_handler.respond_to?(:validate_constraints_fast!)
+
+      begin
+        # Use a duplicate to avoid unintended mutation by validators.
+        route_handler.validate_constraints_fast!(captured_params)
+        true
+      rescue RubyRoutes::ConstraintViolation
+        false
       end
-
-      true
     end
   end
 end

data/lib/ruby_routes/route/check_helpers.rb

@@ -0,0 +1,109 @@
+# 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 constraint[:min_length] && value.length < constraint[:min_length]
+
+        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 constraint[:max_length] && value.length > constraint[:max_length]
+
+        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 constraint[:format] && !value.match?(constraint[: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)
+        return unless constraint[:range] && !constraint[:range].cover?(value.to_i)
+
+        raise RubyRoutes::ConstraintViolation, 'Value not in allowed range'
+      end
+    end
+  end
+end

data/lib/ruby_routes/route/constraint_validator.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative '../constant'
+
+module RubyRoutes
+  class Route
+    # ConstraintValidator: extracted constraint logic.
+    #
+    # This module provides methods for validating route constraints, including
+    # support for regular expressions, procs, hash-based constraints, and built-in
+    # validation rules. It also handles timeouts and raises appropriate exceptions
+    # for constraint violations.
+    module ConstraintValidator
+      # Validate all constraints for the given parameters.
+      #
+      # This method iterates through all constraints and validates each parameter
+      # against its corresponding rule.
+      #
+      # @param params [Hash] The parameters to validate.
+      # @return [void]
+      def validate_constraints_fast!(params)
+        @constraints.each do |key, rule|
+          param_key = key.to_s
+          next unless params.key?(param_key)
+
+          validate_constraint_for(rule, key, params[param_key])
+        end
+      end
+
+      # Dispatch a single constraint check.
+      #
+      # This method validates a single parameter against its constraint rule.
+      #
+      # @param rule [Object] The constraint rule (Regexp, Proc, Symbol, Hash).
+      # @param key [String, Symbol] The parameter key.
+      # @param value [Object] The value to validate.
+      # @return [void]
+      def validate_constraint_for(rule, key, value)
+        case rule
+        when Regexp then validate_regexp_constraint(rule, value)
+        when Proc then validate_proc_constraint(key, rule, value)
+        when Hash then validate_hash_constraint!(rule, value.to_s)
+        else
+          validate_builtin_constraint(rule, value)
+        end
+      end
+
+      # Handle built-in symbol/string rules via a simple lookup.
+      #
+      # @param rule [Symbol, String] The built-in constraint rule.
+      # @param value [Object] The value to validate.
+      # @return [void]
+      def validate_builtin_constraint(rule, value)
+        method_sym = RubyRoutes::Constant::BUILTIN_VALIDATORS[rule.to_sym] if rule
+        send(method_sym, value) if method_sym
+      end
+
+      # Validate a regexp constraint.
+      #
+      # This method validates a value against a regular expression constraint.
+      # It raises a timeout error if the validation takes too long.
+      #
+      # @param regexp [Regexp] The regular expression to match.
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value does not match the regexp.
+      def validate_regexp_constraint(regexp, value)
+        Timeout.timeout(0.1) { invalid! unless regexp.match?(value.to_s) }
+      rescue Timeout::Error
+        raise RubyRoutes::ConstraintViolation, 'Regex constraint timed out'
+      end
+
+      # Validate a proc constraint.
+      #
+      # This method validates a value using a proc constraint. It emits a
+      # deprecation warning for proc constraints and handles timeouts and errors.
+      #
+      # @param key [String, Symbol] The parameter key.
+      # @param proc [Proc] The proc to call.
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the proc constraint fails or times out.
+      def validate_proc_constraint(key, proc, value)
+        warn_proc_constraint_deprecation(key)
+        Timeout.timeout(0.05) { invalid! unless proc.call(value.to_s) }
+      rescue Timeout::Error
+        raise RubyRoutes::ConstraintViolation, 'Proc constraint timed out'
+      rescue StandardError => e
+        raise RubyRoutes::ConstraintViolation, "Proc constraint failed: #{e.message}"
+      end
+
+      # Validate an integer constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not an integer.
+      def validate_int_constraint(value)
+        invalid! unless value.to_s.match?(/\A\d+\z/)
+      end
+
+      # Validate a UUID constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not a valid UUID.
+      def validate_uuid_constraint(value)
+        validate_uuid!(value)
+      end
+
+      # Validate an email constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not a valid email.
+      def validate_email_constraint(value)
+        invalid! unless value.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+      end
+
+      # Validate a slug constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not a valid slug.
+      def validate_slug_constraint(value)
+        invalid! unless value.to_s.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/)
+      end
+
+      # Validate an alpha constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not alphabetic.
+      def validate_alpha_constraint(value)
+        invalid! unless value.to_s.match?(/\A[a-zA-Z]+\z/)
+      end
+
+      # Validate an alphanumeric constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not alphanumeric.
+      def validate_alphanumeric_constraint(value)
+        invalid! unless value.to_s.match?(/\A[a-zA-Z0-9]+\z/)
+      end
+
+      # Validate a UUID.
+      #
+      # This method validates that a value is a properly formatted UUID.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not a valid UUID.
+      def validate_uuid!(value)
+        string = value.to_s
+        unless string.length == 36 && string.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
+          invalid!
+        end
+      end
+
+      # Raise a constraint violation.
+      #
+      # @raise [RubyRoutes::ConstraintViolation] Always raises this exception.
+      def invalid!
+        raise RubyRoutes::ConstraintViolation
+      end
+    end
+  end
+end