ruby_routes 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07fa3c9d3d13ac8b73c6f4775871cd5ad6c3cd7c5d0e571797b83fb0dea72189
-  data.tar.gz: 2684722163772fe4489d4e8c32eaff036002c5b58e05be68e25e9a0c59cd680b
+  metadata.gz: 33b60562a702b7d2def6960af7e255d460b17e508367563aefd9ef85856abe52
+  data.tar.gz: be3560f98947dd313afeef38603a9f97bb6a39917d471db9a26b4dcdbb42d2bc
 SHA512:
-  metadata.gz: dfc84b5cfa67c1da89ab8067ad01c8706c81717611969c287a4a536055fe1ee1b4ac80b791248c05dddb090548f1e29006889d2d7f5e91b9058349b9f9a8b317
-  data.tar.gz: b2ab1c86ca6838a4164621987c813b7320e3f042d1666576e00c3acf48576204c837fd13582ed42f2cf896334b9e1683c8ceab8868c03b7f9a482dcb808a5052
+  metadata.gz: 87b6d61fda5213a0db9e5fba0ad35a3158341e3df9af8e708c38aee60524c3b1c4d2ca85051a4578c3caa57dcfc5fc01d3c37c833652fcb69bd23b6c35580a2e
+  data.tar.gz: 2378650e65113fc8d29c2062dbfb85127629f18d7f82a4dc00a98f5453b9c933c3fce20cbcc27e6a25b9d07313fec4c03778015ab0a55cf2e55abd4fb251029b

data/README.md

@@ -447,29 +447,6 @@ This gem is available as open source under the terms of the [MIT License](LICENS
 
 This gem was inspired by Rails routing and aims to provide a lightweight alternative for Ruby applications that need flexible routing without the full Rails framework.
 
-## Thread-safe Build (Isolated Builder)
-
-Use the builder to accumulate routes without mutating a live router:
-
-```ruby
-router = RubyRoutes::Router.build do
-  resources :users
-  namespace :admin do
-    resources :posts
-  end
-end
-# router is now finalized (immutable)
-```
-
-If you need manual steps:
-
-```ruby
-builder = RubyRoutes::Router::Builder.new do
-  get '/health', to: 'system#health'
-end
-router = builder.build  # finalized
-```
-
 ## Fluent Method Chaining
 
 For a more concise style, the routing DSL supports method chaining:

data/lib/ruby_routes/constant.rb

@@ -74,6 +74,23 @@ module RubyRoutes
       default: ->(_node, _segment, _idx, _segments, _params) { nil }
     }.freeze
 
+    TRAVERSAL_STRATEGIES = {
+      static: lambda do |node, segment, _index, _segments|
+        static_child = node.static_children[segment]
+        [static_child, false, Constant::EMPTY_HASH] if static_child
+      end,
+      dynamic: lambda do |node, segment, _index, _segments|
+        dynamic_child = node.dynamic_child
+        [dynamic_child, false, { dynamic_child.param_name => segment }] if dynamic_child
+      end,
+      wildcard: lambda do |node, _segment, index, segments|
+        wildcard_child = node.wildcard_child
+        [wildcard_child, true, { wildcard_child.param_name => segments[index..-1].join('/') }] if wildcard_child
+      end
+    }.freeze
+
+    TRAVERSAL_ORDER = %i[static dynamic wildcard].freeze
+
     # Singleton instances to avoid per-cache strategy allocations.
     #
     # @return [RubyRoutes::LruStrategies::HitStrategy, RubyRoutes::LruStrategies::MissStrategy]
@@ -105,9 +122,7 @@ module RubyRoutes
     # recently used entries will be evicted.
     #
     # @return [Integer]
-    QUERY_CACHE_SIZE = 128
-
-    METHOD_CACHE_MAX_SIZE = 1000
+    CACHE_SIZE = 2048
 
     # HTTP method constants.
     HTTP_GET     = 'GET'

data/lib/ruby_routes/lru_strategies/hit_strategy.rb

@@ -30,7 +30,7 @@ module RubyRoutes
         lru.increment_hits
         # Internal storage name (@hash) is intentionally accessed reflectively
         # to keep strategy decoupled from public API surface.
-        store = lru.instance_variable_get(:@hash)
+        store = lru.hash
         value = store.delete(key)
         store[key] = value
         value

data/lib/ruby_routes/node.rb

@@ -1,115 +1,42 @@
 # frozen_string_literal: true
 
 require_relative 'segment'
