ruby_routes 2.5.0 → 2.6.0

data/lib/ruby_routes/radix_tree.rb

@@ -9,38 +9,14 @@ 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
+    include RubyRoutes::RadixTree::Inserter
+    include RubyRoutes::RadixTree::Finder
 
     class << self
-      # Backwards DSL convenience: RadixTree.new(args) → Route
+      # Allow RadixTree.new(path, options...) to act as a convenience factory
       def new(*args, &block)
         if args.any?
           RubyRoutes::Route.new(*args, &block)
@@ -50,48 +26,22 @@ module RubyRoutes
       end
     end
 
-    # Initialize empty tree and split cache.
     def initialize
-      @root          = Node.new
-      @split_cache        = RubyRoutes::Route::SmallLru.new(2048)
-      @split_cache_max    = 2048
-      @split_cache_order  = []
-      @empty_segment_list = [].freeze
+      @root = Node.new
+      @split_cache = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
+      @split_cache_max = RubyRoutes::Constant::CACHE_SIZE      # larger cache for better hit rates
+      @empty_segments = [].freeze  # reuse for root path
     end
 
-    # 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
-
-    # Public find delegates to Finder#find (now simplified on this class).
-    def find(request_path_input, request_method_input, params_out = {})
-      super
+    def add(path, methods, handler)
+      insert_route(path, methods, handler)
     end
 
     private
 
-    # 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 == '/'
-
-      cached = @split_cache.get(raw_path)
-      return cached if cached
-
-      segments = split_path(raw_path)
-      @split_cache.set(raw_path, segments)
-      segments
+    # Cached path splitting with optimized common cases
+    def split_path_cached(path)
+      @split_cache.get(path) || @split_cache.set(path, split_path(path))
     end
   end
 end

data/lib/ruby_routes/route/check_helpers.rb

@@ -20,7 +20,7 @@ module RubyRoutes
       # @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
+        return unless (min = constraint[:min_length]) && value&.length < min
 
         raise RubyRoutes::ConstraintViolation, "Value too short (minimum #{constraint[:min_length]} characters)"
       end
@@ -36,7 +36,7 @@ module RubyRoutes
       # @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
+        return unless (max = constraint[:max_length]) && value&.length > max
 
         raise RubyRoutes::ConstraintViolation, "Value too long (maximum #{constraint[:max_length]} characters)"
       end
@@ -52,7 +52,7 @@ module RubyRoutes
       # @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)
+        return unless (format = constraint[:format]) && !value&.match?(format)
 
         raise RubyRoutes::ConstraintViolation, 'Value does not match required format'
       end

data/lib/ruby_routes/route/constraint_validator.rb

@@ -2,6 +2,7 @@
 
 require 'timeout'
 require_relative '../constant'
+require_relative 'warning_helpers'
 
 module RubyRoutes
   class Route
@@ -12,6 +13,7 @@ module RubyRoutes
     # validation rules. It also handles timeouts and raises appropriate exceptions
     # for constraint violations.
     module ConstraintValidator
+      include RubyRoutes::Route::WarningHelpers
       # Validate all constraints for the given parameters.
       #
       # This method iterates through all constraints and validates each parameter
@@ -47,6 +49,24 @@ module RubyRoutes
         end
       end
 
+      # Validate hash-form constraint rules.
+      #
+      # This method validates a value against a set of hash-form constraints,
+      # such as minimum length, maximum length, format, inclusion, exclusion,
+      # and range.
+      #
+      # @param constraint [Hash] The constraint rules.
+      # @param value [String] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value violates any constraint.
+      # @return [void]
+      def validate_hash_constraint!(constraint, value)
+        check_min_length(constraint, value)
+        check_max_length(constraint, value)
+        check_format(constraint, value)
+        check_in_list(constraint, value)
+        check_not_in_list(constraint, value)
+        check_range(constraint, value)
+      end
       # Handle built-in symbol/string rules via a simple lookup.
       #
       # @param rule [Symbol, String] The built-in constraint rule.
@@ -124,7 +144,8 @@ module RubyRoutes
       # @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/)
