ruby_routes 2.1.0 → 2.3.0

data/lib/ruby_routes/radix_tree.rb

@@ -1,9 +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
+  #
+  # 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)
@@ -13,161 +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      # larger cache for better hit rates
-      @empty_segments = [].freeze  # reuse for root path
+      @root_node          = Node.new
+      @split_cache        = RubyRoutes::Route::SmallLru.new(2048)
+      @split_cache_max    = 2048
+      @split_cache_order  = []
+      @empty_segment_list = [].freeze
     end
 
-    def add(path, methods, handler)
-      current = @root
-      segments = split_path_raw(path)
-
-      segments.each do |raw_seg|
-        seg = RubyRoutes::Segment.for(raw_seg)
-        current = seg.ensure_child(current)
-        break if seg.wildcard?
-      end
-
-      # Normalize methods once during registration
-      Array(methods).each { |method| current.add_handler(method.to_s.upcase, 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
 
-    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 || {}]
-        else
-          return [nil, {}]
-        end
-      end
-
-      segments = split_path_cached(clean_path)
-      current = @root
-      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
-          end
-        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
-        end
-      end
-
-      return [nil, {}] unless current
-      handler = current.get_handler(method)
-      return [nil, {}] unless current.is_endpoint && handler
-
-      # Fast constraint check
-      if handler.respond_to?(:constraints) && !handler.constraints.empty?
-        return [nil, {}] unless constraints_match_fast(handler.constraints, params)
-      end
-
-      [handler, 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
 
-    # Cached path splitting with optimized common cases
-    def split_path_cached(path)
-      return @empty_segments if path == '/' || path.empty?
-
-      if (cached = @split_cache[path])
-        return cached
-      end
-
-      result = split_path_raw(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)
-      end
-
-      result
-    end
-
-    # Raw path splitting without caching (for registration)
-    def split_path_raw(path)
-      return [] if path == '/' || path.empty?
+    # 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 == '/'
 
-      # Optimized trimming: avoid string allocations when possible
-      start_idx = path.start_with?('/') ? 1 : 0
-      end_idx = path.end_with?('/') ? -2 : -1
+      cached = @split_cache.get(raw_path)
+      return cached if cached
 
-      if start_idx == 0 && end_idx == -1
-        path.split('/')
-      else
-        path[start_idx..end_idx].split('/')
-      end
+      segments = split_path(raw_path)
+      @split_cache.set(raw_path, segments)
+      segments
     end
 
-    # Optimized constraint matching with fast paths
-    def constraints_match_fast(constraints, params)
-      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)
-        next unless value
-
-        case constraint
-        when Regexp
-          return false unless constraint.match?(value)
-        when Proc
-          return false unless constraint.call(value)
-        when :int
-          # Fast integer check without regex
-          return false unless value.is_a?(String) && value.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
-        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