-require_relative 'utility/path_utility'
 require_relative 'utility/method_utility'
 require_relative 'constant'
 
 module RubyRoutes
-  # Node
-  #
-  # A single vertex in the routing radix tree.
-  #
-  # Structure:
-  # - static_children: Hash<String, Node> exact literal matches.
-  # - dynamic_child:   Node (":param") matches any single segment, captures value.
-  # - wildcard_child:  Node ("*splat") matches remaining segments (greedy).
-  #
-  # Handlers:
-  # - @handlers maps canonical HTTP method strings (e.g. "GET") to Route objects (or callable handlers).
-  # - @is_endpoint marks that at least one handler is attached (terminal path).
-  #
-  # Matching precedence (most → least specific):
-  #   static → dynamic → wildcard
-  #
-  # Thread safety: not thread-safe (build during boot).
-  #
-  # @api internal
   class Node
+    include RubyRoutes::Utility::MethodUtility
+
     attr_accessor :param_name, :is_endpoint, :dynamic_child, :wildcard_child
     attr_reader :handlers, :static_children
 
-    include RubyRoutes::Utility::PathUtility
-    include RubyRoutes::Utility::MethodUtility
-
     def initialize
-      @is_endpoint     = false
-      @handlers        = {}
-      @static_children = {}
-      @dynamic_child   = nil
-      @wildcard_child  = nil
-      @param_name      = nil
+      @is_endpoint      = false
+      @handlers         = {}
+      @static_children  = {}
+      @dynamic_child    = nil
+      @wildcard_child   = nil
+      @param_name       = nil
     end
 
-    # Register a handler under an HTTP method.
-    #
-    # @param method [String, Symbol]
-    # @param handler [Object] route or callable
-    # @return [Object] handler
     def add_handler(method, handler)
-      method_key = normalize_http_method(method)
-      @handlers[method_key] = handler
-      @is_endpoint = true
-      handler
+      method_str            = normalize_http_method(method)
+      @handlers[method_str] = handler
+      @is_endpoint          = true
     end
 
-    # Fetch a handler for a method.
-    #
-    # @param method [String, Symbol]
-    # @return [Object, nil]
     def get_handler(method)
       @handlers[normalize_http_method(method)]
     end
 
-    # Traverses from this node using a single path segment.
-    # Returns [next_node_or_nil, stop_traversal(Boolean), captured_params(Hash)].
-    #
-    # Optimized + simplified (cyclomatic / perceived complexity, length).
-    #
-    # @param segment [String] the path segment to match
-    # @param index [Integer] the segment index in the full path
-    # @param segments [Array<String>] all path segments
-    # @param params [Hash] (unused in this method; mutation deferred)
-    # @return [Array] [next_node, stop, captured] or NO_TRAVERSAL_RESULT
     def traverse_for(segment, index, segments, params)
-      return [@static_children[segment], false, {}] if @static_children[segment]
-
-      if @dynamic_child
-        captured = capture_dynamic_param(@dynamic_child, segment)
-        return [@dynamic_child, false, captured]
-      end
-
-      if @wildcard_child
-        captured = capture_wildcard_param(@wildcard_child, segments, index)
-        return [@wildcard_child, true, captured]
+      RubyRoutes::Constant::TRAVERSAL_ORDER.each do |strategy_name|
+        result = RubyRoutes::Constant::TRAVERSAL_STRATEGIES[strategy_name].call(self, segment, index, segments)
+        return result if result
       end
 
       RubyRoutes::Constant::NO_TRAVERSAL_RESULT
     end
-
-    private
-
-    # Captures a dynamic parameter value and returns it for later assignment.
-    #
-    # @param dynamic_node [Node] the dynamic child node
-    # @param value [String] the segment value to capture
-    # @return [Hash] captured parameter hash or empty hash if no param
-    def capture_dynamic_param(dynamic_node, value)
-      return {} unless dynamic_node.param_name
-
-      { dynamic_node.param_name => value }
-    end
-
-    # Captures a wildcard parameter value and returns it for later assignment.
-    #
-    # @param wc_node [Node] the wildcard child node
-    # @param segments [Array<String>] the full path segments
-    # @param index [Integer] the current segment index
-    # @return [Hash] captured parameter hash or empty hash if no param
-    def capture_wildcard_param(wildcard_node, segments, index)
-      return {} unless wildcard_node.param_name
-
-      { wildcard_node.param_name => segments[index..].join('/') }
-    end
   end
 end