+        email_regex = /\A[a-zA-Z0-9.!\#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+\z/
+        invalid! unless value.to_s.match?(email_regex)
       end
 
       # Validate a slug constraint.

data/lib/ruby_routes/route/matcher.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class Route
+    module Matcher
+      def match(path, method)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/ruby_routes/route/param_support.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'path_generation'
 require_relative 'warning_helpers'
-require_relative 'constraint_validator'
+require_relative 'query_helpers'
 
 module RubyRoutes
   class Route
@@ -15,6 +14,7 @@ module RubyRoutes
     # Thread-safety: Thread-local storage is used to avoid allocation and cross-thread mutation.
     module ParamSupport
       include RubyRoutes::Route::WarningHelpers
+      include RubyRoutes::Route::QueryHelpers
 
       private
 
@@ -26,11 +26,9 @@ module RubyRoutes
       # @param params [Hash] The user-provided parameters.
       # @return [Hash] The merged parameters.
       def build_merged_params(params)
-        return @defaults if params.nil? || params.empty?
-
         merged_hash = acquire_merge_hash
         merge_defaults_into(merged_hash)
-        merge_user_params_into(merged_hash, params)
+        merge_user_params_into(merged_hash, params) unless params.nil? || params.empty?
         merged_hash
       end
 
@@ -60,9 +58,12 @@ module RubyRoutes
       # @return [void]
       def merge_user_params_into(merged_hash, params)
         params.each do |key, value|
-          next if value.nil?
-
-          merged_hash[key.is_a?(String) ? key : key.to_s] = value
+          string_key = if key.is_a?(String)
+                        key
+                      else
+                        (Thread.current[:ruby_routes_symbol_keys] ||= {})[key] ||= key.to_s.freeze
+                      end
+          merged_hash[string_key] = value
         end
       end
 

data/lib/ruby_routes/route/path_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'small_lru'
+
 module RubyRoutes
   class Route
     # PathBuilder: generation + segment encoding
@@ -25,7 +27,7 @@ module RubyRoutes
       # Append a segment to the buffer.
       #
       # @param buffer [String] the buffer to append to
-      # @param segment [Hash] the segment to append
+      # @param segment [RubyRoutes::Segments::BaseSegment] the segment to append
       # @param merged [Hash] the merged parameters
       # @param index [Integer] the current index
       # @param last_index [Integer] the last index
@@ -48,8 +50,8 @@ module RubyRoutes
         # Rough heuristic (static sizes + average dynamic)
         base = 1
         @compiled_segments.each do |segment|
-          base += case segment[:type]
-                  when :static then segment[:value].length + 1
+          base += case segment
+                  when RubyRoutes::Segments::StaticSegment then segment.literal_text.length + 1
                   else 20
                   end
         end
@@ -75,9 +77,12 @@ module RubyRoutes
       def encode_segment_fast(string)
         return string if RubyRoutes::Constant::UNRESERVED_RE.match?(string)
 
-        @encoding_cache ||= {}
-        # Use gsub instead of tr for proper replacement of + with %20
-        @encoding_cache[string] ||= URI.encode_www_form_component(string).gsub('+', '%20')
+        @encoding_cache ||= RubyRoutes::Route::SmallLru.new(256)
+        cached = @encoding_cache.get(string)
+        return cached if cached
+
+        encoded = URI.encode_www_form_component(string).gsub('+', '%20')
+        @encoding_cache.set(string, encoded)
       end
     end
   end

data/lib/ruby_routes/route/path_generation.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'warning_helpers'
+require_relative 'validation_helpers'
+require_relative 'param_support'
 
 module RubyRoutes
   class Route
@@ -9,6 +11,8 @@ module RubyRoutes
     # route-related warnings (kept separate to reduce parent module size).
     module PathGeneration
       include RubyRoutes::Route::WarningHelpers
+      include RubyRoutes::Route::ValidationHelpers
+      include RubyRoutes::Route::ParamSupport
 
       private
 
@@ -25,8 +29,8 @@ module RubyRoutes
         return @static_path if static_short_circuit?(params)
         return @static_path || RubyRoutes::Constant::ROOT_PATH if trivial_route?
 
-        validate_required_once(params)
         merged_params = build_merged_params(params)
+        validate_required_once(merged_params.dup)
 
         build_or_fetch_generated_path(merged_params)
       end

data/lib/ruby_routes/route/small_lru.rb

@@ -27,7 +27,7 @@ module RubyRoutes
       # @return [Integer] number of cache hits
       # @return [Integer] number of cache misses
       # @return [Integer] number of evictions (when capacity exceeded)
-      attr_reader :max_size, :hits, :misses, :evictions
+      attr_reader :max_size, :hits, :misses, :evictions, :hash
 
       # @param max_size [Integer] positive maximum size
       # @raise [ArgumentError] if max_size < 1
@@ -91,6 +91,42 @@ module RubyRoutes
         @hash.keys
       end
 
+      # Check if a key exists in the cache.
+      #
+      # @param key [Object] The key to check.
+      # @return [Boolean] True if the key exists, false otherwise.
+      def has_key?(key)
+        @hash.key?(key)
+      end
+
+      # Hash-like access for reading (delegates to get).
+      #
+      # @param key [Object] The key to retrieve.
+      # @return [Object, nil] The cached value or nil.
+      def [](key)
+        get(key)
+      end
+
+      # Include matcher (checks for key-value pair).
+      #
+      # @param pair [Hash] A hash with a single key-value pair (e.g., { 'key' => 'value' }).
+      # @return [Boolean] True if the pair exists in the cache, false otherwise.
+      def include?(pair)
+        return false unless pair.is_a?(Hash) && pair.size == 1
+
+        key, value = pair.first
+        @hash[key] == value
+      end
+
+      # Hash-like access for writing (delegates to set).
+      #
+      # @param key [Object] The key to set.
+      # @param value [Object] The value to cache.
+      # @return [Object] The value.
+      def []=(key, value)
+        set(key, value)
+      end
+
       # Debug / spec helper (avoid exposing internal Hash directly).
       # @return [Hash] shallow copy of internal store
       def inspect_hash
@@ -109,6 +145,12 @@ module RubyRoutes
         @misses += 1
       end
 
+      def clear_counters!
+        @hits = 0
+        @misses = 0
+        @evictions = 0
+      end
+
       # Internal helper used by hit strategy to promote key.
       # @param key [Object]
       # @return [void]
@@ -116,7 +158,6 @@ module RubyRoutes
         val = @hash.delete(key)
         @hash[key] = val if val
       end
-      private :promote
     end
   end
 end

data/lib/ruby_routes/route/validation_helpers.rb

@@ -48,20 +48,14 @@ module RubyRoutes
       def validate_required_once(params)
         return if @required_params.empty?
 
-        # Check cache for existing validation result
         cached_result = get_cached_validation(params)
         if cached_result
           missing, nils = cached_result
         else
-          # Perform validation
           missing, nils = validate_required_params(params)
-          # Cache the result only if params are frozen
-          if params.frozen?
-            cache_validation_result(params, [missing, nils])
-          end
+          cache_validation_result(params.freeze, [missing, nils])
         end
 
-        # Raise if invalid
         raise RouteNotFound, "Missing params: #{missing.join(', ')}" unless missing.empty?
         raise RouteNotFound, "Missing or nil params: #{nils.join(', ')}" unless nils.empty?
       end
@@ -78,10 +72,6 @@ module RubyRoutes
         return RubyRoutes::Constant::EMPTY_PAIR if @required_params.empty?
         params ||= {}
 
-        if (cached = get_cached_validation(params))
-          return cached
-        end
-
         missing = []
         nils = []
         @required_params.each do |required_key|
@@ -124,14 +114,13 @@ module RubyRoutes
       # @return [void]
       def cache_validation_result(params, result)
         return unless params.frozen?
-        return unless @validation_cache && @validation_cache.size < 64
+        return unless @validation_cache
 
-        @cache_mutex.synchronize { @validation_cache.set(params.hash, result) }
+        @cache_mutex.synchronize do
+          return if @validation_cache.size >= 64
+          @validation_cache.set(params.hash, result)
+        end
       end
-
-      # Fetch cached validation result.
-      #
-      # This method retrieves a cached validation result for the given parameters.
       #
       # @param params [Hash] The parameters used for validation.
       # @return [Object, nil] The cached validation result, or `nil` if not found.
@@ -150,25 +139,6 @@ module RubyRoutes
         pool = Thread.current[:ruby_routes_hash_pool] ||= []
         pool.push(hash) if pool.size < 5
       end
-
-      # Validate hash-form constraint rules.
-      #
-      # This method validates a value against a set of hash-form constraints,
-      # such as minimum length, maximum length, format, inclusion, exclusion,
-      # and range.
-      #
-      # @param constraint [Hash] The constraint rules.
-      # @param value [String] The value to validate.
-      # @raise [RubyRoutes::ConstraintViolation] If the value violates any constraint.
-      # @return [void]
-      def validate_hash_constraint!(constraint, value)
-        check_min_length(constraint, value)
-        check_max_length(constraint, value)
-        check_format(constraint, value)
-        check_in_list(constraint, value)
-        check_not_in_list(constraint, value)
-        check_range(constraint, value)
-      end
     end
   end
 end

data/lib/ruby_routes/route.rb

@@ -12,13 +12,15 @@ require_relative 'utility/method_utility'
 require_relative 'utility/path_utility'
 require_relative 'utility/route_utility'
 require_relative 'route/param_support'
-require_relative 'route/segment_compiler'
+require_relative 'segment'
 require_relative 'route/path_builder'
 require_relative 'route/constraint_validator'
 require_relative 'route/check_helpers'
 require_relative 'route/query_helpers'
 require_relative 'route/validation_helpers'
+require_relative 'route/segment_compiler'
 require_relative 'route/path_generation'
+require_relative 'route_set/cache_helpers'
 
 module RubyRoutes
   # Route
@@ -51,43 +53,43 @@ module RubyRoutes
   # @api public
   class Route
     include ParamSupport
-    include SegmentCompiler
     include PathBuilder
     include RubyRoutes::Route::ConstraintValidator
     include RubyRoutes::Route::ValidationHelpers
     include RubyRoutes::Route::QueryHelpers
     include RubyRoutes::Route::PathGeneration
+    include RubyRoutes::Route::SegmentCompiler
     include RubyRoutes::Utility::MethodUtility
     include RubyRoutes::Utility::PathUtility
     include RubyRoutes::Utility::KeyBuilderUtility
+    include RubyRoutes::RouteSet::CacheHelpers
 
     attr_reader :path, :methods, :controller, :action, :name, :constraints, :defaults
 
-    public :extract_params, :parse_query_params, :query_params, :generate_path
+    public :extract_params, :parse_query_params, :query_params, :generate_path, :merge_query_params_into_hash
 
     # Create a new Route.
     #
     # @param path [String] The raw route path (may include `:params` or `*splat`).
     # @param options [Hash] The options for the route.
     # @option options [Symbol, String, Array<Symbol, String>] :via (:get) HTTP method(s).
-    # @option options [String] :to ("controller#action") The controller and action.
-    # @option options [String] :controller Explicit controller (overrides `:to`).
-    # @option options [String, Symbol] :action Explicit action (overrides part after `#`).
-    # @option options [Hash] :constraints Parameter constraints (Regexp / Symbol / Hash).
-    # @option options [Hash] :defaults Default parameter values.
-    # @option options [Symbol, String] :as The route name.
+    # @option options [String] :to The controller#action string.
+    # @option options [String] :controller The controller name.
+    # @option options [String] :action The action name.
+    # @option options [String] :as The route name.
+    # @option options [Hash] :constraints The route constraints.
+    # @option options [Hash] :defaults The route defaults.
     def initialize(path, options = {})
+      @options = options
       @path = normalize_path(path)
-
-      setup_methods(options)
-      setup_controller_and_action(options)
-
-      @name = options[:as]
-      @constraints = (options[:constraints] || {}).freeze
-      @defaults = (options[:defaults] || {}).transform_keys(&:to_s).freeze
+      @name = @options[:as]
+      @constraints = (@options[:constraints] || {}).freeze
+      @defaults = (@options[:defaults] || {}).transform_keys(&:to_s).freeze
       @param_key_slots = [[nil, nil], [nil, nil]]
       @required_validated_once = false
 
+      setup_caches
+
       precompile_route_data
       validate_route!
     end
@@ -121,55 +123,32 @@ module RubyRoutes
 
     private
 
-    # Set up HTTP methods from options.
+    # Split path into parts.
     #
-    # @param options [Hash] The options for the route.
-    # @return [void]
-    def setup_methods(options)
-      raw_http_methods = Array(options[:via] || :get)
-      @methods = raw_http_methods.map { |method| normalize_http_method(method) }.freeze
-      @methods_set = @methods.to_set.freeze
+    # @param path [String] The path to split.
+    # @return [Array<String>]
+    def split_path(path)
+      path.split('/').reject(&:empty?)
     end
 
-    # Set up controller and action from options.
-    #
-    # @param options [Hash] The options for the route.
-    # @return [void]
-    def setup_controller_and_action(options)
-      @controller = extract_controller(options)
-      @action = options[:action] || extract_action(options[:to])
-    end
-
-    # Infer controller name from options or `:to`.
-    #
-    # @param options [Hash] The options for the route.
-    # @return [String, nil] The inferred controller name.
-    def extract_controller(options)
-      return options[:controller] if options[:controller]
-      to = options[:to]
-      return nil unless to
-
-      to.to_s.split('#', 2).first
-    end
-
-    # Infer action from `:to` string.
-    #
-    # @param to [String, nil] The `:to` string.
-    # @return [String, nil] The inferred action name.
-    def extract_action(to)
-      return nil unless to
-
-      to.to_s.split('#', 2).last
-    end
+    # Expose for testing / external callers.
+    public :extract_path_params_fast
 
     # Precompile route data for performance.
     #
     # @return [void]
     def precompile_route_data
+      raw_http_methods = Array(@options[:via] || :get)
+      @methods = raw_http_methods.map { |method| normalize_http_method(method) }.freeze
+      @methods_set = @methods.to_set.freeze
+
+      to_str = @options[:to].to_s
+      to_controller, to_action = to_str.split('#', 2)
+      @controller = @options[:controller] || to_controller
+      @action = @options[:action] || to_action
+
       @is_resource = @path.match?(%r{/:id(?:$|\.)})
-      @gen_cache = SmallLru.new(512)
-      @query_cache = SmallLru.new(RubyRoutes::Constant::QUERY_CACHE_SIZE)
-      @cache_mutex = Mutex.new  # Thread-safe access to caches
+
       initialize_validation_cache
       compile_segments
       compile_required_params