data/lib/ruby_routes/radix_tree/finder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../constant'
+require_relative 'traversal_strategy'
 
 module RubyRoutes
   class RadixTree
@@ -8,6 +9,21 @@ module RubyRoutes
     # Handles path normalization, segment traversal, and parameter extraction.
     module Finder
 
+      # Pre-allocated buffers to minimize object creation
+      EMPTY_PARAMS = {}.freeze
+      TRAVERSAL_STATE_TEMPLATE = {
+        current: nil,
+        best_node: nil,
+        best_params: nil,
+        best_captured: nil,
+        matched: false
+      }.freeze
+
+      # Reusable hash for captured parameters to avoid repeated allocations
+      PARAMS_BUFFER_KEY = :ruby_routes_finder_params_buffer
+      CAPTURED_PARAMS_BUFFER_KEY = :ruby_routes_finder_captured_params_buffer
+      STATE_BUFFER_KEY = :ruby_routes_finder_state_buffer
+
       # Evaluate constraint rules for a candidate route.
       #
       # @param route_handler [Object]
@@ -18,32 +34,33 @@ module RubyRoutes
 
         begin
           # Use a duplicate to avoid unintended mutation by validators.
-          route_handler.validate_constraints_fast!(captured_params)
+          route_handler.validate_constraints_fast!(captured_params.dup)
           true
         rescue RubyRoutes::ConstraintViolation
           false
         end
       end
 
-      private
-
       # Finds a route handler for the given path and HTTP method.
       #
       # @param path_input [String] the input path to match
       # @param method_input [String, Symbol] the HTTP method
       # @param params_out [Hash] optional output hash for captured parameters
-      # @return [Array] [handler, params] or [nil, params] if no match
-      def find(path_input, method_input, params_out = nil)
-        path = path_input.to_s
-        method = normalize_http_method(method_input)
-        return root_match(method, params_out) if path.empty? || path == RubyRoutes::Constant::ROOT_PATH
+      # @return [Array] [handler, params] or [nil, {}] if no match
+      def find(path_input, http_method, params_out = nil)
+        # Handle nil or empty path input
+        return [nil, EMPTY_PARAMS] if path_input.nil?
 
-        segments = split_path_cached(path)
-        return [nil, params_out || {}] if segments.empty?
+        method = normalize_http_method(http_method)
+        return root_match(method, params_out || EMPTY_PARAMS) if path_input.empty? || path_input == RubyRoutes::Constant::ROOT_PATH
 
-        params = params_out || {}
-        state = traversal_state
-        captured_params = {}
+        segments = split_path_cached(path_input)
+        return [nil, EMPTY_PARAMS] if segments.empty?
+
+        # Use thread-local, reusable hashes to avoid allocations
+        params = acquire_params_buffer(params_out)
+        state = acquire_state_buffer
+        captured_params = acquire_captured_params_buffer
 
         result = perform_traversal(segments, state, method, params, captured_params)
         return result unless result.nil?
@@ -54,17 +71,28 @@ module RubyRoutes
       # Initializes the traversal state for route matching.
       #
       # @return [Hash] state hash with :current, :best_node, :best_params, :best_captured, :matched
-      def traversal_state
-        {
-          current: @root,
-          best_node: nil,
-          best_params: nil,
-          best_captured: nil,
-          matched: false # Track if any segment was successfully matched
-        }
+      def acquire_state_buffer
+        state = Thread.current[STATE_BUFFER_KEY] ||= {}
+        state.clear
+        state[:current] = @root
+        state
+      end
+
+      def acquire_params_buffer(initial_params)
+        buffer = Thread.current[PARAMS_BUFFER_KEY] ||= {}
+        buffer.clear
+        buffer.merge!(initial_params) if initial_params
+        buffer
+      end
+
+      def acquire_captured_params_buffer
+        buffer = Thread.current[CAPTURED_PARAMS_BUFFER_KEY] ||= {}
+        buffer.clear
+        buffer
       end
 
       # Performs traversal through path segments to find a matching route.
+      # Optimized for common cases of 1-3 segments.
       #
       # @param segments [Array<String>] path segments
       # @param state [Hash] traversal state
@@ -72,17 +100,8 @@ module RubyRoutes
       # @param params [Hash] parameters hash
       # @param captured_params [Hash] hash to collect captured parameters
       # @return [nil, Array] nil if traversal succeeds, Array from finalize_on_fail if traversal fails
-      def perform_traversal(segments, state, method, params, captured_params)
-        segments.each_with_index do |segment, index|
-          next_node, stop = traverse_for_segment(state[:current], segment, index, segments, params, captured_params)
-          return finalize_on_fail(state, method, params, captured_params) unless next_node
-
-          state[:current] = next_node
-          state[:matched] = true # Set matched to true if at least one segment matched
-          record_candidate(state, method, params, captured_params) if endpoint_with_method?(state[:current], method)
-          break if stop
-        end
-        nil # Return nil to indicate successful traversal
+      def perform_traversal(segments, state, method, params, captured_params) # rubocop:disable Metrics/AbcSize
+        TraversalStrategy.for(segments.size, self).execute(segments, state, method, params, captured_params)
       end
 
       # Traverses to the next node for a given segment.
@@ -93,13 +112,10 @@ module RubyRoutes
       # @param segments [Array<String>] all segments
       # @param params [Hash] parameters hash
       # @param captured_params [Hash] hash to collect captured parameters
-      # @return [Array] [next_node, stop_traversal, segment_captured]
+      # @return [Array] [next_node, stop_traversal]
       def traverse_for_segment(node, segment, index, segments, params, captured_params)
         next_node, stop, segment_captured = node.traverse_for(segment, index, segments, params)
-        if segment_captured
-          params.merge!(segment_captured)  # Merge into running params hash at each step
-          captured_params.merge!(segment_captured)  # Keep for best candidate consistency
-        end
+        merge_captured_params(params, captured_params, segment_captured)
         [next_node, stop]
       end
 
@@ -111,7 +127,7 @@ module RubyRoutes
       # @param captured_params [Hash] captured parameters from traversal
       def record_candidate(state, _method, params, captured_params)
         state[:best_node] = state[:current]
-        state[:best_params] = params.dup
+        state[:best_params] = params
         state[:best_captured] = captured_params.dup
       end
 
@@ -145,17 +161,17 @@ module RubyRoutes
       # @param captured_params [Hash] captured parameters from traversal
       # @return [Array] [handler, params] or [nil, params]
       def finalize_success(state, method, params, captured_params)
-        result = finalize_match(state[:current], method, params, captured_params)
-        return result if result[0]
+        handler, final_params = finalize_match(state[:current], method, params, captured_params)
+        return [handler, final_params] if handler
 
         # Try best candidate if current failed
         if state[:best_node]
           best_params = state[:best_params] || params
           best_captured = state[:best_captured] || captured_params
-          finalize_match(state[:best_node], method, best_params, best_captured)
-        else
-          result
+          handler, final_params = finalize_match(state[:best_node], method, best_params, best_captured)
         end
+
+        [handler, final_params]
       end
 
       # Falls back to the best candidate if no exact match.
@@ -181,7 +197,7 @@ module RubyRoutes
 
         if node && endpoint_with_method?(node, method)
           handler = node.handlers[method]
-          if check_constraints(handler, params)
+          if check_constraints(handler, captured_params)
             return [handler, params]
           end
         end
@@ -194,9 +210,9 @@ module RubyRoutes
       # @return [Array] [handler, params] or [nil, params]
       def root_match(method, params_out)
         if @root.is_endpoint && (handler = @root.handlers[method])
-          [handler, params_out || {}]
+          [handler, params_out]
         else
-          [nil, params_out || {}]
+          [nil, EMPTY_PARAMS]
         end
       end
 
@@ -205,7 +221,19 @@ module RubyRoutes
       # @param params [Hash] the final parameters hash
       # @param captured_params [Hash] captured parameters from traversal
       def apply_captured_params(params, captured_params)
-        params.merge!(captured_params) if captured_params && !captured_params.empty?
+        merge_captured_params(params, params, captured_params)
+      end
+
+      # Merges captured parameters into the parameter hashes.
+      #
+      # @param params [Hash] the main parameters hash
+      # @param captured_params [Hash] the captured parameters hash
+      # @param segment_captured [Hash] the newly captured parameters
+      def merge_captured_params(params, captured_params, segment_captured)
+        return if segment_captured.empty?
+
+        params.merge!(segment_captured)
+        captured_params.merge!(segment_captured)
       end
     end
   end

data/lib/ruby_routes/radix_tree/inserter.rb

@@ -5,7 +5,6 @@ module RubyRoutes
     # 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.
       #
@@ -16,7 +15,7 @@ module RubyRoutes
       def insert_route(path_string, http_methods, route_handler)
         return route_handler if path_string.nil? || path_string.empty?
 
-        tokens = split_path(path_string)
+        tokens = split_path_cached(path_string)
         current_node = @root
         tokens.each { |token| current_node = advance_node(current_node, token) }
         finalize_endpoint(current_node, http_methods, route_handler)
@@ -29,59 +28,7 @@ module RubyRoutes
       # @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..]
-        raise ArgumentError, "Dynamic parameter name cannot be empty" if param_name.nil? || param_name.empty?
-        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
+        Segment.for(token).ensure_child(current_node)
       end
 
       # Finalizes the endpoint by adding handlers for HTTP methods.

data/lib/ruby_routes/radix_tree/traversal_strategy/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class RadixTree
+    module TraversalStrategy
+      # Base class for all traversal strategies.
+      class Base
+        def initialize(finder)
+          @finder = finder
+        end
+
+        def execute(_segments, _state, _method, _params, _captured_params)
+          raise NotImplementedError, "#{self.class.name} must implement #execute"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_routes/radix_tree/traversal_strategy/generic_loop.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RubyRoutes
+  class RadixTree
+    module TraversalStrategy
+      # Traversal strategy using a generic loop, ideal for longer paths (4+ segments).
+      class GenericLoop < Base
+        def execute(segments, state, method, params, captured_params)
+          segments.each_with_index do |segment, index|
+            next_node, stop = @finder.send(:traverse_for_segment, state[:current], segment, index, segments, params, captured_params)
+            return @finder.send(:finalize_on_fail, state, method, params, captured_params) unless next_node
+
+            state[:current] = next_node
+            state[:matched] = true
+            @finder.send(:record_candidate, state, method, params, captured_params) if @finder.send(:endpoint_with_method?, state[:current], method)
+            break if stop
+          end
+          nil # Signal successful traversal
+        end
+      end
+    end
+  end
+end

data/lib/ruby_routes/radix_tree/traversal_strategy/unrolled.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RubyRoutes
+  class RadixTree
+    module TraversalStrategy
+      # Traversal strategy using unrolled loops for common short paths (1-3 segments).
+      # This provides a performance boost by avoiding loop overhead for the most frequent cases.
+      class Unrolled < Base
+        def execute(segments, state, method, params, captured_params)
+          # This case statement manually unrolls the traversal loop for paths
+          # with 1, 2, or 3 segments. The `TraversalStrategy.for` factory ensures
+          # this strategy is only used for these lengths.
+          case segments.size
+          when 1
+            traverse_segment(0, segments, state, method, params, captured_params)
+          when 2
+            traverse_segment(0, segments, state, method, params, captured_params)
+            traverse_segment(1, segments, state, method, params, captured_params)
+          when 3
+            traverse_segment(0, segments, state, method, params, captured_params)
+            traverse_segment(1, segments, state, method, params, captured_params)
+            traverse_segment(2, segments, state, method, params, captured_params)
+          end
+          nil # Return nil to indicate successful traversal
+        end
+
+        private
+
+        # Traverses a single segment, updates state, and records candidate if applicable.
+        # Returns true if traversal should stop (e.g., due to wildcard), false otherwise.
+        def traverse_segment(index, segments, state, method, params, captured_params)
+          next_node, stop = @finder.traverse_for_segment(state[:current], segments[index], index, segments, params, captured_params)
+          return false unless next_node
+
+          state[:current] = next_node
+          state[:matched] = true
+          @finder.record_candidate(state, method, params, captured_params) if @finder.endpoint_with_method?(state[:current], method)
+          stop
+        end
+      end
+    end
+  end
+end

data/lib/ruby_routes/radix_tree/traversal_strategy.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'traversal_strategy/base'
+require_relative 'traversal_strategy/generic_loop'
+require_relative 'traversal_strategy/unrolled'
+
+module RubyRoutes
+  class RadixTree
+    # This module encapsulates the different strategies for traversing the RadixTree.
+    # It provides a factory to select the appropriate strategy based on path length.
+    module TraversalStrategy
+      # Selects the appropriate traversal strategy based on the number of segments.
+      #
+      # @param segment_count [Integer] The number of segments in the path.
+      # @param finder [RubyRoutes::RadixTree::Finder] The finder instance.
+      # @return [Base] An instance of a traversal strategy.
+      def self.for(segment_count, finder)
+        if segment_count <= 3
+          Unrolled.new(finder)
+        else
+          GenericLoop.new(finder)
+        end
+      end
+    end
+  end
+end